POST /api/ocr-structured-v4

The /api/ocr-structured-v4 endpoint provides the most advanced invoice extraction with comprehensive India GST support, multi-page PDF processing, and sophisticated reconciliation logic.

Endpoint

POST /api/ocr-structured-v4

Request Body

imageBase64

string

Base64-encoded image data or data URL. Required if pdfUrl and pdfBase64 are not provided.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)

pdfUrl

string

Publicly accessible URL to a PDF document. Required if imageBase64 and pdfBase64 are not provided.

pdfBase64

string

Base64-encoded PDF data or data URL. Required if imageBase64 and pdfUrl are not provided.

filename

string

default:"invoice.pdf"

Optional filename for PDF documents

model

string

Override the default model. Default: google/gemini-2.0-flash if OPENROUTER_MODEL not set

annotations

object

Pass-through OpenRouter annotations to avoid re-parsing costs on subsequent requests

plugins

array

Override PDF parsing plugins. Advanced use only.Default:

[
  {
    "id": "file-parser",
    "pdf": { "engine": "pdf-text" }
  }
]

Response Schema

The v4 schema provides comprehensive invoice data with normalized GST calculations:

Document Level

doc_level

object

Invoice header metadata

Show properties

supplier_name

string

Supplier/seller name

supplier_gstin

string

Supplier GSTIN (15 characters)

invoice_number

string

Invoice number

invoice_date

string

Invoice date in YYYY-MM-DD format

place_of_supply_state_code

string

State code (2 digits, e.g., “27” for Maharashtra)

buyer_gstin

string

Buyer GSTIN

currency

string

Currency code (typically “INR”)

Items Array

items

array

Line items with detailed breakdowns

Show items

name

string

Item name or description

hsn

string

HSN/SAC code

qty

number

Quantity

uom

string

Unit of measurement (GST UQC code: NOS, PCS, KGS, LTR, etc.)

rate_ex_tax

number

Tax-exclusive unit rate

discount

object

Discount breakdown

Show properties

d1_pct

number | null

First discount percentage (e.g., Trade Discount)

d2_pct

number | null

Second discount percentage (e.g., Special Discount)

flat_per_unit

number | null

Flat discount per unit (applied after percentages)

effective_pct

number

Combined effective discount percentage

amount

number

Total discount amount

gst

object

GST breakdown

Show properties

rate

number

GST rate percentage (0, 0.25, 3, 5, 12, 18, or 28)

cgst

number

CGST amount (intra-state)

sgst

number

SGST amount (intra-state)

igst

number

IGST amount (inter-state)

amount

number

Total GST amount (CGST+SGST or IGST)

totals

object

Line totals

Show properties

line_ex_tax

number

Line total excluding tax

line_inc_tax

number

Line total including tax

raw

object

Raw values from invoice for debugging

Show properties

rate_printed

number | null

Rate as printed on invoice

price_mode_detected

string

"WITH_TAX" or "WITHOUT_TAX"

discount_pct_printed

number | null

First discount percentage printed

special_discount_pct_printed

number | null

Second discount percentage printed

amount_printed

number | null

Line amount as printed

ui_hints

object

Display hints for UI rendering

Show properties

qty_x_rate_text

string

Formatted “10 × ₹1,000” string

discount_row

object

Discount row display

tax_row

object

Tax row display

confidence

number

Extraction confidence (0.0 to 1.0)

Header Discounts

header_discounts

array

Invoice-level discounts applied before charges and GST

Show items

label

string

Discount name (e.g., “Trade Discount”)

type

string

"PERCENT" or "FLAT"

value

number

Percentage or absolute amount

order

number

Application order (1, 2, …)

Charges

charges

array

Additional charges (Freight, Packing, Insurance, etc.)

Show items

label

string

Charge name

ex_tax

number

Charge amount excluding GST

gst_rate_hint

number | null

GST rate if taxable

gst_amount

number

GST on charge

inc_tax

number

Charge amount including GST

taxable

boolean

Whether charge is subject to GST

TCS

tcs

object

Tax Collected at Source

Show properties

rate

number

TCS rate percentage

amount

number

TCS amount

base_used

string

Base for TCS calculation (typically “grand_total_before_tcs”)

Round-Off

round_off

number

Rounding adjustment (typically ±1.00)

Totals

totals

object

Computed invoice totals

Show properties

items_ex_tax

number

Total of all line items excluding tax

header_discounts_ex_tax

number

Total header discounts

charges_ex_tax

number

Total charges excluding GST

taxable_ex_tax

number

Total taxable amount (items - discounts + charges)

gst_total

number

Total GST amount

grand_total

number

Final payable amount

Printed Values

printed

object

Values extracted from printed subtotals/tables

