{ "openapi": "3.1.0", "info": { "title": "Conformo HTTP API", "version": "0.2.4", "description": "Stateless HTTP API over @conformo/toolkit: create, validate, convert and parse EN 16931 e-invoices. No accounts, no sessions, nothing written to disk. There is no authentication: put it behind a TLS reverse proxy with auth before exposing it. Conformo only produces, reads and checks documents. It does not transmit anything (no Peppol access point, no French PA/PDP, no KSeF, no SdI) and does not support FatturaPA or Facturae; it handles KSeF FA(3) only as domestic PLN invoices it writes and schema-checks (it cannot read them). A valid result means the rule sets listed in `ruleSets` passed, not that a tax authority accepts the invoice. The server stores nothing.", "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" } }, "servers": [ { "url": "/" } ], "tags": [ { "name": "create" }, { "name": "validate" }, { "name": "convert" }, { "name": "reference" }, { "name": "meta" } ], "paths": { "/v1/invoices/xml": { "post": { "operationId": "createInvoiceXml", "tags": [ "create" ], "summary": "Create e-invoice XML", "description": "Serializes a structured invoice to CII, UBL, XRechnung or Peppol BIS XML. Money fields end in \"Minor\" and are integers in minor units; totals and the VAT breakdown are computed, never sent. Conformo only produces, reads and checks documents. It does not transmit anything (no Peppol access point, no French PA/PDP, no KSeF, no SdI) and does not support FatturaPA or Facturae; it handles KSeF FA(3) only as domestic PLN invoices it writes and schema-checks (it cannot read them). A valid result means the rule sets listed in `ruleSets` passed, not that a tax authority accepts the invoice. The server stores nothing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "format": { "$ref": "#/components/schemas/FormatId" } }, "required": [ "invoice", "format" ], "additionalProperties": false }, "example": { "invoice": { "number": "INV-2026-001", "issueDate": "2026-09-01", "dueDate": "2026-09-30", "currency": "EUR", "buyerReference": "04011000-1234512345-06", "paymentTerms": "Payable within 30 days.", "seller": { "name": "Example Software GmbH", "vatId": "DE123456789", "street": "Hauptstrasse 1", "city": "Berlin", "postcode": "10115", "country": "DE", "electronicAddress": "billing@example-software.example", "electronicAddressScheme": "EM", "contact": { "name": "Erika Mustermann", "phone": "+49 30 1234567", "email": "billing@example-software.example" } }, "buyer": { "name": "Beispiel AG", "street": "Marktplatz 2", "city": "Hamburg", "postcode": "20095", "country": "DE", "electronicAddress": "ap@beispiel.example", "electronicAddressScheme": "EM" }, "payment": { "meansCode": "58", "iban": "DE89370400440532013000" }, "lines": [ { "name": "Consulting", "quantity": 10, "unitPriceMinor": 10000, "unitCode": "HUR", "taxCategory": "S", "taxRate": 19 } ] }, "format": "xrechnung-ubl" } } } }, "responses": { "200": { "description": "The XML.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XmlResponse" } } } }, "400": { "description": "The body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "malformed_json", "message": "The request body is not valid JSON." } } } }, "413": { "description": "The body exceeds the size limit (default 8 MiB, CONFORMO_SERVER_MAX_BODY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "payload_too_large", "message": "The request body exceeds the 8388608-byte limit." } } } }, "422": { "description": "The body is valid JSON but cannot be processed: a bad invoice (every bad field listed in `issues`), a missing or conflicting field, or a document that is not a supported invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_invoice", "message": "The invoice cannot be written: 1 problem.", "issues": [ { "path": "lines[0].taxRate", "bt": "BT-152", "severity": "error", "message": "VAT rate is required for category S" } ] } } } } } } }, "/v1/invoices/pdf": { "post": { "operationId": "createInvoicePdf", "tags": [ "create" ], "summary": "Create a Factur-X / ZUGFeRD PDF", "description": "Creates a PDF/A-3b with the XML embedded. Returns the PDF bytes (application/pdf) by default; send `Accept: application/json` to get {pdfBase64, xml, xmlFilename, conformanceLevel} instead. Deterministic: the same invoice gives the same bytes. Conformo only produces, reads and checks documents. It does not transmit anything (no Peppol access point, no French PA/PDP, no KSeF, no SdI) and does not support FatturaPA or Facturae; it handles KSeF FA(3) only as domestic PLN invoices it writes and schema-checks (it cannot read them). A valid result means the rule sets listed in `ruleSets` passed, not that a tax authority accepts the invoice. The server stores nothing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "profile": { "type": "string", "enum": [ "en16931", "xrechnung", "extended" ], "description": "Factur-X / ZUGFeRD profile. Default en16931." }, "template": { "type": "string", "enum": [ "classic", "modern", "compact" ], "description": "Page layout. Default classic." }, "language": { "type": "string", "enum": [ "en", "de", "fr" ], "description": "Language of the printed labels: en, de or fr. Default en. The embedded XML is the same in every language." } }, "required": [ "invoice" ], "additionalProperties": false }, "example": { "invoice": { "number": "INV-2026-001", "issueDate": "2026-09-01", "dueDate": "2026-09-30", "currency": "EUR", "buyerReference": "04011000-1234512345-06", "paymentTerms": "Payable within 30 days.", "seller": { "name": "Example Software GmbH", "vatId": "DE123456789", "street": "Hauptstrasse 1", "city": "Berlin", "postcode": "10115", "country": "DE", "electronicAddress": "billing@example-software.example", "electronicAddressScheme": "EM", "contact": { "name": "Erika Mustermann", "phone": "+49 30 1234567", "email": "billing@example-software.example" } }, "buyer": { "name": "Beispiel AG", "street": "Marktplatz 2", "city": "Hamburg", "postcode": "20095", "country": "DE", "electronicAddress": "ap@beispiel.example", "electronicAddressScheme": "EM" }, "payment": { "meansCode": "58", "iban": "DE89370400440532013000" }, "lines": [ { "name": "Consulting", "quantity": 10, "unitPriceMinor": 10000, "unitCode": "HUR", "taxCategory": "S", "taxRate": 19 } ] }, "profile": "en16931", "template": "classic" } } } }, "responses": { "200": { "description": "The PDF (default) or a JSON envelope (Accept: application/json).", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PdfJsonResponse" } } } }, "400": { "description": "The body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "malformed_json", "message": "The request body is not valid JSON." } } } }, "413": { "description": "The body exceeds the size limit (default 8 MiB, CONFORMO_SERVER_MAX_BODY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "payload_too_large", "message": "The request body exceeds the 8388608-byte limit." } } } }, "422": { "description": "The body is valid JSON but cannot be processed: a bad invoice (every bad field listed in `issues`), a missing or conflicting field, or a document that is not a supported invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_invoice", "message": "The invoice cannot be written: 1 problem.", "issues": [ { "path": "lines[0].taxRate", "bt": "BT-152", "severity": "error", "message": "VAT rate is required for category S" } ] } } } } } } }, "/v1/validate": { "post": { "operationId": "validateInvoice", "tags": [ "validate" ], "summary": "Validate an e-invoice", "description": "Checks XML (or the XML embedded in a Factur-X/ZUGFeRD PDF) against XSD and the official Schematron rule sets. The HTTP status is 200 whether the document is valid or not: validity is `valid` in the body. A non-2xx status means the request or document could not be processed at all. Conformo only produces, reads and checks documents. It does not transmit anything (no Peppol access point, no French PA/PDP, no KSeF, no SdI) and does not support FatturaPA or Facturae; it handles KSeF FA(3) only as domestic PLN invoices it writes and schema-checks (it cannot read them). A valid result means the rule sets listed in `ruleSets` passed, not that a tax authority accepts the invoice. The server stores nothing.", "requestBody": { "required": true, "description": "Exactly one of `xml` or `pdfBase64`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "xml": { "type": "string", "description": "The invoice as XML text (CII, UBL Invoice/CreditNote, XRechnung, Peppol BIS)." }, "pdfBase64": { "type": "string", "description": "A Factur-X / ZUGFeRD PDF/A-3 as base64 (standard alphabet); the embedded XML is used." }, "options": { "type": "object", "properties": { "country": { "type": "string", "enum": [ "FR", "DE" ], "description": "Add a country layer on top of EN 16931." }, "profile": { "type": "string", "enum": [ "en16931", "xrechnung", "peppol" ], "description": "Force the rule set instead of reading it from BT-24." }, "xsd": { "type": "boolean", "description": "Run XSD validation too. Default true." } }, "additionalProperties": false } }, "additionalProperties": false, "oneOf": [ { "required": [ "xml" ] }, { "required": [ "pdfBase64" ] } ] }, "example": { "xml": "…use the xml returned by /v1/invoices/xml…", "options": { "country": "DE" } } } } }, "responses": { "200": { "description": "The full validation result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResult" } } } }, "400": { "description": "The body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "malformed_json", "message": "The request body is not valid JSON." } } } }, "413": { "description": "The body exceeds the size limit (default 8 MiB, CONFORMO_SERVER_MAX_BODY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "payload_too_large", "message": "The request body exceeds the 8388608-byte limit." } } } }, "422": { "description": "The body is valid JSON but cannot be processed: a bad invoice (every bad field listed in `issues`), a missing or conflicting field, or a document that is not a supported invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "message": "Provide exactly one of `xml` or `pdfBase64`.", "issues": [ { "path": "", "bt": "", "severity": "error", "message": "Provide exactly one of `xml` or `pdfBase64`." } ] } } } } } } }, "/v1/convert": { "post": { "operationId": "convertInvoice", "tags": [ "convert" ], "summary": "Convert an e-invoice between syntaxes", "description": "Reads an existing e-invoice and writes it in another syntax. Fields the target cannot carry are not invented; validate the result. Conformo only produces, reads and checks documents. It does not transmit anything (no Peppol access point, no French PA/PDP, no KSeF, no SdI) and does not support FatturaPA or Facturae; it handles KSeF FA(3) only as domestic PLN invoices it writes and schema-checks (it cannot read them). A valid result means the rule sets listed in `ruleSets` passed, not that a tax authority accepts the invoice. The server stores nothing.", "requestBody": { "required": true, "description": "Exactly one of `source` or `sourcePdfBase64`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "description": "The source invoice as XML text. Provide this OR sourcePdfBase64." }, "sourcePdfBase64": { "type": "string", "description": "The source as a Factur-X / ZUGFeRD PDF, base64. Provide this OR source." }, "to": { "$ref": "#/components/schemas/FormatId" } }, "required": [ "to" ], "additionalProperties": false, "oneOf": [ { "required": [ "source" ] }, { "required": [ "sourcePdfBase64" ] } ] }, "example": { "source": "…use the xml returned by /v1/invoices/xml…", "to": "ubl" } } } }, "responses": { "200": { "description": "The converted XML.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResponse" } } } }, "400": { "description": "The body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "malformed_json", "message": "The request body is not valid JSON." } } } }, "413": { "description": "The body exceeds the size limit (default 8 MiB, CONFORMO_SERVER_MAX_BODY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "payload_too_large", "message": "The request body exceeds the 8388608-byte limit." } } } }, "422": { "description": "The body is valid JSON but cannot be processed: a bad invoice (every bad field listed in `issues`), a missing or conflicting field, or a document that is not a supported invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unprocessable_document", "message": "The document is not a supported invoice syntax." } } } } } } }, "/v1/parse": { "post": { "operationId": "parseInvoice", "tags": [ "convert" ], "summary": "Parse an e-invoice into JSON", "description": "Reads CII, UBL, XRechnung or Peppol XML, or a Factur-X/ZUGFeRD PDF, into the Invoice model (the shape /v1/invoices/xml accepts). It does not validate. `totalsCheck` says whether the totals stated in the document survive recomputation from its lines.", "requestBody": { "required": true, "description": "Exactly one of `xml` or `pdfBase64`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "xml": { "type": "string", "description": "The invoice as XML text (CII, UBL Invoice/CreditNote, XRechnung, Peppol BIS)." }, "pdfBase64": { "type": "string", "description": "A Factur-X / ZUGFeRD PDF/A-3 as base64 (standard alphabet); the embedded XML is used." } }, "additionalProperties": false, "oneOf": [ { "required": [ "xml" ] }, { "required": [ "pdfBase64" ] } ] }, "example": { "xml": "…use the xml returned by /v1/invoices/xml…" } } } }, "responses": { "200": { "description": "The parsed invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResponse" } } } }, "400": { "description": "The body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "malformed_json", "message": "The request body is not valid JSON." } } } }, "413": { "description": "The body exceeds the size limit (default 8 MiB, CONFORMO_SERVER_MAX_BODY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "payload_too_large", "message": "The request body exceeds the 8388608-byte limit." } } } }, "422": { "description": "The body is valid JSON but cannot be processed: a bad invoice (every bad field listed in `issues`), a missing or conflicting field, or a document that is not a supported invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unprocessable_document", "message": "The document is not a supported invoice syntax." } } } } } } }, "/v1/requirements": { "get": { "operationId": "listRequirements", "tags": [ "reference" ], "summary": "List countries with e-invoicing data", "responses": { "200": { "description": "Supported countries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequirementsList" }, "example": { "countries": [ { "country": "DE", "name": "Germany" } ] } } } } } } }, "/v1/requirements/{country}": { "get": { "operationId": "getRequirements", "tags": [ "reference" ], "summary": "E-invoicing requirements for a country", "description": "What the sourced dataset says (mandates, dates, thresholds, required formats, official sources) plus `conformoSupport`: per required format, whether this toolkit can generate, read and validate it. Items with status \"unverified\" are not confirmed from an official source. Information, not legal advice.", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 code, case-insensitive.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "DE" } ], "responses": { "200": { "description": "The country record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Requirements" } } } }, "404": { "description": "No data for that country.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found", "message": "No data for country \"XX\"." } } } } } } }, "/v1/rules/{id}": { "get": { "operationId": "explainRule", "tags": [ "reference" ], "summary": "Explain a validation rule", "description": "The publisher's wording from the compiled rule sets plus a plain-language summary, why it exists and how to fix it, where one exists.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Rule id as returned by /v1/validate.", "schema": { "type": "string", "minLength": 1 }, "example": "BR-CO-15" } ], "responses": { "200": { "description": "The explanation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleExplanation" } } } }, "404": { "description": "The id is unknown to the compiled rule sets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found", "message": "No rule \"X\" is known to the compiled rule sets." } } } } } } }, "/healthz": { "get": { "operationId": "health", "tags": [ "meta" ], "summary": "Liveness", "responses": { "200": { "description": "The server is up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "example": { "status": "ok", "version": "0.2.4" } } } } } } }, "/openapi.json": { "get": { "operationId": "openapi", "tags": [ "meta" ], "summary": "This document", "responses": { "200": { "description": "The OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/docs": { "get": { "operationId": "docs", "tags": [ "meta" ], "summary": "Human-readable entry page", "responses": { "200": { "description": "A static HTML page linking to openapi.json.", "content": { "text/html": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "ConvertResponse": { "type": "object", "properties": { "xml": { "type": "string" }, "from": { "type": "string", "enum": [ "cii", "ubl-invoice", "ubl-credit-note" ] }, "to": { "$ref": "#/components/schemas/FormatId" }, "warnings": { "type": "array", "items": { "type": "string" } }, "totalsCheck": { "type": "object", "properties": { "matches": { "type": "boolean" }, "differences": { "type": "array", "items": { "type": "string" } } }, "required": [ "matches", "differences" ], "additionalProperties": false, "description": "Whether the totals stated in the document equal the totals recomputed from its lines." } }, "required": [ "xml", "from", "to", "warnings", "totalsCheck" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_invoice", "invalid_request", "malformed_json", "payload_too_large", "unprocessable_document", "not_found", "method_not_allowed", "internal_error" ] }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" }, "description": "Present for invalid_invoice and invalid_request." } }, "required": [ "error", "message" ], "additionalProperties": false, "description": "Every non-2xx response has this shape. Stack traces are never included." }, "FormatId": { "type": "string", "enum": [ "cii", "cii-extended", "ubl", "xrechnung-cii", "xrechnung-ubl", "peppol-ubl", "ksef-fa3" ], "description": "Output XML syntax." }, "Health": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "version": { "type": "string" } }, "required": [ "status", "version" ], "additionalProperties": false }, "Invoice": { "type": "object", "properties": { "number": { "type": "string", "description": "BT-1 invoice number." }, "typeCode": { "type": "string", "description": "BT-3 invoice type code, UNTDID 1001. Default 380 (commercial invoice). 381 credit note, 384 corrected invoice, 389 self-billed invoice, 326 partial invoice, 875/876/877 partial/construction invoices. Credit-note codes are written as a UBL CreditNote." }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "BT-2 invoice issue date. ISO date yyyy-mm-dd." }, "taxPointDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "BT-7 value added tax point date. Use this OR taxPointDateCode. ISO date yyyy-mm-dd." }, "taxPointDateCode": { "type": "string", "description": "BT-8 value added tax point date code, UNTDID 2005: 3 invoice date, 35 delivery date, 432 paid-to-date." }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "BT-9 payment due date. ISO date yyyy-mm-dd." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "BT-5 invoice currency code, ISO 4217, e.g. EUR." }, "taxCurrency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "BT-6 VAT accounting currency, when it differs from BT-5. Then taxTotalInTaxCurrencyMinor (BT-111) is mandatory (BR-53)." }, "taxTotalInTaxCurrencyMinor": { "type": "integer", "description": "BT-111 invoice total VAT amount in the accounting currency. Needs an exchange rate, so the caller supplies it. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "buyerReference": { "type": "string", "description": "BT-10 buyer reference. For German public-sector invoices this is the Leitweg-ID (BR-DE-15)." }, "projectReference": { "type": "string", "description": "BT-11 project reference." }, "contractReference": { "type": "string", "description": "BT-12 contract reference." }, "orderReference": { "type": "string", "description": "BT-13 purchase order reference. Peppol needs BT-10 or BT-13 (PEPPOL-EN16931-R003)." }, "salesOrderReference": { "type": "string", "description": "BT-14 sales order reference." }, "receivingAdviceReference": { "type": "string", "description": "BT-15 receiving advice reference." }, "despatchAdviceReference": { "type": "string", "description": "BT-16 despatch advice reference." }, "tenderOrLotReference": { "type": "string", "description": "BT-17 tender or lot reference." }, "invoicedObjectId": { "type": "string", "description": "BT-18 invoiced object identifier (e.g. a meter or asset number)." }, "invoicedObjectIdScheme": { "type": "string", "description": "BT-18-1 scheme identifier of the invoiced object identifier." }, "buyerAccountingReference": { "type": "string", "description": "BT-19 buyer accounting reference." }, "businessProcess": { "type": "string", "description": "BT-23 business process type. A plain string on purpose: France wants a closed list (B1, S1, M1, ...), Peppol and XRechnung want a profile URN. Each format decides what it accepts." }, "notes": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "BT-22 invoice note text." }, "subjectCode": { "type": "string", "description": "BT-21 invoice note subject code. France requires AAB, PMD and PMT on every invoice." } }, "required": [ "text" ], "additionalProperties": false, "description": "BG-1 invoice note." }, "description": "BG-1 invoice notes." }, "paymentTerms": { "type": "string", "description": "BT-20 payment terms text. XRechnung uses a structured #SKONTO# syntax here for early-payment discounts." }, "seller": { "type": "object", "properties": { "name": { "type": "string", "description": "BT-27 seller name / BT-44 buyer name (legal name)." }, "tradingName": { "type": "string", "description": "BT-28 / BT-45 trading name." }, "id": { "type": "string", "description": "BT-29 / BT-46 party identifier (first one)." }, "idScheme": { "type": "string", "description": "Scheme identifier of BT-29 / BT-46." }, "additionalIds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Further identifier value." }, "scheme": { "type": "string", "description": "Scheme of this identifier." } }, "required": [ "id" ], "additionalProperties": false }, "description": "BT-29 / BT-46 can repeat; these are the further identifiers (the first one is `id`)." }, "legalId": { "type": "string", "description": "BT-30 seller / BT-47 buyer legal registration identifier (e.g. SIREN, company number)." }, "legalIdScheme": { "type": "string", "description": "ISO 6523 ICD code for BT-30 / BT-47, e.g. 0002 SIREN, 0009 SIRET, 0208 BE enterprise number. Required when legalId is set." }, "vatId": { "type": "string", "description": "BT-31 seller / BT-48 buyer VAT identifier including the country prefix, e.g. DE123456789." }, "taxRegistrationId": { "type": "string", "description": "BT-32, seller only. Tax number where no VAT id exists, e.g. a German Steuernummer. BR-S-02 accepts BT-31, BT-32 or BT-63." }, "additionalLegalInfo": { "type": "string", "description": "BT-33, seller only. Legal form and capital, e.g. \"SARL au capital de 10 000 EUR\"." }, "street": { "type": "string", "description": "BT-35 seller / BT-50 buyer address line 1." }, "street2": { "type": "string", "description": "BT-36 / BT-51 address line 2." }, "street3": { "type": "string", "description": "BT-162 / BT-163 address line 3." }, "city": { "type": "string", "description": "BT-37 / BT-52 city." }, "postcode": { "type": "string", "description": "BT-38 / BT-53 post code." }, "subdivision": { "type": "string", "description": "BT-39 / BT-54 country subdivision (state, region)." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "BT-40 seller / BT-55 buyer country. ISO 3166-1 alpha-2 country code, e.g. DE, FR." }, "electronicAddress": { "type": "string", "description": "BT-34 seller / BT-49 buyer electronic address. Optional in EN 16931, MANDATORY in France, Peppol and XRechnung." }, "electronicAddressScheme": { "type": "string", "description": "EAS code of the electronic address, e.g. EM (e-mail), 0088 GLN, 0204 Leitweg-ID, 0208 BE enterprise number, 9925 BE VAT. Defaults to EM only for a value containing \"@\"." }, "contact": { "type": "object", "properties": { "name": { "type": "string", "description": "BT-41 / BT-56 contact point name." }, "phone": { "type": "string", "description": "BT-42 / BT-57 contact telephone number." }, "email": { "type": "string", "description": "BT-43 / BT-58 contact e-mail address." } }, "additionalProperties": false, "description": "BG-6 seller contact / BG-9 buyer contact. XRechnung makes the seller contact mandatory (BR-DE-2)." } }, "required": [ "name", "country" ], "additionalProperties": false, "description": "BG-4 seller (with BG-5 postal address and BG-6 contact)." }, "buyer": { "type": "object", "properties": { "name": { "type": "string", "description": "BT-27 seller name / BT-44 buyer name (legal name)." }, "tradingName": { "type": "string", "description": "BT-28 / BT-45 trading name." }, "id": { "type": "string", "description": "BT-29 / BT-46 party identifier (first one)." }, "idScheme": { "type": "string", "description": "Scheme identifier of BT-29 / BT-46." }, "additionalIds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Further identifier value." }, "scheme": { "type": "string", "description": "Scheme of this identifier." } }, "required": [ "id" ], "additionalProperties": false }, "description": "BT-29 / BT-46 can repeat; these are the further identifiers (the first one is `id`)." }, "legalId": { "type": "string", "description": "BT-30 seller / BT-47 buyer legal registration identifier (e.g. SIREN, company number)." }, "legalIdScheme": { "type": "string", "description": "ISO 6523 ICD code for BT-30 / BT-47, e.g. 0002 SIREN, 0009 SIRET, 0208 BE enterprise number. Required when legalId is set." }, "vatId": { "type": "string", "description": "BT-31 seller / BT-48 buyer VAT identifier including the country prefix, e.g. DE123456789." }, "taxRegistrationId": { "type": "string", "description": "BT-32, seller only. Tax number where no VAT id exists, e.g. a German Steuernummer. BR-S-02 accepts BT-31, BT-32 or BT-63." }, "additionalLegalInfo": { "type": "string", "description": "BT-33, seller only. Legal form and capital, e.g. \"SARL au capital de 10 000 EUR\"." }, "street": { "type": "string", "description": "BT-35 seller / BT-50 buyer address line 1." }, "street2": { "type": "string", "description": "BT-36 / BT-51 address line 2." }, "street3": { "type": "string", "description": "BT-162 / BT-163 address line 3." }, "city": { "type": "string", "description": "BT-37 / BT-52 city." }, "postcode": { "type": "string", "description": "BT-38 / BT-53 post code." }, "subdivision": { "type": "string", "description": "BT-39 / BT-54 country subdivision (state, region)." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "BT-40 seller / BT-55 buyer country. ISO 3166-1 alpha-2 country code, e.g. DE, FR." }, "electronicAddress": { "type": "string", "description": "BT-34 seller / BT-49 buyer electronic address. Optional in EN 16931, MANDATORY in France, Peppol and XRechnung." }, "electronicAddressScheme": { "type": "string", "description": "EAS code of the electronic address, e.g. EM (e-mail), 0088 GLN, 0204 Leitweg-ID, 0208 BE enterprise number, 9925 BE VAT. Defaults to EM only for a value containing \"@\"." }, "contact": { "type": "object", "properties": { "name": { "type": "string", "description": "BT-41 / BT-56 contact point name." }, "phone": { "type": "string", "description": "BT-42 / BT-57 contact telephone number." }, "email": { "type": "string", "description": "BT-43 / BT-58 contact e-mail address." } }, "additionalProperties": false, "description": "BG-6 seller contact / BG-9 buyer contact. XRechnung makes the seller contact mandatory (BR-DE-2)." } }, "required": [ "name", "country" ], "additionalProperties": false, "description": "BG-7 buyer (with BG-8 postal address and BG-9 contact)." }, "taxRepresentative": { "type": "object", "properties": { "name": { "type": "string", "description": "BT-62 seller tax representative name." }, "vatId": { "type": "string", "description": "BT-63 seller tax representative VAT identifier." }, "street": { "type": "string", "description": "BT-64 address line 1." }, "street2": { "type": "string", "description": "BT-65 address line 2." }, "street3": { "type": "string", "description": "BT-164 address line 3." }, "city": { "type": "string", "description": "BT-66 city." }, "postcode": { "type": "string", "description": "BT-67 post code." }, "subdivision": { "type": "string", "description": "BT-68 country subdivision." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "BT-69 tax representative country. ISO 3166-1 alpha-2 country code, e.g. DE, FR." } }, "required": [ "name", "vatId", "country" ], "additionalProperties": false, "description": "BG-11 seller tax representative party, with its address BG-12." }, "delivery": { "type": "object", "properties": { "partyName": { "type": "string", "description": "BT-70 deliver-to party name." }, "locationId": { "type": "string", "description": "BT-71 deliver-to location identifier." }, "locationIdScheme": { "type": "string", "description": "BT-71-1 scheme of the location identifier." }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "BT-72 actual delivery date. ISO date yyyy-mm-dd." }, "street": { "type": "string", "description": "BT-75 deliver-to address line 1." }, "street2": { "type": "string", "description": "BT-76 address line 2." }, "street3": { "type": "string", "description": "BT-165 address line 3." }, "city": { "type": "string", "description": "BT-77 deliver-to city." }, "postcode": { "type": "string", "description": "BT-78 deliver-to post code." }, "subdivision": { "type": "string", "description": "BT-79 deliver-to country subdivision." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "BT-80 deliver-to country. ISO 3166-1 alpha-2 country code, e.g. DE, FR." } }, "additionalProperties": false, "description": "BG-13 delivery information with BG-15 deliver-to address." }, "payee": { "type": "object", "properties": { "name": { "type": "string", "description": "BT-59 payee name." }, "id": { "type": "string", "description": "BT-60 payee identifier." }, "idScheme": { "type": "string", "description": "BT-60-1 scheme of the payee identifier." }, "legalId": { "type": "string", "description": "BT-61 payee legal registration identifier." }, "legalIdScheme": { "type": "string", "description": "BT-61-1 scheme of the payee legal registration identifier." } }, "required": [ "name" ], "additionalProperties": false, "description": "BG-10 payee, when the party paid is not the seller." }, "periodStart": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "BT-73 invoicing period start date (BG-14). ISO date yyyy-mm-dd." }, "periodEnd": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "BT-74 invoicing period end date (BG-14). ISO date yyyy-mm-dd." }, "precedingInvoices": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string", "description": "BT-25 preceding invoice reference." }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "BT-26 preceding invoice issue date. ISO date yyyy-mm-dd." } }, "required": [ "number" ], "additionalProperties": false, "description": "BG-3 preceding invoice reference. Needed in practice for credit notes (type 381)." }, "description": "BG-3 preceding invoice references." }, "payment": { "type": "object", "properties": { "meansCode": { "type": "string", "description": "BT-81 payment means type code, UNTDID 4461. 58 = SEPA credit transfer, 59 = SEPA direct debit, 30 = credit transfer, 48 = bank card." }, "meansText": { "type": "string", "description": "BT-82 payment means text." }, "reference": { "type": "string", "description": "BT-83 remittance information: what the payer must quote on the transfer." }, "iban": { "type": "string", "description": "BT-84 payment account identifier (IBAN) of the first account." }, "accountName": { "type": "string", "description": "BT-85 payment account name." }, "bic": { "type": "string", "description": "BT-86 payment service provider identifier (BIC)." }, "additionalAccounts": { "type": "array", "items": { "type": "object", "properties": { "iban": { "type": "string", "description": "BT-84 payment account identifier (IBAN)." }, "accountName": { "type": "string", "description": "BT-85 payment account name." }, "bic": { "type": "string", "description": "BT-86 payment service provider identifier (BIC)." } }, "required": [ "iban" ], "additionalProperties": false, "description": "BG-17 credit transfer account." }, "description": "BG-17 can repeat: further accounts the buyer may pay into (the first one is iban/accountName/bic)." }, "card": { "type": "object", "properties": { "pan": { "type": "string", "description": "BT-87 payment card primary account number: the LAST 4-6 DIGITS ONLY." }, "holderName": { "type": "string", "description": "BT-88 payment card holder name." } }, "required": [ "pan" ], "additionalProperties": false, "description": "BG-18 payment card information." }, "directDebit": { "type": "object", "properties": { "mandateId": { "type": "string", "description": "BT-89 mandate reference identifier." }, "creditorId": { "type": "string", "description": "BT-90 bank assigned creditor identifier (the seller's SEPA Glaeubiger-ID)." }, "debitedAccountIban": { "type": "string", "description": "BT-91 debited account identifier (IBAN)." } }, "additionalProperties": false, "description": "BG-19 direct debit (SEPA Lastschrift, meansCode 59)." } }, "required": [ "meansCode" ], "additionalProperties": false, "description": "BG-16 payment instructions." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "BT-122 supporting document reference." }, "description": { "type": "string", "description": "BT-123 supporting document description." }, "url": { "type": "string", "description": "BT-124 external document location (URL). Use this OR `content`." }, "content": { "type": "string", "description": "BT-125 attached document, base64-encoded. Together with mimeCode and filename it is embedded." }, "mimeCode": { "type": "string", "description": "BT-125-1 attached document MIME code, e.g. application/pdf." }, "filename": { "type": "string", "description": "BT-125-2 attached document filename." } }, "required": [ "id" ], "additionalProperties": false, "description": "BG-24 additional supporting document: an attachment or a link." }, "description": "BG-24 additional supporting documents, any number." }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "BT-126 invoice line identifier. Defaults to the 1-based position when absent." }, "note": { "type": "string", "description": "BT-127 invoice line note." }, "objectId": { "type": "string", "description": "BT-128 invoice line object identifier." }, "objectIdScheme": { "type": "string", "description": "BT-128-1 scheme identifier of the line object identifier." }, "orderLineReference": { "type": "string", "description": "BT-132 referenced purchase order line reference." }, "buyerAccountingReference": { "type": "string", "description": "BT-133 invoice line buyer accounting reference." }, "periodStart": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "BT-134 invoice line period start date (BG-26). ISO date yyyy-mm-dd." }, "periodEnd": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "BT-135 invoice line period end date (BG-26). ISO date yyyy-mm-dd." }, "name": { "type": "string", "description": "BT-153 item name." }, "description": { "type": "string", "description": "BT-154 item description." }, "sellerAssignedId": { "type": "string", "description": "BT-155 item seller identifier." }, "buyerAssignedId": { "type": "string", "description": "BT-156 item buyer identifier." }, "standardItemId": { "type": "string", "description": "BT-157 item standard identifier, e.g. a GTIN. Needs standardItemIdScheme." }, "standardItemIdScheme": { "type": "string", "description": "BT-157-1 scheme of the standard item identifier, e.g. 0160 for GTIN." }, "classifications": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "BT-158 item classification identifier." }, "scheme": { "type": "string", "description": "BT-158-1 list identifier, e.g. STI, CPV, UNSPSC." }, "schemeVersion": { "type": "string", "description": "BT-158-2 list version identifier." } }, "required": [ "code", "scheme" ], "additionalProperties": false, "description": "BT-158 item classification identifier with its list and version." }, "description": "BT-158 item classification identifiers." }, "originCountry": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "BT-159 item country of origin. ISO 3166-1 alpha-2 country code, e.g. DE, FR." }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "BT-160 item attribute name." }, "value": { "type": "string", "description": "BT-161 item attribute value." } }, "required": [ "name", "value" ], "additionalProperties": false, "description": "BG-32 item attribute." }, "description": "BG-32 item attributes." }, "quantity": { "type": "number", "description": "BT-129 invoiced quantity, a decimal number (negative on a credit-note line is allowed). Read exactly, never as a binary float." }, "netAmountMinor": { "type": "integer", "description": "BT-131 line net amount as stated in a document. Normally leave it UNSET: the net amount is computed from quantity, price and line allowances/charges. Set only to reproduce a document that states another value. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "unitPriceMinor": { "type": "number", "description": "BT-146 item NET price per unit in minor units. May be fractional (1.25 = 0.0125 in a two-decimal currency) because EN 16931 allows unit prices with more decimals than the currency." }, "priceDiscountMinor": { "type": "number", "description": "BT-147 item price discount in minor units (informational: BT-146 is already net)." }, "grossPriceMinor": { "type": "number", "description": "BT-148 item gross price in minor units. When set together with BT-147, BT-146 must equal BT-148 - BT-147." }, "priceBaseQuantity": { "type": "number", "description": "BT-149 item price base quantity (default 1)." }, "priceBaseUnitCode": { "type": "string", "description": "BT-150 item price base quantity unit of measure code." }, "unitCode": { "type": "string", "description": "BT-130 invoiced quantity unit of measure, UN/ECE Recommendation 20. C62 = piece, HUR = hour, DAY = day, KGM = kilogram." }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "integer", "description": "BT-136 line allowance / BT-141 line charge amount, always positive. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "baseAmountMinor": { "type": "integer", "description": "BT-137 / BT-142 base amount the percentage applies to. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "percent": { "type": "number", "description": "BT-138 / BT-143 percentage (e.g. 10 for 10 %)." }, "reason": { "type": "string", "description": "BT-139 / BT-144 reason text." }, "reasonCode": { "type": "string", "description": "BT-140 / BT-145 reason code, UNTDID 5189 (allowance) or 7161 (charge)." } }, "required": [ "amountMinor" ], "additionalProperties": false, "description": "BG-27 line level allowance (a discount) or BG-28 line level charge. Same shape, different array." }, "description": "BG-27 invoice line allowances." }, "charges": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "integer", "description": "BT-136 line allowance / BT-141 line charge amount, always positive. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "baseAmountMinor": { "type": "integer", "description": "BT-137 / BT-142 base amount the percentage applies to. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "percent": { "type": "number", "description": "BT-138 / BT-143 percentage (e.g. 10 for 10 %)." }, "reason": { "type": "string", "description": "BT-139 / BT-144 reason text." }, "reasonCode": { "type": "string", "description": "BT-140 / BT-145 reason code, UNTDID 5189 (allowance) or 7161 (charge)." } }, "required": [ "amountMinor" ], "additionalProperties": false, "description": "BG-27 line level allowance (a discount) or BG-28 line level charge. Same shape, different array." }, "description": "BG-28 invoice line charges." }, "taxCategory": { "type": "string", "enum": [ "S", "Z", "E", "AE", "K", "G", "O", "L", "M" ], "description": "BT-151 invoiced item VAT category code (S, Z, E, AE, K, G, O, L, M)." }, "taxRate": { "type": "number", "description": "BT-152 invoiced item VAT rate in percent (19 for 19 %). Ignored for category O: BR-O-05 forbids a rate on a line \"not subject to VAT\". Use 0 for Z, E, AE, K, G, O." }, "exemptionReason": { "type": "string", "description": "BT-120 VAT exemption reason text (for categories E, AE, K, G, O)." }, "exemptionCode": { "type": "string", "description": "BT-121 VAT exemption reason code, VATEX code list, e.g. VATEX-EU-AE." } }, "required": [ "name", "quantity", "unitPriceMinor", "taxCategory", "taxRate" ], "additionalProperties": false, "description": "BG-25 invoice line (with BG-29 price details, BG-30 line VAT information, BG-31 item information)." }, "description": "BG-25 invoice lines. At least one is required (BR-16)." }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "integer", "description": "BT-92 document allowance / BT-99 document charge amount, always positive. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "baseAmountMinor": { "type": "integer", "description": "BT-93 / BT-100 base amount the percentage applies to. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "percent": { "type": "number", "description": "BT-94 / BT-101 percentage (e.g. 10 for 10 %)." }, "reason": { "type": "string", "description": "BT-97 / BT-104 reason text." }, "reasonCode": { "type": "string", "description": "BT-98 / BT-105 reason code, UNTDID 5189 (allowance) or 7161 (charge)." }, "taxCategory": { "type": "string", "enum": [ "S", "Z", "E", "AE", "K", "G", "O", "L", "M" ], "description": "BT-95 / BT-102 VAT category code of the allowance or charge." }, "taxRate": { "type": "number", "description": "BT-96 / BT-103 VAT rate in percent of the allowance or charge." }, "exemptionCode": { "type": "string", "description": "Only needed to pick a breakdown when several share this category and rate but differ in exemption (VATEX code, BT-121)." }, "exemptionReason": { "type": "string", "description": "Only needed to pick a breakdown when several share this category and rate but differ in exemption (BT-120)." } }, "required": [ "amountMinor", "taxCategory", "taxRate" ], "additionalProperties": false, "description": "BG-20 document level allowance (a discount) or BG-21 document level charge. Same shape, different array." }, "description": "BG-20 document level allowances." }, "charges": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "integer", "description": "BT-92 document allowance / BT-99 document charge amount, always positive. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "baseAmountMinor": { "type": "integer", "description": "BT-93 / BT-100 base amount the percentage applies to. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "percent": { "type": "number", "description": "BT-94 / BT-101 percentage (e.g. 10 for 10 %)." }, "reason": { "type": "string", "description": "BT-97 / BT-104 reason text." }, "reasonCode": { "type": "string", "description": "BT-98 / BT-105 reason code, UNTDID 5189 (allowance) or 7161 (charge)." }, "taxCategory": { "type": "string", "enum": [ "S", "Z", "E", "AE", "K", "G", "O", "L", "M" ], "description": "BT-95 / BT-102 VAT category code of the allowance or charge." }, "taxRate": { "type": "number", "description": "BT-96 / BT-103 VAT rate in percent of the allowance or charge." }, "exemptionCode": { "type": "string", "description": "Only needed to pick a breakdown when several share this category and rate but differ in exemption (VATEX code, BT-121)." }, "exemptionReason": { "type": "string", "description": "Only needed to pick a breakdown when several share this category and rate but differ in exemption (BT-120)." } }, "required": [ "amountMinor", "taxCategory", "taxRate" ], "additionalProperties": false, "description": "BG-20 document level allowance (a discount) or BG-21 document level charge. Same shape, different array." }, "description": "BG-21 document level charges." }, "statedVatAmounts": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "S", "Z", "E", "AE", "K", "G", "O", "L", "M" ], "description": "BT-118 VAT category of the breakdown this stated amount belongs to." }, "rate": { "type": "number", "description": "BT-119 VAT rate in percent of that breakdown." }, "amountMinor": { "type": "integer", "description": "BT-117 VAT category tax amount as stated in a source document. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "exemptionCode": { "type": "string", "description": "BT-121 exemption code, to pick the breakdown when several share category and rate." }, "exemptionReason": { "type": "string", "description": "BT-120 exemption reason, to pick the breakdown when several share category and rate." } }, "required": [ "category", "rate", "amountMinor" ], "additionalProperties": false }, "description": "BT-117 per VAT breakdown (BG-23) as stated in a document. Normally leave unset: VAT amounts are computed. Set only to reproduce a source document's stated value; it is honoured only within one minor unit of the computed amount." }, "prepaidMinor": { "type": "integer", "description": "BT-113 paid amount (prepayment already received). Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." }, "roundingMinor": { "type": "integer", "description": "BT-114 rounding amount, added to the amount due (BR-CO-16). May be negative. Integer in minor units (cents): EUR 12.34 = 1234. Never a decimal." } }, "required": [ "number", "issueDate", "currency", "seller", "buyer", "lines" ], "additionalProperties": false, "description": "An EN 16931 invoice (the Conformo model). Totals (BT-106..BT-115) and the VAT breakdown (BG-23) are NOT input: they are computed from the lines, allowances and charges. All money is integer minor units.", "title": "Conformo Invoice (EN 16931)" }, "Issue": { "type": "object", "properties": { "path": { "type": "string", "description": "Path of the offending field in the request body, e.g. lines[0].taxRate." }, "bt": { "type": "string", "description": "EN 16931 business term (BT-/BG-) the field maps to; empty when none applies." }, "severity": { "type": "string", "description": "\"error\" or \"warning\"." }, "message": { "type": "string" } }, "required": [ "path", "bt", "severity", "message" ], "additionalProperties": false, "description": "One problem with the input." }, "ParseResponse": { "type": "object", "properties": { "invoice": { "type": "object", "properties": {}, "additionalProperties": true, "description": "The Invoice, in the shape of the Invoice schema. Money in integer minor units." }, "format": { "type": "string", "enum": [ "cii", "ubl-invoice", "ubl-credit-note" ] }, "origin": { "type": "string", "enum": [ "xml", "pdf" ] }, "embeddedFilename": { "type": "string" }, "totalsCheck": { "type": "object", "properties": { "matches": { "type": "boolean" }, "differences": { "type": "array", "items": { "type": "string" } } }, "required": [ "matches", "differences" ], "additionalProperties": false, "description": "Whether the totals stated in the document equal the totals recomputed from its lines." }, "visibleTotals": { "type": "object", "properties": {}, "additionalProperties": true, "description": "PDF only: printed totals compared with the embedded XML." } }, "required": [ "invoice", "format", "origin", "totalsCheck" ], "additionalProperties": false }, "PdfJsonResponse": { "type": "object", "properties": { "pdfBase64": { "type": "string" }, "xml": { "type": "string", "description": "The XML embedded in the PDF." }, "xmlFilename": { "type": "string", "description": "Name of the embedded attachment." }, "conformanceLevel": { "type": "string", "description": "fx:ConformanceLevel written to the XMP packet." } }, "required": [ "pdfBase64", "xml", "xmlFilename", "conformanceLevel" ], "additionalProperties": false }, "Requirements": { "type": "object", "properties": { "country": { "type": "string" }, "name": { "type": "string" }, "conformoSupport": { "type": "object", "additionalProperties": { "type": "object", "properties": { "generate": { "type": "boolean" }, "read": { "type": "boolean" }, "validate": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "generate", "read", "validate", "note" ], "additionalProperties": false }, "description": "Per required format: can this toolkit generate, read, validate it? FatturaPA and Facturae: no. KSeF FA(3): generate and XSD-validate domestic PLN invoices, no reading." } }, "required": [ "country", "name", "conformoSupport" ], "additionalProperties": true, "description": "The sourced country record (mandates, dates, thresholds, sources) plus conformoSupport. This is information, not legal advice." }, "RequirementsList": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "name": { "type": "string" } }, "required": [ "country", "name" ], "additionalProperties": false } } }, "required": [ "countries" ], "additionalProperties": false }, "RuleExplanation": { "type": "object", "properties": { "ruleId": { "type": "string" }, "found": { "type": "boolean" }, "official": { "type": "array", "items": { "type": "object", "properties": { "ruleSet": { "type": "string" }, "text": { "type": "string" } }, "required": [ "ruleSet", "text" ], "additionalProperties": false } }, "plainLanguage": { "type": "object", "properties": { "summary": { "type": "string" }, "why": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "summary", "why", "fix" ], "additionalProperties": false } }, "required": [ "ruleId", "found", "official" ], "additionalProperties": false }, "ValidationResult": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "True only when no error-level rule failed and XSD (if it ran) passed. The HTTP status is 200 either way." }, "origin": { "type": "string", "enum": [ "xml", "pdf" ] }, "embeddedFilename": { "type": "string" }, "firedCount": { "type": "number", "description": "Schematron rules that fired across every rule set that ran." }, "results": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "fatal", "warning", "info" ] }, "fields": { "type": "array", "items": { "type": "string" } }, "xpath": { "type": "string" }, "message": { "type": "string" }, "originalSeverity": { "type": "string", "enum": [ "error", "fatal", "warning", "info" ] }, "ruleSet": { "type": "string" }, "plainLanguage": { "type": "object", "properties": { "summary": { "type": "string" }, "why": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "summary", "why", "fix" ], "additionalProperties": false }, "element": { "type": "string", "description": "The offending element without namespaces, e.g. LineTotalAmount." }, "path": { "type": "string", "description": "A short readable path, e.g. \"line 1 > NetPriceProductTradePrice > ChargeAmount\". xpath is the exact location." }, "line": { "type": "integer", "description": "1-based invoice line number when the node is inside an invoice line." } }, "required": [ "ruleId", "severity", "fields", "xpath", "message", "ruleSet" ], "additionalProperties": false }, "description": "Every rule finding, errors and advisories." }, "detected": { "type": "object", "properties": { "syntax": { "type": "string", "enum": [ "cii", "ubl-invoice", "ubl-creditnote" ] }, "profile": { "type": "string" }, "customizationId": { "type": "string" }, "businessProcess": { "type": "string" }, "variant": { "type": "string", "enum": [ "standard", "extension", "cvd" ] } }, "required": [ "syntax", "profile" ], "additionalProperties": false }, "ruleSets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string" }, "fired": { "type": "number" }, "failed": { "type": "number" }, "advisory": { "type": "number" } }, "required": [ "id", "label", "source", "fired", "failed", "advisory" ], "additionalProperties": false }, "description": "Exactly the rule sets that ran. Never claim more than this list." }, "xsd": { "type": "object", "properties": { "ran": { "type": "boolean" }, "schema": { "type": "string" }, "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "skippedReason": { "type": "string" } }, "required": [ "ran", "errors" ], "additionalProperties": false }, "notices": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "severity", "code", "message" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "official": { "type": "object", "properties": { "checked": { "type": "number" }, "failed": { "type": "number" }, "advisory": { "type": "number" } }, "required": [ "checked", "failed", "advisory" ], "additionalProperties": false, "description": "What the official rule sets report." }, "conformoErrors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "description": "Conformo's own checks that failed (error-level notices), counted apart from the official rules." }, "xsdFailed": { "type": "boolean" }, "text": { "type": "string", "description": "The one-line verdict, e.g. \"INVALID - 89 official rules checked, 0 failed, 0 advisory; 1 Conformo check failed (XRECHNUNG-ID-UNKNOWN).\"" } }, "required": [ "official", "conformoErrors", "xsdFailed", "text" ], "additionalProperties": false, "description": "The verdict in numbers, with Conformo checks counted apart from the official rule sets." } }, "required": [ "valid", "origin", "firedCount", "results", "detected", "ruleSets", "xsd", "notices" ], "additionalProperties": false }, "XmlResponse": { "type": "object", "properties": { "xml": { "type": "string" }, "format": { "$ref": "#/components/schemas/FormatId" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal findings, e.g. a missing XRechnung precondition." } }, "required": [ "xml", "format", "warnings" ], "additionalProperties": false } } } }