{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "EU E-Invoice API", "version": "1.0.0", "summary": "Validate, parse and generate EU e-invoices – XRechnung, ZUGFeRD / Factur-X, Peppol BIS, France, Romania, Croatia, Italy and Polish KSeF FA(3).", "description": "Stateless REST API for German XRechnung (UBL and CII), ZUGFeRD 2.x / Factur-X hybrid PDFs (all profiles from\nMINIMUM to EXTENDED and XRECHNUNG), Peppol BIS Billing 3.0 (UBL) and the Polish KSeF structure FA(3).\n\n* **Validation** uses the official KoSIT validator with the current XRechnung configuration, the FeRD\n ZUGFeRD/Factur-X rules, the OpenPeppol BIS Billing 3.0 rules, the French rules of FNFE-MPE, the Romanian CIUS-RO\n rules, the Croatian HR-CIUS rules of the Tax Administration, the official FA(3) XML schema of the Polish\n Ministry of Finance (schema check only), the FatturaPA XML schema and veraPDF for PDF/A-3. The rule-set versions in use are listed by\n `GET /v1/formats` and reported with every result.\n* **France:** for invoices of sellers in France (BT-40 = FR) in EN 16931 UBL/CII or Factur-X BASIC WL, EN 16931\n and EXTENDED, the French rules BR-FR (FNFE-MPE France_RFE, FATAL variant) run in addition to the document's own\n rules; EXTENDED-CTC-FR is validated as a profile of its own (format `fr-ctc`). Factur-X MINIMUM and BASIC from a\n French seller get the warning `PROFILE-NOT-FR`. XRechnung and Peppol BIS documents are not affected.\n* **Romania:** CIUS-RO 1.0.1 (RO e-Factura) is validated with the official rules (validation artefacts 1.0.9) and\n generated as UBL (`cius-ro-ubl`). Romania publishes these rules for UBL only; CII with the CIUS-RO identifier is\n checked against EN 16931 and gets the info finding `CIUS-RO-CII`.\n* **Croatia:** the eRačun (HR-CIUS 2025 with the HR extension, Fiscalization 2.0) is validated with the Tax\n Administration's XML Schema and rules (HR-BR-*, version of 13 Mar 2026), parsed (issue time and operator in\n `issueTime` and `seller.operator`) and generated as UBL (`hr-cius-ubl`). HR-CIUS exists for UBL only: CII with the\n Croatian identifier is an error (`HR-SYNTAX-NOT-UBL`). An invoice between two Croatian parties without the HR\n identifier gets the warning `PROFILE-NOT-HR`. Fiscalization and delivery through an information intermediary are\n not performed (info `HR-NOT-PERFORMED`).\n* **Slovakia** (domestic B2B e-invoicing from 1 Jan 2027) uses plain Peppol BIS Billing 3.0 with electronic\n addresses in scheme 0245 (DIČ). For sellers in Slovakia three advisory warnings of this API are added\n (`SK-ENDPOINT-SELLER`, `SK-ENDPOINT-BUYER`, `SK-BT8`); they are not official rules and never change `valid`.\n* **Italy:** FatturaPA 1.2.3 (FPR12 for businesses, FPA12 for the public sector; syntax `FATTURAPA`) is validated\n against the official XML Schema and the SDI content controls that can be checked offline (findings\n `SDI-00xxx`, our implementation of Allegato A 1.9.1; registry, duplicate, signature and file-name controls are\n not performed, see the `SDI-NOT-PERFORMED` info). FatturaPA is not EN 16931: `/v1/parse` maps what the\n normalized model can carry and reports the rest as `PARSE-UNMAPPED`; of a batch file it returns the first\n invoice (`PARSE-BATCH`). `/v1/generate?format=fatturapa-fpr12|fatturapa-fpa12` writes an unsigned FatturaPA\n (ordinary regime RF01) and rejects input FatturaPA cannot carry, such as withholding tax; public-sector invoices\n (FPA12) must be signed by the issuer before sending (warning `FPA12-UNSIGNED`). The suggested file name follows\n the SDI convention `IT_.xml`.\n* **KSeF FA(3)** is not EN 16931: `/v1/parse` maps what the normalized model can carry and reports the rest as\n `PARSE-UNMAPPED`; `/v1/generate?format=ksef-fa3` writes VAT invoices of a Polish seller (typeCode 380 or 389)\n and rejects input FA(3) cannot carry.\n* **Privacy:** documents are processed in memory only. Invoice content is never written to disk or logs.\n* **Hosting:** validation runs on servers in Germany; the API gateway (Zuplo) forwards requests and may process\n them outside the EU.\n* **Size and time:** documents up to 10 MB (the plan may allow less). A typical invoice is processed in well\n under 0.1 s at the service; a 5 MB UBL invoice with about 7,000 lines takes about 5 s. Processing stops after\n 15 s with HTTP 504. Reuse HTTP connections (keep-alive) when you send many documents: a new TLS handshake costs\n 100–150 ms per call, more than the validation itself.\n\n**Authentication.** Send the API key from your subscription in the developer portal as `Authorization: Bearer `. Plans, quotas and usage are shown in the portal.\n\n**Errors** are RFC 9457 `application/problem+json` objects. `detail` says what to fix and `requestId` identifies\nthe call. A document that can be read but is invalid is **not** an HTTP error: `/v1/validate` and\n`/v1/parse` answer 200 with `valid: false` and the findings. 401 (API key), 403 (plan feature or monthly quota)\nand 429 (rate limit) are answered by the API gateway (Zuplo) before the request reaches the service; these\nresponses may differ in shape (for example without `requestId`).\n\n**Notation.** `xpath` values use the prefixes `rsm`, `ram`, `udt`, `qdt` (CII), `ubl`, `cn`, `cac`, `cbc`,\n`ext` (UBL), `fa` (KSeF FA(3)), `p` (the FatturaPA root element; FatturaPA child elements have no namespace and\nno prefix) and `ds` (XML Signature).\n", "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "servers": [ { "url": "https://einvoice-api-main-f5141d8.zuplo.app", "description": "API gateway (developer portal keys)" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Documents", "description": "Validate, parse and generate e-invoices." }, { "name": "Service", "description": "Health and the configured rule sets." } ], "paths": { "/v1/validate": { "post": { "tags": [ "Documents" ], "operationId": "validateInvoice", "summary": "Validate an e-invoice (XRechnung, EN 16931, ZUGFeRD / Factur-X, French rules, Peppol BIS, CIUS-RO, KSeF, FatturaPA)", "description": "The format is detected from the content: CII or UBL XML, KSeF FA(3) or FatturaPA XML, or a PDF with an embedded\n`factur-x.xml`. For a seller in France the French rules (BR-FR) run in addition. For PDFs,\nPDF/A-3 conformance (veraPDF), the attachment and the Factur-X XMP metadata are checked as well. Send the\ndocument as the raw body or as multipart with a part named `file`.\n", "parameters": [ { "$ref": "#/components/parameters/ruleset" } ], "requestBody": { "$ref": "#/components/requestBodies/Document" }, "responses": { "200": { "description": "Validation result (also for invalid documents).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" }, "examples": { "valid": { "$ref": "#/components/examples/ValidationValid" }, "invalid": { "$ref": "#/components/examples/ValidationInvalid" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "411": { "$ref": "#/components/responses/LengthRequired" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnrecognizedDocument" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Overloaded" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/v1/preview/validate": { "post": { "tags": [ "Documents" ], "operationId": "validatePreview", "summary": "Validate against the upcoming rule sets before they become mandatory (paid plans)", "description": "Like `/v1/validate`, but where the rule-set owner (KoSIT, FeRD) has published an upcoming release that is not\nin force yet, the document is validated against that release instead. Use it to find out early whether your\ninvoices will still pass. Rule sets used this way are marked `preview: true` in `rulesets`, with the date from\nwhich they become mandatory (`effectiveFrom`) when it is known. Documents that no upcoming release covers are\nvalidated against the rules in force and get an `info` finding `PREVIEW-NONE`; this is also the case while no\nupcoming release has been published (`GET /v1/formats` lists them with `status: preview`).\n`ruleset` pins may name preview and current versions. The verdict of `/v1/validate` is never affected.\n", "parameters": [ { "$ref": "#/components/parameters/ruleset" } ], "requestBody": { "$ref": "#/components/requestBodies/Document" }, "responses": { "200": { "description": "Validation result against the upcoming rule sets (also for invalid documents).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" }, "examples": { "preview": { "$ref": "#/components/examples/ValidationPreview" }, "noPreviewPublished": { "$ref": "#/components/examples/ValidationPreviewNone" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "411": { "$ref": "#/components/responses/LengthRequired" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnrecognizedDocument" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Overloaded" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/v1/parse": { "post": { "tags": [ "Documents" ], "operationId": "parseInvoice", "summary": "Parse an invoice into normalized JSON, with validation and recomputed totals", "description": "Validates like `/v1/validate` and returns the invoice in the normalized EN 16931 model\n([schema](https://api.einvoice-api.eu/schemas/normalized-invoice/v1)) plus `calculation`. Totals are recomputed\nserver-side: differences in BT-106…BT-115 and the VAT breakdown are listed exactly; line net amounts and VAT\namounts per category are additionally checked with a tolerance of 0.01 (`CALC-*` warnings). Content outside\nEN 16931 (for example ZUGFeRD EXTENDED) is not mapped and listed in a `PARSE-UNMAPPED` finding.\n", "parameters": [ { "$ref": "#/components/parameters/ruleset" } ], "requestBody": { "$ref": "#/components/requestBodies/Document" }, "responses": { "200": { "description": "Parse result. `invoice` is absent if the document cannot be read (CII, UBL, KSeF FA(3) and FatturaPA documents are read).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResponse" }, "examples": { "parsed": { "$ref": "#/components/examples/Parsed" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "406": { "$ref": "#/components/responses/NotAcceptable" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "411": { "$ref": "#/components/responses/LengthRequired" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnrecognizedDocument" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Overloaded" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/v1/generate": { "post": { "tags": [ "Documents" ], "operationId": "generateInvoice", "summary": "Generate XRechnung, EN 16931, ZUGFeRD / Factur-X, CIUS-RO, Peppol BIS, KSeF FA(3) or FatturaPA from normalized JSON", "description": "Input is the normalized invoice (the same schema `/v1/parse` returns). BT-24 is set from `format`; BT-23\n(`context.businessProcessType`) is taken from the input when given. `en16931-cii` and `en16931-ubl` write plain\nEN 16931 (BT-24 `urn:cen.eu:en16931:2017`), e.g. for France, where BT-23 must be a billing framework code such\nas `S1` and the French rules apply to sellers in France. `hr-cius-ubl` writes the Croatian eRačun: BT-23 must be\n`P1`-`P12` or `P99:...`, and `issueTime` and `seller.operator` (name and OIB) are required by the Croatian rules;\nVAT categories S (25, 13, 5 %), Z, E, AE, K, G and O are supported. Every generated document is validated before it is\nreturned; if it is not valid, the response is 422 with the\nfindings and no document. For PDF formats a neutral layout is rendered, or send multipart with your own\nPDF/A-1, -2 or -3 in the part `pdf` and the XML is embedded into it.\n", "parameters": [ { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "xrechnung-cii", "xrechnung-ubl", "zugferd-en16931", "facturx-basic", "en16931-cii", "en16931-ubl", "cius-ro-ubl", "hr-cius-ubl", "peppol-bis", "ksef-fa3", "fatturapa-fpr12", "fatturapa-fpa12" ] }, "example": "xrechnung-ubl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormalizedInvoice" }, "examples": { "xrechnung": { "summary": "Synthetic XRechnung invoice (samples/invoice.json)", "value": { "invoiceNumber": "RE-2026-0042", "issueDate": "2026-10-18", "typeCode": "380", "currency": "EUR", "dueDate": "2026-11-17", "buyerReference": "04011000-12345-34", "purchaseOrderReference": "BEST-2026-117", "notes": [ { "subjectCode": "AAI", "text": "Vielen Dank für Ihren Auftrag." } ], "seller": { "name": "Muster Software GmbH", "vatId": "DE123456789", "electronicAddress": { "value": "rechnung@muster-software.example", "schemeId": "EM" }, "address": { "line1": "Hauptstraße 1", "city": "Berlin", "postCode": "10115", "countryCode": "DE" }, "contact": { "name": "Erika Beispiel", "phone": "+49 30 1234567", "email": "buchhaltung@muster-software.example" } }, "buyer": { "name": "Beispielamt der Stadt Musterstadt", "electronicAddress": { "value": "04011000-12345-34", "schemeId": "0204" }, "address": { "line1": "Rathausplatz 5", "city": "Musterstadt", "postCode": "12345", "countryCode": "DE" } }, "delivery": { "actualDeliveryDate": "2026-10-15" }, "payment": { "meansCode": "58", "creditTransfers": [ { "accountId": "DE02120300000000202051", "accountName": "Muster Software GmbH" } ], "terms": "Zahlbar innerhalb von 30 Tagen ohne Abzug." }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "HUR", "netAmount": "1000.00", "price": { "netPrice": "100.00" }, "vat": { "categoryCode": "S", "rate": "19" }, "item": { "name": "Beratungsleistung", "description": "Anforderungsanalyse E-Rechnung, Oktober 2026" } }, { "id": "2", "quantity": "1", "unitCode": "C62", "netAmount": "250.00", "price": { "netPrice": "250.00" }, "vat": { "categoryCode": "S", "rate": "19" }, "item": { "name": "Softwarelizenz Jahresabonnement", "sellerItemId": "LIC-STD-12" } } ], "vatBreakdown": [ { "taxableAmount": "1250.00", "taxAmount": "237.50", "categoryCode": "S", "rate": "19" } ], "totals": { "lineNetTotal": "1250.00", "taxExclusiveAmount": "1250.00", "vatTotal": "237.50", "taxInclusiveAmount": "1487.50", "amountDue": "1487.50" } } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "invoice" ], "properties": { "invoice": { "$ref": "#/components/schemas/NormalizedInvoice" }, "pdf": { "type": "string", "contentMediaType": "application/pdf", "description": "Optional PDF/A-1, -2 or -3 used as the visual part (PDF formats only)." } } }, "encoding": { "invoice": { "contentType": "application/json" }, "pdf": { "contentType": "application/pdf" } } } } }, "responses": { "200": { "description": "The generated, validated document.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "example": "attachment; filename=\"RE-2026-0042-xrechnung-ubl.xml\"" }, "X-Validation-Warnings": { "description": "Number of non-blocking findings of the generated document.", "schema": { "type": "integer", "minimum": 0 } }, "X-Rulesets": { "description": "Rule packs that validated the document.", "schema": { "type": "string" }, "example": "xrechnung@3.0.2" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/xml": { "schema": { "type": "string" } }, "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } } } }, "400": { "description": "Invalid format parameter, invalid JSON, schema violation, or input the format cannot carry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "schemaViolation": { "$ref": "#/components/examples/SchemaViolation" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "411": { "$ref": "#/components/responses/LengthRequired" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "description": "The generated document is not valid (`generated-invoice-invalid`, with findings) or the supplied PDF is not a usable PDF/A (`unusable-pdf`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid": { "$ref": "#/components/examples/GeneratedInvalid" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/Overloaded" }, "504": { "$ref": "#/components/responses/Timeout" } } } }, "/v1/formats": { "get": { "tags": [ "Service" ], "operationId": "listFormats", "summary": "Supported formats, profiles and rule-set versions", "responses": { "200": { "description": "Configured rule packs and the documents (specification identifiers) each validates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Formats" }, "examples": { "formats": { "$ref": "#/components/examples/Formats" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "description": "Supported formats, profiles and rule-set versions." } }, "/v1/health": { "get": { "tags": [ "Service" ], "operationId": "health", "summary": "Liveness, warm-up result, release and loaded rule sets", "security": [], "responses": { "200": { "description": "The service is up and all rule packs are compiled. `status` is `DEGRADED` (still HTTP 200) if the self-test at start (generating, validating and parsing a shipped sample invoice) had failed steps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "examples": { "up": { "$ref": "#/components/examples/Health" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "description": "Liveness, warm-up result, release and loaded rule sets." } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key of your subscription (developer portal)." } }, "parameters": { "ruleset": { "name": "ruleset", "in": "query", "required": false, "description": "Pin a rule-set version instead of the default, as `@` (see `GET /v1/formats`). Repeat the parameter or separate values with commas. Preview versions (status preview) can only be pinned on `/v1/preview/validate`; elsewhere they give 400 `preview-ruleset`.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9-]+@.+$" } }, "style": "form", "explode": true, "example": [ "xrechnung@3.0.2" ] } }, "headers": { "X-Request-Id": { "description": "Request id (the gateway's request id when called through the gateway). It identifies the call.", "schema": { "type": "string" } } }, "requestBodies": { "Document": { "required": true, "description": "The invoice, max. 10 MB (a 5 MB invoice takes about 5 s). The format is detected from the content, not from the media type.", "content": { "application/xml": { "schema": { "type": "string" } }, "text/xml": { "schema": { "type": "string" } }, "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } }, "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream" } } } } } } }, "responses": { "BadRequest": { "description": "Malformed request (empty or incomplete body, missing multipart part, unknown rule-set version, …).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unknownRuleset": { "$ref": "#/components/examples/UnknownRuleset" }, "previewRuleset": { "$ref": "#/components/examples/PreviewRuleset" } } } } }, "Unauthorized": { "description": "Missing or invalid API key. Answered by the API gateway (Zuplo); the shape may differ from the service's problems (for example without `requestId`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "The plan does not include this endpoint (e.g. `/v1/preview/validate` on the Free plan) or the monthly document quota is used up. Answered by the API gateway (Zuplo); the shape may differ from the service's problems.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotAcceptable": { "description": "The Accept header excludes application/json.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RequestTimeout": { "description": "The request body did not arrive completely within 60 seconds (`body-timeout`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "LengthRequired": { "description": "The request has no Content-Length header (chunked uploads are not accepted by the gateway).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Rate limit of the plan exceeded; retry after the number of seconds in `Retry-After`. Answered by the API gateway (Zuplo); the shape may differ from the service's problems.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InternalError": { "description": "Unexpected error in the service (`internal-error`). Retry once; `requestId` identifies the call.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PayloadTooLarge": { "description": "Request body above 10 MB or above the plan's file size.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UnsupportedMediaType": { "description": "Content-Type not accepted by this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "json": { "$ref": "#/components/examples/UnsupportedMediaType" } } } } }, "UnrecognizedDocument": { "description": "The payload is neither a PDF nor a CII / UBL, KSeF FA(3) or FatturaPA XML document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Overloaded": { "description": "All workers busy; retry after the number of seconds in `Retry-After`.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Timeout": { "description": "Processing took longer than 15 seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Severity": { "type": "string", "enum": [ "fatal", "error", "warning", "info" ], "description": "`fatal` and `error` make a document invalid." }, "Finding": { "type": "object", "additionalProperties": false, "required": [ "severity", "ruleId", "message" ], "properties": { "severity": { "$ref": "#/components/schemas/Severity" }, "ruleId": { "type": "string", "description": "Rule id of the rule set (e.g. BR-CO-15, BR-DE-15) or of this service (e.g. PDFA-6.2.4.3-2, XMP-CONFORMANCE-LEVEL, CALC-LINE-NET)." }, "message": { "type": "string", "description": "Official rule text, or this service's explanation of what to fix." }, "xpath": { "type": "string", "description": "Location in the invoice XML (prefix notation)." }, "source": { "type": "string", "description": "Layer that raised it: xsd:, schematron:, kosit: (the KoSIT validator itself, e.g. no matching scenario), pdfa:veraPDF, pdf, xmp, xml, profile, calc, parse, preview (/v1/preview/validate)." }, "docUrl": { "type": "string", "format": "uri", "description": "Public page of the rule on einvoice-api.eu with the official text, severity per rule set and the Schematron test (e.g. https://einvoice-api.eu/rules/br-de-15.html). Present for Schematron rules of the rule sets in force; absent for XML Schema, PDF/A, XMP, profile and calculation findings and for preview rule sets.", "examples": [ "https://einvoice-api.eu/rules/br-de-15.html" ] } } }, "RulesetRef": { "type": "object", "additionalProperties": false, "required": [ "id", "version" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "release": { "type": "string" }, "preview": { "type": "boolean", "description": "Present (true) only for an upcoming rule set used by `/v1/preview/validate`." }, "effectiveFrom": { "type": "string", "format": "date", "description": "Date from which the rule set is mandatory, if known." } } }, "Summary": { "type": "object", "additionalProperties": false, "required": [ "fatal", "error", "warning", "info" ], "properties": { "fatal": { "type": "integer", "minimum": 0 }, "error": { "type": "integer", "minimum": 0 }, "warning": { "type": "integer", "minimum": 0 }, "info": { "type": "integer", "minimum": 0 } } }, "ValidationResponse": { "type": "object", "additionalProperties": false, "required": [ "requestId", "valid", "summary", "findings" ], "properties": { "requestId": { "type": "string" }, "valid": { "type": "boolean" }, "format": { "type": "string", "enum": [ "xrechnung", "en16931", "zugferd", "peppol-bis", "ksef", "fr-ctc", "cius-ro", "hr-cius", "fatturapa" ] }, "container": { "type": "string", "enum": [ "XML", "PDF" ] }, "syntax": { "type": "string", "enum": [ "CII", "UBL", "KSEF", "FATTURAPA" ] }, "profile": { "type": "string", "examples": [ "XRECHNUNG", "EN16931", "MINIMUM", "BASIC-WL", "BASIC", "EXTENDED", "PEPPOL-BIS-3", "FA3", "EXTENDED-CTC-FR", "CIUS-RO", "FPR12", "FPA12" ] }, "guidelineId": { "type": "string", "description": "Specification identifier (BT-24) found in the document; for KSeF the form code (KodFormularza/@kodSystemowy, e.g. FA (3)); for FatturaPA the versione attribute (FPR12, FPA12)." }, "attachmentName": { "type": "string", "description": "Name of the embedded invoice XML (PDFs only)." }, "rulesets": { "type": "array", "items": { "$ref": "#/components/schemas/RulesetRef" } }, "summary": { "$ref": "#/components/schemas/Summary" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } } } }, "Difference": { "type": "object", "additionalProperties": false, "required": [ "field", "rule" ], "properties": { "field": { "type": "string", "examples": [ "BT-106" ] }, "rule": { "type": "string", "examples": [ "BR-CO-10", "CALC-LINE-NET" ] }, "lineId": { "type": "string" }, "category": { "type": "string", "examples": [ "S 19" ] }, "declared": { "type": "string" }, "computed": { "type": "string" } } }, "Calculation": { "type": "object", "additionalProperties": false, "required": [ "consistent", "differences" ], "properties": { "consistent": { "type": "boolean" }, "differences": { "type": "array", "items": { "$ref": "#/components/schemas/Difference" } } } }, "ParseResponse": { "type": "object", "additionalProperties": false, "required": [ "requestId", "valid", "summary", "findings" ], "properties": { "requestId": { "type": "string" }, "valid": { "type": "boolean" }, "format": { "type": "string", "enum": [ "xrechnung", "en16931", "zugferd", "peppol-bis", "ksef", "fr-ctc", "cius-ro", "hr-cius", "fatturapa" ] }, "container": { "type": "string", "enum": [ "XML", "PDF" ] }, "syntax": { "type": "string", "enum": [ "CII", "UBL", "KSEF", "FATTURAPA" ] }, "profile": { "type": "string" }, "guidelineId": { "type": "string" }, "attachmentName": { "type": "string" }, "rulesets": { "type": "array", "items": { "$ref": "#/components/schemas/RulesetRef" } }, "summary": { "$ref": "#/components/schemas/Summary" }, "invoice": { "$ref": "#/components/schemas/NormalizedInvoice" }, "calculation": { "$ref": "#/components/schemas/Calculation" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } } } }, "Problem": { "type": "object", "description": "RFC 9457 problem details, plus `requestId` and type-specific members.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "available": { "type": "array", "items": { "type": "string" }, "description": "unknown-ruleset, preview-ruleset - rule-set versions that can be pinned on this endpoint." }, "formats": { "type": "array", "items": { "type": "string" }, "description": "invalid-format - accepted values." }, "errors": { "type": "array", "description": "schema-violation / invalid-for-format - one entry per offending value.", "items": { "type": "object", "required": [ "pointer", "message" ], "properties": { "pointer": { "type": "string", "description": "JSON Pointer into the request body." }, "message": { "type": "string" } } } }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "description": "generated-invoice-invalid - findings of the generated document." }, "rulesets": { "type": "array", "items": { "$ref": "#/components/schemas/RulesetRef" } }, "maxBytes": { "type": "integer" }, "retryAfterSeconds": { "type": "integer", "description": "overloaded - seconds to wait before retrying." }, "timeoutSeconds": { "type": "integer", "description": "processing-timeout", "body-timeout - the limit that was exceeded.": null } } }, "Health": { "type": "object", "additionalProperties": false, "required": [ "status", "version", "release", "rulesets" ], "properties": { "status": { "type": "string", "enum": [ "UP", "DEGRADED" ], "description": "`DEGRADED`: the self-test at start had failed steps; the service still answers." }, "version": { "type": "string" }, "release": { "type": "string", "description": "Build the service runs (a short commit id", "or `unknown`).": null }, "rulesets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "default" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "release": { "type": "string" }, "default": { "type": "boolean" }, "preview": { "type": "boolean", "description": "Present (true) only for upcoming rule sets." } } } } } }, "Formats": { "type": "object", "additionalProperties": false, "required": [ "rulesets" ], "properties": { "rulesets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "default", "status", "pin", "documents" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "release": { "type": "string" }, "default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "current", "preview" ], "description": "`current`: in force. `preview`: upcoming, used only by `/v1/preview/validate`." }, "effectiveFrom": { "type": "string", "format": "date", "description": "Date from which the version is mandatory, if known." }, "pin": { "type": "string", "description": "Value for the ruleset query parameter (preview versions only on /v1/preview/validate)." }, "description": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "guidelineId", "profile", "format", "syntaxes", "containers", "en16931Invoice" ], "properties": { "guidelineId": { "type": "string" }, "profile": { "type": "string" }, "format": { "type": "string" }, "syntaxes": { "type": "array", "items": { "type": "string", "enum": [ "CII", "UBL", "KSEF", "FATTURAPA" ] } }, "containers": { "type": "array", "items": { "type": "string", "enum": [ "XML", "PDF" ] } }, "en16931Invoice": { "type": "boolean" }, "appliesWhen": { "type": "object", "additionalProperties": false, "description": "Present for national rules that run in addition to the document's own rules when the condition holds, e.g. the French rules (BR-FR) for invoices of sellers in France. All given fields must hold.", "properties": { "sellerCountry": { "type": "string", "description": "Seller country code (BT-40)", "ISO 3166-1 alpha-2.": null }, "buyerCountry": { "type": "string", "description": "Buyer country code (BT-55)", "ISO 3166-1 alpha-2.": null } } } } } } } } } } }, "InvoiceDate": { "type": "string", "format": "date", "examples": [ "2026-10-18" ] }, "InvoiceCurrencyCode": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217.", "examples": [ "EUR" ] }, "InvoiceCountryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2.", "examples": [ "DE" ] }, "InvoiceVatCategoryCode": { "type": "string", "description": "UNTDID 5305 subset: S, Z, E, AE, K, G, O, L, M.", "examples": [ "S" ] }, "InvoiceAmount": { "type": "string", "pattern": "^-?[0-9]{1,17}(\\.[0-9]{1,2})?$", "description": "Monetary amount as a decimal string, at most 2 fraction digits (EN 16931). Parse output of national formats (KSeF FA(3), FatturaPA) may carry more decimals than generation accepts.", "examples": [ "1190.00" ] }, "InvoiceUnitPrice": { "type": "string", "pattern": "^[0-9]{1,17}(\\.[0-9]{1,20})?$", "description": "Unit price as a decimal string; non-negative. EN 16931 does not limit the fraction digits (up to 20 accepted).", "examples": [ "12.3456" ] }, "InvoiceQuantity": { "type": "string", "pattern": "^-?[0-9]{1,17}(\\.[0-9]{1,20})?$", "description": "Quantity as a decimal string. EN 16931 does not limit the fraction digits (up to 20 accepted).", "examples": [ "3", "1.5" ] }, "InvoicePercentage": { "type": "string", "pattern": "^[0-9]{1,3}(\\.[0-9]{1,4})?$", "description": "Percentage as a decimal string, e.g. \"19\" or \"7.00\".", "examples": [ "19.00" ] }, "InvoiceIdentifier": { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "string", "minLength": 1 }, "schemeId": { "type": "string", "description": "Scheme identifier (ISO 6523 ICD for party IDs, EAS for electronic addresses)." } } }, "InvoiceAddress": { "type": "object", "additionalProperties": false, "required": [ "countryCode" ], "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "line3": { "type": "string" }, "city": { "type": "string" }, "postCode": { "type": "string" }, "countrySubdivision": { "type": "string" }, "countryCode": { "$ref": "#/components/schemas/InvoiceCountryCode" } }, "x-bt-map": { "seller": [ "BT-35", "BT-36", "BT-162", "BT-37", "BT-38", "BT-39", "BT-40" ], "buyer": [ "BT-50", "BT-51", "BT-163", "BT-52", "BT-53", "BT-54", "BT-55" ], "sellerTaxRepresentative": [ "BT-64", "BT-65", "BT-164", "BT-66", "BT-67", "BT-68", "BT-69" ], "delivery": [ "BT-75", "BT-76", "BT-165", "BT-77", "BT-78", "BT-79", "BT-80" ] } }, "InvoiceContact": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } }, "x-bt-map": { "seller": [ "BT-41", "BT-42", "BT-43" ], "buyer": [ "BT-56", "BT-57", "BT-58" ] } }, "InvoicePeriod": { "type": "object", "additionalProperties": false, "properties": { "start": { "$ref": "#/components/schemas/InvoiceDate" }, "end": { "$ref": "#/components/schemas/InvoiceDate" } } }, "InvoiceSeller": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "x-bt": "BT-27" }, "tradingName": { "type": "string", "x-bt": "BT-28" }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceIdentifier" }, "x-bt": "BT-29" }, "legalRegistrationId": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-30" }, "vatId": { "type": "string", "examples": [ "DE123456789" ], "x-bt": "BT-31" }, "taxRegistrationId": { "type": "string", "description": "Local tax number (German Steuernummer).", "x-bt": "BT-32" }, "additionalLegalInfo": { "type": "string", "x-bt": "BT-33" }, "electronicAddress": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-34" }, "address": { "$ref": "#/components/schemas/InvoiceAddress", "x-bt": "BG-5" }, "contact": { "$ref": "#/components/schemas/InvoiceContact", "x-bt": "BG-6" }, "operator": { "$ref": "#/components/schemas/InvoiceOperator" } } }, "InvoiceOperator": { "type": "object", "additionalProperties": false, "description": "The person who issued the invoice for the seller. Not an EN 16931 term: UBL cac:AccountingSupplierParty/cac:SellerContact, read and written only by the national formats that require it (Croatia: operator label HR-BT-4 and operator OIB HR-BT-5, both mandatory in hr-cius). Not the seller contact (BG-6).", "properties": { "name": { "type": "string", "description": "Operator label or name (Croatia HR-BT-4)." }, "id": { "type": "string", "description": "Operator identifier (Croatia: the operator's OIB, HR-BT-5)." } } }, "InvoiceBuyer": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "x-bt": "BT-44" }, "tradingName": { "type": "string", "x-bt": "BT-45" }, "identifier": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-46" }, "legalRegistrationId": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-47" }, "vatId": { "type": "string", "x-bt": "BT-48" }, "electronicAddress": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-49" }, "address": { "$ref": "#/components/schemas/InvoiceAddress", "x-bt": "BG-8" }, "contact": { "$ref": "#/components/schemas/InvoiceContact", "x-bt": "BG-9" } } }, "InvoiceDocumentAllowanceCharge": { "type": "object", "additionalProperties": false, "required": [ "amount", "vatCategoryCode" ], "properties": { "amount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": [ "BT-92", "BT-99" ] }, "baseAmount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": [ "BT-93", "BT-100" ] }, "percentage": { "$ref": "#/components/schemas/InvoicePercentage", "x-bt": [ "BT-94", "BT-101" ] }, "vatCategoryCode": { "$ref": "#/components/schemas/InvoiceVatCategoryCode", "x-bt": [ "BT-95", "BT-102" ] }, "vatRate": { "$ref": "#/components/schemas/InvoicePercentage", "x-bt": [ "BT-96", "BT-103" ] }, "reason": { "type": "string", "x-bt": [ "BT-97", "BT-104" ] }, "reasonCode": { "type": "string", "description": "UNTDID 5189 (allowances) or 7161 (charges).", "x-bt": [ "BT-98", "BT-105" ] } } }, "InvoiceLineAllowanceCharge": { "type": "object", "additionalProperties": false, "required": [ "amount" ], "properties": { "amount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": [ "BT-136", "BT-141" ] }, "baseAmount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": [ "BT-137", "BT-142" ] }, "percentage": { "$ref": "#/components/schemas/InvoicePercentage", "x-bt": [ "BT-138", "BT-143" ] }, "reason": { "type": "string", "x-bt": [ "BT-139", "BT-144" ] }, "reasonCode": { "type": "string", "x-bt": [ "BT-140", "BT-145" ] } } }, "InvoiceInvoiceLine": { "type": "object", "additionalProperties": false, "required": [ "id", "quantity", "unitCode", "netAmount", "price", "vat", "item" ], "properties": { "id": { "type": "string", "minLength": 1, "x-bt": "BT-126" }, "note": { "type": "string", "x-bt": "BT-127" }, "objectIdentifier": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-128" }, "quantity": { "$ref": "#/components/schemas/InvoiceQuantity", "x-bt": "BT-129" }, "unitCode": { "type": "string", "description": "UN/ECE Recommendation 20/21 unit code, e.g. C62 (piece), HUR (hour), KGM.", "examples": [ "C62" ], "x-bt": "BT-130" }, "netAmount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-131" }, "orderLineReference": { "type": "string", "x-bt": "BT-132" }, "buyerAccountingReference": { "type": "string", "x-bt": "BT-133" }, "period": { "$ref": "#/components/schemas/InvoicePeriod", "x-bt": "BG-26" }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineAllowanceCharge" }, "x-bt": "BG-27" }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineAllowanceCharge" }, "x-bt": "BG-28" }, "price": { "type": "object", "additionalProperties": false, "required": [ "netPrice" ], "properties": { "netPrice": { "$ref": "#/components/schemas/InvoiceUnitPrice", "x-bt": "BT-146" }, "discount": { "$ref": "#/components/schemas/InvoiceUnitPrice", "x-bt": "BT-147" }, "grossPrice": { "$ref": "#/components/schemas/InvoiceUnitPrice", "x-bt": "BT-148" }, "baseQuantity": { "$ref": "#/components/schemas/InvoiceQuantity", "x-bt": "BT-149" }, "baseQuantityUnitCode": { "type": "string", "x-bt": "BT-150" } }, "x-bt": "BG-29" }, "vat": { "type": "object", "description": "Parse output of national formats omits it when the national VAT code has no unambiguous EN 16931 category (e.g. FatturaPA Natura N1, N3.3-N3.6, N5, N7); the code is then reported as PARSE-UNMAPPED.", "additionalProperties": false, "required": [ "categoryCode" ], "properties": { "categoryCode": { "$ref": "#/components/schemas/InvoiceVatCategoryCode", "x-bt": "BT-151" }, "rate": { "$ref": "#/components/schemas/InvoicePercentage", "x-bt": "BT-152" } }, "x-bt": "BG-30" }, "item": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "x-bt": "BT-153" }, "description": { "type": "string", "x-bt": "BT-154" }, "sellerItemId": { "type": "string", "x-bt": "BT-155" }, "buyerItemId": { "type": "string", "x-bt": "BT-156" }, "standardItemId": { "$ref": "#/components/schemas/InvoiceIdentifier", "description": "e.g. GTIN with schemeId 0160.", "x-bt": "BT-157" }, "classifications": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "value", "listId" ], "properties": { "value": { "type": "string", "minLength": 1 }, "listId": { "type": "string", "description": "UNTDID 7143 code." }, "listVersion": { "type": "string" } } }, "x-bt": "BT-158" }, "originCountry": { "$ref": "#/components/schemas/InvoiceCountryCode", "x-bt": "BT-159" }, "attributes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "value" ], "properties": { "name": { "type": "string", "x-bt": "BT-160" }, "value": { "type": "string", "x-bt": "BT-161" } } }, "x-bt": "BG-32" } }, "x-bt": "BG-31" } }, "x-bt": "BG-25" }, "NormalizedInvoice": { "title": "NormalizedInvoice", "description": "Syntax-neutral representation of an EN 16931 invoice or credit note. Output of POST /v1/parse and input of POST /v1/generate. Each property carries its EN 16931 business term in 'x-bt'. Code-list values are validated by the rule sets, not by this schema.", "type": "object", "additionalProperties": false, "required": [ "invoiceNumber", "issueDate", "typeCode", "currency", "seller", "buyer", "totals" ], "properties": { "invoiceNumber": { "type": "string", "minLength": 1, "x-bt": "BT-1" }, "issueDate": { "$ref": "#/components/schemas/InvoiceDate", "x-bt": "BT-2" }, "issueTime": { "type": "string", "pattern": "^[0-9]{2}:[0-9]{2}:[0-9]{2}$", "description": "Issue time hh:mm:ss. Not an EN 16931 term: read from and written to UBL cbc:IssueTime only by the national formats that require it (Croatia: HR-BT-2, mandatory in hr-cius).", "examples": [ "12:00:00" ] }, "typeCode": { "type": "string", "pattern": "^[0-9]{1,3}$", "description": "UNTDID 1001 code, e.g. 380 commercial invoice, 381 credit note, 384 corrected invoice, 389 self-billed invoice, 326 partial invoice.", "examples": [ "380" ], "x-bt": "BT-3" }, "currency": { "$ref": "#/components/schemas/InvoiceCurrencyCode", "x-bt": "BT-5" }, "vatAccountingCurrency": { "$ref": "#/components/schemas/InvoiceCurrencyCode", "x-bt": "BT-6" }, "taxPointDate": { "$ref": "#/components/schemas/InvoiceDate", "x-bt": "BT-7" }, "vatPointDateCode": { "type": "string", "description": "UNTDID 2005 code (3, 35, 432).", "x-bt": "BT-8" }, "dueDate": { "$ref": "#/components/schemas/InvoiceDate", "x-bt": "BT-9" }, "buyerReference": { "type": "string", "description": "For XRechnung B2G this carries the Leitweg-ID.", "x-bt": "BT-10" }, "projectReference": { "type": "string", "x-bt": "BT-11" }, "contractReference": { "type": "string", "x-bt": "BT-12" }, "purchaseOrderReference": { "type": "string", "x-bt": "BT-13" }, "salesOrderReference": { "type": "string", "x-bt": "BT-14" }, "receivingAdviceReference": { "type": "string", "x-bt": "BT-15" }, "despatchAdviceReference": { "type": "string", "x-bt": "BT-16" }, "tenderOrLotReference": { "type": "string", "x-bt": "BT-17" }, "invoicedObjectIdentifier": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-18" }, "buyerAccountingReference": { "type": "string", "x-bt": "BT-19" }, "context": { "type": "object", "description": "Process context detected by /parse. On /generate, BT-24 (specificationIdentifier) is set from the 'format' parameter (a conflicting value is rejected with 400); BT-23 (businessProcessType) is taken from the input when given, e.g. the French billing framework code such as S1 or B1 (BR-FR-08), and otherwise defaults per format.", "additionalProperties": false, "properties": { "businessProcessType": { "type": "string", "x-bt": "BT-23" }, "specificationIdentifier": { "type": "string", "x-bt": "BT-24" } }, "x-bt": "BG-2" }, "notes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "subjectCode": { "type": "string", "description": "UNTDID 4451 code.", "x-bt": "BT-21" }, "text": { "type": "string", "minLength": 1, "x-bt": "BT-22" } } }, "x-bt": "BG-1" }, "precedingInvoices": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "number" ], "properties": { "number": { "type": "string", "minLength": 1, "x-bt": "BT-25" }, "issueDate": { "$ref": "#/components/schemas/InvoiceDate", "x-bt": "BT-26" } } }, "x-bt": "BG-3" }, "seller": { "$ref": "#/components/schemas/InvoiceSeller", "x-bt": "BG-4" }, "buyer": { "$ref": "#/components/schemas/InvoiceBuyer", "x-bt": "BG-7" }, "payee": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "x-bt": "BT-59" }, "identifier": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-60" }, "legalRegistrationId": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-61" } }, "x-bt": "BG-10" }, "sellerTaxRepresentative": { "type": "object", "additionalProperties": false, "required": [ "name", "vatId", "address" ], "properties": { "name": { "type": "string", "minLength": 1, "x-bt": "BT-62" }, "vatId": { "type": "string", "x-bt": "BT-63" }, "address": { "$ref": "#/components/schemas/InvoiceAddress", "x-bt": "BG-12" } }, "x-bt": "BG-11" }, "delivery": { "type": "object", "additionalProperties": false, "properties": { "partyName": { "type": "string", "x-bt": "BT-70" }, "locationId": { "$ref": "#/components/schemas/InvoiceIdentifier", "x-bt": "BT-71" }, "actualDeliveryDate": { "$ref": "#/components/schemas/InvoiceDate", "x-bt": "BT-72" }, "address": { "$ref": "#/components/schemas/InvoiceAddress", "x-bt": "BG-15" } }, "x-bt": "BG-13" }, "invoicingPeriod": { "$ref": "#/components/schemas/InvoicePeriod", "x-bt": "BG-14" }, "payment": { "type": "object", "additionalProperties": false, "properties": { "meansCode": { "type": "string", "description": "UNTDID 4461 code, e.g. 58 SEPA credit transfer, 59 SEPA direct debit, 30 credit transfer.", "x-bt": "BT-81" }, "meansText": { "type": "string", "x-bt": "BT-82" }, "remittanceInformation": { "type": "string", "x-bt": "BT-83" }, "creditTransfers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "accountId" ], "properties": { "accountId": { "type": "string", "minLength": 1, "description": "Payment account identifier. For SEPA this is the IBAN (normalized: upper case, no spaces).", "examples": [ "DE02120300000000202051" ], "x-bt": "BT-84" }, "accountName": { "type": "string", "x-bt": "BT-85" }, "bic": { "type": "string", "x-bt": "BT-86" } } }, "x-bt": "BG-17" }, "card": { "type": "object", "additionalProperties": false, "required": [ "accountNumberLast4to6" ], "properties": { "accountNumberLast4to6": { "type": "string", "pattern": "^[0-9]{4,6}$", "description": "EN 16931 allows only the last 4–6 digits of the card number.", "x-bt": "BT-87" }, "holderName": { "type": "string", "x-bt": "BT-88" } }, "x-bt": "BG-18" }, "directDebit": { "type": "object", "additionalProperties": false, "properties": { "mandateReference": { "type": "string", "x-bt": "BT-89" }, "creditorId": { "type": "string", "x-bt": "BT-90" }, "debitedAccountId": { "type": "string", "x-bt": "BT-91" } }, "x-bt": "BG-19" }, "terms": { "type": "string", "description": "Payment terms as free text. XRechnung structured Skonto syntax (#SKONTO#...) is passed through verbatim.", "x-bt": "BT-20" } }, "x-bt": "BG-16" }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDocumentAllowanceCharge" }, "x-bt": "BG-20" }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDocumentAllowanceCharge" }, "x-bt": "BG-21" }, "totals": { "type": "object", "additionalProperties": false, "required": [ "taxExclusiveAmount", "taxInclusiveAmount", "amountDue" ], "properties": { "lineNetTotal": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-106" }, "allowanceTotal": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-107" }, "chargeTotal": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-108" }, "taxExclusiveAmount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-109" }, "vatTotal": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-110" }, "vatTotalInAccountingCurrency": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-111" }, "taxInclusiveAmount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-112" }, "prepaidAmount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-113" }, "roundingAmount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-114" }, "amountDue": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-115" } }, "x-bt": "BG-22" }, "vatBreakdown": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "categoryCode", "taxableAmount", "taxAmount" ], "properties": { "taxableAmount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-116" }, "taxAmount": { "$ref": "#/components/schemas/InvoiceAmount", "x-bt": "BT-117" }, "categoryCode": { "$ref": "#/components/schemas/InvoiceVatCategoryCode", "description": "Parse output of national formats omits it when the national VAT code has no unambiguous EN 16931 category (e.g. FatturaPA Natura N1, N3.3-N3.6, N5, N7); the code is then reported as PARSE-UNMAPPED.", "x-bt": "BT-118" }, "rate": { "$ref": "#/components/schemas/InvoicePercentage", "x-bt": "BT-119" }, "exemptionReason": { "type": "string", "x-bt": "BT-120" }, "exemptionReasonCode": { "type": "string", "description": "VATEX code list.", "x-bt": "BT-121" } } }, "x-bt": "BG-23" }, "additionalDocuments": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "minLength": 1, "x-bt": "BT-122" }, "description": { "type": "string", "x-bt": "BT-123" }, "externalUri": { "type": "string", "x-bt": "BT-124" }, "attachment": { "type": "object", "additionalProperties": false, "required": [ "mimeCode", "filename", "contentBase64" ], "properties": { "mimeCode": { "type": "string", "examples": [ "application/pdf" ] }, "filename": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "contentEncoding": "base64" } }, "x-bt": "BT-125" } } }, "x-bt": "BG-24" }, "lines": { "type": "array", "minItems": 1, "description": "Absent for profiles without line items (MINIMUM, BASIC WL).", "items": { "$ref": "#/components/schemas/InvoiceInvoiceLine" }, "x-bt": "BG-25" } }, "examples": [ { "invoiceNumber": "RE-2026-0042", "issueDate": "2026-10-18", "typeCode": "380", "currency": "EUR", "dueDate": "2026-11-17", "buyerReference": "04011000-12345-34", "seller": { "name": "Muster Software GmbH", "vatId": "DE123456789", "electronicAddress": { "value": "rechnung@muster-software.example", "schemeId": "EM" }, "address": { "line1": "Hauptstraße 1", "city": "Berlin", "postCode": "10115", "countryCode": "DE" }, "contact": { "name": "Erika Beispiel", "phone": "+49 30 1234567", "email": "buchhaltung@muster-software.example" } }, "buyer": { "name": "Beispielamt der Stadt Musterstadt", "electronicAddress": { "value": "04011000-12345-34", "schemeId": "0204" }, "address": { "line1": "Rathausplatz 5", "city": "Musterstadt", "postCode": "12345", "countryCode": "DE" } }, "payment": { "meansCode": "58", "creditTransfers": [ { "accountId": "DE02120300000000202051", "accountName": "Muster Software GmbH" } ], "terms": "Zahlbar innerhalb von 30 Tagen ohne Abzug." }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "HUR", "netAmount": "1000.00", "price": { "netPrice": "100.00" }, "vat": { "categoryCode": "S", "rate": "19" }, "item": { "name": "Beratungsleistung" } } ], "vatBreakdown": [ { "categoryCode": "S", "rate": "19", "taxableAmount": "1000.00", "taxAmount": "190.00" } ], "totals": { "lineNetTotal": "1000.00", "taxExclusiveAmount": "1000.00", "vatTotal": "190.00", "taxInclusiveAmount": "1190.00", "amountDue": "1190.00" } } ] } }, "examples": { "ValidationValid": { "summary": "Valid XRechnung (UBL)", "value": { "requestId": "7dda6c33-1d07-43ba-a875-dfa1966801ed", "valid": true, "format": "xrechnung", "container": "XML", "syntax": "UBL", "profile": "XRECHNUNG", "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0", "rulesets": [ { "id": "xrechnung", "version": "3.0.2", "release": "2026-08-31" } ], "summary": { "fatal": 0, "error": 0, "warning": 0, "info": 0 }, "findings": [] } }, "ValidationInvalid": { "summary": "ZUGFeRD PDF with a calculation error and a PDF/A defect", "value": { "requestId": "40ae147c-1fb8-4666-91a0-c953003b3295", "valid": false, "format": "zugferd", "container": "PDF", "syntax": "CII", "profile": "EN16931", "guidelineId": "urn:cen.eu:en16931:2017", "attachmentName": "factur-x.xml", "rulesets": [ { "id": "zugferd", "version": "2.5.2", "release": "mustang-2.26.0" } ], "summary": { "fatal": 0, "error": 2, "warning": 0, "info": 0 }, "findings": [ { "severity": "error", "ruleId": "PDFA-6.2.4.3-2", "message": "PDF/A-3U clause 6.2.4.3: DeviceRGB colour space is used without RGB output intent profile (5 occurrences)", "source": "pdfa:veraPDF" }, { "severity": "error", "ruleId": "BR-CO-15", "message": "Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110).", "xpath": "/rsm:CrossIndustryInvoice[1]/rsm:SupplyChainTradeTransaction[1]/ram:ApplicableHeaderTradeSettlement[1]/ram:SpecifiedTradeSettlementHeaderMonetarySummation[1]", "source": "schematron:zugferd@2.5.2" } ] } }, "Parsed": { "summary": "Parsed XRechnung with an inconsistent amount due", "value": { "requestId": "0b1d6f7e-8d8f-4c8e-9a51-2f8c1e0d6a10", "valid": false, "format": "xrechnung", "container": "XML", "syntax": "UBL", "profile": "XRECHNUNG", "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0", "rulesets": [ { "id": "xrechnung", "version": "3.0.2", "release": "2026-08-31" } ], "summary": { "fatal": 1, "error": 0, "warning": 0, "info": 0 }, "invoice": { "invoiceNumber": "RE-2026-0042", "issueDate": "2026-10-18", "typeCode": "380", "currency": "EUR", "buyerReference": "04011000-12345-34", "context": { "businessProcessType": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0", "specificationIdentifier": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0" }, "seller": { "name": "Muster Software GmbH", "vatId": "DE123456789", "address": { "city": "Berlin", "countryCode": "DE" } }, "buyer": { "name": "Beispielamt der Stadt Musterstadt", "address": { "city": "Musterstadt", "countryCode": "DE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "HUR", "netAmount": "1000.00", "price": { "netPrice": "100.00" }, "vat": { "categoryCode": "S", "rate": "19" }, "item": { "name": "Beratungsleistung" } } ], "vatBreakdown": [ { "taxableAmount": "1000.00", "taxAmount": "190.00", "categoryCode": "S", "rate": "19" } ], "totals": { "lineNetTotal": "1000.00", "taxExclusiveAmount": "1000.00", "vatTotal": "190.00", "taxInclusiveAmount": "1190.00", "amountDue": "1.00" } }, "calculation": { "consistent": false, "differences": [ { "field": "BT-115", "rule": "BR-CO-16", "declared": "1.00", "computed": "1190.00" } ] }, "findings": [ { "severity": "fatal", "ruleId": "BR-CO-16", "message": "Amount due for payment (BT-115) = Invoice total amount with VAT (BT-112) - Paid amount (BT-113) + Rounding amount (BT-114).", "xpath": "/ubl:Invoice[1]/cac:LegalMonetaryTotal[1]", "source": "schematron:xrechnung@3.0.2" } ] } }, "SchemaViolation": { "summary": "Amount sent as a JSON number", "value": { "type": "https://api.einvoice-api.eu/problems/schema-violation", "title": "Invoice does not match the schema", "status": 400, "detail": "1 value(s) do not match the normalized invoice schema; see 'errors' (JSON Pointers).", "instance": "/v1/generate", "requestId": "5f2c9a7e-0c1b-4d7a-9f3e-1a2b3c4d5e6f", "errors": [ { "pointer": "/totals/amountDue", "message": "/totals/amountDue: number found, string expected" } ] } }, "GeneratedInvalid": { "summary": "Required XRechnung fields missing", "value": { "type": "https://api.einvoice-api.eu/problems/generated-invoice-invalid", "title": "Generated invoice is invalid", "status": 422, "detail": "The xrechnung-ubl document built from your input does not pass validation; nothing was returned. Fix the input fields named in 'findings' (rule ids refer to EN 16931 / XRechnung / Factur-X).", "instance": "/v1/generate", "requestId": "3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7", "findings": [ { "severity": "fatal", "ruleId": "BR-DE-15", "message": "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.", "xpath": "/ubl:Invoice[1]", "source": "schematron:xrechnung@3.0.2", "docUrl": "https://einvoice-api.eu/rules/br-de-15.html" } ], "rulesets": [ { "id": "xrechnung", "version": "3.0.2", "release": "2026-08-31" } ] } }, "UnknownRuleset": { "value": { "type": "https://api.einvoice-api.eu/problems/unknown-ruleset", "title": "Unknown rule set", "status": 400, "detail": "Unknown rule set 'xrechnung@2.3.1'. Use @, one of xrechnung@3.0.2, zugferd@2.5.2", "instance": "/v1/validate", "requestId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "available": [ "xrechnung@3.0.2", "zugferd@2.5.2" ] } }, "PreviewRuleset": { "value": { "type": "https://api.einvoice-api.eu/problems/preview-ruleset", "title": "Preview rule set", "status": 400, "detail": "'xrechnung@3.0.3' is a preview of an upcoming rule set and is not in force yet. Validate against it with POST /v1/preview/validate; on this endpoint use one of: xrechnung@3.0.2, zugferd@2.5.2", "instance": "/v1/validate", "requestId": "1f2e3d4c-5b6a-4978-8a6b-5c4d3e2f1a0b", "available": [ "xrechnung@3.0.2", "zugferd@2.5.2" ] } }, "ValidationPreview": { "summary": "An XRechnung checked against an upcoming release", "value": { "requestId": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "valid": true, "format": "xrechnung", "container": "XML", "syntax": "UBL", "profile": "XRECHNUNG", "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0", "rulesets": [ { "id": "xrechnung", "version": "3.0.3", "release": "2027-01-31", "preview": true, "effectiveFrom": "2027-08-01" } ], "summary": { "fatal": 0, "error": 0, "warning": 0, "info": 0 }, "findings": [] } }, "ValidationPreviewNone": { "summary": "No upcoming release covers the document", "value": { "requestId": "0a9b8c7d-6e5f-4a3b-9c1d-2e3f4a5b6c7d", "valid": true, "format": "xrechnung", "container": "XML", "syntax": "UBL", "profile": "XRECHNUNG", "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0", "rulesets": [ { "id": "xrechnung", "version": "3.0.2", "release": "2026-08-31" } ], "summary": { "fatal": 0, "error": 0, "warning": 0, "info": 1 }, "findings": [ { "severity": "info", "ruleId": "PREVIEW-NONE", "message": "No upcoming rule set covers this document (BT-24 'urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0'), so it was validated against the rules in force: xrechnung@3.0.2. No preview rule set has been published yet.", "source": "preview" } ] } }, "UnsupportedMediaType": { "value": { "type": "https://api.einvoice-api.eu/problems/unsupported-media-type", "title": "Unsupported media type", "status": 415, "detail": "Content-Type 'application/json' is not accepted by /v1/validate. Send the invoice as application/xml, text/xml, application/pdf or application/octet-stream, or as multipart/form-data with a part named 'file'.", "instance": "/v1/validate", "requestId": "8287433d-ec43-440f-8f99-2c72ef179bdd" } }, "Formats": { "value": { "rulesets": [ { "id": "xrechnung", "version": "3.0.2", "release": "2026-08-31", "default": true, "status": "current", "pin": "xrechnung@3.0.2", "description": "KoSIT validator configuration for XRechnung 3.0.2 (CEN EN 16931 Schematron 1.3.16, XRechnung Schematron 2.6.0)", "documents": [ { "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0", "profile": "XRECHNUNG", "format": "xrechnung", "syntaxes": [ "CII", "UBL" ], "containers": [ "XML", "PDF" ], "en16931Invoice": true } ] }, { "id": "zugferd", "version": "2.5.2", "release": "mustang-2.26.0", "default": true, "status": "current", "pin": "zugferd@2.5.2", "documents": [ { "guidelineId": "urn:factur-x.eu:1p0:minimum", "profile": "MINIMUM", "format": "zugferd", "syntaxes": [ "CII" ], "containers": [ "XML", "PDF" ], "en16931Invoice": false } ] }, { "id": "xrechnung", "version": "3.0.3", "release": "2027-01-31", "default": false, "status": "preview", "effectiveFrom": "2027-08-01", "pin": "xrechnung@3.0.3", "description": "Upcoming XRechnung release (illustration; used by POST /v1/preview/validate)", "documents": [ { "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0", "profile": "XRECHNUNG", "format": "xrechnung", "syntaxes": [ "CII", "UBL" ], "containers": [ "XML", "PDF" ], "en16931Invoice": true } ] } ] } }, "Health": { "value": { "status": "UP", "version": "0.1.0-SNAPSHOT", "release": "bf05008", "rulesets": [ { "id": "xrechnung", "version": "3.0.2", "release": "2026-08-31", "default": true }, { "id": "zugferd", "version": "2.5.2", "release": "mustang-2.26.0", "default": true } ] } } } }, "externalDocs": { "description": "Markdown documentation for developers and coding agents", "url": "https://einvoice-api.eu/llms.txt" } }