{ "openapi": "3.1.1", "info": { "title": "InvoiceXML API", "description": "EN 16931 e-invoicing service — create, convert, render, extract, validate. All `/v1/create/*` endpoints accept the `CreateInvoiceRequest` envelope (`{ invoice, options }`). Errors follow RFC 7807 ProblemDetails with a machine-readable `errorCode` extension (see `x-error-codes` on the document root).", "version": "1.0.0" }, "servers": [ { "url": "http://api.invoicexml.com/" } ], "paths": { "/v1/convert/cii/to/ubl": { "post": { "tags": [ "Convert" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/convert/ubl/to/cii": { "post": { "tags": [ "Convert" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/create/ubl": { "post": { "tags": [ "Create" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/create/cii": { "post": { "tags": [ "Create" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/create/xrechnung": { "post": { "tags": [ "Create" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/create/facturx": { "post": { "tags": [ "Create" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/create/zugferd": { "post": { "tags": [ "Create" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/embed/xml": { "post": { "tags": [ "Embed" ], "summary": "Accepts a PDF and a CII XML as multipart form fields and returns a\nPDF/A-3 with the XML embedded as a Factur-X / ZUGFeRD attachment.", "requestBody": { "description": "A UN/CEFACT Cross Industry Invoice (CII) XML document.", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } }, { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } ] } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/extract/xml": { "post": { "tags": [ "Extract" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/extract/json": { "post": { "tags": [ "Extract" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/": { "get": { "tags": [ "Home" ], "responses": { "200": { "description": "OK" } } } }, "/v1/parse/json": { "post": { "tags": [ "Parse" ], "summary": "Accepts a PDF (typed, scanned, or photographed) and runs the AI extraction\npipeline to produce a structured `InvoiceDocument` JSON. Any embedded\nXML in the PDF is ignored; use `POST /v1/extract/json` if you want\nthe embedded XML parsed instead.", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/render/xrechnung/to/pdf": { "post": { "tags": [ "Render" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } }, { "type": "object", "properties": { "language": { "type": "string", "default": "en" } } } ] } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/render/cii/to/pdf": { "post": { "tags": [ "Render" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } }, { "type": "object", "properties": { "language": { "type": "string", "default": "en" } } } ] } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/render/ubl/to/pdf": { "post": { "tags": [ "Render" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } }, { "type": "object", "properties": { "language": { "type": "string", "default": "en" } } } ] } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/transform/to/ubl": { "post": { "tags": [ "Transform" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/transform/to/cii": { "post": { "tags": [ "Transform" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/transform/to/xrechnung": { "post": { "tags": [ "Transform" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } }, { "type": "object", "properties": { "buyerReference": { "type": "string" } } } ] } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/transform/to/zugferd": { "post": { "tags": [ "Transform" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } }, { "type": "object", "properties": { "language": { "type": "string", "default": "en" } } } ] } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/transform/to/facturx": { "post": { "tags": [ "Transform" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } }, { "type": "object", "properties": { "language": { "type": "string", "default": "en" } } } ] } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/validate/ubl": { "post": { "tags": [ "Validate" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/validate/cii": { "post": { "tags": [ "Validate" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/validate/xrechnung": { "post": { "tags": [ "Validate" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/v1/validate/{format}": { "post": { "tags": [ "Validate" ], "parameters": [ { "name": "format", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ContentType": { "type": "string" }, "ContentDisposition": { "type": "string" }, "Headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "Name": { "type": "string" }, "FileName": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "BuyerContact": { "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "phone": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] } } }, "BuyerElectronicAddress": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "BuyerIdentifier": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "BuyerLegalRegistration": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "BuyerParty": { "required": [ "name", "postalAddress" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "tradingName": { "type": [ "null", "string" ] }, "postalAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BuyerPostalAddress" } ] }, "contact": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BuyerContact" } ] }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerIdentifier" } }, "legalRegistration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BuyerLegalRegistration" } ] }, "vatIdentifier": { "type": [ "null", "string" ] }, "electronicAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BuyerElectronicAddress" } ] } } }, "BuyerPostalAddress": { "required": [ "country" ], "type": "object", "properties": { "line1": { "type": [ "null", "string" ] }, "line2": { "type": [ "null", "string" ] }, "line3": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "postCode": { "type": [ "null", "string" ] }, "countrySubdivision": { "type": [ "null", "string" ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CountryCode" } ] } } }, "CountryCode": { "type": "integer" }, "CreateInvoiceRequest": { "required": [ "invoice" ], "type": "object", "properties": { "invoice": { "oneOf": [ { "type": "null" }, { "description": "The invoice document itself (BT-first EN 16931 model).", "$ref": "#/components/schemas/InvoiceDocument" } ] }, "options": { "description": "Optional rendering / processing settings. Defaults apply when omitted.", "$ref": "#/components/schemas/InvoiceOptions" } }, "description": "Envelope for all `/v1/create/*` endpoints. Wraps the BT-first\nInvoiceDocument together with non-BT processing options.", "example": { "invoice": { "invoiceNumber": "INV-2026-00045", "issueDate": "2026-05-17", "currency": "EUR", "seller": { "name": "Acme Engineering GmbH", "vatIdentifier": "DE123456789", "legalRegistration": "HRB 12345", "postalAddress": { "line1": "Hauptstraße 12", "city": "Berlin", "postCode": "10115", "country": "DE" } }, "buyer": { "name": "Globex SAS", "postalAddress": { "line1": "15 rue de Rivoli", "city": "Paris", "postCode": "75001", "country": "FR" } }, "paymentDetails": { "paymentAccountIdentifier": "DE89370400440532013000" }, "lines": [ { "quantity": 10, "priceDetails": { "netPrice": 150.00 }, "vatInformation": { "rate": 19.00 }, "item": { "name": "Senior consulting" } } ] }, "options": { "language": "EN", "brandColor": "#0F766E" } } }, "CurrencyCode": { "type": "integer" }, "DeliveryInformation": { "type": "object", "properties": { "receiverName": { "type": [ "null", "string" ] }, "locationIdentifier": { "type": [ "null", "string" ] }, "actualDeliveryDate": { "type": [ "null", "string" ], "format": "date" }, "deliveryAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeliveryPostalAddress" } ] } } }, "DeliveryPostalAddress": { "type": "object", "properties": { "line1": { "type": [ "null", "string" ] }, "line2": { "type": [ "null", "string" ] }, "line3": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "postCode": { "type": [ "null", "string" ] }, "countrySubdivision": { "type": [ "null", "string" ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CountryCode" } ] } } }, "DocumentLevelAllowance": { "type": "object", "properties": { "amount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "baseAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "percentage": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "vatCategoryCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VatCategoryCode" } ] }, "vatRate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "reason": { "type": [ "null", "string" ] }, "reasonCode": { "type": [ "null", "string" ] } } }, "DocumentLevelCharge": { "type": "object", "properties": { "amount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "baseAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "percentage": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "vatCategoryCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VatCategoryCode" } ] }, "vatRate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "reason": { "type": [ "null", "string" ] }, "reasonCode": { "type": [ "null", "string" ] } } }, "DocumentTotals": { "type": "object", "properties": { "sumOfLineNetAmounts": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "sumOfAllowances": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "sumOfCharges": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "taxBasisTotalAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "taxTotalAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "taxTotalAmountInAccountingCurrency": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "grandTotalAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "paidAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "roundingAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "duePayableAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" } } }, "InvoiceDocument": { "required": [ "invoiceNumber", "currency", "seller", "buyer", "lines" ], "type": "object", "properties": { "invoiceNumber": { "type": [ "null", "string" ] }, "issueDate": { "type": [ "null", "string" ], "format": "date" }, "dueDate": { "type": [ "null", "string" ], "format": "date" }, "typeCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvoiceTypeCode" } ] }, "currency": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CurrencyCode" } ] }, "taxCurrency": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CurrencyCode" } ] }, "specificationId": { "type": [ "null", "string" ] }, "businessProcessType": { "type": [ "null", "string" ] }, "buyerReference": { "type": [ "null", "string" ] }, "purchaseOrderReference": { "type": [ "null", "string" ] }, "notes": { "type": "array", "items": { "type": "string" } }, "precedingInvoiceReferences": { "type": "array", "items": { "$ref": "#/components/schemas/PrecedingInvoiceReference" } }, "seller": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SellerParty" } ] }, "buyer": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BuyerParty" } ] }, "delivery": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeliveryInformation" } ] }, "invoicingPeriod": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvoicingPeriod" } ] }, "paymentDetails": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentDetails" } ] }, "totals": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentTotals" } ] }, "vatBreakdowns": { "type": "array", "items": { "$ref": "#/components/schemas/VatBreakdown" } }, "lines": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" } }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLevelAllowance" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLevelCharge" } } } }, "InvoiceLine": { "required": [ "quantity", "priceDetails", "vatInformation", "item" ], "type": "object", "properties": { "lineId": { "type": [ "null", "string" ] }, "lineNote": { "type": [ "null", "string" ] }, "objectIdentifier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LineObjectIdentifier" } ] }, "quantity": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "unitCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnitCode" } ] }, "lineNetAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "buyerOrderLineReference": { "type": [ "null", "string" ] }, "lineBuyerAccountingReference": { "type": [ "null", "string" ] }, "linePeriod": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvoiceLinePeriod" } ] }, "priceDetails": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PriceDetails" } ] }, "vatInformation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LineVatInformation" } ] }, "item": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ItemInformation" } ] }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/LineAllowance" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/LineCharge" } } } }, "InvoiceLinePeriod": { "type": "object", "properties": { "startDate": { "type": [ "null", "string" ], "format": "date" }, "endDate": { "type": [ "null", "string" ], "format": "date" } } }, "InvoiceOptions": { "type": "object", "properties": { "language": { "oneOf": [ { "type": "null" }, { "description": "Localisation for PDF rendering. Defaults to PdfLanguage.EN\nwhen omitted.", "$ref": "#/components/schemas/PdfLanguage" } ] }, "brandColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": [ "null", "string" ], "description": "Primary brand colour applied to PDF headings and accent backgrounds\n(document title, table header, totals box, section headers).\nHex format `#RRGGBB`. When omitted the renderer uses its default.\nBody text is never recoloured so legibility is preserved regardless of brand." } }, "description": "Non-BT processing options that travel alongside an invoice in\nCreateInvoiceRequest. Extend this type to add new\ncustomisation knobs without touching `InvoiceDocument` or any\ncontroller signature." }, "InvoiceTypeCode": { "type": "integer" }, "InvoicingPeriod": { "type": "object", "properties": { "startDate": { "type": [ "null", "string" ], "format": "date" }, "endDate": { "type": [ "null", "string" ], "format": "date" } } }, "ItemClassification": { "required": [ "identifier", "schemeId", "schemeVersion" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] }, "schemeVersion": { "type": [ "null", "string" ] } } }, "ItemInformation": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "sellerIdentifier": { "type": [ "null", "string" ] }, "buyerIdentifier": { "type": [ "null", "string" ] }, "standardIdentifier": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ItemStandardIdentifier" } ] }, "classifications": { "type": "array", "items": { "$ref": "#/components/schemas/ItemClassification" } }, "countryOfOrigin": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CountryCode" } ] } } }, "ItemStandardIdentifier": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "LineAllowance": { "type": "object", "properties": { "amount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "baseAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "percentage": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "reason": { "type": [ "null", "string" ] }, "reasonCode": { "type": [ "null", "string" ] } } }, "LineCharge": { "type": "object", "properties": { "amount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "baseAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "percentage": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "reason": { "type": [ "null", "string" ] }, "reasonCode": { "type": [ "null", "string" ] } } }, "LineObjectIdentifier": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "LineVatInformation": { "type": "object", "properties": { "categoryCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VatCategoryCode" } ] }, "rate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" } } }, "PaymentDetails": { "type": "object", "properties": { "paymentMeansCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaymentMeansCode" } ] }, "paymentMeansText": { "type": [ "null", "string" ] }, "remittanceInformation": { "type": [ "null", "string" ] }, "paymentAccountIdentifier": { "type": [ "null", "string" ] }, "paymentAccountName": { "type": [ "null", "string" ] }, "bic": { "type": [ "null", "string" ] }, "mandateReference": { "type": [ "null", "string" ] }, "paymentTerms": { "type": [ "null", "string" ] } } }, "PaymentMeansCode": { "type": "integer" }, "PdfLanguage": { "type": "integer" }, "PrecedingInvoiceReference": { "type": "object", "properties": { "reference": { "type": [ "null", "string" ] }, "issueDate": { "type": [ "null", "string" ], "format": "date" } } }, "PriceDetails": { "required": [ "netPrice" ], "type": "object", "properties": { "netPrice": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "discountAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "grossPrice": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "priceBaseQuantity": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "priceBaseUnit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UnitCode" } ] } } }, "SellerContact": { "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "phone": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] } } }, "SellerElectronicAddress": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "SellerIdentifier": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "SellerLegalRegistration": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "SellerParty": { "required": [ "name", "postalAddress" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "tradingName": { "type": [ "null", "string" ] }, "postalAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SellerPostalAddress" } ] }, "contact": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SellerContact" } ] }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/SellerIdentifier" } }, "legalRegistration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SellerLegalRegistration" } ] }, "vatIdentifier": { "type": [ "null", "string" ] }, "taxRegistrationIdentifier": { "type": [ "null", "string" ] }, "additionalLegalInformation": { "type": [ "null", "string" ] }, "electronicAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SellerElectronicAddress" } ] } } }, "SellerPostalAddress": { "required": [ "country" ], "type": "object", "properties": { "line1": { "type": [ "null", "string" ] }, "line2": { "type": [ "null", "string" ] }, "line3": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "postCode": { "type": [ "null", "string" ] }, "countrySubdivision": { "type": [ "null", "string" ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CountryCode" } ] } } }, "UnitCode": { "type": "integer" }, "VatBreakdown": { "type": "object", "properties": { "taxableAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "taxAmount": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "categoryCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VatCategoryCode" } ] }, "rate": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "exemptionReasonText": { "type": [ "null", "string" ] }, "exemptionReasonCode": { "type": [ "null", "string" ] } } }, "VatCategoryCode": { "type": "integer" } } }, "tags": [ { "name": "Convert" }, { "name": "Create" }, { "name": "Embed" }, { "name": "Extract" }, { "name": "Home" }, { "name": "Parse" }, { "name": "Render" }, { "name": "Transform" }, { "name": "Validate" } ], "x-error-codes": [ { "code": 401, "name": "Unauthorized", "description": "Bearer token missing or invalid." }, { "code": 4000, "name": "Unknown", "description": "Catch-all server error not covered by a more specific code." }, { "code": 4001, "name": "XmlValidation", "description": "Generated XML failed EN 16931 / Schematron validation (see `errors.xml` and `errors.friendly`)." }, { "code": 4002, "name": "ModelValidation", "description": "Request body / form payload failed MVC validation (missing or invalid fields)." }, { "code": 4003, "name": "MissingFile", "description": "Multipart endpoint expected a file but none was provided." }, { "code": 4004, "name": "UnsupportedContentType", "description": "Uploaded file's content-type or extension wasn't acceptable for the endpoint." }, { "code": 4005, "name": "FileTooLarge", "description": "Upload exceeded the per-file size limit." }, { "code": 4006, "name": "NoEmbeddedXml", "description": "PDF didn't contain an embedded ZUGFeRD/Factur-X XML attachment." }, { "code": 4007, "name": "PdfError", "description": "Failure during PDF processing (corruption, encryption, or rendering pipeline)." }, { "code": 4008, "name": "NotAnInvoice", "description": "Document was classified as not being an invoice (AI extraction pre-flight)." }, { "code": 4009, "name": "MultipleInvoices", "description": "Uploaded PDF appears to contain multiple invoices; submit one per request." } ] }