Show properties

taxable_subtotal

number | null

Printed taxable subtotal

gst_total

number | null

Printed total GST

hsn_tax_table

array

HSN-wise tax table if printed

grand_total

number | null

Printed grand total

Reconciliation

reconciliation

object

Calculation verification results

Show properties

error_absolute

number

Absolute difference between computed and printed total

alternates_considered

array

Alternative calculation strategies evaluated

warnings

array

Warnings about potential issues

Metadata

Example Requests

curl -X POST https://your-domain.com/api/ocr-structured-v4 \
  -H "Content-Type: application/json" \
  -d '{
    "imageBase64": "data:image/png;base64,iVBORw0KGgo...",
    "model": "google/gemini-2.0-flash"
  }'

Example Response

Success (200) - Excerpt

{
  "doc_level": {
    "supplier_name": "Tech Solutions Pvt Ltd",
    "supplier_gstin": "27AABCT1234C1Z5",
    "invoice_number": "INV-2024-001",
    "invoice_date": "2024-01-15",
    "place_of_supply_state_code": "27",
    "buyer_gstin": "27AABCU9603R1ZM",
    "currency": "INR"
  },
  "items": [
    {
      "name": "Premium Widget",
      "hsn": "8517",
      "qty": 10,
      "uom": "PCS",
      "rate_ex_tax": 1000.00,
      "discount": {
        "d1_pct": 10.0,
        "d2_pct": 5.0,
        "flat_per_unit": null,
        "effective_pct": 14.5,
        "amount": 1450.00
      },
      "gst": {
        "rate": 18.0,
        "cgst": 769.50,
        "sgst": 769.50,
        "igst": 0.00,
        "amount": 1539.00
      },
      "totals": {
        "line_ex_tax": 8550.00,
        "line_inc_tax": 10089.00
      },
      "raw": {
        "rate_printed": 1000.00,
        "price_mode_detected": "WITHOUT_TAX",
        "discount_pct_printed": 10.0,
        "special_discount_pct_printed": 5.0,
        "amount_printed": 8550.00
      },
      "ui_hints": {
        "qty_x_rate_text": "10 × ₹1,000.00",
        "discount_row": { "label": "Discount", "percent": 14.5, "amount": 1450.00 },
        "tax_row": { "label": "GST @18%", "percent": 18.0, "amount": 1539.00 }
      },
      "confidence": 0.95
    }
  ],
  "header_discounts": [],
  "charges": [
    {
      "label": "Freight",
      "ex_tax": 500.00,
      "gst_rate_hint": 18.0,
      "gst_amount": 90.00,
      "inc_tax": 590.00,
      "taxable": true
    }
  ],
  "tcs": { "rate": 0.0, "amount": 0.0, "base_used": "grand_total_before_tcs" },
  "round_off": -0.00,
  "totals": {
    "items_ex_tax": 8550.00,
    "header_discounts_ex_tax": 0.0,
    "charges_ex_tax": 500.00,
    "taxable_ex_tax": 9050.00,
    "gst_total": 1629.00,
    "grand_total": 10679.00
  },
  "printed": {
    "taxable_subtotal": 9050.00,
    "gst_total": 1629.00,
    "hsn_tax_table": [
      { "hsn": "8517", "taxable": 9050.00, "cgst": 814.50, "sgst": 814.50, "total": 10679.00 }
    ],
    "grand_total": 10679.00
  },
  "reconciliation": {
    "error_absolute": 0.00,
    "alternates_considered": [],
    "warnings": []
  },
  "meta": {
    "pages_processed": 1,
    "language": "en",
    "overall_confidence": 0.92
  }
}

Reconciliation Logic

The v4 reconciliation engine (lib/invoice_v4.ts) performs sophisticated validation:

Price Mode Detection: Determines if printed rates are WITH_TAX or WITHOUT_TAX by comparing with GST summary
Sequential Discounts: Applies d1 then d2: effective = d1 + d2 - (d1 × d2)
Line Calculation: line_ex_tax = qty × rate_ex_tax × (1 - effective_pct) - flat_discount
Header Discounts: Applied to subtotal before charges and GST
Charges: Added with GST (inherits weighted avg rate if not specified)
TCS: Applied after GST
Round-Off: Applied last
Validation: Compares against printed totals and HSN tables
Alternate Strategies: Tests multiple calculation approaches, selects lowest error

Schema Constraints

The system prompt enforces:

GST Slabs: 0, 0.25, 3, 5, 12, 18, 28 (as percentages, not decimals)
UQC Codes: Valid GST unit codes only (NOS, PCS, KGS, LTR, MTR, etc.)
Date Format: YYYY-MM-DD (ISO 8601)
Decimal Precision: 2 decimals in final JSON, higher precision internally
Unknown Values: null with reduced confidence
Round-Off: Expected |round_off| ≤ 1.00 unless explicitly printed

