{ "openapi": "3.0.3", "info": { "title": "RechnungsAPI", "version": "1.0.0", "description": "RechnungsAPI creates, validates and analyzes German e-invoices: **ZUGFeRD** (PDF/A-3 with embedded XML) and **XRechnung** (XML), both based on the European standard EN 16931.\n\n## Hosts\n\nTwo hosts serve this API and accept the same token:\n\n- `https://api.rechnungsapi.de` is the default server of this document (V1 endpoints under `/api/v1/…`).\n- `https://api.v2.rechnungsapi.de` serves the V2 endpoints: PDF analysis, asynchronous analysis and the one-call PDF-to-ZUGFeRD conversion. Those operations declare their own `servers` entry, and they are grouped under the tags **PDF Analysis** and **PDF to ZUGFeRD**, so each generated API class talks to exactly one host. If your client generator ignores operation-level servers (e.g. `typescript-fetch`), set the base URL `https://api.v2.rechnungsapi.de` on those two API classes; everything else uses `https://api.rechnungsapi.de`.\n\n## Authentication\n\nSend `Authorization: Bearer ` on every call. You get your token in the dashboard under *Profile*. A raw token without the `Bearer ` prefix, or an `authtoken` header, is rejected.\n\n## Conventions\n\n- **Files** (PDF, images) travel as base64 strings inside JSON bodies. The only exception is the success response of `createZugferdFromPdf`, which is the raw PDF (`application/pdf`).\n- **Dates in requests** (invoice generation) are accepted as `YYYYMMDD`, `YYYY-MM-DD` or an ISO 8601 local date-time without a timezone offset, e.g. `2026-10-14T00:00:00` (the form the playground sends). **Dates in analysis results** are `DD.MM.YYYY` strings. Both are declared as plain strings on purpose: a `date-time` format would make generated clients add an offset or reject the analysis format.\n- **Amounts** are JSON numbers with a dot as decimal separator.\n- **HTTP 200 does not mean valid.** Validation and generation endpoints answer 200 when the request was processed; check `valid` / `zugferdValid` / `xInvoiceValid` and the error lists for rule violations.\n- **Error bodies** differ by endpoint family: the V2 endpoints return `{ \"success\": false, \"error\": { \"code\", \"userMessage\", … } }` with a stable `code` and a German `userMessage` that is safe to show to end users; the V1 endpoints return short `{ \"message\" }` / `{ \"error\" }` bodies.\n- **Size limits:** 11 MiB per document (decoded). Request bodies above about 16 MB are rejected by the platform with a plain, non-JSON error.\n- **Field names are case-sensitive and not uniform** (e.g. `xinvoiceXML` in one request, `xInvoiceXml` in another). Use them exactly as listed.\n\nFull documentation with examples: https://www.rechnungsapi.de/api-docs\n", "termsOfService": "https://www.rechnungsapi.de/terms", "contact": { "name": "RechnungsAPI Support", "email": "support@rechnungsapi.de", "url": "https://www.rechnungsapi.de/contact" } }, "externalDocs": { "description": "API documentation", "url": "https://www.rechnungsapi.de/api-docs" }, "servers": [ { "url": "https://api.rechnungsapi.de", "description": "RechnungsAPI V1 gateway" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "PDF Analysis", "description": "Extract structured invoice data from PDFs and images (V2 host `https://api.v2.rechnungsapi.de`)." }, { "name": "PDF to ZUGFeRD", "description": "Convert a PDF or scan into a validated ZUGFeRD PDF/A-3 in one call (V2 host `https://api.v2.rechnungsapi.de`)." }, { "name": "Invoice Generation", "description": "Create XRechnung XML and ZUGFeRD PDF/A-3 from JSON or XML." }, { "name": "Validation", "description": "Validate XRechnung XML and ZUGFeRD PDFs against EN 16931 and the XRechnung rules." }, { "name": "Extraction", "description": "Read the embedded XML data out of a ZUGFeRD PDF." }, { "name": "Email Delivery", "description": "Send generated invoices by email (requires the email delivery add-on)." }, { "name": "Legacy", "description": "Superseded V1 endpoints that keep working for existing integrations." } ], "paths": { "/createJSONFromAnalysedPdf": { "post": { "tags": [ "PDF Analysis" ], "operationId": "analyzeInvoicePdf", "summary": "Analyze invoice PDF or image (V2, recommended)", "description": "Extracts structured EN 16931 invoice data from a PDF, PNG, JPEG or TIFF. The type is detected from the content, so the request field keeps its historical name `pdfInvoiceBase64`.\n\nA successful extraction takes roughly 7–25 s (OCR/model time, not file size): use a client timeout of at least 60 s, or the async endpoint for large or multi-page documents. Rejections (bad input, auth, oversized file) return in well under a second.\n\nDates in the result are `DD.MM.YYYY` strings and amounts are JSON numbers, so both need converting before you send the data to a generation endpoint. Fields without a value on the source are omitted.\n\nRuns on the V2 host `https://api.v2.rechnungsapi.de`; the Bearer token is the same as for the V1 host.", "servers": [ { "url": "https://api.v2.rechnungsapi.de", "description": "RechnungsAPI V2 host (same Bearer token)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzePdfRequest" } } } }, "responses": { "200": { "description": "Analyzed successfully. `extractionConfidence` (0–100) says how complete the extraction is, see `confidenceBasis`; below 100 the mandatory details that are missing are listed in `mandatoryFieldReport`. Fields with no value on the source document are omitted entirely (never null or an empty string). Dates are DD.MM.YYYY strings and amounts are JSON numbers with a dot decimal: both need converting before XRechnung/ZUGFeRD serialization. Field semantics follow EN 16931 (BT business terms), see the `Invoice` schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfAnalysisResult" }, "examples": { "complete": { "summary": "Complete extraction (confidence 100, ZUGFeRD-ready)", "value": { "extractionConfidence": 100, "invoice": { "invoiceNumber": "RE-2026-0100", "invoiceIssueDate": "05.11.2026", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "paymentDueDate": "19.11.2026", "buyerReference": "04011000-12345-67", "paymentTerms": "Zahlbar bis 19.11.2026 per Ueberweisung an Muster GmbH", "seller": { "sellerName": "Muster GmbH", "sellerVatIdentifier": "DE123475223", "sellerElectronicAddress": "max@muster-gmbh.de", "sellerPostalAddress": { "sellerAddressLine1": "Hauptstr. 1", "sellerCity": "Berlin", "sellerPostCode": "10115", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Max Muster", "sellerContactTelephoneNumber": "+49 30 1234567", "sellerContactEmailAddress": "max@muster-gmbh.de" } }, "buyer": { "buyerName": "Test AG", "buyerElectronicAddress": "einkauf@test-ag.de", "buyerPostalAddress": { "buyerAddressLine1": "Ring 2", "buyerCity": "Koeln", "buyerPostCode": "50667", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactEmailAddress": "einkauf@test-ag.de" } }, "paymentInstructions": { "paymentMeansTypeCode": "58", "creditTransfer": [ { "paymentAccountIdentifier": "DE02120300000000202051", "paymentAccountName": "Muster GmbH", "paymentServiceProviderIdentifier": "BYLADEM1001" } ] }, "documentTotals": { "sumOfInvoiceLineNetAmount": 200, "invoiceTotalAmountWithoutVat": 200, "invoiceTotalVatAmount": 38, "invoiceTotalAmountWithVat": 238, "amountDueForPayment": 238 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 200, "vatCategoryTaxAmount": 38, "vatCategoryCode": "S", "vatCategoryRate": 19 } ], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoicedQuantity": 2, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 200, "priceDetails": { "itemNetPrice": 100 }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung" } } ] }, "zugferdReady": true, "lineItemCheck": { "status": "ok", "verified": true, "lines": 1, "linesRecomputed": 1, "linesInconsistent": 0, "lineSum": 200, "sumCheck": "ok", "confirmedBy": "printed BT-106", "vatCheck": "ok" }, "confidenceBasis": { "requirementsChecked": 41, "requirementsMet": 41 }, "warnings": [] } }, "incomplete": { "summary": "Mandatory details missing (confidence below 100)", "value": { "extractionConfidence": 95, "invoice": { "invoiceNumber": "RE-2026-0001", "invoiceIssueDate": "05.11.2026", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "paymentDueDate": "19.11.2026", "buyerReference": "No BuyerReference provided", "paymentTerms": "Zahlbar bis 19.11.2026", "seller": { "sellerName": "Muster GmbH", "sellerVatIdentifier": "DE123456789", "sellerPostalAddress": { "sellerAddressLine1": "Hauptstr. 1", "sellerCity": "Berlin", "sellerPostCode": "10115", "sellerCountryCode": "DE" }, "sellerContact": {} }, "buyer": { "buyerName": "Test AG", "buyerElectronicAddress": "notfilledemail@buyerdomain.de", "buyerPostalAddress": { "buyerAddressLine1": "Ring 2", "buyerCity": "Koeln", "buyerPostCode": "50667", "buyerCountryCode": "DE" } }, "paymentInstructions": { "paymentMeansTypeCode": "58", "creditTransfer": [ { "paymentAccountIdentifier": "DE02120300000000202051", "paymentAccountName": "Muster GmbH" } ] }, "documentTotals": { "sumOfInvoiceLineNetAmount": 200, "invoiceTotalAmountWithoutVat": 200, "invoiceTotalVatAmount": 38, "invoiceTotalAmountWithVat": 238, "amountDueForPayment": 238 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 200, "vatCategoryTaxAmount": 38, "vatCategoryCode": "S", "vatCategoryRate": 19 } ], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoicedQuantity": 2, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 200, "priceDetails": { "itemNetPrice": 100 }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung" } } ] }, "zugferdReady": false, "mandatoryFieldReport": [ { "rule": "BR-DE-6", "bt": "BT-42", "field": "seller.sellerContact.sellerContactTelephoneNumber", "label": "Telefon des Verkaeufers" }, { "rule": "BR-DE-7", "bt": "BT-43", "field": "seller.sellerContact.sellerContactEmailAddress", "label": "E-Mail des Verkaeufers" } ], "lineItemCheck": { "status": "ok", "verified": true, "lines": 1, "linesRecomputed": 1, "linesInconsistent": 0, "lineSum": 200, "sumCheck": "ok", "confirmedBy": "printed BT-106", "vatCheck": "ok" }, "confidenceBasis": { "requirementsChecked": 41, "requirementsMet": 39 }, "warnings": [ { "code": "VALUE_DERIVED", "field": "BT-40/BT-55", "message": "Land DE angenommen (inländische Adresse, kein Land gedruckt)" }, { "code": "PLACEHOLDER_INSERTED", "field": "BT-10", "message": "Keine Käuferreferenz / Leitweg-ID gedruckt: Platzhalter \"No BuyerReference provided\" (XRechnung verlangt BT-10)" }, { "code": "PLACEHOLDER_INSERTED", "field": "BT-49", "message": "Keine E-Mail-Adresse des Käufers gedruckt: Platzhalter notfilledemail@buyerdomain.de (XRechnung verlangt BT-49)" } ] } } } } } }, "400": { "$ref": "#/components/responses/AnalysisBadRequest" }, "403": { "$ref": "#/components/responses/AnalysisUnauthorized" }, "413": { "$ref": "#/components/responses/AnalysisPayloadTooLarge" }, "422": { "$ref": "#/components/responses/AnalysisUnprocessable" }, "500": { "$ref": "#/components/responses/AnalysisUnknownError" }, "503": { "$ref": "#/components/responses/AnalysisTemporaryError" } } } }, "/createJSONFromAnalysedPdfAsync": { "post": { "tags": [ "PDF Analysis" ], "operationId": "submitInvoicePdfAnalysis", "summary": "Analyze invoice PDF in the background (async, submit)", "description": "Submits a PDF or TIFF for background analysis instead of waiting inline. Use it for large or multi-page invoices that would exceed the 60-second gateway timeout of the synchronous endpoint. For small single-page invoices the synchronous endpoint is simpler.\n\nReturns immediately with a `job_id` (HTTP 200, not 202). Poll `getInvoicePdfAnalysisStatus` about every 3 s until it reports `done` or `failed`. Jobs and results are kept for 24 hours.\n\nAuthentication is `Authorization: Bearer ` only; a raw token or an `authtoken` header is answered with 403.\n\nRuns on the V2 host `https://api.v2.rechnungsapi.de`.", "servers": [ { "url": "https://api.v2.rechnungsapi.de", "description": "RechnungsAPI V2 host (same Bearer token)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzePdfAsyncRequest" } } } }, "responses": { "200": { "description": "Job accepted for background processing (200, not 202).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncSubmitResult" }, "example": { "job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890", "status": "processing" } } } }, "400": { "$ref": "#/components/responses/AnalysisBadRequest" }, "403": { "$ref": "#/components/responses/AnalysisUnauthorized" }, "413": { "$ref": "#/components/responses/AnalysisPayloadTooLarge" }, "422": { "$ref": "#/components/responses/AnalysisUnprocessable" }, "500": { "$ref": "#/components/responses/AnalysisUnknownError" }, "503": { "$ref": "#/components/responses/AnalysisTemporaryError" } } } }, "/rechnungsapi-invoice-async-status": { "get": { "tags": [ "PDF Analysis" ], "operationId": "getInvoicePdfAnalysisStatus", "summary": "Check async analysis status", "description": "Polls the result of a job created by `submitInvoicePdfAnalysis`. This path is a fixed route name (`rechnungsapi-invoice-async-status`), not derived from the submit path: do not build it by appending `Status` to the submit URL.\n\nResults are kept for 24 hours after completion, then purged.\n\nRuns on the V2 host `https://api.v2.rechnungsapi.de`.", "servers": [ { "url": "https://api.v2.rechnungsapi.de", "description": "RechnungsAPI V2 host (same Bearer token)" } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The `job_id` returned by the submit call. Any non-UUID value is treated as not found." } ], "responses": { "200": { "description": "Job state. `status` is `processing` (keep polling), `done` (`result` present) or `failed` (`error` present; same shape as the synchronous endpoint's errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncAnalysisStatus" }, "examples": { "processing": { "summary": "Still processing", "value": { "job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890", "status": "processing" } }, "done": { "summary": "Analysis complete", "value": { "job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890", "status": "done", "result": { "extractionConfidence": 100, "invoice": { "invoiceNumber": "RE-2026-0100", "invoiceIssueDate": "05.11.2026", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "paymentDueDate": "19.11.2026", "buyerReference": "04011000-12345-67", "paymentTerms": "Zahlbar bis 19.11.2026 per Ueberweisung an Muster GmbH", "seller": { "sellerName": "Muster GmbH", "sellerVatIdentifier": "DE123475223", "sellerElectronicAddress": "max@muster-gmbh.de", "sellerPostalAddress": { "sellerAddressLine1": "Hauptstr. 1", "sellerCity": "Berlin", "sellerPostCode": "10115", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Max Muster", "sellerContactTelephoneNumber": "+49 30 1234567", "sellerContactEmailAddress": "max@muster-gmbh.de" } }, "buyer": { "buyerName": "Test AG", "buyerElectronicAddress": "einkauf@test-ag.de", "buyerPostalAddress": { "buyerAddressLine1": "Ring 2", "buyerCity": "Koeln", "buyerPostCode": "50667", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactEmailAddress": "einkauf@test-ag.de" } }, "paymentInstructions": { "paymentMeansTypeCode": "58", "creditTransfer": [ { "paymentAccountIdentifier": "DE02120300000000202051", "paymentAccountName": "Muster GmbH", "paymentServiceProviderIdentifier": "BYLADEM1001" } ] }, "documentTotals": { "sumOfInvoiceLineNetAmount": 200, "invoiceTotalAmountWithoutVat": 200, "invoiceTotalVatAmount": 38, "invoiceTotalAmountWithVat": 238, "amountDueForPayment": 238 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 200, "vatCategoryTaxAmount": 38, "vatCategoryCode": "S", "vatCategoryRate": 19 } ], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoicedQuantity": 2, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 200, "priceDetails": { "itemNetPrice": 100 }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung" } } ] }, "zugferdReady": true, "lineItemCheck": { "status": "ok", "verified": true, "lines": 1, "linesRecomputed": 1, "linesInconsistent": 0, "lineSum": 200, "sumCheck": "ok", "confirmedBy": "printed BT-106", "vatCheck": "ok" }, "confidenceBasis": { "requirementsChecked": 41, "requirementsMet": 41 }, "warnings": [] } } }, "failed": { "summary": "Analysis failed", "value": { "job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890", "status": "failed", "error": { "code": "PDF_NO_TEXT", "userMessage": "Diese Datei enthält keinen auslesbaren Text (vermutlich ein reines Scan- oder Bilddokument). Bitte laden Sie eine Version mit Textebene hoch oder wenden Sie sich an den Support.", "reference": "REA-144853" } } }, "doneBelowHundred": { "summary": "Analysis complete, mandatory details missing (confidence below 100)", "value": { "job_id": "1b2c3d4e-5f6a-7890-abcd-ef1234567890", "status": "done", "result": { "extractionConfidence": 95, "invoice": { "invoiceNumber": "RE-2026-0001", "invoiceIssueDate": "05.11.2026", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "paymentDueDate": "19.11.2026", "buyerReference": "No BuyerReference provided", "paymentTerms": "Zahlbar bis 19.11.2026", "seller": { "sellerName": "Muster GmbH", "sellerVatIdentifier": "DE123456789", "sellerPostalAddress": { "sellerAddressLine1": "Hauptstr. 1", "sellerCity": "Berlin", "sellerPostCode": "10115", "sellerCountryCode": "DE" }, "sellerContact": {} }, "buyer": { "buyerName": "Test AG", "buyerElectronicAddress": "notfilledemail@buyerdomain.de", "buyerPostalAddress": { "buyerAddressLine1": "Ring 2", "buyerCity": "Koeln", "buyerPostCode": "50667", "buyerCountryCode": "DE" } }, "paymentInstructions": { "paymentMeansTypeCode": "58", "creditTransfer": [ { "paymentAccountIdentifier": "DE02120300000000202051", "paymentAccountName": "Muster GmbH" } ] }, "documentTotals": { "sumOfInvoiceLineNetAmount": 200, "invoiceTotalAmountWithoutVat": 200, "invoiceTotalVatAmount": 38, "invoiceTotalAmountWithVat": 238, "amountDueForPayment": 238 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 200, "vatCategoryTaxAmount": 38, "vatCategoryCode": "S", "vatCategoryRate": 19 } ], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoicedQuantity": 2, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 200, "priceDetails": { "itemNetPrice": 100 }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung" } } ] }, "zugferdReady": false, "mandatoryFieldReport": [ { "rule": "BR-DE-6", "bt": "BT-42", "field": "seller.sellerContact.sellerContactTelephoneNumber", "label": "Telefon des Verkaeufers" }, { "rule": "BR-DE-7", "bt": "BT-43", "field": "seller.sellerContact.sellerContactEmailAddress", "label": "E-Mail des Verkaeufers" } ], "lineItemCheck": { "status": "ok", "verified": true, "lines": 1, "linesRecomputed": 1, "linesInconsistent": 0, "lineSum": 200, "sumCheck": "ok", "confirmedBy": "printed BT-106", "vatCheck": "ok" }, "confidenceBasis": { "requirementsChecked": 41, "requirementsMet": 39 }, "warnings": [ { "code": "VALUE_DERIVED", "field": "BT-40/BT-55", "message": "Land DE angenommen (inländische Adresse, kein Land gedruckt)" }, { "code": "PLACEHOLDER_INSERTED", "field": "BT-10", "message": "Keine Käuferreferenz / Leitweg-ID gedruckt: Platzhalter \"No BuyerReference provided\" (XRechnung verlangt BT-10)" }, { "code": "PLACEHOLDER_INSERTED", "field": "BT-49", "message": "Keine E-Mail-Adresse des Käufers gedruckt: Platzhalter notfilledemail@buyerdomain.de (XRechnung verlangt BT-49)" } ] } } } } } } }, "401": { "description": "Not authorized, or out of credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncStatusUnauthorized" }, "example": { "status": "unauthorized", "message": "Not authorized or insufficient credits." } } } }, "403": { "description": "The job belongs to a different account/token than the one polling." }, "410": { "description": "Unknown or expired job id. Results are only kept for 24 hours after completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncStatusGone" }, "example": { "status": "gone", "message": "Job not found or expired (past 24h retention)." } } } } } } }, "/api/v1/zugferd/createJSONFromAnalysedPdf": { "post": { "tags": [ "Legacy" ], "operationId": "analyzeInvoicePdfLegacy", "deprecated": true, "summary": "Analyze invoice PDF (V1, legacy)", "description": "Analyzes a PDF invoice and extracts buyer, seller, line items, VAT and totals. Existing integrations keep working; new integrations should use `analyzeInvoicePdf` (V2) for higher accuracy and large-invoice support.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzePdfLegacyRequest" } } } }, "responses": { "200": { "description": "PDF analyzed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyPdfAnalysisResult" } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "412": { "description": "No invoice file transmitted." } } } }, "/createZugferdFromPdf": { "post": { "tags": [ "PDF to ZUGFeRD" ], "operationId": "createZugferdFromPdf", "summary": "Convert PDF or scan to ZUGFeRD (one call)", "description": "Sends a PDF or scanned invoice image and returns either a validated ZUGFeRD PDF/A-3 (EN 16931 XML embedded, already passed both ZUGFeRD and XRechnung validation) or a JSON error explaining why none could be produced: never both.\n\nIn one synchronous request this analyzes the document, cross-checks the totals computed from the extracted line items against the totals printed on the page, and builds the ZUGFeRD file. The conversion is refused rather than shipping a document whose figures the source does not support.\n\n**Success is raw bytes, not JSON.** The 200 body is the PDF (`Content-Type: application/pdf`). Detect success with `response.ok` together with a `Content-Type` starting with `application/pdf`, never by status code alone. Log the `X-Zugferd-Reference` header; support needs it to trace a conversion.\n\n**Timeouts:** analysis and build together take a few seconds up to several minutes depending on page count and OCR needs. Set the client (and any proxy in front of it) read timeout to at least 600 s.\n\n**Billing:** a successful conversion records one invocation per page for both the analysis and the build step. There is no idempotency key, so identical requests convert and bill again: deduplicate double-submits client-side.\n\nRuns on the V2 host `https://api.v2.rechnungsapi.de`.", "servers": [ { "url": "https://api.v2.rechnungsapi.de", "description": "RechnungsAPI V2 host (same Bearer token)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateZugferdFromPdfRequest" } } } }, "responses": { "200": { "description": "Converted successfully. The body is the ZUGFeRD PDF/A-3 itself.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "Suggested filename: the input name with its extension replaced by `-zugferd.pdf`.", "example": "attachment; filename=\"Rechnung-2026-0042-zugferd.pdf\"" }, "X-Zugferd-Status": { "schema": { "type": "string" }, "description": "Constant `success`." }, "X-Zugferd-Reference": { "schema": { "type": "string" }, "description": "`ZAPI-`. Log it for support.", "example": "ZAPI-151430" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "No file in the request (`INVALID_REQUEST`). Not retryable without changing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZugferdFromPdfError" }, "examples": { "INVALID_REQUEST": { "summary": "INVALID_REQUEST", "description": "error.code INVALID_REQUEST — no file in the request: the field is missing, no multipart part was found, or the value is empty/whitespace-only. Fix the upload; not retryable without changing the request.", "value": { "success": false, "error": { "code": "INVALID_REQUEST", "stage": "input", "httpStatus": 400, "retryable": false, "userMessage": "Es wurde keine Datei übermittelt. Bitte senden Sie das Dokument als Base64 im Feld \"pdfInvoiceBase64\".", "detail": "Im Request fehlt das Feld \"pdfInvoiceBase64\".", "reference": "ZAPI-151429" }, "email": { "subject": "[FEHLER] ZUGFeRD-Konvertierung fehlgeschlagen", "text": "Es wurde keine Datei übermittelt. Bitte senden Sie das Dokument erneut.", "html": "
Es wurde keine Datei übermittelt. Bitte senden Sie das Dokument erneut.
" } } } } } } }, "403": { "description": "Invalid token or exhausted quota (`UNAUTHORIZED`). Route to billing/support, not to retry. An unreachable access verifier answers 503, never this code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZugferdFromPdfError" }, "examples": { "UNAUTHORIZED": { "summary": "UNAUTHORIZED", "description": "error.code UNAUTHORIZED — invalid token or quota exhausted. Route to billing/support, not to \"try again\". Note: the access verifier being unreachable returns 503 PROCESSING_TEMPORARY_ERROR instead, never this code — an outage on our side is never shown as \"access denied\".", "value": { "success": false, "error": { "code": "UNAUTHORIZED", "stage": "access", "httpStatus": 403, "retryable": false, "userMessage": "Zugriff nicht möglich: Ihr Zugang ist nicht berechtigt oder Ihr Kontingent ist aufgebraucht. Bitte wenden Sie sich an den Support.", "detail": "Die Zugangsprüfung hat den Zugriff abgelehnt.", "reference": "ZAPI-151435" } } } } } } }, "413": { "description": "Decoded file larger than 11 MiB (`FILE_TOO_LARGE`). Not retryable with the same file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZugferdFromPdfError" }, "examples": { "FILE_TOO_LARGE": { "summary": "FILE_TOO_LARGE", "description": "error.code FILE_TOO_LARGE — decoded file over 11 MiB (11,534,336 bytes; ≈14.7 MB base64). error.detail carries the exact byte figures; rely on the 11 MiB limit rather than the figure in userMessage. Enforce this limit client-side too: requests with a body above about 16 MB are rejected with a plain, non-JSON error instead of this envelope.", "value": { "success": false, "error": { "code": "FILE_TOO_LARGE", "stage": "input", "httpStatus": 413, "retryable": false, "userMessage": "Die Datei ist zu groß. Bitte laden Sie ein Dokument mit maximal 20 MB hoch.", "detail": "Die Datei ist 12.061.931 Bytes groß; erlaubt sind maximal 11.534.336 Bytes.", "reference": "ZAPI-151434" } } } } } } }, "422": { "description": "No document was produced. `error.code` is `PDF_CORRUPT`, `PDF_ENCRYPTED`, `PDF_NO_TEXT`, `EXTRACTION_LOW_CONFIDENCE`, `MISSING_MANDATORY_FIELDS` (the invoice lacks mandatory data), `VERIFICATION_FAILED` (computed totals disagree with the printed totals) or `ZUGFERD_REJECTED` (the built invoice failed validation). Not retryable with the same file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZugferdFromPdfError" }, "examples": { "PDF_CORRUPT": { "summary": "PDF_CORRUPT", "description": "error.code PDF_CORRUPT — unreadable, truncated, or an unsupported format. Detection is by magic bytes, not filename or Content-Type; HEIC/HEIF, WEBP, BMP, GIF, SVG, Office files, and ZIP are not supported (convert HEIC to JPEG client-side first). Ask for a different file; not retryable with the same bytes.", "value": { "success": false, "error": { "code": "PDF_CORRUPT", "stage": "input", "httpStatus": 422, "retryable": false, "userMessage": "Der Inhalt ist weder ein PDF noch ein PNG-, JPEG- oder TIFF-Bild.", "detail": "Das übermittelte Dokument konnte nicht als PDF, PNG, JPEG oder TIFF erkannt werden.", "reference": "ZAPI-151430" } } }, "PDF_ENCRYPTED": { "summary": "PDF_ENCRYPTED", "description": "error.code PDF_ENCRYPTED — password-protected PDF. Ask the user to remove the protection; not retryable until then.", "value": { "success": false, "error": { "code": "PDF_ENCRYPTED", "stage": "input", "httpStatus": 422, "retryable": false, "userMessage": "Diese PDF-Datei ist passwortgeschützt und kann nicht gelesen werden. Bitte entfernen Sie den Passwortschutz und laden Sie die Datei erneut hoch.", "detail": "Das PDF ist passwortgeschützt bzw. verschlüsselt und kann nicht gelesen werden.", "reference": "ZAPI-151431" } } }, "PDF_NO_TEXT": { "summary": "PDF_NO_TEXT", "description": "error.code PDF_NO_TEXT — no readable text (a pure image scan that OCR could not rescue). Ask for the original PDF; not retryable with the same file.", "value": { "success": false, "error": { "code": "PDF_NO_TEXT", "stage": "analyse", "httpStatus": 422, "retryable": false, "userMessage": "In diesem Dokument konnte kein Text erkannt werden. Bitte laden Sie eine schärfere oder höher aufgelöste Aufnahme hoch – oder idealerweise das Original-PDF.", "detail": "", "reference": "ZAPI-151432" } } }, "EXTRACTION_LOW_CONFIDENCE": { "summary": "EXTRACTION_LOW_CONFIDENCE", "description": "error.code EXTRACTION_LOW_CONFIDENCE — text was extracted but too degraded to map to invoice fields reliably (see error.extractionConfidence). Do not retry with the same file — send a better copy. Not retryable with the same file.", "value": { "success": false, "error": { "code": "EXTRACTION_LOW_CONFIDENCE", "stage": "analyse", "httpStatus": 422, "retryable": false, "userMessage": "Das Dokument konnte nur unzureichend gelesen werden – die Qualität reicht für eine verlässliche Rechnungserkennung nicht aus. Bitte laden Sie eine bessere Vorlage hoch (höhere Auflösung, gerade ausgerichtet, idealerweise das Original-PDF statt eines Scans oder Fotos).", "detail": "Der erkannte Text war zu fehlerhaft, um die Rechnungsfelder zuverlässig zuzuordnen.", "reference": "ZAPI-151433", "extractionConfidence": 54 } } }, "MISSING_MANDATORY_FIELDS": { "summary": "MISSING_MANDATORY_FIELDS", "description": "error.code MISSING_MANDATORY_FIELDS — EN 16931/XRechnung mandatory data simply isn't on the document; nothing is guessed. error.fields lists each gap as { bt, field, label, rule? } — field is a dotted path into the extracted invoice JSON. error.explanations carries the plain-German rule text for each entry in error.ruleCodes. Not retryable with the same file. Every error response carries the same `email` object; it is shown in this example only, for brevity.", "value": { "success": false, "error": { "code": "MISSING_MANDATORY_FIELDS", "stage": "missing", "httpStatus": 422, "retryable": false, "userMessage": "Die Rechnung enthält nicht alle für eine ZUGFeRD-Rechnung erforderlichen Pflichtangaben. Es wurde daher keine ZUGFeRD-Datei erzeugt.", "detail": "Der Rechnung fehlen 2 Pflichtangabe(n) für eine ZUGFeRD-Konvertierung.", "reference": "ZAPI-151436", "upstreamReference": "REA-151430", "fields": [ { "bt": "BT-5", "field": "invoiceCurrencyCode", "label": "Währung", "rule": "BR-05" }, { "bt": "BT-31", "field": "seller.sellerVatIdentifier", "label": "USt-IdNr. des Verkäufers", "rule": "BR-IC-02" } ], "ruleCodes": [ "BR-05", "BR-IC-02" ], "explanations": [ { "code": "BR-05", "found": true, "title": "Die Rechnungswährung (BT-5) ist eine Pflichtangabe.", "description": "Schweregrad: fatal. Die Rechnungswährung (BT-5) ist eine Pflichtangabe. Behebung: Tragen Sie den ISO-4217-Währungscode ein.", "source": "KoSIT XRechnung 3.0 Schematron", "file": "BR-05.md" } ], "extractionConfidence": 87 }, "email": { "subject": "[FEHLENDE PFLICHTANGABEN] ZUGFeRD-Konvertierung fehlgeschlagen: Rechnung-2026-0042.pdf", "text": "Die Rechnung enthält nicht alle für eine ZUGFeRD-Rechnung erforderlichen Pflichtangaben (Referenz ZAPI-151436). Fehlend: Währung (BT-5), USt-IdNr. des Verkäufers (BT-31).", "html": "

Die Rechnung enthält nicht alle für eine ZUGFeRD-Rechnung erforderlichen Pflichtangaben.

  • Währung (BT-5)
  • USt-IdNr. des Verkäufers (BT-31)

Referenz: ZAPI-151436

" } } }, "VERIFICATION_FAILED": { "summary": "VERIFICATION_FAILED", "description": "error.code VERIFICATION_FAILED — the totals computed from the extracted line items disagree with the totals printed on the page. No document is produced on purpose — an e-invoice asserting a figure the PDF doesn't support is a tax liability. error.fields lists each mismatch as { field, extracted, foundInDocument, note } (either value may be null when absent entirely). Not retryable with the same file.", "value": { "success": false, "error": { "code": "VERIFICATION_FAILED", "stage": "verify", "httpStatus": 422, "retryable": false, "userMessage": "Die berechneten Beträge stimmen nicht mit den auf der Rechnung ausgewiesenen Beträgen überein. Es wurde daher keine ZUGFeRD-Datei erzeugt.", "detail": "1 Abweichung zwischen berechneten und gedruckten Beträgen gefunden.", "reference": "ZAPI-151437", "fields": [ { "field": "BT-112 invoiceTotalAmountWithVat", "extracted": 1190, "foundInDocument": 1109, "note": "Aus den Positionen errechneter Wert weicht vom auf der Rechnung ausgewiesenen Wert ab (Differenz 81)." } ] } } }, "ZUGFERD_REJECTED": { "summary": "ZUGFERD_REJECTED", "description": "error.code ZUGFERD_REJECTED — the assembled invoice failed ZUGFeRD and/or XRechnung validation. error.fields is the merged, de-duplicated rule-violation list from both validators, each as { rule, message, type, location }; error.explanations carries the plain-German text per rule code. Not retryable with the same file.", "value": { "success": false, "error": { "code": "ZUGFERD_REJECTED", "stage": "zugferd", "httpStatus": 422, "retryable": false, "userMessage": "Die erzeugte ZUGFeRD-Datei hat die Validierung nicht bestanden. Es wurde daher keine Datei ausgeliefert.", "detail": "1 Validierungsfehler gefunden.", "reference": "ZAPI-151438", "fields": [ { "rule": "PEPPOL-EN16931-R008", "message": "Document MUST not contain empty elements.", "type": "fatal", "location": "/rsm:CrossIndustryInvoice[1]/…/ram:ShipToTradeParty[1]" } ], "ruleCodes": [ "PEPPOL-EN16931-R008" ], "explanations": [ { "code": "PEPPOL-EN16931-R008", "found": true, "title": "Leere Elemente sind nicht zulässig.", "description": "Schweregrad: fatal. Leere Elemente sind nicht zulässig. Behebung: Entfernen Sie das leere Element oder befüllen Sie es.", "source": "PEPPOL BIS Billing 3.0", "file": "PEPPOL-EN16931-R008.md" } ] } } } } } } }, "500": { "description": "Unclassified failure (`UNKNOWN_ERROR`). Show `error.reference` and point to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZugferdFromPdfError" }, "examples": { "UNKNOWN_ERROR": { "summary": "UNKNOWN_ERROR", "description": "error.code UNKNOWN_ERROR — unclassified failure. Any code not in this table is normalised to this one before it leaves the API, so a switch with a default branch is complete by construction. Show the reference and point to support.", "value": { "success": false, "error": { "code": "UNKNOWN_ERROR", "stage": "unknown", "httpStatus": 500, "retryable": false, "detail": "Die Ursache konnte nicht automatisch bestimmt werden.", "reference": "ZAPI-151440" } } } } } } }, "503": { "description": "Outage or timeout on our side (`PROCESSING_TEMPORARY_ERROR`). The only retryable code: retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZugferdFromPdfError" }, "examples": { "PROCESSING_TEMPORARY_ERROR": { "summary": "PROCESSING_TEMPORARY_ERROR", "description": "error.code PROCESSING_TEMPORARY_ERROR — an outage or timeout on our side (access verifier unreachable, an internal step failed, a timeout, or the build response couldn't be parsed). The only retryable code — retry with backoff; the same file will normally succeed.", "value": { "success": false, "error": { "code": "PROCESSING_TEMPORARY_ERROR", "stage": "unknown", "httpStatus": 503, "retryable": true, "userMessage": "Bei der Verarbeitung ist vorübergehend ein Problem aufgetreten. Bitte versuchen Sie es in einigen Minuten erneut. Falls das Problem weiterhin besteht, kontaktieren Sie bitte den Support unter Angabe der Referenz ZAPI-151439.", "reference": "ZAPI-151439" } } } } } } } } } }, "/api/v1/zugferd/createXinvoiceFromJson": { "post": { "tags": [ "Invoice Generation" ], "operationId": "createXRechnungFromJson", "summary": "Generate XRechnung XML from JSON", "description": "Generates an EN 16931-compliant XRechnung XML document from structured JSON invoice data. No PDF required. The XML syntax is CII by default; set `xmlFormat` to `UBL` to get a UBL document instead (`xmlFormat: \"CII\"` returns CII, the same as omitting the field). The invoice JSON is identical for both syntaxes: only the XML in the response changes. UBL output is available on this endpoint only; the ZUGFeRD endpoints always embed CII XML, as the ZUGFeRD standard requires.\n\nHTTP 200 means the request was processed: check `valid` and `xInvoiceErrors` for validation issues. Add the optional `transport` object to also email the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateXRechnungFromJsonRequest" }, "examples": { "cii": { "summary": "CII (default; same as omitting xmlFormat)", "value": { "invoice": { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2025-02-09T00:00:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "paymentDueDate": "2025-02-23T00:00:00", "buyerReference": "BEST-2025-042", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "processControl": { "businessProcessTypeIdentifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0", "specificationIdentifier": "urn:cen.eu:en16931:2017" }, "seller": { "sellerName": "Musterfirma Software", "sellerTradingName": "Ihre Firma", "sellerIdentifier": [ "DE1111111" ], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE115235681", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "Geschäftsführer: Max Mustermann", "sellerElectronicAddress": "info@musterfirma.example", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "2. OG", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "BE", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@musterfirma.example" } }, "buyer": { "buyerName": "Beispielkunde Tierarztpraxis", "buyerIdentifier": "DE2222222", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@beispielkunde.example", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "BE", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "Einkauf", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@beispielkunde.example" } }, "deliveryInformation": { "actualDeliveryDate": "2025-02-09T00:00:00", "deliverToAddress": { "deliverToAddressLine1": "Kundenstraße 42", "deliverToCity": "Berlin", "deliverToPostCode": "10115", "deliverToCountrySubdivision": "BE", "deliverToCountryCode": "DE" } }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Musterfirma Software", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ] }, "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19 } ], "additionalSupportingDocuments": [ { "supportingDocumentReference": "LS-2025-0042", "supportingDocumentTypeCodex": 916, "supportingDocumentDescription": "Lieferschein zur Rechnung", "externalDocumentLocation": "https://musterfirma.example/lieferschein-2025-0042.pdf" } ], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "Beratung und Projektbegleitung", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "PO-001-1", "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "Dienstleistung", "itemSellersIdentifier": "SRV-001" } }, { "invoiceLineIdentifier": "2", "invoicedQuantity": 1, "invoicedQuantityUnitOfMeasureCode": "C62", "invoiceLineNetAmount": 599, "referencedPurchaseOrderLineReference": "PO-001-2", "priceDetails": { "itemNetPrice": 599, "itemPriceDiscount": 0, "itemGrossPrice": 599, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "C62" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Software-Lizenz (Jahresabo)", "itemDescription": "Lizenz", "itemSellersIdentifier": "LIC-2025" } } ] }, "xmlFormat": "CII" } }, "ubl": { "summary": "UBL", "value": { "invoice": { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2025-02-09T00:00:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "paymentDueDate": "2025-02-23T00:00:00", "buyerReference": "BEST-2025-042", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "processControl": { "businessProcessTypeIdentifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0", "specificationIdentifier": "urn:cen.eu:en16931:2017" }, "seller": { "sellerName": "Musterfirma Software", "sellerTradingName": "Ihre Firma", "sellerIdentifier": [ "DE1111111" ], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE115235681", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "Geschäftsführer: Max Mustermann", "sellerElectronicAddress": "info@musterfirma.example", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "2. OG", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "BE", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@musterfirma.example" } }, "buyer": { "buyerName": "Beispielkunde Tierarztpraxis", "buyerIdentifier": "DE2222222", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@beispielkunde.example", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "BE", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "Einkauf", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@beispielkunde.example" } }, "deliveryInformation": { "actualDeliveryDate": "2025-02-09T00:00:00", "deliverToAddress": { "deliverToAddressLine1": "Kundenstraße 42", "deliverToCity": "Berlin", "deliverToPostCode": "10115", "deliverToCountrySubdivision": "BE", "deliverToCountryCode": "DE" } }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Musterfirma Software", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ] }, "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19 } ], "additionalSupportingDocuments": [ { "supportingDocumentReference": "LS-2025-0042", "supportingDocumentTypeCodex": 916, "supportingDocumentDescription": "Lieferschein zur Rechnung", "externalDocumentLocation": "https://musterfirma.example/lieferschein-2025-0042.pdf" } ], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "Beratung und Projektbegleitung", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "PO-001-1", "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "Dienstleistung", "itemSellersIdentifier": "SRV-001" } }, { "invoiceLineIdentifier": "2", "invoicedQuantity": 1, "invoicedQuantityUnitOfMeasureCode": "C62", "invoiceLineNetAmount": 599, "referencedPurchaseOrderLineReference": "PO-001-2", "priceDetails": { "itemNetPrice": 599, "itemPriceDiscount": 0, "itemGrossPrice": 599, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "C62" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Software-Lizenz (Jahresabo)", "itemDescription": "Lizenz", "itemSellersIdentifier": "LIC-2025" } } ] }, "xmlFormat": "UBL" } } } } } }, "responses": { "200": { "description": "- XRechnung XML created and valid (CII, the default). The body carries the XML itself (`xInvoice`), a download link (`downloadURL`) and the invoice as the API normalised it (`invoice`). `resendToken` is an empty string unless `transport` was used on a valid document — see the `transport` object.\n- UBL requested (`xmlFormat: \"UBL\"`): the response has the same fields as above; `xInvoice` and the file at `downloadURL` hold a UBL 2.1 `Invoice` (root element `ubl:Invoice`, namespace `urn:oasis:names:specification:ubl:schema:xsd:Invoice-2`) instead of a CII `rsm:CrossIndustryInvoice`. The business data, the `invoice` echo and the validity fields work the same.\n- XML generated, but it fails validation: `valid` is `false` and `xInvoiceErrors` lists every violation. The XML and `downloadURL` are still returned, so you can inspect or fix the document. Shortened here to 2 of 10 findings. Typical trap: price details you omit are filled with `0` — a missing `priceDetails.itemPriceBaseQuantity` triggers `PEPPOL-EN16931-R121`, a missing `itemGrossPrice` triggers `PEPPOL-EN16931-R046`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateXRechnungResult" }, "examples": { "valid": { "summary": "XML created and valid (CII, the default)", "value": { "message": "xInvoice generated", "valid": true, "numberOfXInvoiceErrors": 0, "xInvoiceErrors": [], "xInvoice": "...", "downloadURL": "https://api.rechnungsapi.de/file/get/1793267754_Qx7LmN2pVd9RtKs4WbHy8CfJe1ZaGu3o", "resendToken": "", "invoice": [ { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": null, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [] } } ] } ] } }, "validUbl": { "summary": "UBL requested: XML created and valid", "value": { "message": "xInvoice generated", "valid": true, "numberOfXInvoiceErrors": 0, "xInvoiceErrors": [], "xInvoice": "...", "downloadURL": "https://api.rechnungsapi.de/file/get/1793267803_Wd5TrB1nXcQ8LsKy3MzHp6EvAj2UfGo9", "resendToken": "", "invoice": [ { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": null, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [] } } ] } ] } }, "invalid": { "summary": "XML generated, but it fails validation", "value": { "message": "xInvoice generated", "valid": false, "numberOfXInvoiceErrors": 10, "xInvoiceErrors": [ { "message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.", "schemaFile": "EN16931-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]", "id": "BR-CO-25", "line": null }, { "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.", "schemaFile": "XRechnung-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]", "id": "BR-DE-15", "line": null } ], "xInvoice": "...", "downloadURL": "https://api.rechnungsapi.de/file/get/1793267782_Hk3VnB8sQwXc5MtYj2PdLr7EaUf9ZoGi", "resendToken": "", "invoice": [ { "invoiceNumber": "RE-2025-002", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": null, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [] } } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "402": { "description": "No API access: no active subscription or no credits left. The exact message text varies (e.g. `no access to api`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "no access to api" } } } }, "412": { "description": "Mandatory data is missing, so nothing is generated. `errorlist` names every missing business term, `noOfMissingData` counts them. Seen for a missing seller or buyer electronic address (BT-34, BT-49) and a missing invoice issue date (BT-2); an empty `invoice` object returns all of them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MissingDataError" }, "example": { "message": "Data are missing in input.", "noOfMissingData": 3, "errorlist": [ { "businessTerm": "BT-34", "businessTermDescription": "BT-34 (sellerElectronicAddress)", "errormessage": "field is required to be filled with an valid email address" }, { "businessTerm": "BT-49", "businessTermDescription": "BT-49 ( buyerElectronicAddress)", "errormessage": "field is required to be filled with an valid email address" }, { "businessTerm": "BT-2", "businessTermDescription": "BT-2 (invoiceIssueDate)", "errormessage": "Invoice issue date is required" } ] } } } } } } }, "/api/v1/zugferd/createZugferdFromJson": { "post": { "tags": [ "Invoice Generation" ], "operationId": "createZugferdFromJson", "summary": "Generate ZUGFeRD from JSON + PDF", "description": "Combines structured JSON invoice data with an existing PDF into a ZUGFeRD-compliant PDF/A-3 document with embedded XRechnung XML.\n\nHTTP 200 means the request was processed: check `zugferdValid`, `xInvoiceValid` and the error lists. Add the optional `transport` object to also email the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateZugferdFromJsonRequest" } } } }, "responses": { "200": { "description": "- ZUGFeRD PDF created and valid. The PDF is in `zugferd` (base64) and the embedded XML in `xInvoice`. HTTP 200 only means the document was generated — always check `zugferdValid` and `xInvoiceValid`: unlike `createInvoicePdfFromJson`, this endpoint also returns the PDF when it breaks validation rules (see the second example). `resendToken` is `\"\"` unless `transport` was used on a valid document — see the `transport` object.\n- ZUGFeRD PDF created, but the invoice breaks validation rules: `zugferdValid` and `xInvoiceValid` are `false` and the error lists name every violated rule (here 2 of 3 findings are shown). The PDF, the XML and `downloadURL` are still returned, so you can inspect or fix the document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateZugferdResult" }, "examples": { "valid": { "summary": "ZUGFeRD created and valid", "value": { "message": "ZUGFeRD created", "xInvoice": "...", "zugferd": "JVBERi0xLjcKJaLN+vwK...", "downloadURL": "https://api.rechnungsapi.de/file/get/1793359631_NbRS0bMYy68cicTsBocYzDK8MHCAFIz0", "resendToken": "", "xInvoiceValid": true, "zugferdValid": true, "numberOfxInvoiceErrors": 0, "numberOfZugferdErrors": 0, "xInvoiceErrorList": [], "zugferdErrorList": [], "invoiceJson": [ { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": null, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [] } } ] } ], "invoice": [ { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": null, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [] } } ] } ] } }, "invalid": { "summary": "ZUGFeRD created, but the invoice breaks validation rules", "value": { "message": "ZUGFeRD created", "xInvoice": "...", "zugferd": "JVBERi0xLjcKJaLN+vwK...", "downloadURL": "https://api.rechnungsapi.de/file/get/1793364463_3uLBx0wWp4ABuFRtYQFzpqzQ0MGthdNV", "resendToken": "", "xInvoiceValid": false, "zugferdValid": false, "numberOfxInvoiceErrors": 3, "numberOfZugferdErrors": 3, "xInvoiceErrorList": [ { "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.", "schemaFile": "XRechnung-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]", "id": "BR-DE-15", "line": null }, { "message": "[BR-DE-6] Das Element \"Seller contact telephone number\" (BT-42) muss übermittelt werden.", "schemaFile": "XRechnung-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}SupplyChainTradeTransaction[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ApplicableHeaderTradeAgreement[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}SellerTradeParty[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}DefinedTradeContact[1]", "id": "BR-DE-6", "line": null } ], "zugferdErrorList": [ { "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.", "schemaFile": "XRechnung-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]", "id": "BR-DE-15", "line": null } ], "invoiceJson": [ { "invoiceNumber": "RE-2025-002", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": null, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [] } } ] } ], "invoice": [ { "invoiceNumber": "RE-2025-002", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": null, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [] } } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "402": { "description": "No API access: no active subscription or no credits left. The exact message text varies (e.g. `no access to api (no credits)`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "no access to api (no credits)" } } } }, "412": { "description": "No invoice file or invoice data transmitted, or the data is unusable. The body is `{ message, noOfMissingData, errorlist }`, but unlike `createXinvoiceFromJson` the reason is usually only in `message`: in our test `noOfMissingData` was `0` and `errorlist` empty. Note the lowercase `l` in `errorlist`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MissingDataError" }, "example": { "message": "buyer electronic email address is invalid ><", "noOfMissingData": 0, "errorlist": [] } } } } } } }, "/api/v1/zugferd/createZugferdPdfFromXinvoice": { "post": { "tags": [ "Invoice Generation" ], "operationId": "createZugferdPdfFromXRechnung", "summary": "Create ZUGFeRD PDF from XRechnung", "description": "Creates a ZUGFeRD-compliant PDF/A-3 by embedding an existing XRechnung XML into a PDF document.\n\nHTTP 200 means the request was processed: check `valid` and `zugferdErrors`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateZugferdPdfFromXRechnungRequest" }, "example": { "xInvoiceXml": "...", "invoicePdf64": "JVBERi0xLjQK..." } } } }, "responses": { "200": { "description": "ZUGFeRD PDF created. HTTP 200 only means the PDF was built — always check `valid` and `zugferdErrors`; the PDF is returned either way. The embedded XML is rebuilt from the data parsed out of your XML, so findings can appear even though your own XML validated cleanly (`validXRechnung` is `true`): for example `PEPPOL-EN16931-R008` (empty `ShipToTradeParty`) is currently reported when your XML contains no delivery information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateZugferdPdfFromXRechnungResult" }, "example": { "message": "zugferd created", "valid": false, "numberOfZugferdErrors": 1, "zugferdErrors": [ { "message": "[PEPPOL-EN16931-R008]-Document MUST not contain empty elements.", "schemaFile": "XRechnung-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}SupplyChainTradeTransaction[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ApplicableHeaderTradeDelivery[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ShipToTradeParty[1]", "id": "PEPPOL-EN16931-R008", "line": null } ], "zugferdFile": "JVBERi0xLjcKJaOIwOMKMyAwIG9iago...", "createdInvoice": [ { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": null, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [] } } ] } ], "extractedInvoice": [ { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": { "deliverToPartyName": "", "deliverToLocationIdentifier": null, "actualDeliveryDate": null, "deliverToAddress": { "deliverToAddressLine1": "", "deliverToAddressLine2": "", "deliverToAddressLine3": "", "deliverToCity": "", "deliverToPostCode": "", "deliverToCountrySubdivision": null, "deliverToCountryCode": "" } }, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [ { "itemAttributeName": null, "itemAttributeValue": null } ] } } ] } ], "validXRechnung": true, "xrechnungErrors": [] } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "402": { "description": "No API access: no active subscription or no credits left. The exact message text varies (e.g. `no access to api`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "no access to api" } } } }, "412": { "description": "No invoice file or XRechnung XML provided. The body is `{ message }` only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "no xInvoice data found" } } } } } } }, "/api/v1/zugferd/createInvoicePdfFromJson": { "post": { "tags": [ "Invoice Generation" ], "operationId": "createInvoicePdfFromJson", "summary": "Generate ZUGFeRD invoice PDF from JSON (template)", "description": "Generates a ZUGFeRD-compliant invoice PDF from JSON data, rendered with your own Word or design template. Add the optional `transport` object to also email the result.\n\n**Status codes.** A freshly generated document is answered with HTTP 201; an Idempotency-Key replay with HTTP 200. A document that breaks a validation rule is not returned: it is answered with 412 and an `errorList`.\n\n**Idempotency.** Send an optional `Idempotency-Key` request header (any unique string, e.g. a UUID; it is a header, not a body field). The first request with a key is processed normally and its response is cached for 24 hours. Resending the same key with an identical body within that window replays the cached response instead of generating a new invoice, and consumes no credits. The same key with a different body is rejected with 409, also without consuming credits. The `X-Idempotency-Key-Reused` response header tells which happened.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoicePdfFromJsonRequest" } } } }, "responses": { "200": { "description": "Idempotency-Key replay: the same key was sent again with an identical body within 24 hours. The API answers HTTP 200 with the cached document instead of generating a new one, and the response header `X-Idempotency-Key-Reused` is `true`. No credits are used. `iqDataId`, `documentId` and `fsNodeId` are `0` and there is no `resendToken`. The `message` text is returned exactly as shown, including its spelling.", "headers": { "X-Idempotency-Key-Reused": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Reflects the idempotency outcome when an `Idempotency-Key` request header was sent: `true` for a replayed response from the cache, `false` for a freshly generated one." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoicePdfResult" }, "example": { "message": "returned because of same itempotency-key", "iqDataId": 0, "documentId": 0, "fsNodeId": 0, "fileName": "my-custom-invoice-name.pdf", "fileExtension": "pdf", "fileSize": 99288, "filecontentB64": "JVBERi0xLjcK...", "downloadURL": "https://api.rechnungsapi.de/file/get/1793363429_Qx7LmN2pVd9RtKs4WbHy8CfJe1ZaGu3o", "zugferdIsValid": true, "zugferdErrors": [] } } } }, "201": { "description": "Invoice PDF created. A freshly generated document is answered with HTTP 201. The PDF itself is in `filecontentB64`; `downloadURL` is a second way to get it. `resendToken` is `\"\"` unless `transport` was used on a valid document — see the `transport` object. If a request Idempotency-Key was sent, the response carries `X-Idempotency-Key-Reused: false`. A document that breaks a validation rule is not returned here — it is answered with 412 and an `errorList` instead.", "headers": { "X-Idempotency-Key-Reused": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Reflects the idempotency outcome when an `Idempotency-Key` request header was sent: `true` for a replayed response from the cache, `false` for a freshly generated one." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoicePdfResult" }, "example": { "message": "pdf created, downloaded and not stored in DMS", "iqDataId": 136951, "downloadURL": "https://api.rechnungsapi.de/file/get/1793363431_Zk4NpQ8sVtYw2RbJc7XmH5LdFe9GuAo3", "resendToken": "ttsYDNZrEj9JZO12rSH5w4JwM/w7VJjEEyjcTWHj2sWa/4tV6f72K9PP6YkqkO46/d9aTLWtWAofRJxx70/RVg==", "fileName": "my-custom-invoice-name.pdf", "fileExtension": "pdf", "fileSize": 99288, "filecontentB64": "JVBERi0xLjcK...", "zugferdIsValid": true, "zugferdErrors": [] } } } }, "400": { "description": "Invalid input data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "message": "Invalid invoice data provided", "errors": [ "invoiceNumber is required", "dueDate must be after invoiceDate" ] } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "406": { "description": "Input rejected before anything was generated. Seen so far: `no invoice templateId found.` (`templateId` missing or empty) and `buyerElectronicAddress (email address) invalid or not present.` (a mandatory invoice field is missing). The body is `{ message }` only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "no invoice templateId found." } } } }, "409": { "description": "The `Idempotency-Key` was reused with a different request body. No credits are consumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "message": "Idempotency key exists with different content." } } } }, "412": { "description": "- The invoice data was accepted but breaks one or more validation rules, so no PDF was produced. `errorList` names every violated rule; `errors` is their count. Note the spelling: this list is called `errorList` here, while other endpoints use `xInvoiceErrors` or `zugferdErrors`. Shortened here to 2 of 3 findings.\n- The PDF could not be rendered — seen with an unknown `templateId`. The body is `{ message }` only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoicePdfValidationError" }, "examples": { "errorsInData": { "summary": "Invoice breaks validation rules: no PDF", "value": { "message": "errors in data", "invoiceId": 1280660, "iqDataId": 136957, "errors": 3, "errorList": [ { "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.", "schemaFile": "XRechnung-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]", "id": "BR-DE-15", "line": null }, { "message": "[BR-DE-7] Das Element \"Seller contact email address\" (BT-43) muss übermittelt werden.", "schemaFile": "XRechnung-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}SupplyChainTradeTransaction[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}ApplicableHeaderTradeAgreement[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}SellerTradeParty[1]/Q{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}DefinedTradeContact[1]", "id": "BR-DE-7", "line": null } ] } }, "renderingFailed": { "summary": "PDF could not be rendered", "value": { "message": "invoice created. pdf rendering failed" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "message": "Internal Server Error", "errors": [] } } } } } } }, "/api/v1/zugferd/validateXinvoiceXml": { "post": { "tags": [ "Validation" ], "operationId": "validateXRechnungXml", "summary": "Validate XRechnung XML", "description": "Validates XRechnung XML (CII or UBL syntax) against EN 16931 and the XRechnung business rules. Returns structured errors with rule ids and locations so issues can be fixed before sending. Once a document passes those rules, additional checks run (seller VAT ID, due date) and the response also reports separately whether the IBAN in the invoice is valid (`isIbanValidInXML`). Which of these fields come back depends on how far validation got: see the example responses.\n\nHTTP 200 only means the request ran: check `valid` for the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateXRechnungXmlRequest" }, "example": { "xinvoiceXML": "..." } } } }, "responses": { "200": { "description": "- Validation completed and the document is valid. HTTP 200 only means the request ran – always check the `valid` field for the actual result.\n- The document passed the schema and Schematron rules, but the additional checks found problems: the seller VAT ID (BT-31) is not valid (`location: sellerVatId`), or the due date (BT-9) is missing (`location: dueDate`) — the message mentions payment terms as well, but in our tests a payment-terms text alone did not satisfy this check, so send the due date. These findings carry `schemaFile: additional-validation`, and `id` and `line` are empty strings.\n- The document violates schema or Schematron rules. The additional checks are skipped, so `isIbanValidInXML` is not returned, and `message` is `validation done`. The extra `xmllength` field holds the length of the submitted XML in characters.\n- The submitted text is not parsable XML. The request still succeeds (HTTP 200) with `valid: false` and a single finding in which `schemaFile`, `location`, `id` and `line` are `null`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateXRechnungXmlResult" }, "examples": { "valid": { "summary": "Document is valid", "value": { "message": "validated. (4649)", "isIbanValidInXML": true, "valid": true, "xInvoiceErrors": [] } }, "additionalChecks": { "summary": "Additional checks found problems", "value": { "message": "validated. (4544)", "isIbanValidInXML": true, "valid": false, "xInvoiceErrors": [ { "message": "Verkäufer Vat ID ist ungültig", "schemaFile": "additional-validation", "type": "fatal", "location": "sellerVatId", "id": "", "line": "" }, { "message": "Fälligkeitsdatum oder Zahlungsbedingungen nicht vorhanden.", "schemaFile": "additional-validation", "type": "fatal", "location": "dueDate", "id": "", "line": "" } ] } }, "ruleViolations": { "summary": "Schema or Schematron rules violated", "value": { "message": "validation done", "xmllength": 4413, "valid": false, "xInvoiceErrors": [ { "message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.", "schemaFile": "EN16931-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]", "id": "BR-CO-25", "line": null } ] } }, "notParsable": { "summary": "Not parsable XML", "value": { "message": "validation done", "xmllength": 7, "valid": false, "xInvoiceErrors": [ { "message": "The attached XML content is either corrupt or not parsable.", "schemaFile": null, "type": "fatal", "location": null, "id": null, "line": null } ] } } } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "412": { "description": "No XML data transmitted (`xinvoiceXML` missing or empty).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateXRechnungXmlResult" }, "example": { "message": "no xInvoice data found", "xmllength": 0 } } } } } } }, "/api/v1/zugferd/validateZugferdPdf": { "post": { "tags": [ "Validation" ], "operationId": "validateZugferdPdf", "summary": "Validate ZUGFeRD PDF", "description": "Validates an existing ZUGFeRD PDF including its embedded XML against EN 16931. Returns a pass/fail with a detailed, actionable error list. The response also reports separately whether the IBAN in the invoice is valid (`isIbanValidInZugferd`).\n\nHTTP 200 only means the validation ran: check `valid` for the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateZugferdPdfRequest" }, "example": { "zugferdFile64": "JVBERi0xLjQK...", "comparePDF2XML": true } } } }, "responses": { "200": { "description": "- Validation result. HTTP 200 only means the validation ran – check the `valid` field.\n- Validation passed: `valid` is `true` and `zugferdErrors` is empty.\n- `comparePDF2XML` was `true` but the visible PDF content could not be extracted for the comparison, so nothing was compared: `valid` is `false`, `zugferdErrors` is empty (`numberOfZugferdErrors` is `0`) and `isIbanValidInZugferd` is not returned. Without `comparePDF2XML` the same file is validated normally.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateZugferdPdfResult" }, "examples": { "findings": { "summary": "Validation result with findings", "value": { "valid": false, "message": "File was validated", "isIbanValidInZugferd": true, "numberOfZugferdErrors": 10, "zugferdErrors": [ { "id": "BR-CO-25", "line": null, "location": "/rsm:CrossIndustryInvoice", "message": "In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.", "schemaFile": "EN16931-CII-validation", "type": "fatal" } ] } }, "valid": { "summary": "Validation passed", "value": { "message": "File was validated", "valid": true, "isIbanValidInZugferd": true, "numberOfZugferdErrors": 0, "zugferdErrors": [] } }, "cannotCompare": { "summary": "PDF content could not be extracted for the comparison", "value": { "message": "cannot extract data to validate", "valid": false, "numberOfZugferdErrors": 0, "zugferdErrors": [] } } } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "412": { "description": "- No file was transmitted: `zugferdFile64` is missing or empty.\n- The file has no embedded e-invoice XML — it is a plain PDF (not ZUGFeRD) or not a PDF at all. Nothing is validated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "examples": { "noFile": { "summary": "No file transmitted", "value": { "message": "No file was found for validation." } }, "noXml": { "summary": "No embedded e-invoice XML", "value": { "message": "invoice pdf does not contain einvoice xml" } } } } } } } } }, "/api/v1/zugferd/extractXinvoiceFromZugferdToJson": { "post": { "tags": [ "Extraction" ], "operationId": "extractXRechnungFromZugferdToJson", "summary": "Extract XRechnung data from a ZUGFeRD PDF as JSON", "description": "Extracts the embedded XRechnung XML from a ZUGFeRD PDF and returns it as a structured JSON invoice object.\n\nThe embedded XML is validated as well (`zugferdIsValid`, `zugferdErrorlist`). HTTP 400 is used both for a PDF without usable XML and for embedded XML that fails validation: in the second case the body still carries the extracted data, so read it before discarding the response.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractXRechnungRequest" }, "example": { "zugferd64": "JVBERi0xLjcKJbe3wvUKMyAwIG9iago8PC9UeXBl..." } } } }, "responses": { "200": { "description": "Extraction successful. Returns the embedded XRechnung data as structured JSON, together with the validation result of the embedded XML. Two differences from the `invoice` of `createXinvoiceFromJson`: `deliveryInformation` is always an object here (with empty values when the XML has no delivery data, never `null`), and a line without attributes still carries one empty entry in `itemAttributes`. Values the XML does not contain, such as `priceDetails` without a gross price, come back as `null`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractXRechnungResult" }, "example": { "extractedInvoice": { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": { "deliverToPartyName": "", "deliverToLocationIdentifier": null, "actualDeliveryDate": null, "deliverToAddress": { "deliverToAddressLine1": "", "deliverToAddressLine2": "", "deliverToAddressLine3": "", "deliverToCity": "", "deliverToPostCode": "", "deliverToCountrySubdivision": null, "deliverToCountryCode": "" } }, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [ { "itemAttributeName": null, "itemAttributeValue": null } ] } } ] }, "zugferdIsValid": true, "zugferdErrorlist": [] } } } }, "400": { "description": "- The PDF contains no usable XML — it is a plain PDF (not ZUGFeRD) or not a PDF at all. `extractedInvoice` is `null`, `zugferdIsValid` is `false` and `zugferdErrorlist` holds one finding with `null` in `schemaFile`, `location` and `id`.\n- The PDF contains XML, but the embedded XML fails validation. The status is 400, yet the body still carries the extracted data: `extractedInvoice` is filled, `zugferdIsValid` is `false` and `zugferdErrorlist` lists the findings. So on a 400, read the body before discarding the response. Shortened here — `extractedInvoice` is the same full invoice object as in the 200 response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractXRechnungResult" }, "examples": { "noXml": { "summary": "No usable XML in the PDF", "value": { "extractedInvoice": null, "zugferdIsValid": false, "zugferdErrorlist": [ { "message": "The provided file is not a valid Zugferd PDF or does not contain XML content.", "schemaFile": null, "type": "fatal", "location": null, "id": null, "line": null } ] } }, "invalidXml": { "summary": "Embedded XML fails validation", "value": { "extractedInvoice": { "invoiceNumber": "RE-LEAN-001", "invoiceIssueDate": "2026-02-16T00:00:00+01:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "vatAccountingCurrencyCode": null, "valueAddedTaxPointDate": null, "valueAddedTaxPointDateCode": "", "paymentDueDate": "2026-03-02T00:00:00+01:00", "buyerReference": "BEST-2025-042", "projectReference": { "projectReferenceIdentifier": "", "projectReferenceName": "" }, "contractReference": "", "purchaseOrderReference": "", "salesOrderReference": "", "receivingAdviceReference": "", "despatchAdviceReference": "", "tenderOrLotReference": null, "invoicedObjectIdentifier": null, "buyerAccountingReference": "Sachkonto 12000", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "invoiceNote": [], "processControl": { "businessProcessTypeIdentifier": "", "specificationIdentifier": "" }, "precedingInvoiceReference": [], "seller": { "sellerName": "Ihre Firma GmbH", "sellerTradingName": "", "sellerIdentifier": [], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE123456789", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "", "sellerElectronicAddress": "info@ihre-firma.de", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "", "sellerAddressLine3": "", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@ihre-firma.de" } }, "buyer": { "buyerName": "Müller und Mayer GmbH", "buyerTradingName": "", "buyerIdentifier": "", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@mueller-mayer.de", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerAddressLine2": "", "buyerAddressLine3": "", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@mueller-mayer.de" } }, "payee": { "payeeName": "", "payeeIdentifier": "", "payeeLegalRegistrationIdentifier": "" }, "sellerTaxRepresentativeParty": { "sellerTaxRepresentativeName": "", "sellerTaxRepresentativeVatIdentifier": "", "sellerTaxRepresentativePostalAddress": { "taxRepresentativeAddressLine1": "", "taxRepresentativeAddressLine2": "", "taxRepresentativeAddressLine3": "", "taxRepresentativeCity": "", "taxRepresentativePostCode": "", "taxRepresentativeCountrySubdivision": "", "taxRepresentativeCountryCode": "" } }, "deliveryInformation": { "deliverToPartyName": "", "deliverToLocationIdentifier": null, "actualDeliveryDate": null, "deliverToAddress": { "deliverToAddressLine1": "", "deliverToAddressLine2": "", "deliverToAddressLine3": "", "deliverToCity": "", "deliverToPostCode": "", "deliverToCountrySubdivision": null, "deliverToCountryCode": "" } }, "invoicingPeriod": { "invoicingPeriodStartDate": null, "invoicingPeriodEndDate": null }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Ihre Firma GmbH", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ], "paymentCardInformation": { "paymentCardPrimaryAccountNumber": "", "paymentCardHolderName": "" }, "directDebit": { "mandateReferenceIdentifier": "", "bankAssignedCreditorIdentifier": "", "debitedAccountIdentifier": "" } }, "documentLevelAllowances": [], "documentLevelCharges": [], "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalVatAmountInAccountingCurrency": 0, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19, "vatExemptionReasonText": "", "vatExemptionReasonCode": "" } ], "additionalSupportingDocuments": [], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "", "invoiceLineObjectIdentifier": "", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "", "invoiceLineBuyerAccountingReference": "", "invoiceLinePeriod": { "invoiceLinePeriodStartDate": null, "invoiceLinePeriodEndDate": null }, "invoiceLineAllowances": [], "invoiceLineCharges": [], "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "", "itemSellersIdentifier": "", "itemBuyersIdentifier": "", "itemStandardIdentifier": "", "itemStandardIdentifierSchemeIdentifier": "", "itemClassificationIdentifier": [], "itemCountryOfOrigin": "", "itemAttributes": [ { "itemAttributeName": null, "itemAttributeValue": null } ] } } ] }, "zugferdIsValid": false, "zugferdErrorlist": [ { "message": "Business process MUST be provided.", "schemaFile": "XRechnung-CII-validation", "type": "fatal", "location": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}ExchangedDocumentContext[1]", "id": "PEPPOL-EN16931-R001", "line": null } ] } } } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "412": { "description": "No file was transmitted: `zugferd64` is missing or empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "no data." } } } }, "500": { "description": "Internal server error during extraction." } } } }, "/api/v1/delivery": { "post": { "tags": [ "Email Delivery" ], "operationId": "sendEmail", "summary": "Send a standalone email", "description": "Sends an email to the given recipients, independent of generating an invoice document. Requires the email delivery add-on. Uses an extended transport object compared to the generation endpoints (fields nested under `transport.email`, plus a free-form `content` object for placeholders).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" }, "example": { "transport": { "type": "email", "useTransport": true, "email": { "sender": "support@rechnungsapi.de", "senderName": "rechnungsAPI", "receiver": "empfaenger@domain.de", "cc": "cc1@domain.de, cc2@domain.de", "bcc": "bcc1@domain.de, bcc2@domain.de", "subject": "testrechnung vom {invoicedate}. Rechnungsnummer: {invoicenumber}", "message": "Hallo {lastname},\nIhre Rechnung {invoicenumber} vom {invoicedate} befindet sich im Anhang.", "content": { "invoicedate": "02.09.2026", "invoicenumber": "RE-2024-001", "lastname": "Mustermann" }, "attachments": [ { "fileBase64": "", "fileName": "file1.pdf" } ] } } } } } }, "responses": { "200": { "description": "- Email sent. resendToken can be used to resend the same email later via sendEmailWithZugferdData.\n- useTransport omitted or false — nothing was sent. An empty body is answered the same way (HTTP 200, not an error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailResult" }, "examples": { "sent": { "summary": "Email sent", "value": { "message": "email sent", "resendToken": "RjBcXJ9k2mZpQ7vT4uYs1LwNdHo6EaKf" } }, "nothingToDo": { "summary": "useTransport omitted or false: nothing was sent", "value": { "message": "nothing to do. Send option not set to send." } } } } } }, "400": { "description": "Sending failed. Details may be in the message text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "sending failed" } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "403": { "description": "The email delivery add-on is not booked for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "service not ordered" } } } } } } }, "/api/v1/sendEmailWithZugferdData": { "post": { "tags": [ "Email Delivery" ], "operationId": "resendEmail", "summary": "Resend a previously sent email", "description": "Resends the email of a previously generated document without regenerating it. Use the `resendToken` returned by `createXRechnungFromJson`, `createZugferdFromJson`, `createInvoicePdfFromJson` or `sendEmail`. The token is only present when `transport` was used and a valid document was produced.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendEmailRequest" } } } }, "responses": { "200": { "description": "Email resent to the original recipients (receiver, cc, bcc).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "resend" } } } }, "401": { "$ref": "#/components/responses/GatewayUnauthorized" }, "403": { "description": "Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "invalid token" } } } }, "404": { "description": "Nothing to resend. An unknown `resendToken` answers `resend token not found`; a request without a token answers `invoice email entry not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" }, "example": { "message": "resend token not found" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token from the dashboard (*Profile*), sent as `Authorization: Bearer `." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Any unique string (e.g. a UUID). Replays the cached response for an identical request within 24 hours without consuming credits; a different body under the same key is rejected with 409.", "example": "5f0c2a3e-8a1b-4c57-9f0e-6d2b7f1a9c11" } }, "responses": { "AnalysisBadRequest": { "description": "No file in the request (`INVALID_REQUEST`). Not retryable without changing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisError" }, "examples": { "INVALID_REQUEST": { "summary": "INVALID_REQUEST", "description": "error.code INVALID_REQUEST — no file in the request: the field is missing, null, empty, or whitespace-only. Not retryable without changing the request.", "value": { "success": false, "error": { "code": "INVALID_REQUEST", "userMessage": "Es wurde keine Datei übermittelt. Bitte senden Sie das Dokument als Base64 im Feld \"pdfInvoiceBase64\".", "detail": "Im Request fehlt das Feld \"pdfInvoiceBase64\".", "reference": "REA-144845" } } } } } } }, "AnalysisUnauthorized": { "description": "Invalid token or exhausted quota (`UNAUTHORIZED`). Not retryable: fix the credentials or top up the quota first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisError" }, "examples": { "UNAUTHORIZED": { "summary": "UNAUTHORIZED", "description": "error.code UNAUTHORIZED — no token, an invalid token, or your quota is exhausted. Not retryable — fix the credentials or top up quota first.", "value": { "success": false, "error": { "code": "UNAUTHORIZED", "userMessage": "Zugriff nicht möglich: Ihr Zugang ist nicht berechtigt oder Ihr Kontingent ist aufgebraucht. Bitte wenden Sie sich an den Support.", "detail": "Die Zugangsprüfung hat den Zugriff abgelehnt.", "reference": "REA-144846" } } } } } } }, "AnalysisPayloadTooLarge": { "description": "Decoded file larger than 11 MiB (`FILE_TOO_LARGE`). Not retryable with the same file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisError" }, "examples": { "FILE_TOO_LARGE": { "summary": "FILE_TOO_LARGE", "description": "error.code FILE_TOO_LARGE — the decoded file is over the 11 MB (≈14.7 MB base64) size limit. The enforced limit is 11 MB — rely on that figure rather than the one in userMessage. Not retryable with the same file.", "value": { "success": false, "error": { "code": "FILE_TOO_LARGE", "userMessage": "Die Datei ist zu groß. Bitte laden Sie ein Dokument mit maximal 20 MB hoch.", "detail": "Die Datei ist 12.061.931 Bytes groß; erlaubt sind maximal 11.534.336 Bytes.", "reference": "REA-144847" } } } } } } }, "AnalysisUnprocessable": { "description": "The document could not be processed. `error.code` is `PDF_CORRUPT`, `PDF_ENCRYPTED`, `PDF_NO_TEXT` or `EXTRACTION_LOW_CONFIDENCE`. Not retryable with the same file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisError" }, "examples": { "PDF_CORRUPT": { "summary": "PDF_CORRUPT", "description": "error.code PDF_CORRUPT — the file is truncated, malformed, or not a readable PDF/PNG/JPEG/TIFF; detail names the specific fault (e.g. missing %%EOF, missing PNG IEND, corrupt cross-reference table). Do not retry — the same bytes will always fail. Open the file locally to check it, then re-export and re-upload.", "value": { "success": false, "error": { "code": "PDF_CORRUPT", "userMessage": "Wir konnten diese Datei nicht lesen – sie scheint beschädigt oder unvollständig zu sein. Bitte öffnen Sie die Datei kurz lokal zur Kontrolle, exportieren bzw. laden Sie sie erneut hoch und versuchen Sie es noch einmal.", "detail": "Das übermittelte PDF ist unvollständig: 50.666 Bytes empfangen, davon sind die letzten 1.514 Bytes leer. Die PDF-Endmarkierung (%%EOF) fehlt.", "reference": "REA-144848" } } }, "PDF_ENCRYPTED": { "summary": "PDF_ENCRYPTED", "description": "error.code PDF_ENCRYPTED — the PDF is password-protected. Not retryable until the password is removed.", "value": { "success": false, "error": { "code": "PDF_ENCRYPTED", "userMessage": "Diese PDF-Datei ist passwortgeschützt und kann nicht gelesen werden. Bitte entfernen Sie den Passwortschutz und laden Sie die Datei erneut hoch.", "detail": "Das PDF ist passwortgeschützt bzw. verschlüsselt und kann nicht gelesen werden.", "reference": "REA-144849" } } }, "PDF_NO_TEXT": { "summary": "PDF_NO_TEXT", "description": "error.code PDF_NO_TEXT — the file parsed fine but no usable text was found, typically a scan or photo with no text layer that OCR couldn't read either. userMessage differs slightly for documents vs. photos (the example shows the photo variant). Not retryable with the same file.", "value": { "success": false, "error": { "code": "PDF_NO_TEXT", "userMessage": "In diesem Bild konnte kein Text erkannt werden. Bitte laden Sie eine schärfere oder höher aufgelöste Aufnahme hoch – oder idealerweise das Original-PDF.", "reference": "REA-144850" } } }, "EXTRACTION_LOW_CONFIDENCE": { "summary": "EXTRACTION_LOW_CONFIDENCE", "description": "error.code EXTRACTION_LOW_CONFIDENCE — text was extracted but too degraded to map to invoice fields reliably. Do not retry with the same file — send a better copy (higher resolution, straight-on, ideally the original PDF instead of a scan or photo).", "value": { "success": false, "error": { "code": "EXTRACTION_LOW_CONFIDENCE", "userMessage": "Das Dokument konnte nur unzureichend gelesen werden – die Qualität reicht für eine verlässliche Rechnungserkennung nicht aus. Bitte laden Sie eine bessere Vorlage hoch (höhere Auflösung, gerade ausgerichtet, idealerweise das Original-PDF statt eines Scans oder Fotos).", "detail": "Der erkannte Text war zu fehlerhaft, um die Rechnungsfelder zuverlässig zuzuordnen.", "reference": "REA-144851" } } } } } } }, "AnalysisUnknownError": { "description": "Unclassified failure (`UNKNOWN_ERROR`). Retry once; if it happens again, contact support with `error.reference`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisError" }, "examples": { "UNKNOWN_ERROR": { "summary": "UNKNOWN_ERROR", "description": "error.code UNKNOWN_ERROR — unclassified failure. Retry once; if it happens again, contact support with the reference.", "value": { "success": false, "error": { "code": "UNKNOWN_ERROR", "detail": "Die Ursache konnte nicht automatisch bestimmt werden.", "reference": "REA-144852" } } } } } } }, "AnalysisTemporaryError": { "description": "Temporary problem on our side (`PROCESSING_TEMPORARY_ERROR`). Retry later with exponential backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisError" }, "examples": { "PROCESSING_TEMPORARY_ERROR": { "summary": "PROCESSING_TEMPORARY_ERROR", "description": "error.code PROCESSING_TEMPORARY_ERROR — an issue on our side: the access verifier was unreachable, an internal step failed, a timeout occurred, or the model's response couldn't be parsed. Retry is appropriate — wait a few minutes and use exponential backoff.", "value": { "success": false, "error": { "code": "PROCESSING_TEMPORARY_ERROR", "userMessage": "Bei der Verarbeitung ist vorübergehend ein Problem aufgetreten. Bitte versuchen Sie es in einigen Minuten erneut. Falls das Problem weiterhin besteht, kontaktieren Sie bitte den Support unter Angabe der Referenz REA-144842.", "reference": "REA-144842" } } } } } } }, "GatewayUnauthorized": { "description": "Missing or invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" }, "example": { "error": "Invalid token." } } } }, "PaymentRequired": { "description": "No API access: no active subscription or no credits left. Contact support." } }, "schemas": { "Invoice": { "type": "object", "description": "Invoice data following the EN 16931 semantic model. Every property carries its Business Term id (BT-nn, or BG-nn for groups). Properties marked required are mandatory for a valid XRechnung/ZUGFeRD document; optional groups can be omitted entirely. Dates are accepted as `YYYYMMDD`, `YYYY-MM-DD` or `YYYY-MM-DDT00:00:00` (local date-time, no timezone offset; the form the RechnungsAPI playground sends). Amounts are JSON numbers with a dot as decimal separator.", "required": [ "invoiceNumber", "invoiceIssueDate", "invoiceTypeCode", "invoiceCurrencyCode", "buyerReference", "seller", "buyer", "paymentInstructions", "documentTotals", "vatBreakdown", "invoiceLine" ], "properties": { "invoiceNumber": { "type": "string", "description": "BT-1. Unique invoice identifier assigned by the seller." }, "invoiceIssueDate": { "type": "string", "example": "2026-10-14T00:00:00", "description": "BT-2. Date the invoice was issued. Format YYYYMMDD or YYYY-MM-DD. Also accepted: `YYYY-MM-DDT00:00:00` (local date-time, no timezone offset), which is what the playground sends." }, "invoiceTypeCode": { "type": "string", "description": "BT-3. Type code: 380 = invoice, 381 = credit note, 384 = corrected invoice." }, "invoiceCurrencyCode": { "type": "string", "description": "BT-5. ISO 4217 currency code of the invoice (e.g. EUR)." }, "vatAccountingCurrencyCode": { "type": "string", "description": "BT-6. Currency used for VAT accounting when different from the invoice currency.", "nullable": true }, "valueAddedTaxPointDate": { "type": "string", "example": "2026-10-14T00:00:00", "description": "BT-7. VAT point date – the date the VAT becomes due. Send as `YYYY-MM-DDT00:00:00` (no timezone offset).", "nullable": true }, "valueAddedTaxPointDateCode": { "type": "string", "description": "BT-8. Code identifying which date determines the VAT point.", "nullable": true }, "paymentDueDate": { "type": "string", "example": "2026-10-14T00:00:00", "description": "BT-9. Date payment is due. Required if there is an outstanding amount and no payment terms text. Same date formats as `invoiceIssueDate`.", "nullable": true }, "buyerReference": { "type": "string", "description": "BT-10. Buyer reference (Leitweg-ID for German public sector, otherwise any reference agreed with the buyer)." }, "projectReference": { "$ref": "#/components/schemas/ProjectReference" }, "contractReference": { "type": "string", "description": "BT-12. Identifier of the underlying contract.", "nullable": true }, "purchaseOrderReference": { "type": "string", "description": "BT-13. Buyer purchase order reference.", "nullable": true }, "salesOrderReference": { "type": "string", "description": "BT-14. Seller sales order reference.", "nullable": true }, "receivingAdviceReference": { "type": "string", "description": "BT-15", "nullable": true }, "despatchAdviceReference": { "type": "string", "description": "BT-16", "nullable": true }, "tenderOrLotReference": { "type": "string", "description": "BT-17. Tender or lot reference.", "nullable": true }, "invoicedObjectIdentifier": { "type": "string", "description": "BT-18", "nullable": true }, "buyerAccountingReference": { "type": "string", "description": "BT-19. Accounting reference text supplied by the buyer.", "nullable": true }, "paymentTerms": { "type": "string", "description": "BT-20. Payment terms in free text. Required if BT-9 is omitted.", "nullable": true }, "invoiceNote": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceNote" }, "description": "BT-21/22. Free-text notes about the invoice, each with an optional subject code.", "nullable": true }, "processControl": { "$ref": "#/components/schemas/ProcessControl" }, "precedingInvoiceReference": { "type": "array", "items": { "$ref": "#/components/schemas/PrecedingInvoiceReference" }, "description": "BT-25/26. Reference to a preceding invoice (for corrections / credit notes).", "nullable": true }, "seller": { "$ref": "#/components/schemas/Seller" }, "buyer": { "$ref": "#/components/schemas/Buyer" }, "payee": { "$ref": "#/components/schemas/Payee" }, "sellerTaxRepresentativeParty": { "$ref": "#/components/schemas/SellerTaxRepresentativeParty" }, "deliveryInformation": { "$ref": "#/components/schemas/DeliveryInformation" }, "invoicingPeriod": { "$ref": "#/components/schemas/InvoicingPeriod" }, "paymentInstructions": { "$ref": "#/components/schemas/PaymentInstructions" }, "documentLevelAllowances": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLevelAllowance" }, "description": "BG-20 / BT-92 to BT-98. Document-level allowances/discounts.", "nullable": true }, "documentLevelCharges": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLevelCharge" }, "description": "BG-21 / BT-99 to BT-105. Document-level charges/surcharges.", "nullable": true }, "documentTotals": { "$ref": "#/components/schemas/DocumentTotals" }, "vatBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/VatBreakdown" }, "minItems": 1 }, "additionalSupportingDocuments": { "type": "array", "items": { "$ref": "#/components/schemas/AdditionalSupportingDocument" }, "description": "BG-24 / BT-122 to BT-125. Supporting documents (timesheet, delivery note, etc.). Provide either an external URL or a base64 attachment.", "nullable": true }, "invoiceLine": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" }, "minItems": 1 } }, "example": { "invoiceNumber": "RE-2025-001", "invoiceIssueDate": "2025-02-09T00:00:00", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "paymentDueDate": "2025-02-23T00:00:00", "buyerReference": "BEST-2025-042", "paymentTerms": "Zahlung innerhalb von 14 Tagen nach Rechnungsdatum.", "processControl": { "businessProcessTypeIdentifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0", "specificationIdentifier": "urn:cen.eu:en16931:2017" }, "seller": { "sellerName": "Musterfirma Software", "sellerTradingName": "Ihre Firma", "sellerIdentifier": [ "DE1111111" ], "sellerLegalRegistrationIdentifier": "HRB 67890 B", "sellerVatIdentifier": "DE115235681", "sellerTaxRegistrationIdentifier": "12/345/67890", "sellerAdditionalLegalInformation": "Geschäftsführer: Max Mustermann", "sellerElectronicAddress": "info@musterfirma.example", "sellerPostalAddress": { "sellerAddressLine1": "Musterstraße 1", "sellerAddressLine2": "2. OG", "sellerCity": "Berlin", "sellerPostCode": "12345", "sellerCountrySubdivision": "BE", "sellerCountryCode": "DE" }, "sellerContact": { "sellerContactPoint": "Vertrieb", "sellerContactTelephoneNumber": "+49 30 9876543", "sellerContactEmailAddress": "info@musterfirma.example" } }, "buyer": { "buyerName": "Beispielkunde Tierarztpraxis", "buyerIdentifier": "DE2222222", "buyerLegalRegistrationIdentifier": "HRB 12345", "buyerVatIdentifier": "DE987654321", "buyerElectronicAddress": "rechnung@beispielkunde.example", "buyerPostalAddress": { "buyerAddressLine1": "Kundenstraße 42", "buyerCity": "Berlin", "buyerPostCode": "10115", "buyerCountrySubdivision": "BE", "buyerCountryCode": "DE" }, "buyerContact": { "buyerContactPoint": "Einkauf", "buyerContactTelephoneNumber": "+49 30 12345678", "buyerContactEmailAddress": "rechnung@beispielkunde.example" } }, "deliveryInformation": { "actualDeliveryDate": "2025-02-09T00:00:00", "deliverToAddress": { "deliverToAddressLine1": "Kundenstraße 42", "deliverToCity": "Berlin", "deliverToPostCode": "10115", "deliverToCountrySubdivision": "BE", "deliverToCountryCode": "DE" } }, "paymentInstructions": { "paymentMeansTypeCode": "58", "paymentMeansText": "SEPA-Überweisung", "remittanceInformation": "RE-2025-001", "creditTransfer": [ { "paymentAccountIdentifier": "DE89370400440532013000", "paymentAccountName": "Musterfirma Software", "paymentServiceProviderIdentifier": "COBADEFFXXX" } ] }, "documentTotals": { "sumOfInvoiceLineNetAmount": 1799, "sumOfAllowancesOnDocumentLevel": 0, "sumOfChargesOnDocumentLevel": 0, "invoiceTotalAmountWithoutVat": 1799, "invoiceTotalVatAmount": 341.81, "invoiceTotalAmountWithVat": 2140.81, "paidAmount": 0, "roundingAmount": 0, "amountDueForPayment": 2140.81 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 1799, "vatCategoryTaxAmount": 341.81, "vatCategoryCode": "S", "vatCategoryRate": 19 } ], "additionalSupportingDocuments": [ { "supportingDocumentReference": "LS-2025-0042", "supportingDocumentTypeCodex": 916, "supportingDocumentDescription": "Lieferschein zur Rechnung", "externalDocumentLocation": "https://musterfirma.example/lieferschein-2025-0042.pdf" } ], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoiceLineNote": "Beratung und Projektbegleitung", "invoicedQuantity": 10, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1200, "referencedPurchaseOrderLineReference": "PO-001-1", "priceDetails": { "itemNetPrice": 120, "itemPriceDiscount": 0, "itemGrossPrice": 120, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "HUR" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratung & Projektbegleitung", "itemDescription": "Dienstleistung", "itemSellersIdentifier": "SRV-001" } }, { "invoiceLineIdentifier": "2", "invoicedQuantity": 1, "invoicedQuantityUnitOfMeasureCode": "C62", "invoiceLineNetAmount": 599, "referencedPurchaseOrderLineReference": "PO-001-2", "priceDetails": { "itemNetPrice": 599, "itemPriceDiscount": 0, "itemGrossPrice": 599, "itemPriceBaseQuantity": 1, "itemPriceBaseQuantityUnitOfMeasure": "C62" }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Software-Lizenz (Jahresabo)", "itemDescription": "Lizenz", "itemSellersIdentifier": "LIC-2025" } } ] } }, "ProjectReference": { "type": "object", "properties": { "projectReferenceIdentifier": { "type": "string", "description": "BT-11", "nullable": true }, "projectReferenceName": { "type": "string", "description": "BT-11-0", "nullable": true } }, "description": "BT-11. Optional project reference (identifier + name)." }, "InvoiceNote": { "type": "object", "properties": { "invoiceNoteSubjectCode": { "type": "string", "description": "BT-21", "nullable": true }, "invoiceNote": { "type": "string", "description": "BT-22", "nullable": true } } }, "ProcessControl": { "type": "object", "properties": { "businessProcessTypeIdentifier": { "type": "string", "description": "BT-23", "nullable": true }, "specificationIdentifier": { "type": "string", "description": "BT-24", "nullable": true } }, "description": "BT-23/24. Business-process and specification identifiers." }, "PrecedingInvoiceReference": { "type": "object", "properties": { "precedingInvoiceReference": { "type": "string", "description": "BT-25", "nullable": true }, "precedingInvoiceIssueDate": { "type": "string", "example": "2026-10-14T00:00:00", "description": "BT-26", "nullable": true } } }, "Seller": { "type": "object", "required": [ "sellerName", "sellerVatIdentifier", "sellerElectronicAddress", "sellerPostalAddress" ], "properties": { "sellerName": { "type": "string", "description": "BT-27. Registered legal name of the seller." }, "sellerTradingName": { "type": "string", "description": "BT-28. Trading name if different from the legal name.", "nullable": true }, "sellerIdentifier": { "type": "array", "items": { "type": "string" }, "description": "BT-29. Additional seller identifiers (e.g. GLN).", "nullable": true }, "sellerLegalRegistrationIdentifier": { "type": "string", "description": "BT-30. Commercial registration number.", "nullable": true }, "sellerVatIdentifier": { "type": "string", "description": "BT-31. Seller VAT identification number." }, "sellerTaxRegistrationIdentifier": { "type": "string", "description": "BT-32. Tax registration identifier (e.g. Steuernummer).", "nullable": true }, "sellerAdditionalLegalInformation": { "type": "string", "description": "BT-33. Additional legal text (managing directors, registry court, etc.).", "nullable": true }, "sellerElectronicAddress": { "type": "string", "description": "BT-34. Electronic address of the seller (typically an e-invoice mailbox or email)." }, "sellerPostalAddress": { "$ref": "#/components/schemas/SellerPostalAddress" }, "sellerContact": { "$ref": "#/components/schemas/SellerContact" } } }, "SellerPostalAddress": { "type": "object", "required": [ "sellerCity", "sellerPostCode", "sellerCountryCode" ], "properties": { "sellerAddressLine1": { "type": "string", "description": "BT-35. Street and number (line 1).", "nullable": true }, "sellerAddressLine2": { "type": "string", "description": "BT-36", "nullable": true }, "sellerAddressLine3": { "type": "string", "description": "BT-162", "nullable": true }, "sellerCity": { "type": "string", "description": "BT-37. City." }, "sellerPostCode": { "type": "string", "description": "BT-38. Postal code." }, "sellerCountrySubdivision": { "type": "string", "description": "BT-39", "nullable": true }, "sellerCountryCode": { "type": "string", "description": "BT-40. ISO 3166-1 alpha-2 country code (e.g. DE)." } } }, "SellerContact": { "type": "object", "properties": { "sellerContactPoint": { "type": "string", "description": "BT-41", "nullable": true }, "sellerContactTelephoneNumber": { "type": "string", "description": "BT-42", "nullable": true }, "sellerContactEmailAddress": { "type": "string", "description": "BT-43", "nullable": true } }, "description": "BT-41/42/43. Contact point: name, phone, email." }, "Buyer": { "type": "object", "required": [ "buyerName", "buyerElectronicAddress", "buyerPostalAddress" ], "properties": { "buyerName": { "type": "string", "description": "BT-44. Registered legal name of the buyer." }, "buyerTradingName": { "type": "string", "description": "BT-45. Trading name if different from the legal name.", "nullable": true }, "buyerIdentifier": { "type": "string", "description": "BT-46. Additional buyer identifier.", "nullable": true }, "buyerLegalRegistrationIdentifier": { "type": "string", "description": "BT-47. Buyer commercial registration number.", "nullable": true }, "buyerVatIdentifier": { "type": "string", "description": "BT-48. Buyer VAT identification number.", "nullable": true }, "buyerElectronicAddress": { "type": "string", "description": "BT-49. Electronic address of the buyer." }, "buyerPostalAddress": { "$ref": "#/components/schemas/BuyerPostalAddress" }, "buyerContact": { "$ref": "#/components/schemas/BuyerContact" } } }, "BuyerPostalAddress": { "type": "object", "required": [ "buyerCity", "buyerPostCode", "buyerCountryCode" ], "properties": { "buyerAddressLine1": { "type": "string", "description": "BT-50. Street and number (line 1).", "nullable": true }, "buyerAddressLine2": { "type": "string", "description": "BT-51", "nullable": true }, "buyerAddressLine3": { "type": "string", "description": "BT-163", "nullable": true }, "buyerCity": { "type": "string", "description": "BT-52. City." }, "buyerPostCode": { "type": "string", "description": "BT-53. Postal code." }, "buyerCountrySubdivision": { "type": "string", "description": "BT-54", "nullable": true }, "buyerCountryCode": { "type": "string", "description": "BT-55. ISO 3166-1 alpha-2 country code." } } }, "BuyerContact": { "type": "object", "properties": { "buyerContactPoint": { "type": "string", "description": "BT-56", "nullable": true }, "buyerContactTelephoneNumber": { "type": "string", "description": "BT-57", "nullable": true }, "buyerContactEmailAddress": { "type": "string", "description": "BT-58", "nullable": true } }, "description": "BT-56/57/58. Contact point: name, phone, email." }, "Payee": { "type": "object", "properties": { "payeeName": { "type": "string", "description": "BT-59", "nullable": true }, "payeeIdentifier": { "type": "string", "description": "BT-60", "nullable": true }, "payeeLegalRegistrationIdentifier": { "type": "string", "description": "BT-61", "nullable": true } }, "description": "BG-10 / BT-59 to BT-61. Payee party if different from the seller." }, "SellerTaxRepresentativeParty": { "type": "object", "properties": { "sellerTaxRepresentativeName": { "type": "string", "description": "BT-62", "nullable": true }, "sellerTaxRepresentativeVatIdentifier": { "type": "string", "description": "BT-63", "nullable": true }, "sellerTaxRepresentativePostalAddress": { "$ref": "#/components/schemas/TaxRepresentativePostalAddress" } }, "description": "BG-11 / BT-62 to BT-69. Seller's tax representative (typically for non-EU sellers)." }, "TaxRepresentativePostalAddress": { "type": "object", "properties": { "taxRepresentativeAddressLine1": { "type": "string", "description": "BT-64", "nullable": true }, "taxRepresentativeAddressLine2": { "type": "string", "description": "BT-65", "nullable": true }, "taxRepresentativeAddressLine3": { "type": "string", "description": "BT-164", "nullable": true }, "taxRepresentativeCity": { "type": "string", "description": "BT-66", "nullable": true }, "taxRepresentativePostCode": { "type": "string", "description": "BT-67", "nullable": true }, "taxRepresentativeCountrySubdivision": { "type": "string", "description": "BT-68", "nullable": true }, "taxRepresentativeCountryCode": { "type": "string", "description": "BT-69", "nullable": true } } }, "DeliveryInformation": { "type": "object", "properties": { "deliverToPartyName": { "type": "string", "description": "BT-70", "nullable": true }, "deliverToLocationIdentifier": { "type": "string", "description": "BT-71", "nullable": true }, "actualDeliveryDate": { "type": "string", "example": "2026-10-14T00:00:00", "description": "BT-72", "nullable": true }, "deliverToAddress": { "$ref": "#/components/schemas/DeliverToAddress" } }, "description": "BG-13 / BT-70 to BT-80. Delivery party, location and actual delivery date." }, "DeliverToAddress": { "type": "object", "properties": { "deliverToAddressLine1": { "type": "string", "description": "BT-75", "nullable": true }, "deliverToAddressLine2": { "type": "string", "description": "BT-76", "nullable": true }, "deliverToAddressLine3": { "type": "string", "description": "BT-165", "nullable": true }, "deliverToCity": { "type": "string", "description": "BT-77", "nullable": true }, "deliverToPostCode": { "type": "string", "description": "BT-78", "nullable": true }, "deliverToCountrySubdivision": { "type": "string", "description": "BT-79", "nullable": true }, "deliverToCountryCode": { "type": "string", "description": "BT-80", "nullable": true } } }, "InvoicingPeriod": { "type": "object", "properties": { "invoicingPeriodStartDate": { "type": "string", "example": "2026-10-14T00:00:00", "description": "BT-73", "nullable": true }, "invoicingPeriodEndDate": { "type": "string", "example": "2026-10-14T00:00:00", "description": "BT-74", "nullable": true } }, "description": "BG-14 / BT-73, BT-74. Invoice-level service period." }, "PaymentInstructions": { "type": "object", "required": [ "paymentMeansTypeCode" ], "properties": { "paymentMeansTypeCode": { "type": "string", "description": "BT-81. UNTDID 4461 payment means code (e.g. 58 = SEPA credit transfer, 30 = credit transfer, 48 = bank card)." }, "paymentMeansText": { "type": "string", "description": "BT-82. Free-text payment instructions.", "nullable": true }, "remittanceInformation": { "type": "string", "description": "BT-83. Remittance information (used by the buyer when paying).", "nullable": true }, "creditTransfer": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTransfer" }, "nullable": true }, "paymentCardInformation": { "$ref": "#/components/schemas/PaymentCardInformation" }, "directDebit": { "$ref": "#/components/schemas/DirectDebit" } } }, "CreditTransfer": { "type": "object", "properties": { "paymentAccountIdentifier": { "type": "string", "description": "BT-84. IBAN or bank account number receiving the payment.", "nullable": true }, "paymentAccountName": { "type": "string", "description": "BT-85. Account holder name.", "nullable": true }, "paymentServiceProviderIdentifier": { "type": "string", "description": "BT-86. BIC of the receiving bank.", "nullable": true } } }, "PaymentCardInformation": { "type": "object", "properties": { "paymentCardPrimaryAccountNumber": { "type": "string", "description": "BT-87", "nullable": true }, "paymentCardHolderName": { "type": "string", "description": "BT-88", "nullable": true } }, "description": "BT-87/88. Card payment information (PAN, holder)." }, "DirectDebit": { "type": "object", "properties": { "mandateReferenceIdentifier": { "type": "string", "description": "BT-89", "nullable": true }, "bankAssignedCreditorIdentifier": { "type": "string", "description": "BT-90", "nullable": true }, "debitedAccountIdentifier": { "type": "string", "description": "BT-91", "nullable": true } }, "description": "BT-89/90/91. Direct-debit mandate information." }, "DocumentLevelAllowance": { "type": "object", "properties": { "documentLevelAllowanceAmount": { "type": "number", "description": "BT-92", "nullable": true }, "documentLevelAllowanceBaseAmount": { "type": "number", "description": "BT-93", "nullable": true }, "documentLevelAllowancePercentage": { "type": "number", "description": "BT-94", "nullable": true }, "documentLevelAllowanceVatCategoryCode": { "type": "string", "description": "BT-95", "nullable": true }, "documentLevelAllowanceVatRate": { "type": "number", "description": "BT-96", "nullable": true }, "documentLevelAllowanceReason": { "type": "string", "description": "BT-97", "nullable": true }, "documentLevelAllowanceReasonCode": { "type": "string", "description": "BT-98", "nullable": true } } }, "DocumentLevelCharge": { "type": "object", "properties": { "documentLevelChargeAmount": { "type": "number", "description": "BT-99", "nullable": true }, "documentLevelChargeBaseAmount": { "type": "number", "description": "BT-100", "nullable": true }, "documentLevelChargePercentage": { "type": "number", "description": "BT-101", "nullable": true }, "documentLevelChargeVatCategoryCode": { "type": "string", "description": "BT-102", "nullable": true }, "documentLevelChargeVatRate": { "type": "number", "description": "BT-103", "nullable": true }, "documentLevelChargeReason": { "type": "string", "description": "BT-104", "nullable": true }, "documentLevelChargeReasonCode": { "type": "string", "description": "BT-105", "nullable": true } } }, "DocumentTotals": { "type": "object", "required": [ "sumOfInvoiceLineNetAmount", "invoiceTotalAmountWithoutVat", "invoiceTotalVatAmount", "invoiceTotalAmountWithVat", "amountDueForPayment" ], "properties": { "sumOfInvoiceLineNetAmount": { "type": "number", "description": "BT-106. Sum of all invoice line net amounts." }, "sumOfAllowancesOnDocumentLevel": { "type": "number", "description": "BT-107. Sum of allowances at document level.", "nullable": true }, "sumOfChargesOnDocumentLevel": { "type": "number", "description": "BT-108. Sum of charges at document level.", "nullable": true }, "invoiceTotalAmountWithoutVat": { "type": "number", "description": "BT-109. Invoice total without VAT (net total)." }, "invoiceTotalVatAmount": { "type": "number", "description": "BT-110. Total VAT amount." }, "invoiceTotalVatAmountInAccountingCurrency": { "type": "number", "description": "BT-111. Total VAT in the accounting currency (BT-6) if different from BT-5.", "nullable": true }, "invoiceTotalAmountWithVat": { "type": "number", "description": "BT-112. Invoice total including VAT (gross total)." }, "paidAmount": { "type": "number", "description": "BT-113. Amount already paid.", "nullable": true }, "roundingAmount": { "type": "number", "description": "BT-114. Rounding adjustment.", "nullable": true }, "amountDueForPayment": { "type": "number", "description": "BT-115. Amount due for payment (BT-112 − BT-113 + BT-114)." } } }, "VatBreakdown": { "type": "object", "required": [ "vatCategoryTaxableAmount", "vatCategoryTaxAmount", "vatCategoryCode", "vatCategoryRate" ], "properties": { "vatCategoryTaxableAmount": { "type": "number", "description": "BT-116. Taxable amount for this VAT category." }, "vatCategoryTaxAmount": { "type": "number", "description": "BT-117. VAT amount for this category (BT-116 × BT-119 / 100)." }, "vatCategoryCode": { "type": "string", "description": "BT-118. VAT category code: S (standard), Z (zero), E (exempt), AE (reverse charge), K (intra-community), G (export), O (out of scope), L (Canary Islands), M (Ceuta/Melilla)." }, "vatCategoryRate": { "type": "number", "description": "BT-119. VAT rate as a percentage (e.g. 19 for 19%)." }, "vatExemptionReasonText": { "type": "string", "description": "BT-120. Required when the category is exempt or zero-rated. Free-text reason.", "nullable": true }, "vatExemptionReasonCode": { "type": "string", "description": "BT-121. Coded exemption reason (e.g. VATEX-EU-AE, VATEX-EU-IC).", "nullable": true } } }, "AdditionalSupportingDocument": { "type": "object", "properties": { "supportingDocumentReference": { "type": "string", "description": "BT-122", "nullable": true }, "supportingDocumentDescription": { "type": "string", "description": "BT-123", "nullable": true }, "externalDocumentLocation": { "type": "string", "description": "BT-124", "nullable": true }, "attachedDocument": { "type": "string", "description": "BT-125", "nullable": true }, "supportingDocumentTypeCodex": { "type": "integer", "description": "Document type code (UNTDID 1001, e.g. 916 = referenced document, 130 = invoice data sheet).", "nullable": true }, "attachedDocumentFilename": { "type": "string", "description": "File name of the attached document (BT-125) when `attachedDocument` is sent.", "nullable": true } } }, "InvoiceLine": { "type": "object", "required": [ "invoiceLineIdentifier", "invoicedQuantity", "invoicedQuantityUnitOfMeasureCode", "invoiceLineNetAmount", "priceDetails", "lineVatInformation", "itemInformation" ], "properties": { "invoiceLineIdentifier": { "type": "string", "description": "BT-126. Unique line number within the invoice." }, "invoiceLineNote": { "type": "string", "description": "BT-127. Free-text note for the line.", "nullable": true }, "invoiceLineObjectIdentifier": { "type": "string", "description": "BT-128. Object identifier referenced by the line.", "nullable": true }, "invoicedQuantity": { "type": "number", "description": "BT-129. Invoiced quantity." }, "invoicedQuantityUnitOfMeasureCode": { "type": "string", "description": "BT-130. UN/ECE Recommendation 20 unit of measure code (e.g. H87 = piece, HUR = hour, KGM = kilogram)." }, "invoiceLineNetAmount": { "type": "number", "description": "BT-131. Line net amount (quantity × net price, minus line allowances, plus line charges)." }, "referencedPurchaseOrderLineReference": { "type": "string", "description": "BT-132. Reference to a buyer purchase order line.", "nullable": true }, "invoiceLineBuyerAccountingReference": { "type": "string", "description": "BT-133. Accounting reference for this line.", "nullable": true }, "invoiceLinePeriod": { "$ref": "#/components/schemas/InvoiceLinePeriod" }, "invoiceLineAllowances": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineAllowance" }, "description": "BT-136 to BT-140. Line-level allowances/discounts.", "nullable": true }, "invoiceLineCharges": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineCharge" }, "description": "BT-141 to BT-145. Line-level charges/surcharges.", "nullable": true }, "priceDetails": { "$ref": "#/components/schemas/PriceDetails" }, "lineVatInformation": { "type": "array", "items": { "$ref": "#/components/schemas/LineVatInformation" }, "minItems": 1 }, "itemInformation": { "$ref": "#/components/schemas/ItemInformation" } } }, "InvoiceLinePeriod": { "type": "object", "properties": { "invoiceLinePeriodStartDate": { "type": "string", "example": "2026-10-14T00:00:00", "description": "BT-134", "nullable": true }, "invoiceLinePeriodEndDate": { "type": "string", "example": "2026-10-14T00:00:00", "description": "BT-135", "nullable": true } }, "description": "BT-134/135. Service period for this line (start/end date)." }, "InvoiceLineAllowance": { "type": "object", "properties": { "invoiceLineAllowanceAmount": { "type": "number", "description": "BT-136", "nullable": true }, "invoiceLineAllowanceBaseAmount": { "type": "number", "description": "BT-137", "nullable": true }, "invoiceLineAllowancePercentage": { "type": "number", "description": "BT-138", "nullable": true }, "invoiceLineAllowanceReason": { "type": "string", "description": "BT-139", "nullable": true }, "invoiceLineAllowanceReasonCode": { "type": "string", "description": "BT-140", "nullable": true } } }, "InvoiceLineCharge": { "type": "object", "properties": { "invoiceLineChargeAmount": { "type": "number", "description": "BT-141", "nullable": true }, "invoiceLineChargeBaseAmount": { "type": "number", "description": "BT-142", "nullable": true }, "invoiceLineChargePercentage": { "type": "number", "description": "BT-143", "nullable": true }, "invoiceLineChargeReason": { "type": "string", "description": "BT-144", "nullable": true }, "invoiceLineChargeReasonCode": { "type": "string", "description": "BT-145", "nullable": true } } }, "PriceDetails": { "type": "object", "required": [ "itemNetPrice" ], "properties": { "itemNetPrice": { "type": "number", "description": "BT-146. Net unit price (after any item price discount)." }, "itemPriceDiscount": { "type": "number", "description": "BT-147. Discount applied to the gross unit price to arrive at the net unit price.", "nullable": true }, "itemGrossPrice": { "type": "number", "description": "BT-148. Gross unit price before discount.", "nullable": true }, "itemPriceBaseQuantity": { "type": "number", "description": "BT-149. Base quantity for the unit price + its unit of measure.", "nullable": true }, "itemPriceBaseQuantityUnitOfMeasure": { "type": "string", "description": "BT-150", "nullable": true } } }, "LineVatInformation": { "type": "object", "required": [ "invoicedItemVatCategoryCode", "invoicedItemVatRate" ], "properties": { "invoicedItemVatCategoryCode": { "type": "string", "description": "BT-151. VAT category for this line (matches a vatBreakdown entry)." }, "invoicedItemVatRate": { "type": "number", "description": "BT-152. VAT rate for this line." } } }, "ItemInformation": { "type": "object", "required": [ "itemName" ], "properties": { "itemName": { "type": "string", "description": "BT-153. Item name shown on the invoice." }, "itemDescription": { "type": "string", "description": "BT-154. Detailed item description.", "nullable": true }, "itemSellersIdentifier": { "type": "string", "description": "BT-155. Seller's article number.", "nullable": true }, "itemBuyersIdentifier": { "type": "string", "description": "BT-156. Buyer's article number.", "nullable": true }, "itemStandardIdentifier": { "type": "string", "description": "BT-157. Standard item identifier (e.g. GTIN). Required if BT-157-1 is set.", "nullable": true }, "itemStandardIdentifierSchemeIdentifier": { "type": "string", "description": "BT-157-1. ISO 6523 scheme code for BT-157. Required if BT-157 is set.", "nullable": true }, "itemClassificationIdentifier": { "type": "array", "items": { "$ref": "#/components/schemas/ItemClassification" }, "description": "BT-158. Item classifications (e.g. UNSPSC, eCl@ss) with scheme + version.", "nullable": true }, "itemCountryOfOrigin": { "type": "string", "description": "BT-159. ISO 3166-1 alpha-2 country of origin.", "nullable": true }, "itemAttributes": { "type": "array", "items": { "$ref": "#/components/schemas/ItemAttribute" }, "description": "BT-160/161. Item attribute name/value pairs (e.g. color, size).", "nullable": true } } }, "ItemClassification": { "type": "object", "properties": { "itemClassificationIdentifier": { "type": "string", "description": "BT-158", "nullable": true }, "itemClassificationIdentifierListIdentifier": { "type": "string", "description": "BT-158-1", "nullable": true }, "itemClassificationIdentifierListVersionIdentifier": { "type": "string", "description": "BT-158-2", "nullable": true } } }, "ItemAttribute": { "type": "object", "properties": { "itemAttributeName": { "type": "string", "description": "BT-160", "nullable": true }, "itemAttributeValue": { "type": "string", "description": "BT-161", "nullable": true } } }, "ExtractedInvoice": { "type": "object", "description": "Invoice data as extracted from a document (PDF analysis, or the XML embedded in a ZUGFeRD PDF), following the EN 16931 semantic model. Fields with no value on the source document are omitted, so nothing is guaranteed to be present. Dates are `DD.MM.YYYY` strings, amounts are JSON numbers.", "properties": { "invoiceNumber": { "type": "string", "description": "BT-1. Unique invoice identifier assigned by the seller.", "nullable": true }, "invoiceIssueDate": { "type": "string", "example": "14.10.2026", "description": "BT-2. Date the invoice was issued. Format YYYYMMDD or YYYY-MM-DD.", "nullable": true }, "invoiceTypeCode": { "type": "string", "description": "BT-3. Type code: 380 = invoice, 381 = credit note, 384 = corrected invoice.", "nullable": true }, "invoiceCurrencyCode": { "type": "string", "description": "BT-5. ISO 4217 currency code of the invoice (e.g. EUR).", "nullable": true }, "vatAccountingCurrencyCode": { "type": "string", "description": "BT-6. Currency used for VAT accounting when different from the invoice currency.", "nullable": true }, "valueAddedTaxPointDate": { "type": "string", "example": "14.10.2026", "description": "BT-7. VAT point date – the date the VAT becomes due.", "nullable": true }, "valueAddedTaxPointDateCode": { "type": "string", "description": "BT-8. Code identifying which date determines the VAT point.", "nullable": true }, "paymentDueDate": { "type": "string", "example": "14.10.2026", "description": "BT-9. Date payment is due. Required if there is an outstanding amount and no payment terms text.", "nullable": true }, "buyerReference": { "type": "string", "description": "BT-10. Buyer reference (Leitweg-ID for German public sector, otherwise any reference agreed with the buyer).", "nullable": true }, "projectReference": { "$ref": "#/components/schemas/ExtractedProjectReference" }, "contractReference": { "type": "string", "description": "BT-12. Identifier of the underlying contract.", "nullable": true }, "purchaseOrderReference": { "type": "string", "description": "BT-13. Buyer purchase order reference.", "nullable": true }, "salesOrderReference": { "type": "string", "description": "BT-14. Seller sales order reference.", "nullable": true }, "receivingAdviceReference": { "type": "string", "description": "BT-15", "nullable": true }, "despatchAdviceReference": { "type": "string", "description": "BT-16", "nullable": true }, "tenderOrLotReference": { "type": "string", "description": "BT-17. Tender or lot reference.", "nullable": true }, "invoicedObjectIdentifier": { "type": "string", "description": "BT-18", "nullable": true }, "buyerAccountingReference": { "type": "string", "description": "BT-19. Accounting reference text supplied by the buyer.", "nullable": true }, "paymentTerms": { "type": "string", "description": "BT-20. Payment terms in free text. Required if BT-9 is omitted.", "nullable": true }, "invoiceNote": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedInvoiceNote" }, "description": "Free-text notes about the invoice, each with an optional subject code.", "nullable": true }, "processControl": { "$ref": "#/components/schemas/ExtractedProcessControl" }, "precedingInvoiceReference": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedPrecedingInvoiceReference" }, "description": "Reference to a preceding invoice (for corrections / credit notes).", "nullable": true }, "seller": { "$ref": "#/components/schemas/ExtractedSeller" }, "buyer": { "$ref": "#/components/schemas/ExtractedBuyer" }, "payee": { "$ref": "#/components/schemas/ExtractedPayee" }, "sellerTaxRepresentativeParty": { "$ref": "#/components/schemas/ExtractedSellerTaxRepresentativeParty" }, "deliveryInformation": { "$ref": "#/components/schemas/ExtractedDeliveryInformation" }, "invoicingPeriod": { "$ref": "#/components/schemas/ExtractedInvoicingPeriod" }, "paymentInstructions": { "$ref": "#/components/schemas/ExtractedPaymentInstructions" }, "documentLevelAllowances": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedDocumentLevelAllowance" }, "description": "Document-level allowances/discounts.", "nullable": true }, "documentLevelCharges": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedDocumentLevelCharge" }, "description": "Document-level charges/surcharges.", "nullable": true }, "documentTotals": { "$ref": "#/components/schemas/ExtractedDocumentTotals" }, "vatBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedVatBreakdown" }, "nullable": true }, "additionalSupportingDocuments": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedAdditionalSupportingDocument" }, "description": "Supporting documents (timesheet, delivery note, etc.). Provide either an external URL or a base64 attachment.", "nullable": true }, "invoiceLine": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedInvoiceLine" }, "nullable": true } }, "example": { "invoiceNumber": "RE-2026-08-0815", "invoiceIssueDate": "24.08.2026", "invoiceTypeCode": "380", "invoiceCurrencyCode": "EUR", "paymentDueDate": "23.09.2026", "buyerReference": "04011000-12345-67", "purchaseOrderReference": "BST-2026-4471", "paymentTerms": "Zahlbar innerhalb von 30 Tagen ohne Abzug …", "seller": { "sellerName": "Müller & Söhne Großhandel GmbH", "sellerVatIdentifier": "DE812345678" }, "buyer": { "buyerName": "Bäckerei Schröder KG" }, "deliveryInformation": { "actualDeliveryDate": "31.07.2026" }, "paymentInstructions": { "paymentMeansTypeCode": "58", "creditTransfer": [ { "paymentAccountIdentifier": "DE02 3005 0110 0012 3456 78", "paymentAccountName": "Müller & Söhne Großhandel GmbH", "paymentServiceProviderIdentifier": "DUSSDEDDXXX" } ] }, "documentTotals": { "sumOfInvoiceLineNetAmount": 6519.7, "invoiceTotalAmountWithoutVat": 6519.7, "invoiceTotalVatAmount": 1234.1, "invoiceTotalAmountWithVat": 7753.8, "amountDueForPayment": 7753.8 }, "vatBreakdown": [ { "vatCategoryTaxableAmount": 6481, "vatCategoryTaxAmount": 1231.39, "vatCategoryCode": "S", "vatCategoryRate": 19 }, { "vatCategoryTaxableAmount": 38.7, "vatCategoryTaxAmount": 2.71, "vatCategoryCode": "S", "vatCategoryRate": 7 } ], "invoiceLine": [ { "invoiceLineIdentifier": "1", "invoicedQuantity": 12, "invoicedQuantityUnitOfMeasureCode": "HUR", "invoiceLineNetAmount": 1740, "priceDetails": { "itemNetPrice": 145 }, "lineVatInformation": [ { "invoicedItemVatCategoryCode": "S", "invoicedItemVatRate": 19 } ], "itemInformation": { "itemName": "Beratungsleistung Softwarearchitektur" } } ] }, "nullable": true }, "ExtractedProjectReference": { "type": "object", "properties": { "projectReferenceIdentifier": { "type": "string", "description": "BT-11", "nullable": true }, "projectReferenceName": { "type": "string", "description": "BT-11-0", "nullable": true } }, "nullable": true }, "ExtractedInvoiceNote": { "type": "object", "properties": { "invoiceNoteSubjectCode": { "type": "string", "description": "BT-21", "nullable": true }, "invoiceNote": { "type": "string", "description": "BT-22", "nullable": true } }, "nullable": true }, "ExtractedProcessControl": { "type": "object", "properties": { "businessProcessTypeIdentifier": { "type": "string", "description": "BT-23", "nullable": true }, "specificationIdentifier": { "type": "string", "description": "BT-24", "nullable": true } }, "nullable": true }, "ExtractedPrecedingInvoiceReference": { "type": "object", "properties": { "precedingInvoiceReference": { "type": "string", "description": "BT-25", "nullable": true }, "precedingInvoiceIssueDate": { "type": "string", "example": "14.10.2026", "description": "BT-26", "nullable": true } }, "nullable": true }, "ExtractedSeller": { "type": "object", "properties": { "sellerName": { "type": "string", "description": "BT-27. Registered legal name of the seller.", "nullable": true }, "sellerTradingName": { "type": "string", "description": "BT-28. Trading name if different from the legal name.", "nullable": true }, "sellerIdentifier": { "type": "array", "items": { "type": "string" }, "description": "BT-29. Additional seller identifiers (e.g. GLN).", "nullable": true }, "sellerLegalRegistrationIdentifier": { "type": "string", "description": "BT-30. Commercial registration number.", "nullable": true }, "sellerVatIdentifier": { "type": "string", "description": "BT-31. Seller VAT identification number.", "nullable": true }, "sellerTaxRegistrationIdentifier": { "type": "string", "description": "BT-32. Tax registration identifier (e.g. Steuernummer).", "nullable": true }, "sellerAdditionalLegalInformation": { "type": "string", "description": "BT-33. Additional legal text (managing directors, registry court, etc.).", "nullable": true }, "sellerElectronicAddress": { "type": "string", "description": "BT-34. Electronic address of the seller (typically an e-invoice mailbox or email).", "nullable": true }, "sellerPostalAddress": { "$ref": "#/components/schemas/ExtractedSellerPostalAddress" }, "sellerContact": { "$ref": "#/components/schemas/ExtractedSellerContact" } }, "nullable": true }, "ExtractedSellerPostalAddress": { "type": "object", "properties": { "sellerAddressLine1": { "type": "string", "description": "BT-35. Street and number (line 1).", "nullable": true }, "sellerAddressLine2": { "type": "string", "description": "BT-36", "nullable": true }, "sellerAddressLine3": { "type": "string", "description": "BT-162", "nullable": true }, "sellerCity": { "type": "string", "description": "BT-37. City.", "nullable": true }, "sellerPostCode": { "type": "string", "description": "BT-38. Postal code.", "nullable": true }, "sellerCountrySubdivision": { "type": "string", "description": "BT-39", "nullable": true }, "sellerCountryCode": { "type": "string", "description": "BT-40. ISO 3166-1 alpha-2 country code (e.g. DE).", "nullable": true } }, "nullable": true }, "ExtractedSellerContact": { "type": "object", "properties": { "sellerContactPoint": { "type": "string", "description": "BT-41", "nullable": true }, "sellerContactTelephoneNumber": { "type": "string", "description": "BT-42", "nullable": true }, "sellerContactEmailAddress": { "type": "string", "description": "BT-43", "nullable": true } }, "nullable": true }, "ExtractedBuyer": { "type": "object", "properties": { "buyerName": { "type": "string", "description": "BT-44. Registered legal name of the buyer.", "nullable": true }, "buyerTradingName": { "type": "string", "description": "BT-45. Trading name if different from the legal name.", "nullable": true }, "buyerIdentifier": { "type": "string", "description": "BT-46. Additional buyer identifier.", "nullable": true }, "buyerLegalRegistrationIdentifier": { "type": "string", "description": "BT-47. Buyer commercial registration number.", "nullable": true }, "buyerVatIdentifier": { "type": "string", "description": "BT-48. Buyer VAT identification number.", "nullable": true }, "buyerElectronicAddress": { "type": "string", "description": "BT-49. Electronic address of the buyer.", "nullable": true }, "buyerPostalAddress": { "$ref": "#/components/schemas/ExtractedBuyerPostalAddress" }, "buyerContact": { "$ref": "#/components/schemas/ExtractedBuyerContact" } }, "nullable": true }, "ExtractedBuyerPostalAddress": { "type": "object", "properties": { "buyerAddressLine1": { "type": "string", "description": "BT-50. Street and number (line 1).", "nullable": true }, "buyerAddressLine2": { "type": "string", "description": "BT-51", "nullable": true }, "buyerAddressLine3": { "type": "string", "description": "BT-163", "nullable": true }, "buyerCity": { "type": "string", "description": "BT-52. City.", "nullable": true }, "buyerPostCode": { "type": "string", "description": "BT-53. Postal code.", "nullable": true }, "buyerCountrySubdivision": { "type": "string", "description": "BT-54", "nullable": true }, "buyerCountryCode": { "type": "string", "description": "BT-55. ISO 3166-1 alpha-2 country code.", "nullable": true } }, "nullable": true }, "ExtractedBuyerContact": { "type": "object", "properties": { "buyerContactPoint": { "type": "string", "description": "BT-56", "nullable": true }, "buyerContactTelephoneNumber": { "type": "string", "description": "BT-57", "nullable": true }, "buyerContactEmailAddress": { "type": "string", "description": "BT-58", "nullable": true } }, "nullable": true }, "ExtractedPayee": { "type": "object", "properties": { "payeeName": { "type": "string", "description": "BT-59", "nullable": true }, "payeeIdentifier": { "type": "string", "description": "BT-60", "nullable": true }, "payeeLegalRegistrationIdentifier": { "type": "string", "description": "BT-61", "nullable": true } }, "nullable": true }, "ExtractedSellerTaxRepresentativeParty": { "type": "object", "properties": { "sellerTaxRepresentativeName": { "type": "string", "description": "BT-62", "nullable": true }, "sellerTaxRepresentativeVatIdentifier": { "type": "string", "description": "BT-63", "nullable": true }, "sellerTaxRepresentativePostalAddress": { "$ref": "#/components/schemas/ExtractedTaxRepresentativePostalAddress" } }, "nullable": true }, "ExtractedTaxRepresentativePostalAddress": { "type": "object", "properties": { "taxRepresentativeAddressLine1": { "type": "string", "description": "BT-64", "nullable": true }, "taxRepresentativeAddressLine2": { "type": "string", "description": "BT-65", "nullable": true }, "taxRepresentativeAddressLine3": { "type": "string", "description": "BT-164", "nullable": true }, "taxRepresentativeCity": { "type": "string", "description": "BT-66", "nullable": true }, "taxRepresentativePostCode": { "type": "string", "description": "BT-67", "nullable": true }, "taxRepresentativeCountrySubdivision": { "type": "string", "description": "BT-68", "nullable": true }, "taxRepresentativeCountryCode": { "type": "string", "description": "BT-69", "nullable": true } }, "nullable": true }, "ExtractedDeliveryInformation": { "type": "object", "properties": { "deliverToPartyName": { "type": "string", "description": "BT-70", "nullable": true }, "deliverToLocationIdentifier": { "type": "string", "description": "BT-71", "nullable": true }, "actualDeliveryDate": { "type": "string", "example": "14.10.2026", "description": "BT-72", "nullable": true }, "deliverToAddress": { "$ref": "#/components/schemas/ExtractedDeliverToAddress" } }, "nullable": true }, "ExtractedDeliverToAddress": { "type": "object", "properties": { "deliverToAddressLine1": { "type": "string", "description": "BT-75", "nullable": true }, "deliverToAddressLine2": { "type": "string", "description": "BT-76", "nullable": true }, "deliverToAddressLine3": { "type": "string", "description": "BT-165", "nullable": true }, "deliverToCity": { "type": "string", "description": "BT-77", "nullable": true }, "deliverToPostCode": { "type": "string", "description": "BT-78", "nullable": true }, "deliverToCountrySubdivision": { "type": "string", "description": "BT-79", "nullable": true }, "deliverToCountryCode": { "type": "string", "description": "BT-80", "nullable": true } }, "nullable": true }, "ExtractedInvoicingPeriod": { "type": "object", "properties": { "invoicingPeriodStartDate": { "type": "string", "example": "14.10.2026", "description": "BT-73", "nullable": true }, "invoicingPeriodEndDate": { "type": "string", "example": "14.10.2026", "description": "BT-74", "nullable": true } }, "nullable": true }, "ExtractedPaymentInstructions": { "type": "object", "properties": { "paymentMeansTypeCode": { "type": "string", "description": "BT-81. UNTDID 4461 payment means code (e.g. 58 = SEPA credit transfer, 30 = credit transfer, 48 = bank card).", "nullable": true }, "paymentMeansText": { "type": "string", "description": "BT-82. Free-text payment instructions.", "nullable": true }, "remittanceInformation": { "type": "string", "description": "BT-83. Remittance information (used by the buyer when paying).", "nullable": true }, "creditTransfer": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedCreditTransfer" }, "nullable": true }, "paymentCardInformation": { "$ref": "#/components/schemas/ExtractedPaymentCardInformation" }, "directDebit": { "$ref": "#/components/schemas/ExtractedDirectDebit" } }, "nullable": true }, "ExtractedCreditTransfer": { "type": "object", "properties": { "paymentAccountIdentifier": { "type": "string", "description": "BT-84. IBAN or bank account number receiving the payment.", "nullable": true }, "paymentAccountName": { "type": "string", "description": "BT-85. Account holder name.", "nullable": true }, "paymentServiceProviderIdentifier": { "type": "string", "description": "BT-86. BIC of the receiving bank.", "nullable": true } }, "nullable": true }, "ExtractedPaymentCardInformation": { "type": "object", "properties": { "paymentCardPrimaryAccountNumber": { "type": "string", "description": "BT-87", "nullable": true }, "paymentCardHolderName": { "type": "string", "description": "BT-88", "nullable": true } }, "nullable": true }, "ExtractedDirectDebit": { "type": "object", "properties": { "mandateReferenceIdentifier": { "type": "string", "description": "BT-89", "nullable": true }, "bankAssignedCreditorIdentifier": { "type": "string", "description": "BT-90", "nullable": true }, "debitedAccountIdentifier": { "type": "string", "description": "BT-91", "nullable": true } }, "nullable": true }, "ExtractedDocumentLevelAllowance": { "type": "object", "properties": { "documentLevelAllowanceAmount": { "type": "number", "description": "BT-92", "nullable": true }, "documentLevelAllowanceBaseAmount": { "type": "number", "description": "BT-93", "nullable": true }, "documentLevelAllowancePercentage": { "type": "number", "description": "BT-94", "nullable": true }, "documentLevelAllowanceVatCategoryCode": { "type": "string", "description": "BT-95", "nullable": true }, "documentLevelAllowanceVatRate": { "type": "number", "description": "BT-96", "nullable": true }, "documentLevelAllowanceReason": { "type": "string", "description": "BT-97", "nullable": true }, "documentLevelAllowanceReasonCode": { "type": "string", "description": "BT-98", "nullable": true } }, "nullable": true }, "ExtractedDocumentLevelCharge": { "type": "object", "properties": { "documentLevelChargeAmount": { "type": "number", "description": "BT-99", "nullable": true }, "documentLevelChargeBaseAmount": { "type": "number", "description": "BT-100", "nullable": true }, "documentLevelChargePercentage": { "type": "number", "description": "BT-101", "nullable": true }, "documentLevelChargeVatCategoryCode": { "type": "string", "description": "BT-102", "nullable": true }, "documentLevelChargeVatRate": { "type": "number", "description": "BT-103", "nullable": true }, "documentLevelChargeReason": { "type": "string", "description": "BT-104", "nullable": true }, "documentLevelChargeReasonCode": { "type": "string", "description": "BT-105", "nullable": true } }, "nullable": true }, "ExtractedDocumentTotals": { "type": "object", "properties": { "sumOfInvoiceLineNetAmount": { "type": "number", "description": "BT-106. Sum of all invoice line net amounts.", "nullable": true }, "sumOfAllowancesOnDocumentLevel": { "type": "number", "description": "BT-107. Sum of allowances at document level.", "nullable": true }, "sumOfChargesOnDocumentLevel": { "type": "number", "description": "BT-108. Sum of charges at document level.", "nullable": true }, "invoiceTotalAmountWithoutVat": { "type": "number", "description": "BT-109. Invoice total without VAT (net total).", "nullable": true }, "invoiceTotalVatAmount": { "type": "number", "description": "BT-110. Total VAT amount.", "nullable": true }, "invoiceTotalVatAmountInAccountingCurrency": { "type": "number", "description": "BT-111. Total VAT in the accounting currency (BT-6) if different from BT-5.", "nullable": true }, "invoiceTotalAmountWithVat": { "type": "number", "description": "BT-112. Invoice total including VAT (gross total).", "nullable": true }, "paidAmount": { "type": "number", "description": "BT-113. Amount already paid.", "nullable": true }, "roundingAmount": { "type": "number", "description": "BT-114. Rounding adjustment.", "nullable": true }, "amountDueForPayment": { "type": "number", "description": "BT-115. Amount due for payment (BT-112 − BT-113 + BT-114).", "nullable": true } }, "nullable": true }, "ExtractedVatBreakdown": { "type": "object", "properties": { "vatCategoryTaxableAmount": { "type": "number", "description": "BT-116. Taxable amount for this VAT category.", "nullable": true }, "vatCategoryTaxAmount": { "type": "number", "description": "BT-117. VAT amount for this category (BT-116 × BT-119 / 100).", "nullable": true }, "vatCategoryCode": { "type": "string", "description": "BT-118. VAT category code: S (standard), Z (zero), E (exempt), AE (reverse charge), K (intra-community), G (export), O (out of scope), L (Canary Islands), M (Ceuta/Melilla).", "nullable": true }, "vatCategoryRate": { "type": "number", "description": "BT-119. VAT rate as a percentage (e.g. 19 for 19%).", "nullable": true }, "vatExemptionReasonText": { "type": "string", "description": "BT-120. Required when the category is exempt or zero-rated. Free-text reason.", "nullable": true }, "vatExemptionReasonCode": { "type": "string", "description": "BT-121. Coded exemption reason (e.g. VATEX-EU-AE, VATEX-EU-IC).", "nullable": true } }, "nullable": true }, "ExtractedAdditionalSupportingDocument": { "type": "object", "properties": { "supportingDocumentReference": { "type": "string", "description": "BT-122", "nullable": true }, "supportingDocumentDescription": { "type": "string", "description": "BT-123", "nullable": true }, "externalDocumentLocation": { "type": "string", "description": "BT-124", "nullable": true }, "attachedDocument": { "type": "string", "description": "BT-125", "nullable": true }, "supportingDocumentTypeCodex": { "type": "integer", "description": "Document type code (UNTDID 1001, e.g. 916 = referenced document, 130 = invoice data sheet).", "nullable": true }, "attachedDocumentFilename": { "type": "string", "description": "File name of the attached document (BT-125) when `attachedDocument` is sent.", "nullable": true } }, "nullable": true }, "ExtractedInvoiceLine": { "type": "object", "properties": { "invoiceLineIdentifier": { "type": "string", "description": "BT-126. Unique line number within the invoice.", "nullable": true }, "invoiceLineNote": { "type": "string", "description": "BT-127. Free-text note for the line.", "nullable": true }, "invoiceLineObjectIdentifier": { "type": "string", "description": "BT-128. Object identifier referenced by the line.", "nullable": true }, "invoicedQuantity": { "type": "number", "description": "BT-129. Invoiced quantity.", "nullable": true }, "invoicedQuantityUnitOfMeasureCode": { "type": "string", "description": "BT-130. UN/ECE Recommendation 20 unit of measure code (e.g. H87 = piece, HUR = hour, KGM = kilogram).", "nullable": true }, "invoiceLineNetAmount": { "type": "number", "description": "BT-131. Line net amount (quantity × net price, minus line allowances, plus line charges).", "nullable": true }, "referencedPurchaseOrderLineReference": { "type": "string", "description": "BT-132. Reference to a buyer purchase order line.", "nullable": true }, "invoiceLineBuyerAccountingReference": { "type": "string", "description": "BT-133. Accounting reference for this line.", "nullable": true }, "invoiceLinePeriod": { "$ref": "#/components/schemas/ExtractedInvoiceLinePeriod" }, "invoiceLineAllowances": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedInvoiceLineAllowance" }, "description": "Line-level allowances/discounts.", "nullable": true }, "invoiceLineCharges": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedInvoiceLineCharge" }, "description": "Line-level charges/surcharges.", "nullable": true }, "priceDetails": { "$ref": "#/components/schemas/ExtractedPriceDetails" }, "lineVatInformation": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedLineVatInformation" }, "nullable": true }, "itemInformation": { "$ref": "#/components/schemas/ExtractedItemInformation" } }, "nullable": true }, "ExtractedInvoiceLinePeriod": { "type": "object", "properties": { "invoiceLinePeriodStartDate": { "type": "string", "example": "14.10.2026", "description": "BT-134", "nullable": true }, "invoiceLinePeriodEndDate": { "type": "string", "example": "14.10.2026", "description": "BT-135", "nullable": true } }, "nullable": true }, "ExtractedInvoiceLineAllowance": { "type": "object", "properties": { "invoiceLineAllowanceAmount": { "type": "number", "description": "BT-136", "nullable": true }, "invoiceLineAllowanceBaseAmount": { "type": "number", "description": "BT-137", "nullable": true }, "invoiceLineAllowancePercentage": { "type": "number", "description": "BT-138", "nullable": true }, "invoiceLineAllowanceReason": { "type": "string", "description": "BT-139", "nullable": true }, "invoiceLineAllowanceReasonCode": { "type": "string", "description": "BT-140", "nullable": true } }, "nullable": true }, "ExtractedInvoiceLineCharge": { "type": "object", "properties": { "invoiceLineChargeAmount": { "type": "number", "description": "BT-141", "nullable": true }, "invoiceLineChargeBaseAmount": { "type": "number", "description": "BT-142", "nullable": true }, "invoiceLineChargePercentage": { "type": "number", "description": "BT-143", "nullable": true }, "invoiceLineChargeReason": { "type": "string", "description": "BT-144", "nullable": true }, "invoiceLineChargeReasonCode": { "type": "string", "description": "BT-145", "nullable": true } }, "nullable": true }, "ExtractedPriceDetails": { "type": "object", "properties": { "itemNetPrice": { "type": "number", "description": "BT-146. Net unit price (after any item price discount).", "nullable": true }, "itemPriceDiscount": { "type": "number", "description": "BT-147. Discount applied to the gross unit price to arrive at the net unit price.", "nullable": true }, "itemGrossPrice": { "type": "number", "description": "BT-148. Gross unit price before discount.", "nullable": true }, "itemPriceBaseQuantity": { "type": "number", "description": "BT-149. Base quantity for the unit price + its unit of measure.", "nullable": true }, "itemPriceBaseQuantityUnitOfMeasure": { "type": "string", "description": "BT-150", "nullable": true } }, "nullable": true }, "ExtractedLineVatInformation": { "type": "object", "properties": { "invoicedItemVatCategoryCode": { "type": "string", "description": "BT-151. VAT category for this line (matches a vatBreakdown entry).", "nullable": true }, "invoicedItemVatRate": { "type": "number", "description": "BT-152. VAT rate for this line.", "nullable": true } }, "nullable": true }, "ExtractedItemInformation": { "type": "object", "properties": { "itemName": { "type": "string", "description": "BT-153. Item name shown on the invoice.", "nullable": true }, "itemDescription": { "type": "string", "description": "BT-154. Detailed item description.", "nullable": true }, "itemSellersIdentifier": { "type": "string", "description": "BT-155. Seller's article number.", "nullable": true }, "itemBuyersIdentifier": { "type": "string", "description": "BT-156. Buyer's article number.", "nullable": true }, "itemStandardIdentifier": { "type": "string", "description": "BT-157. Standard item identifier (e.g. GTIN). Required if BT-157-1 is set.", "nullable": true }, "itemStandardIdentifierSchemeIdentifier": { "type": "string", "description": "BT-157-1. ISO 6523 scheme code for BT-157. Required if BT-157 is set.", "nullable": true }, "itemClassificationIdentifier": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedItemClassification" }, "description": "Item classifications (e.g. UNSPSC, eCl@ss) with scheme + version.", "nullable": true }, "itemCountryOfOrigin": { "type": "string", "description": "BT-159. ISO 3166-1 alpha-2 country of origin.", "nullable": true }, "itemAttributes": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedItemAttribute" }, "description": "Item attribute name/value pairs (e.g. color, size).", "nullable": true } }, "nullable": true }, "ExtractedItemClassification": { "type": "object", "properties": { "itemClassificationIdentifier": { "type": "string", "description": "BT-158", "nullable": true }, "itemClassificationIdentifierListIdentifier": { "type": "string", "description": "BT-158-1", "nullable": true }, "itemClassificationIdentifierListVersionIdentifier": { "type": "string", "description": "BT-158-2", "nullable": true } }, "nullable": true }, "ExtractedItemAttribute": { "type": "object", "properties": { "itemAttributeName": { "type": "string", "description": "BT-160", "nullable": true }, "itemAttributeValue": { "type": "string", "description": "BT-161", "nullable": true } }, "nullable": true }, "EmailAttachment": { "type": "object", "required": [ "fileName", "fileBase64" ], "properties": { "fileName": { "type": "string", "example": "Leistungsnachweis.pdf" }, "fileBase64": { "type": "string", "description": "Base64-encoded file content. PDF, JPG and PNG are accepted." } } }, "Transport": { "type": "object", "description": "Optional. When present, the generated invoice is delivered by email in the same call (DKIM-signed, to receiver, CC and BCC at once). Requires the email delivery add-on and an authenticated sender domain. When absent, nothing is sent.", "required": [ "type", "useTransport", "sender", "receiver", "subject", "message" ], "properties": { "type": { "type": "string", "enum": [ "email" ], "description": "Transport channel. Currently only `email`." }, "useTransport": { "type": "boolean", "description": "Set to `true` to send the generated invoice in the same call." }, "sender": { "type": "string", "description": "Sender address on your own domain. The domain must be authenticated once (DKIM/SPF)." }, "senderName": { "type": "string", "description": "Display name shown as the sender." }, "receiver": { "type": "string", "description": "Recipient address(es), comma-separated. Cleaned up before sending." }, "cc": { "type": "string", "description": "CC address(es), comma-separated." }, "bcc": { "type": "string", "description": "BCC address(es), comma-separated, e.g. an archive mailbox." }, "subject": { "type": "string", "description": "Email subject. Supports the placeholders `{invoicenumber}` and `{invoicedate}` (not `{lastname}`)." }, "message": { "type": "string", "description": "Email body as HTML. Supports `{invoicenumber}`, `{invoicedate}` and `{lastname}` (= `invoice.buyer.buyerName`, only here)." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAttachment" }, "description": "Additional attachments as `{ fileName, fileBase64 }` objects. PDF, JPG and PNG are accepted." } }, "example": { "type": "email", "useTransport": true, "sender": "rechnung@ihre-domain.de", "senderName": "Ihre Firma GmbH", "receiver": "buchhaltung@kunde.de, rechnungen@kunde.de", "cc": "steuerberater@kanzlei.de", "bcc": "archiv@ihre-domain.de", "subject": "Rechnung {invoicenumber} vom {invoicedate}", "message": "

Guten Tag,

anbei erhalten Sie die Rechnung {invoicenumber} als ZUGFeRD-Datei.

", "attachments": [ { "fileName": "Leistungsnachweis.pdf", "fileBase64": "" } ] } }, "DeliveryEmail": { "type": "object", "required": [ "sender", "receiver", "subject", "message" ], "properties": { "sender": { "type": "string", "description": "Sender address on your own domain. The domain must be authenticated once (DKIM/SPF)." }, "senderName": { "type": "string", "description": "Display name shown as the sender." }, "receiver": { "type": "string", "description": "Recipient address(es), comma-separated." }, "cc": { "type": "string", "description": "CC address(es), comma-separated." }, "bcc": { "type": "string", "description": "BCC address(es), comma-separated, e.g. an archive mailbox." }, "subject": { "type": "string", "description": "Subject (plain text). Supports placeholders from `content`." }, "message": { "type": "string", "description": "Body (plain text or full HTML). Supports placeholders from `content`." }, "content": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Free key/value pairs that fill placeholders in subject and message, e.g. the key `invoicedate` fills `{invoicedate}`. Unlike the generation endpoints there is no invoice object to auto-fill placeholders." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAttachment" }, "description": "Attachments. Multiple allowed; no document is attached automatically." } } }, "DeliveryTransport": { "type": "object", "required": [ "type", "useTransport", "email" ], "properties": { "type": { "type": "string", "enum": [ "email" ], "description": "Transport channel. Currently only `email`." }, "useTransport": { "type": "boolean", "description": "Must be `true` for an email to actually be sent; otherwise the call answers `nothing to do`." }, "email": { "$ref": "#/components/schemas/DeliveryEmail" } } }, "ValidationMessage": { "type": "object", "description": "One rule violation reported by the validators. The same shape is used in every error list of the API (`xInvoiceErrors`, `xInvoiceErrorList`, `zugferdErrors`, `zugferdErrorList`, `zugferdErrorlist`, `xrechnungErrors`, `errorList`): the spelling of the list name differs from endpoint to endpoint, the entries do not. Use `id` and `location` to navigate to the offending element.", "properties": { "id": { "type": "string", "description": "Rule ID, e.g. `BR-CO-25`, `BR-DE-15` or `PEPPOL-EN16931-R008`. `null` when the file could not be parsed; empty string `\"\"` for `additional-validation` findings, which have no rule ID.", "nullable": true, "example": "BR-CO-25" }, "line": { "type": "string", "description": "Line number as a string (e.g. `\"1\"`) for XML-schema (XSD) findings. Empty for rule findings (`null`, or `\"\"` for `additional-validation` findings) — use `location` there.", "nullable": true }, "location": { "type": "string", "description": "Where the finding occurred: an XPath in `Q{namespace}` notation for schema and Schematron findings, or a field key such as `sellerVatId` or `dueDate` for `additional-validation` findings. `null` when the file could not be parsed.", "nullable": true, "example": "/rsm:CrossIndustryInvoice" }, "message": { "type": "string", "description": "Text of the violated rule. EN 16931 and PEPPOL rules come in English, XRechnung (BR-DE-*) and `additional-validation` findings in German. Rule messages are often prefixed with the rule ID in brackets, e.g. `[BR-CO-25]-…`." }, "schemaFile": { "type": "string", "description": "Rule set that raised the finding. CII documents: `EN16931-CII-validation`, `XRechnung-CII-validation`. UBL documents: `EN16931-UBL-validation`, `XRechnung-UBL-validation`. XML-schema (XSD) findings name the schema, e.g. `UBL-Invoice-2.1`. Also `additional-validation` for the extra checks. `null` when the file could not be parsed.", "nullable": true, "example": "EN16931-CII-validation" }, "type": { "type": "string", "description": "Kind of finding: `fatal` for rule violations, `XSD` for XML-schema violations.", "example": "fatal" } } }, "AnalyzePdfRequest": { "type": "object", "required": [ "pdfInvoiceBase64" ], "properties": { "pdfInvoiceBase64": { "type": "string", "description": "Base64-encoded invoice file content: PDF, PNG, JPEG or TIFF. The type is detected from the content (magic bytes), not from the field name, filename or Content-Type. Also accepted under the field names `invoiceBase64` and `fileBase64`. A `data:…;base64,` prefix and whitespace are stripped. Not supported: HEIC/HEIF, WEBP, BMP, GIF, SVG, Office files, ZIP (convert HEIC to JPEG client-side). Limit: 11 MiB decoded (about 14.7 MB base64); bodies above about 16 MB are rejected by the platform with a plain, non-JSON error, so check the size client-side." }, "withLineItems": { "type": "boolean", "description": "When `true`, line items are extracted in addition to the header data. `false` returns header data only and is roughly 2× faster. Set it explicitly: the playground sends `true`." } }, "example": { "pdfInvoiceBase64": "JVBERi0xLjQKJf...", "withLineItems": true } }, "AnalyzePdfAsyncRequest": { "type": "object", "required": [ "pdfInvoiceBase64" ], "properties": { "pdfInvoiceBase64": { "type": "string", "description": "Base64-encoded invoice file content: PDF or TIFF (no PNG/JPEG on the async endpoint today). Also accepted under `invoiceBase64` and `fileBase64`. A `data:…;base64,` prefix and whitespace are stripped. Same 11 MiB decoded limit as the synchronous endpoint." }, "withLineItems": { "type": "boolean", "default": true, "description": "When `false`, `invoice.invoiceLine[]` is omitted from the eventual result." } }, "example": { "pdfInvoiceBase64": "JVBERi0xLjQKJf...", "withLineItems": true } }, "AnalyzePdfLegacyRequest": { "type": "object", "required": [ "pdfInvoiceBase64" ], "properties": { "pdfInvoiceBase64": { "type": "string", "description": "Base64-encoded PDF invoice file content." } }, "example": { "pdfInvoiceBase64": "JVBERi0xLjQKJf..." } }, "CreateZugferdFromPdfRequest": { "type": "object", "required": [ "pdfInvoiceBase64" ], "properties": { "pdfInvoiceBase64": { "type": "string", "description": "Base64-encoded invoice file content: PDF, PNG, JPEG or TIFF. The type is detected from the content (magic bytes), not from the field name, filename or Content-Type. Also accepted under the field names `invoiceBase64` and `fileBase64`. A `data:…;base64,` prefix and whitespace are stripped. Not supported: HEIC/HEIF, WEBP, BMP, GIF, SVG, Office files, ZIP (convert HEIC to JPEG client-side). Limit: 11 MiB decoded (about 14.7 MB base64); bodies above about 16 MB are rejected by the platform with a plain, non-JSON error, so check the size client-side." }, "fileName": { "type": "string", "default": "invoice.pdf", "description": "Original filename. Drives the output filename (`…-zugferd.pdf`) and the wording of the error email. Sanitised server-side (control characters, quotes and backslashes become spaces, `/` becomes `_`, truncated to 200 characters)." } }, "example": { "pdfInvoiceBase64": "JVBERi0xLjQKJc...", "fileName": "Rechnung-2026-0042.pdf" } }, "CreateXRechnungFromJsonRequest": { "type": "object", "required": [ "invoice" ], "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "transport": { "$ref": "#/components/schemas/Transport" }, "xmlFormat": { "type": "string", "description": "Syntax of the generated XML: `CII` (UN/CEFACT Cross Industry Invoice, the default when the field is omitted) or `UBL` (Universal Business Language, UBL 2.1 `Invoice`). The value is case-insensitive, so `ubl` and `UBL` behave the same. It applies to the XML in `xInvoice` and at `downloadURL`; the request is otherwise identical. Example: `{ \"invoice\": { … }, \"xmlFormat\": \"UBL\" }`. Validation findings name the rule set of the syntax they apply to (see `schemaFile` below).", "enum": [ "CII", "UBL" ], "default": "CII" } } }, "CreateZugferdFromJsonRequest": { "type": "object", "required": [ "invoice", "invoicePdf64" ], "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "invoicePdf64": { "type": "string", "description": "Base64-encoded PDF to embed the XRechnung XML into." }, "transport": { "$ref": "#/components/schemas/Transport" } } }, "CreateZugferdPdfFromXRechnungRequest": { "type": "object", "required": [ "xInvoiceXml", "invoicePdf64" ], "properties": { "xInvoiceXml": { "type": "string", "description": "XRechnung XML as a string." }, "invoicePdf64": { "type": "string", "description": "Base64-encoded PDF to embed the XML into." } } }, "CreateInvoicePdfFromJsonRequest": { "type": "object", "required": [ "invoice", "templateId" ], "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "templateId": { "type": "string", "description": "ID of the Word/design template used to render the PDF." }, "invoiceFilename": { "type": "string", "description": "Custom file name for the generated PDF (also used for the email attachment when `transport` is set). If omitted, a name is assigned automatically." }, "invoicePassthrough": { "type": "boolean", "default": true, "description": "When `true` (default) the invoice is generated and returned without storing anything server-side. Set to `false` to persist it so it appears in your account's invoice list." }, "transport": { "$ref": "#/components/schemas/Transport" } } }, "ValidateXRechnungXmlRequest": { "type": "object", "required": [ "xinvoiceXML" ], "properties": { "xinvoiceXML": { "type": "string", "description": "XRechnung XML content as a string." } } }, "ValidateZugferdPdfRequest": { "type": "object", "required": [ "zugferdFile64" ], "properties": { "zugferdFile64": { "type": "string", "description": "Base64-encoded ZUGFeRD PDF file." }, "comparePDF2XML": { "type": "boolean", "default": false, "description": "When `true`, also checks that the visible PDF content matches the embedded XML invoice data." } } }, "ExtractXRechnungRequest": { "type": "object", "required": [ "zugferd64" ], "properties": { "zugferd64": { "type": "string", "description": "Base64-encoded ZUGFeRD PDF document." } } }, "SendEmailRequest": { "type": "object", "required": [ "transport" ], "properties": { "transport": { "$ref": "#/components/schemas/DeliveryTransport" } } }, "ResendEmailRequest": { "type": "object", "required": [ "resendToken" ], "properties": { "resendToken": { "type": "string", "description": "The `resendToken` from a generation endpoint (used with `transport`) or from `sendEmail`." } }, "example": { "resendToken": "RjBcXJ9k2mZpQ7vT4uYs1LwNdHo6EaKf" } }, "PdfAnalysisResult": { "type": "object", "description": "Result of the V2 analyzer (also the `result` of a finished async job). `extractionConfidence` is 100 only when the extraction satisfies every requirement it was checked against; then `zugferdReady` is `true`, `warnings` is usually empty and `mandatoryFieldReport` is absent. Below 100, `zugferdReady` is `false` and `mandatoryFieldReport` lists the mandatory details missing from the document: such an invoice cannot be converted into a ZUGFeRD invoice as extracted. Fields without a value on the source document are omitted from `invoice` (never `null` or an empty string).", "properties": { "extractionConfidence": { "type": "integer", "description": "How complete the extraction is: the share of checked requirements it satisfies (`confidenceBasis.requirementsMet` of `requirementsChecked`, e.g. 39 of 41 → 95, 41 of 41 → 100). 100 = complete. Anything lower means mandatory details are missing (see `mandatoryFieldReport`) and the invoice cannot be converted into a ZUGFeRD invoice.", "minimum": 0, "maximum": 100 }, "invoice": { "description": "The extracted invoice (see `ExtractedInvoice`). Fields without a value on the source document are omitted.", "allOf": [ { "$ref": "#/components/schemas/ExtractedInvoice" } ] }, "zugferdReady": { "type": "boolean", "description": "`true` when the extraction met all requirements it was checked against (`extractionConfidence` 100). `false` otherwise: `mandatoryFieldReport` then lists what is missing." }, "mandatoryFieldReport": { "type": "array", "description": "The mandatory details missing from the document, one entry per gap. **Present only when `extractionConfidence` is below 100; at 100 the property is left out entirely**: test for its presence, do not assume an empty array. These gaps lower the confidence and block ZUGFeRD generation: add the details to the source document and analyze it again, or add them to the extracted `invoice` before you create the ZUGFeRD.", "items": { "$ref": "#/components/schemas/MandatoryFieldReportItem" } }, "lineItemCheck": { "description": "Plausibility check of the extracted line items against the totals.", "allOf": [ { "$ref": "#/components/schemas/LineItemCheck" } ] }, "confidenceBasis": { "description": "What `extractionConfidence` is based on: `requirementsChecked` is the number of requirements the extraction was checked against, `requirementsMet` how many it satisfied.", "allOf": [ { "$ref": "#/components/schemas/ConfidenceBasis" } ] }, "warnings": { "type": "array", "description": "Notes about values the analyzer had to substitute or derive so the invoice stays processable (see `code`); empty when there are none. A placeholder is not real data: check these.", "items": { "$ref": "#/components/schemas/AnalysisWarning" } } } }, "LegacyPdfAnalysisResult": { "type": "object", "properties": { "apiStatus": { "type": "integer", "example": 200 }, "invoice": { "$ref": "#/components/schemas/ExtractedInvoice" } } }, "AsyncSubmitResult": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Pass this to the status endpoint." }, "status": { "type": "string", "enum": [ "processing" ] } } }, "AsyncAnalysisStatus": { "type": "object", "description": "State of a background analysis job. `result` is present when `status` is `done`, `error` when it is `failed`.", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "processing", "done", "failed" ] }, "result": { "$ref": "#/components/schemas/PdfAnalysisResult" }, "error": { "$ref": "#/components/schemas/AnalysisErrorDetail" } } }, "AsyncStatusUnauthorized": { "type": "object", "properties": { "status": { "type": "string", "example": "unauthorized" }, "message": { "type": "string", "example": "Not authorized or insufficient credits." } } }, "GatewayError": { "type": "object", "description": "Error body of the V1 gateway. Depending on where the request is rejected, the text is in `error` or in `message` (with optional `errors` details).", "properties": { "error": { "type": "string", "example": "Invalid token." }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "MessageResponse": { "type": "object", "properties": { "message": { "type": "string" } } }, "AnalysisErrorDetail": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, machine-readable. One of `INVALID_REQUEST`, `UNAUTHORIZED`, `FILE_TOO_LARGE`, `PDF_CORRUPT`, `PDF_ENCRYPTED`, `PDF_NO_TEXT`, `EXTRACTION_LOW_CONFIDENCE`, `PROCESSING_TEMPORARY_ERROR`, `UNKNOWN_ERROR`. Use a `default` branch for codes added later." }, "userMessage": { "type": "string", "description": "German text that is safe to show to end users." }, "detail": { "type": "string", "description": "Technical detail for logs and debugging." }, "reference": { "type": "string", "description": "Reference (e.g. `REA-144845`) to quote in support requests.", "example": "REA-144845" } } }, "AnalysisError": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "$ref": "#/components/schemas/AnalysisErrorDetail" } } }, "ErrorField": { "type": "object", "description": "One entry of `error.fields`. Which properties are present depends on `error.code`: `MISSING_MANDATORY_FIELDS` → `bt`, `field`, `label`, `rule`; `VERIFICATION_FAILED` → `field`, `extracted`, `foundInDocument`, `note`; `ZUGFERD_REJECTED` → `rule`, `message`, `type`, `location`.", "properties": { "bt": { "type": "string", "description": "EN 16931 business term, e.g. `BT-5`." }, "field": { "type": "string", "description": "Dotted path into the extracted invoice JSON (or the compared total)." }, "label": { "type": "string", "description": "German label of the missing field." }, "rule": { "type": "string", "description": "Violated rule id, e.g. `BR-05`." }, "extracted": { "type": "number", "nullable": true, "description": "Value computed from the extracted line items." }, "foundInDocument": { "type": "number", "nullable": true, "description": "Value printed on the document." }, "note": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string", "description": "Severity, e.g. `fatal`." }, "location": { "type": "string", "description": "XPath of the offending element." } } }, "ErrorExplanation": { "type": "object", "description": "Plain-German explanation of one rule code listed in `error.ruleCodes`.", "properties": { "code": { "type": "string" }, "found": { "type": "boolean" }, "title": { "type": "string" }, "description": { "type": "string" }, "source": { "type": "string" }, "file": { "type": "string" } } }, "ZugferdFromPdfErrorDetail": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, machine-readable. One of `INVALID_REQUEST`, `UNAUTHORIZED`, `FILE_TOO_LARGE`, `PDF_CORRUPT`, `PDF_ENCRYPTED`, `PDF_NO_TEXT`, `EXTRACTION_LOW_CONFIDENCE`, `MISSING_MANDATORY_FIELDS`, `VERIFICATION_FAILED`, `ZUGFERD_REJECTED`, `PROCESSING_TEMPORARY_ERROR`, `UNKNOWN_ERROR`. Any other code is normalised to `UNKNOWN_ERROR` before it leaves the API." }, "stage": { "type": "string", "description": "Pipeline stage that failed: `input`, `access`, `analyse`, `missing`, `verify`, `zugferd` or `unknown`." }, "httpStatus": { "type": "integer" }, "retryable": { "type": "boolean", "description": "`true` only for `PROCESSING_TEMPORARY_ERROR`." }, "userMessage": { "type": "string", "description": "German text that is safe to show to end users." }, "detail": { "type": "string" }, "reference": { "type": "string", "description": "`ZAPI-`. Log it; support needs it to trace a conversion.", "example": "ZAPI-151436" }, "upstreamReference": { "type": "string", "description": "Reference of the analysis step (`REA-…`), when available." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorField" } }, "ruleCodes": { "type": "array", "items": { "type": "string" } }, "explanations": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorExplanation" } }, "extractionConfidence": { "type": "number" } } }, "ErrorEmail": { "type": "object", "description": "Ready-to-send notification for the invoice owner.", "properties": { "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" } } }, "ZugferdFromPdfError": { "type": "object", "description": "Error envelope of `createZugferdFromPdf`. Every rejection carries a ready-to-send `email` object (shown in one example only, for brevity).", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "$ref": "#/components/schemas/ZugferdFromPdfErrorDetail" }, "email": { "$ref": "#/components/schemas/ErrorEmail" } } }, "CreateXRechnungResult": { "type": "object", "properties": { "message": { "type": "string", "description": "Status text, `xInvoice generated`.", "example": "xInvoice generated" }, "valid": { "type": "boolean", "description": "`true` if the generated XML passed validation (`xInvoiceErrors` is empty). The XML is returned either way." }, "numberOfXInvoiceErrors": { "type": "integer", "description": "Number of entries in `xInvoiceErrors`." }, "xInvoiceErrors": { "type": "array", "description": "Validation findings for the generated XML; empty when `valid` is `true`.", "items": { "$ref": "#/components/schemas/ValidationMessage" } }, "xInvoice": { "type": "string", "description": "The generated XRechnung XML (UTF-8) in the syntax requested with `xmlFormat` — CII by default, UBL on request — returned inline, also when `valid` is `false`." }, "downloadURL": { "type": "string", "description": "Link to the generated XML (`Content-Type: application/xml`). It can be opened without an Authorization header, so anyone who has the link can download the file — treat it like a secret." }, "resendToken": { "type": "string", "description": "Empty string `\"\"` when no email was sent. When `transport` was used on a valid document, the token for `sendEmailWithZugferdData` — see the `transport` object." }, "invoice": { "type": "array", "description": "A one-element array holding the invoice as the API understood it: the full invoice object, normalised. Every field is present — unset text fields are `\"\"`, unset dates and objects `null`, unset lists `[]`; dates are ISO-8601 timestamps with a UTC offset (e.g. `2026-02-16T00:00:00+01:00`). Price details you leave out are filled with `0`.", "items": { "$ref": "#/components/schemas/ExtractedInvoice" } } } }, "CreateZugferdResult": { "type": "object", "properties": { "message": { "type": "string", "description": "Status text, `ZUGFeRD created`.", "example": "ZUGFeRD created" }, "xInvoice": { "type": "string", "description": "The XRechnung XML generated from your invoice data and embedded in the PDF (UTF-8), returned inline." }, "zugferd": { "type": "string", "description": "The ZUGFeRD PDF/A-3, base64-encoded — also when validation found errors." }, "downloadURL": { "type": "string", "description": "Link to the generated file. It can be opened without an Authorization header, so anyone who has the link can download it — treat it like a secret." }, "resendToken": { "type": "string", "description": "Empty string `\"\"` when no email was sent. When `transport` was used on a valid document, the token for `sendEmailWithZugferdData` — see the `transport` object." }, "xInvoiceValid": { "type": "boolean", "description": "`true` if the generated XML passed validation (`xInvoiceErrorList` is empty)." }, "zugferdValid": { "type": "boolean", "description": "`true` if the finished ZUGFeRD PDF passed validation (`zugferdErrorList` is empty)." }, "numberOfxInvoiceErrors": { "type": "integer", "description": "Number of entries in `xInvoiceErrorList`. Note the lowercase `x` in this name." }, "numberOfZugferdErrors": { "type": "integer", "description": "Number of entries in `zugferdErrorList`." }, "xInvoiceErrorList": { "type": "array", "description": "Validation findings for the generated XML; empty when `xInvoiceValid` is `true`.", "items": { "$ref": "#/components/schemas/ValidationMessage" } }, "zugferdErrorList": { "type": "array", "description": "Validation findings for the finished ZUGFeRD PDF; empty when `zugferdValid` is `true`. Same properties as `xInvoiceErrorList`.", "items": { "$ref": "#/components/schemas/ValidationMessage" } }, "invoiceJson": { "type": "array", "description": "A one-element array holding the invoice as the API understood it — the full invoice object, normalised (see `createXinvoiceFromJson`). Identical to `invoice`.", "items": { "$ref": "#/components/schemas/ExtractedInvoice" } }, "invoice": { "type": "array", "description": "The same normalised invoice as `invoiceJson`, repeated under the name used by `createXinvoiceFromJson`.", "items": { "$ref": "#/components/schemas/ExtractedInvoice" } } } }, "CreateZugferdPdfFromXRechnungResult": { "type": "object", "properties": { "message": { "type": "string", "description": "Status text, `zugferd created`.", "example": "zugferd created" }, "valid": { "type": "boolean", "description": "`true` if the finished ZUGFeRD PDF passed validation (`zugferdErrors` is empty). The PDF is returned either way." }, "numberOfZugferdErrors": { "type": "integer", "description": "Number of entries in `zugferdErrors`." }, "zugferdErrors": { "type": "array", "description": "Validation findings for the finished ZUGFeRD PDF; empty when `valid` is `true`.", "items": { "$ref": "#/components/schemas/ValidationMessage" } }, "zugferdFile": { "type": "string", "description": "The ZUGFeRD PDF/A-3, base64-encoded." }, "createdInvoice": { "type": "array", "description": "A one-element array: the invoice data the PDF was built from, i.e. your XML parsed into the invoice object structure.", "items": { "$ref": "#/components/schemas/ExtractedInvoice" } }, "extractedInvoice": { "type": "array", "description": "A one-element array: the invoice data read back from the finished ZUGFeRD, in the same form as the `extractedInvoice` of `extractXInvoiceFromZugferdToJson` — but wrapped in an array.", "items": { "$ref": "#/components/schemas/ExtractedInvoice" } }, "validXRechnung": { "type": "boolean", "description": "`true` if the XML you submitted passed XRechnung validation (`xrechnungErrors` is empty)." }, "xrechnungErrors": { "type": "array", "description": "Validation findings for the XML you submitted, in the same shape as `zugferdErrors`; empty when `validXRechnung` is `true`.", "items": { "$ref": "#/components/schemas/ValidationMessage" } } } }, "CreateInvoicePdfResult": { "type": "object", "properties": { "message": { "type": "string", "description": "Status text: `pdf created, downloaded and stored in DMS` when `invoicePassthrough` is `false`, otherwise `pdf created, downloaded and not stored in DMS`." }, "iqDataId": { "type": "integer", "description": "ID of the entry created in your account's invoice list. `0` in an Idempotency-Key replay." }, "documentId": { "type": "integer", "description": "Only present in an Idempotency-Key replay (HTTP 200), where it is `0`." }, "fsNodeId": { "type": "integer", "description": "Only present in an Idempotency-Key replay (HTTP 200), where it is `0`." }, "downloadURL": { "type": "string", "description": "Link to the generated PDF (`Content-Type: application/pdf`). It can be opened without an Authorization header, so anyone who has the link can download the file — treat it like a secret." }, "resendToken": { "type": "string", "description": "Empty string `\"\"` when no email was sent. When `transport` was used on a valid document, the token for `sendEmailWithZugferdData` — see the `transport` object. Not present in an Idempotency-Key replay." }, "fileName": { "type": "string", "description": "File name of the PDF — your `invoiceFilename` if you sent one. Without it the API generates a name that is not meant to be read by people: it carries an opaque suffix and currently ends in `.pdf.pdf`. Set `invoiceFilename` whenever the name matters, e.g. for email attachments." }, "fileExtension": { "type": "string", "description": "File extension, `pdf`." }, "fileSize": { "type": "integer", "description": "Size of the PDF in bytes." }, "filecontentB64": { "type": "string", "description": "The generated ZUGFeRD PDF, base64-encoded. This is the document itself; `downloadURL` points to the same file." }, "zugferdIsValid": { "type": "boolean", "description": "`true` if the ZUGFeRD data embedded in the PDF passed validation." }, "zugferdErrors": { "type": "array", "description": "Validation findings for the returned document, in the same shape as `errorList` in the 412 response; empty when `zugferdIsValid` is `true`.", "items": { "$ref": "#/components/schemas/ValidationMessage" } } } }, "ValidateXRechnungXmlResult": { "type": "object", "properties": { "message": { "type": "string", "description": "`validated. ()` when the document passed the schema and Schematron rules, so the additional checks also ran; `` is the length of the submitted XML in characters. Otherwise `validation done` — see the examples." }, "valid": { "type": "boolean", "description": "`true` if there are no findings in `xInvoiceErrors`, otherwise `false`." }, "isIbanValidInXML": { "type": "boolean", "description": "`true` if the IBAN in the invoice is valid, `false` if it is invalid or the document contains no IBAN. Reported independently of `valid`. A valid IBAN here only means its format and check digits are correct – it does not confirm that the account exists or who owns it. Only present when the document passed the schema and Schematron rules (`message: validated. ()`)." }, "xInvoiceErrors": { "type": "array", "description": "All findings; empty when `valid` is `true`.", "items": { "$ref": "#/components/schemas/ValidationMessage" } }, "xmllength": { "type": "integer", "description": "Length of the submitted XML in characters. Only present together with `message: validation done`, and in the 412 response." } } }, "ValidateZugferdPdfResult": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "`true` if the embedded XML has no findings in `zugferdErrors`, otherwise `false`." }, "message": { "type": "string", "description": "`File was validated` whenever the validation ran. Other texts only come with the special cases." }, "isIbanValidInZugferd": { "type": "boolean", "description": "`true` if the IBAN in the invoice is valid, `false` if it is invalid. Reported independently of `valid`: a ZUGFeRD PDF with an invalid IBAN can still return `valid: true`. A valid IBAN here only means its format and check digits are correct – it does not confirm that the account exists or who owns it. Not returned when `message` is `cannot extract data to validate`." }, "numberOfZugferdErrors": { "type": "integer", "description": "Number of findings in the embedded XML. `zugferdErrors` lists them (the example shows only one of the ten)." }, "zugferdErrors": { "type": "array", "description": "All findings; empty when `valid` is `true`.", "items": { "$ref": "#/components/schemas/ValidationMessage" } } } }, "ExtractXRechnungResult": { "type": "object", "properties": { "extractedInvoice": { "description": "The embedded invoice as a full invoice object. Every field is present — unset values are `\"\"` or `null`, unset lists `[]`; dates are ISO-8601 timestamps with a UTC offset (e.g. `2026-02-16T00:00:00+01:00`). `null` when the PDF contains no readable XML.", "allOf": [ { "$ref": "#/components/schemas/ExtractedInvoice" } ] }, "zugferdIsValid": { "type": "boolean", "description": "`true` if the embedded XML passed validation. `false` comes with HTTP 400." }, "zugferdErrorlist": { "type": "array", "description": "Validation findings of the embedded XML; empty when `zugferdIsValid` is `true`.", "items": { "$ref": "#/components/schemas/ValidationMessage" } } } }, "SendEmailResult": { "type": "object", "properties": { "message": { "type": "string" }, "resendToken": { "type": "string", "description": "Use with `resendEmail` to send the same email again later." } } }, "MissingDataItem": { "type": "object", "properties": { "businessTerm": { "type": "string", "description": "EN 16931 business term that is missing, e.g. `BT-34`.", "example": "BT-34" }, "businessTermDescription": { "type": "string", "description": "Business term with the name of the JSON field to fill, e.g. `BT-34 (sellerElectronicAddress)`.", "example": "BT-34 (sellerElectronicAddress)" }, "errormessage": { "type": "string", "description": "What is wrong with the field, in English (e.g. a valid email address is required)." } } }, "MissingDataError": { "type": "object", "description": "Body of HTTP 412 on the generation endpoints when mandatory invoice data is missing or unusable. Nothing is generated. For `createXinvoiceFromJson` the list names every gap as an EN 16931 business term; for `createZugferdFromJson` the reason is usually only in `message` (`noOfMissingData` `0`, `errorlist` empty). Note the lowercase `l` in `errorlist`.", "properties": { "message": { "type": "string", "description": "`Data are missing in input.`" }, "noOfMissingData": { "type": "integer", "description": "Number of entries in `errorlist`." }, "errorlist": { "type": "array", "description": "One entry per missing business term; empty when the reason is only in `message`.", "items": { "$ref": "#/components/schemas/MissingDataItem" } } } }, "LineItemCheck": { "type": "object", "properties": { "status": { "type": "string", "example": "ok", "description": "Overall result of the line-item check, e.g. `ok`." }, "verified": { "type": "boolean", "description": "`true` if the line items could be confirmed against a printed total." }, "lines": { "type": "integer", "description": "Number of line items found." }, "linesRecomputed": { "type": "integer", "description": "Number of line items whose amount was recomputed for the check." }, "linesInconsistent": { "type": "integer", "description": "Number of line items whose recomputed amount did not match the extracted one. `0` is the good case." }, "lineSum": { "type": "number", "description": "Sum of the line net amounts." }, "sumCheck": { "type": "string", "example": "ok", "description": "Whether `lineSum` agrees with the document's total, e.g. `ok`." }, "confirmedBy": { "type": "string", "example": "printed BT-106", "description": "Which value on the document confirmed the sum, e.g. `printed BT-106` (the printed sum of line net amounts)." }, "vatCheck": { "type": "string", "example": "ok", "description": "Whether the VAT figures are consistent, e.g. `ok`." } }, "description": "Plausibility check of the extracted line items against the totals." }, "ConfidenceBasis": { "type": "object", "properties": { "requirementsChecked": { "type": "integer", "description": "Number of requirements the extraction was checked against." }, "requirementsMet": { "type": "integer", "description": "How many of them it satisfied." } }, "description": "What `extractionConfidence` is based on: `requirementsChecked` is the number of requirements the extraction was checked against, `requirementsMet` how many it satisfied." }, "AnalysisWarning": { "type": "object", "properties": { "code": { "type": "string", "description": "Kind of warning. Observed: `PLACEHOLDER_INSERTED` (a required value was not on the document, so a placeholder was inserted) and `VALUE_DERIVED` (a value was derived rather than read, e.g. country `DE` assumed for a domestic address).", "example": "PLACEHOLDER_INSERTED" }, "field": { "type": "string", "description": "The business term concerned.", "example": "BT-10" }, "message": { "type": "string", "description": "Human-readable explanation, in German." } }, "description": "One note about the extraction. Notes about values the analyzer had to substitute or derive so the invoice stays processable (see `code`); empty when there are none. A placeholder is not real data: check these." }, "MandatoryFieldReportItem": { "type": "object", "description": "One mandatory EN 16931 / XRechnung detail that the document does not provide.", "required": [ "rule", "bt", "field", "label" ], "properties": { "rule": { "type": "string", "description": "The rule that makes the detail mandatory: an EN 16931 business rule (`BR-09`, `BR-CO-26`) or a German XRechnung rule (`BR-DE-1`, `BR-DE-16`).", "example": "BR-DE-6" }, "bt": { "type": "string", "description": "The EN 16931 business term (`BT-40`) or business group (`BG-16`) concerned. Where several terms satisfy the rule alternatively they are joined with `/`, e.g. `BT-29/BT-30/BT-31`.", "example": "BT-42" }, "field": { "type": "string", "description": "Dotted path into `invoice` where the missing value belongs. A whole group is addressed by its object name, e.g. `paymentInstructions`.", "example": "seller.sellerContact.sellerContactTelephoneNumber" }, "label": { "type": "string", "description": "Short German name of the missing detail, for display. Spelled with ae/oe/ue instead of ä/ö/ü (e.g. `Land des Verkaeufers`): show it to users, but use `field`, `bt` or `rule` in code.", "example": "Telefon des Verkaeufers" } } }, "AsyncStatusGone": { "type": "object", "properties": { "status": { "type": "string", "example": "gone" }, "message": { "type": "string", "example": "Job not found or expired (past 24h retention)." } } }, "CreateInvoicePdfValidationError": { "type": "object", "description": "Body of HTTP 412. Either the invoice data broke validation rules (`errorList`, `errors`, `invoiceId`, `iqDataId` present) or the PDF could not be rendered (only `message`).", "properties": { "message": { "type": "string", "description": "Status text, `errors in data`." }, "invoiceId": { "type": "integer", "description": "ID of the invoice record the API created for this attempt." }, "iqDataId": { "type": "integer", "description": "Same kind of ID as in the 201 response." }, "errors": { "type": "integer", "description": "Number of entries in `errorList`." }, "errorList": { "type": "array", "description": "The violated rules.", "items": { "$ref": "#/components/schemas/ValidationMessage" } } } } } } }