Read one Indian GST tax invoice (PDF or image) and return the government's INV-01 JSON payload for it, together with the evidence behind every field.

Accepts .pdf, .png, .jpg, .jpeg, .tif, .tiff and .bmp. Pages that carry a text layer are read directly; scanned pages go through OCR, which is slower (budget a few seconds per scanned page).

Returns an object with four keys: invoice the INV-01 payload, or null when none could be produced missing_fields INV-01 paths that are mandatory but could not be read refusals why the document is out of scope, when it is extraction_meta per-page read method, per-field provenance, and warnings

THREE OUTCOMES ARE NORMAL, AND ONLY THE FIRST GIVES YOU A PAYLOAD.

1. A payload plus warnings. Usable, but read the warnings: they say which fields were read at low OCR confidence, which were assigned by document position rather than by a label, and which were derived rather than printed.

2. No payload, with missing_fields populated. A mandatory field could not be read from the document. Nothing was invented to fill the gap, which is why there is no payload at all.

3. No payload, with refusals populated. Export and SEZ invoices and foreign-currency invoices are refused by design; the refusal message says what was detected, which field revealed it, and what to do instead.

The payload is submission-ready in shape, but this tool does NOT file it and does NOT return an IRN. An IRN is issued by the government's Invoice Registration Portal after you submit the payload there.

Requires a Groq API key in the environment; stage 2 uses an LLM to read the line-item table, and every value it returns is checked back against the document text before it is kept.

Check one GSTIN (the 15-character Indian GST registration number) against its structural rules and its mod-36 check character, without touching any document.

Returns is_valid, structural_ok, checksum_ok, the state code and its name, the embedded PAN, and a human-readable reason when it fails. checksum_ok is null, not false, when the structure itself failed: the checksum was never evaluated, and reporting two failures where one check ran would be misleading.

State code 25 resolves to a distinct 'discontinued' status rather than 'unknown', because a 25 means either a misread or a genuine pre-2020 record, and the caller needs to tell those apart. State code 28 is legacy-but-valid: pre-2014 Andhra Pradesh registrations remain legitimate.

IMPORTANT: a passing checksum proves the number is well-formed, NOT that the registration exists or is currently active. Only the GST portal can tell you that.

Take an INV-01 payload you already have and run the same consistency checks the parser runs, without re-reading any document. Useful for a payload you assembled yourself, or one you edited after parsing.

Four checks run: each item's total against its own components; the invoice total against the value block; each value-block total against the sum of the item fields; and the CGST/SGST-versus-IGST split against the two parties' state codes.

Comparisons use a rupee tolerance (0.05 by default), never exact equality, because real invoices round to the nearest rupee and exact comparison would flag almost every genuine document.

Returns valid (true when nothing was flagged), the warning list with the exact field path for each, and schema_error when the payload does not fit INV-01 at all. The tax-split check reports itself as skipped, as an informational note rather than a warning, under reverse charge and when the place of supply differs from the buyer's registered state, because it cannot evaluate those cases.