Advanced Features

Multi-Page PDF Processing

For PDFs, the endpoint:

Processes all pages
Prefers HSN tax tables and summaries (often on page 2+)
Uses tables as reconciliation anchors
Sets meta.pages_processed count

Price Mode Ambiguity

When unclear if rates include GST:

Tests BOTH WITH_TAX and WITHOUT_TAX modes
Compares each against printed totals, HSN tables, and subtotals
Prefers mode with lowest absolute error AND small round-off (≤ 1.00)
Stores detected mode in raw.price_mode_detected

Confidence Scoring

Each item includes confidence (0.0-1.0) based on:

OCR quality of relevant fields
Presence of validation anchors (HSN table, subtotals)
Calculation consistency
meta.overall_confidence aggregates across document

OpenRouter Annotations

To avoid re-parsing costs on retries:

First request processes the PDF
OpenRouter returns annotations in response metadata
Pass annotations in subsequent requests to reuse parsed content
Significantly faster and cheaper for large PDFs

Migration from Legacy

Upgrading from /api/ocr-structured:

Legacy Field	V4 Equivalent	Notes
`voucher.invoice_number`	`doc_level.invoice_number`	Direct mapping
`voucher.invoice_date`	`doc_level.invoice_date`	Format: dd-mm-yyyy → YYYY-MM-DD
`items[].price`	`items[].rate_ex_tax`	Same concept
`items[].tax_rate`	`items[].gst.rate`	Percentage (18, not 0.18)
`items[].discount_rate`	`items[].discount.effective_pct`	V4 supports multi-level
`voucher.invoice_discount`	`header_discounts[]`	Array for sequential discounts
`voucher.additional_charges`	`charges[]`	Enhanced structure
`party.*`	Not in v4	Extract from `buyer_gstin` if needed
`voucher.reconciliation.status`	`reconciliation.error_absolute`	Numeric error instead of binary status

Best Practices

Use PDF for Multi-Page Invoices

PDFs preserve better quality and allow processing multiple pages with tax summaries

Validate HSN Tax Tables

Check printed.hsn_tax_table matches totals for high-confidence extraction

Monitor Reconciliation Error

Accept error_absolute ≤ 1.00 as normal rounding, investigate larger differences

Use Confidence Scores

Flag items with confidence < 0.7 for manual review

Cache Annotations for PDFs

Store and reuse annotations from response to avoid re-parsing same PDFs

Limitations

Requires India GST format (GSTIN, HSN, CGST/SGST/IGST)
Optimized for myBillBook-style invoices
May struggle with highly custom layouts
Confidence scoring requires validation anchors
TCS support is basic (single rate, single base)

Next Steps

Reconciliation Engine

Deep dive into v4 reconciliation logic

Integration Guide

Build a complete v4 extraction workflow

UI Components

Display v4 data with pre-built components

Testing

Test your v4 integration

Endpoints

Schemas

POST /api/ocr-structured-v4

Endpoint

Request Body

Response Schema

Document Level

Items Array

Header Discounts

Charges

TCS

Round-Off

Totals

Printed Values

Reconciliation

Metadata

Example Requests

Example Response

Reconciliation Logic

Schema Constraints

Advanced Features

Multi-Page PDF Processing

Price Mode Ambiguity

Confidence Scoring

OpenRouter Annotations

Migration from Legacy

Best Practices

Limitations

Next Steps

Reconciliation Engine

Integration Guide

UI Components

Testing

Build docs developers (and LLMs) love

Endpoints

Schemas

​Endpoint

​Request Body

​Response Schema

​Document Level

​Items Array

​Header Discounts

​Charges

​TCS

​Round-Off

​Totals

​Printed Values

​Reconciliation

​Metadata

​Example Requests

​Example Response

​Reconciliation Logic

​Schema Constraints

​Advanced Features

​Multi-Page PDF Processing

​Price Mode Ambiguity

​Confidence Scoring

​OpenRouter Annotations

​Migration from Legacy

​Best Practices

​Limitations

​Next Steps

Reconciliation Engine

Integration Guide

UI Components

Testing

Build docs developers (and LLMs) love

Endpoint

Request Body

Response Schema

Document Level

Items Array

Header Discounts

Charges

TCS

Round-Off

Totals

Printed Values

Reconciliation

Metadata

Example Requests

Example Response

Reconciliation Logic

Schema Constraints

Advanced Features

Multi-Page PDF Processing

Price Mode Ambiguity

Confidence Scoring

OpenRouter Annotations

Migration from Legacy

Best Practices

Limitations

Next Steps