{"openapi":"3.0.3","info":{"title":"Peppol UBL 2.1 / XRechnung E-Invoice Converter & EPC-QR API","version":"1.0.0","description":"Converts between structured JSON invoices and Peppol BIS Billing 3.0 / EN 16931 UBL 2.1 XML, validates EU tax & line-item math, and generates EPC069-12 SEPA Credit Transfer QR payloads (GiroCode)."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"PeppolUblInvoiceResponseData":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"verdict":{"type":"string","enum":["valid","warnings_only","invalid"],"example":"valid"},"mode":{"type":"string","enum":["json_to_ubl","ubl_to_json"],"example":"json_to_ubl"},"en16931_conformant":{"type":"boolean","example":true},"math_valid":{"type":"boolean","example":true},"customization_id":{"type":"string","example":"urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0"},"profile_id":{"type":"string","example":"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"},"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"]},"ubl_xml":{"type":"string","description":"Generated or normalized Peppol BIS Billing 3.0 UBL 2.1 XML document."},"epc_qr_payload":{"type":"string","nullable":true,"example":"BCD\n002\n1\nSCT\nCOBADEFFXXX\nTinplate GmbH\nDE89370400440532013000\nEUR238.00\n\n\nINV-2026-0042","description":"EPC069-12 SEPA Credit Transfer QR payload (GiroCode) for EUR invoices with a valid seller IBAN."},"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","mode","en16931_conformant","math_valid","customization_id","profile_id","invoice","ubl_xml","epc_qr_payload","issues"]},"PeppolUblInvoiceRequest":{"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"],"description":"Structured invoice object to validate against EN 16931, convert to Peppol BIS Billing 3.0 UBL 2.1 XML, and generate a SEPA EPC-QR payment payload."},"ubl_xml":{"type":"string","minLength":20,"maxLength":262144,"description":"Optional raw UBL 2.1 / Peppol BIS Billing 3.0 / XRechnung <Invoice> XML string to parse into JSON and validate."},"seller_bic":{"type":"string","maxLength":11,"example":"COBADEFFXXX","description":"Optional seller BIC/SWIFT code for EPC SEPA QR generation."},"buyer_reference":{"type":"string","maxLength":128,"default":"BUYER-REF-01","example":"LEITWEG-991-12345-67","description":"Peppol BT-10 BuyerReference / German XRechnung Leitweg-ID."}}},"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/peppol-ubl-invoice":{"post":{"tags":["39_PEPPOL_UBL_INVOICE"],"summary":"Convert between JSON invoices and Peppol BIS Billing 3.0 UBL 2.1 / XRechnung XML, validate EN 16931 compliance, and generate SEPA EPC-QR payment codes","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeppolUblInvoiceRequest"}}}},"responses":{"200":{"description":"Validated Peppol UBL 2.1 XML, structured JSON invoice, and EPC SEPA QR payload","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PeppolUblInvoiceResponseData"},"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"}}}}}}}}}