{"openapi":"3.0.3","info":{"title":"Invoice & Receipt Math & EN 16931 Validator API","version":"1.0.0","description":"Validates extracted invoice/receipt line-item arithmetic, VAT breakdowns, EU statutory rates, IBAN/VAT checksums, and EN 16931 / Peppol e-invoicing conformance."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"InvoiceValidateResponseData":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"verdict":{"type":"string","enum":["valid","warnings_only","invalid"],"example":"valid"},"math_valid":{"type":"boolean","example":true},"en16931_conformant":{"type":"boolean","example":true},"computed_totals":{"type":"object","properties":{"subtotal_net":{"type":"number"},"total_vat":{"type":"number"},"total_gross":{"type":"number"},"vat_breakdown":{"type":"array","items":{"type":"object","properties":{"vat_rate":{"type":"number"},"taxable_net":{"type":"number"},"vat_amount":{"type":"number"},"gross_amount":{"type":"number"}},"required":["vat_rate","taxable_net","vat_amount","gross_amount"]}}},"required":["subtotal_net","total_vat","total_gross","vat_breakdown"]},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning"]},"field":{"type":"string"},"message":{"type":"string"},"expected":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"actual":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]}},"required":["code","severity","field","message"]}}},"required":["valid","verdict","math_valid","en16931_conformant","computed_totals","issues"]},"InvoiceValidateRequest":{"type":"object","properties":{"invoice":{"type":"object","properties":{"invoice_number":{"type":"string","example":"INV-2026-0042"},"issue_date":{"type":"string","example":"2026-11-14"},"due_date":{"type":"string","example":"2026-11-28"},"currency":{"type":"string","example":"EUR"},"reverse_charge":{"type":"boolean","default":false},"seller":{"type":"object","properties":{"name":{"type":"string","example":"Tinplate Kft."},"country_code":{"type":"string","maxLength":2,"example":"HU"},"vat_number":{"type":"string","example":"HU12345678"},"tax_id":{"type":"string","example":"12345678-2-41"},"iban":{"type":"string","example":"HU42117730161111101800000000"},"address":{"type":"string","example":"1051 Budapest, Bajcsy-Zsilinszky út 12."}}},"buyer":{"type":"object","properties":{"name":{"type":"string","example":"Tinplate Kft."},"country_code":{"type":"string","maxLength":2,"example":"HU"},"vat_number":{"type":"string","example":"HU12345678"},"tax_id":{"type":"string","example":"12345678-2-41"},"iban":{"type":"string","example":"HU42117730161111101800000000"},"address":{"type":"string","example":"1051 Budapest, Bajcsy-Zsilinszky út 12."}}},"line_items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":512,"example":"Edge API Pro Subscription"},"quantity":{"type":"number","minimum":0,"exclusiveMinimum":true,"example":2},"unit_price":{"type":"number","example":100},"discount":{"type":"number","minimum":0,"default":0,"example":0},"net_amount":{"type":"number","example":200},"vat_rate":{"type":"number","minimum":0,"maximum":100,"example":27},"vat_amount":{"type":"number","example":54},"gross_amount":{"type":"number","example":254}},"required":["description","quantity","unit_price","net_amount","vat_rate"]},"minItems":1,"maxItems":500},"subtotal_net":{"type":"number","example":200},"total_vat":{"type":"number","example":54},"total_gross":{"type":"number","example":254}},"required":["line_items"]},"rounding_tolerance":{"type":"number","minimum":0,"maximum":1,"default":0.02,"example":0.02,"description":"Allowed rounding difference per line or total in currency units (default 0.02)."},"check_en16931":{"type":"boolean","default":true,"example":true,"description":"Verify mandatory EN 16931 / Peppol BIS Billing 3.0 fields (BT-1..BT-115)."}},"required":["invoice"]},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/invoice-validator":{"post":{"tags":["20_INVOICE_VALIDATOR"],"summary":"Validate invoice math, VAT breakdown, IBAN/VAT IDs, and EN 16931 conformance","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceValidateRequest"}}}},"responses":{"200":{"description":"Validation verdict, reconciled totals, VAT breakdown, and issue list","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/InvoiceValidateResponseData"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}