Rule catalog
Every check yields an issue with a code, severity (error blocks upload, warning does not), the JSON path and a message. Codes follow the portal's four-digit style but are this tool's own; einvoice rules prints the list. Business rules run only after the document passes the JSON Schema (code 2001), because most rules assume well-typed fields.
Tolerances: item level arithmetic uses item_tolerance (default Rs 1), invoice level sums use invoice_tolerance (default Rs 1). Both are inclusive.
| Code | Sev | Rule | Notes |
|---|---|---|---|
| 2001 | error | JSON schema violation | One issue per violation, with the path (ItemList[0].HsnCd) |
| 2101 | error | Seller GSTIN format | ^\d{2}[A-Z]{5}\d{4}[A-Z][1-9A-Z]Z[0-9A-Z]$ |
| 2102 | error | Seller GSTIN checksum | Mod-36 check character, see design.md |
| 2103 | error | Buyer GSTIN format | URP is accepted only for EXPWP/EXPWOP |
| 2104 | error | Buyer GSTIN checksum | The message names the expected character |
| 2105 | error | Ship-to GSTIN invalid | Format and checksum |
| 2106 | error | Seller equals buyer GSTIN | |
| 2111 | error | Seller Stcd differs from GSTIN prefix |
|
| 2112 | error | Buyer Stcd differs from GSTIN prefix |
Skipped for exports |
| 2113 | error | Unknown state code | Seller, buyer, Pos, dispatch, ship-to; 96 and 97 are valid |
| 2115 | error | Place of supply missing | BuyerDtls.Pos |
| 2121 | error | IGST on intra-state supply | Intra = seller Stcd equals Pos. Allowed when TranDtls.IgstOnIntra is Y |
| 2122 | error | CGST/SGST on inter-state supply | |
| 2123 | error | Tax on SEZWOP/EXPWOP | All three taxes must be zero |
| 2124 | error | CGST/SGST on SEZ or export | These take IGST only |
| 2131 | error | HSN length | Allowed lengths 4/6/8. Minimum 4 digits up to 5 crore turnover, 6 above, 8 for exports |
| 2132 | error | HSN/SAC vs service flag | Services: 6 digits starting 99. Goods must not start with 99 |
| 2133 | error | Unit missing (goods) or not in UQC list | 46 codes, e.g. NOS, KGS, MTR |
| 2141 | error | GST rate not a slab | 0, 0.1, 0.25, 1, 1.5, 3, 5, 6, 7.5, 12, 14, 18, 28, 40 |
| 2142 | error | Tax amount vs taxable value x rate | CGST, SGST, IGST, Cess (CesRt), State Cess (StateCesRt). Not repeated when 2121-2124 already explain it |
| 2143 | error | TotAmt vs Qty x UnitPrice |
Skipped when Qty is absent |
| 2144 | error | AssAmt vs TotAmt - Discount |
|
| 2145 | error | TotItemVal vs AssAmt + all taxes + cess + non-advol cess + OthChrg |
|
| 2146 | error | SlNo not 1..n in order |
|
| 2151 | error | ValDtls.AssVal vs sum of AssAmt |
|
| 2152 | error | CgstVal, SgstVal, IgstVal, CesVal, StCesVal vs item sums |
CesVal includes non-advol cess |
| 2153 | error | TotInvVal vs sum of TotItemVal + OthChrg - Discount + RndOffAmt |
|
| 2154 | warning | Round-off beyond +-1.00 | Schema allows +-99.99 |
| 2161 | error | Document date after today | |
| 2162 | error | Older than window_days |
Exactly window_days old is accepted. 0 disables |
| 2163 | error | Not a real calendar date | e.g. 31/02/2025 |
| 2171 | error | Duplicate document | Same seller GSTIN, financial year, type and number (case-insensitive) elsewhere in the run |
| 2181 | error | Registered buyer GSTIN required | B2B, SEZ, DEXP buyers cannot be URP |
| 2183 | error | ExpDtls missing for EXPWP/EXPWOP |
|
| 2184 | error | ExpDtls.ForCur / CntCode missing |
|
| 2185 | error | Export buyer must be URP, Stcd 96, Pos 96 |
|
| 2186 | warning | ExpDtls on a non-export supply |
|
| 2187 | warning | CRN/DBN without RefDtls.PrecDocDtls |
Mandatory fields by supply type
| Supply type | Buyer GSTIN | Place of supply | Tax | ExpDtls |
|---|---|---|---|---|
| B2B, DEXP | registered | buyer state or other | CGST+SGST if intra, else IGST | not expected |
| SEZWP | registered | SEZ state | IGST | not expected |
| SEZWOP | registered | SEZ state | zero | not expected |
| EXPWP | URP |
96 | IGST | required |
| EXPWOP | URP |
96 | zero | required |
The base schema additionally requires Version, TranDtls, DocDtls, SellerDtls, BuyerDtls, ItemList, ValDtls, and per party Gstin, LglNm, Addr1, Loc, Pin, Stcd.
Planted errors in the examples
examples/invoices.csv carries 50 invoices. With -c examples/einvoice.toml and examples/resubmitted.json (a second submission of INV/2511/0028) the run reports:
| Code | Invoice |
|---|---|
| 2001 | INV 2511 0014 (spaces in the number) |
| 2103 | INV/2510/0009 |
| 2104 | INV/2511/0007 |
| 2106 | INV/2510/0010 |
| 2111 | INV/2510/0037 |
| 2112 | INV/2510/0031 |
| 2121 | INV/2510/0019 |
| 2122 | INV/2511/0021, INV/2511/0025 |
| 2123 | INV/2511/0039 (SEZWOP with IGST) |
| 2131 | INV/2511/0011 (5-digit HSN), INV/2511/0044 (6-digit HSN on an export) |
| 2132 | INV/2511/0033 |
| 2133 | INV/2511/0013 |
| 2141, 2142 | INV/2510/0023 (rate 17) |
| 2142 | INV/2511/0036 |
| 2153 | INV/2511/0027 |
| 2161 | INV/2510/0015 |
| 2162 | INV/2511/0017 |
| 2171 | INV/2511/0028 (resubmitted.json) |
| 2185 | INV/2510/0043 |
| 2186 (warning) | INV/2511/0012 |
| 2187 (warning) | CN/2511/0050 |