The /api/ocr-structured endpoint extracts invoice data into a structured JSON format compatible with MyBillBook. It includes automatic reconciliation to verify calculations and detect mismatches.
Endpoint Request Body Base64-encoded image data or data URL Formats:
Bare base64: iVBORw0KGgoAAAANS...
Data URL: data:image/png;base64,iVBORw0KGgo...
mimeType
string
default: "image/png"
MIME type of the image (e.g., image/png, image/jpeg, image/webp)
Override the default model. Examples: openai/gpt-4o, anthropic/claude-3.5-sonnet
Response Schema The endpoint returns a structured invoice document with three main sections:
Voucher Object Invoice header information and totals Invoice number (e.g., “INV-2024-001”)
Invoice date in dd-mm-yyyy format (e.g., “15-01-2024”)
Due date in dd-mm-yyyy format
Voucher-level discount amount (numeric string, e.g., “500.00”)
When discount applies: "before_tax", "after_tax", or "" (unknown)
Rounding adjustment (numeric string, typically ±1.00)
Final payable amount including taxes and round-off
Optional voucher-level charges (Freight, Packing, etc.) Charge name (e.g., “Freight”)
Charge amount (numeric string)
GST rate as percentage (numeric string)
Whether amount includes GST (true) or is pre-GST (false)
Calculation verification results (added by reconciliation engine) Assumptions used in reconciliation
Calculated total from line items
Difference between computed and printed total
Total taxable amount from items
Total taxable amount from charges
Items Array Line items extracted from the invoice HSN/SAC code for the item
Quantity (numeric string)
Unit of measurement (e.g., “PCS”, “KG”, “L”)
Tax-exclusive unit price (numeric string)
Discount percentage (numeric string)
Total GST rate percentage (CGST+SGST or IGST)
Party Object Customer/buyer information Example Requests cURL
JavaScript/TypeScript
Python
curl -X POST https://your-domain.com/api/ocr-structured \ -H "Content-Type: application/json" \ -d '{ "imageBase64": "data:image/png;base64,iVBORw0KGgo...", "model": "openai/gpt-4o-mini" }'
Example Response { "voucher" : { "invoice_number" : "INV-2024-001" , "invoice_date" : "15-01-2024" , "invoice_due_date" : "30-01-2024" , "invoice_discount" : "0" , "invoice_discount_mode" : "" , "round_off" : "0.00" , "total_invoice_amount" : "11800.00" , "additional_charges" : [ { "name" : "Freight" , "amount" : "500.00" , "tax_rate" : "18" , "amount_includes_tax" : false } ], "reconciliation" : { "status" : "matched" , "method" : { "discount_mode" : "before_tax" , "charges_inclusive" : false }, "computed_grand_total" : "11800.00" , "difference" : "0.00" , "items_taxable_total" : "10000.00" , "items_tax_total" : "1800.00" , "charges_taxable_total" : "500.00" , "charges_tax_total" : "90.00" } }, "items" : [ { "name" : "Premium Widget" , "hsn_sac_code" : "8517" , "quantity" : "10" , "unit" : "PCS" , "price" : "1000.00" , "discount_rate" : "0" , "tax_rate" : "18" } ], "party" : { "party_name" : "Acme Corporation" , "party_gstin_number" : "27AABCU9603R1ZM" , "party_pan_number" : "AABCU9603R" , "party_address" : "123 Business Street" , "party_city" : "Mumbai" , "party_pincode" : "400001" } }
{ "error" : "Missing 'imageBase64' in request body" }
Reconciliation Logic The endpoint automatically runs reconciliation using lib/invoice.ts:
Parse extracted JSON from model responseCompute line item totals : taxable = qty × price × (1 - discount%); tax = taxable × tax_rate; total = taxable + taxApply voucher discount before or after tax based on invoice_discount_modeAdd charges with their GSTApply round-off adjustmentCompare computed total with total_invoice_amountSet status : "matched" if difference ≤ 0.05, else "unmatched"
Schema Constraints The system prompt enforces these rules:
Numbers : Strings without commas (e.g., "1234.50")Dates : dd-mm-yyyy format (converts from other formats)Unknown values : Empty string ""Tax-exclusive prices : item.price must be pre-GST; model converts if neededDiscount combination : Multiple discounts combined multiplicativelyRound-off : Typically ±1.00 unless explicitly printed
Limitations This endpoint only supports images. For PDF support, use /api/ocr-structured-v4.
Image input only (no PDF support)
Simpler schema than v4 (no header discounts, TCS, etc.)
Less sophisticated reconciliation than v4
Better suited for basic invoices
Migration to V4 For India GST invoices with complex scenarios, migrate to /api/ocr-structured-v4:
PDF support with multi-page processing
Header-level discounts (trade, special)
TCS (Tax Collected at Source)
HSN-wise tax tables
Advanced reconciliation with multiple strategies
Confidence scoring per field
Next Steps
V4 Schema Upgrade to advanced India GST schema
Reconciliation Logic Learn how calculation verification works
