{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "eu-einvoice-canonical conversion API", "version": "1.0.0", "summary": "Turn a received e-invoice into one canonical JSON model built on EN 16931.", "description": "Send the file you received (UBL or CII XML, a Factur-X PDF, a signed `.p7m`, a ZIP, a Peppol SBDH or SOAP envelope,\nor one of the national formats) and get the canonical JSON back. The service is stateless: nothing is stored, nothing is\nwritten to disk, and every request is independent.\n\nThe response bodies are the published JSON Schemas (`schemas/*.v1.schema.json`, draft 2020-12), referenced here and never\ncopied, so the API and the TypeScript types cannot drift apart. The reference server (`einvoice serve`) implements this\ndocument with the same `convert()`, `inspect()` and `detectXml()` functions as the library and the command line.\n\n## Errors\n\nEvery error is `application/problem+json` (RFC 9457). The `type` URI is one of the six categories the command line reports\nas exit codes 2 to 7; `exitCode` carries that number. Requests that exceed a size or count limit answer 413 with the\n`unsafe-or-malformed` type. A problem about a file that was parsed (partial, validation failed, unsupported) also carries\nthe full `ConvertResult` in `result`, so nothing the converter found is lost.\n\n| Type | Status | Exit code | Meaning |\n| --- | --- | --- | --- |\n| `unsafe-or-malformed` | 400, 413 | 2 | Not XML, a DOCTYPE, an unreadable archive, or a limit exceeded (413). |\n| `unsupported` | 422 | 3 | Well-formed, but not an invoice format this converter reads. |\n| `validation-failed` | 422 | 4 | Converted, but the requested validation reported failures. |\n| `partial` | 422 | 5 | Some documents in the file converted and some did not. |\n| `validator-unavailable` | 503 | 6 | Validation or the trusted-list snapshot was requested and cannot run. |\n| `internal` | 500 | 7 | A bug. Please report it with the file hash. |\n\n## Versioning\n\nThe path prefix `/v1` and the `v1` JSON Schemas are versioned together. Additive changes (new optional fields, new\nformats, new endpoints) stay in v1; a breaking change to a response shape publishes `/v2` next to it.\n", "license": { "name": "0BSD", "url": "https://github.com/alexcatdad/eu-einvoice-canonical/blob/main/LICENSE" }, "contact": { "name": "eu-einvoice-canonical", "url": "https://github.com/alexcatdad/eu-einvoice-canonical" } }, "servers": [ { "url": "http://localhost:8080", "description": "The reference server started with `einvoice serve`." } ], "tags": [ { "name": "Conversion" }, { "name": "Registry" }, { "name": "Operations" } ], "paths": { "/v1/convert": { "post": { "tags": [ "Conversion" ], "operationId": "convert", "summary": "Convert an e-invoice file to canonical JSON", "description": "Unwraps the file, detects the format of every XML document in it, and maps each invoice to the canonical model.\nSend the file as `multipart/form-data` (field `file`) or as the raw request body with its content type.\nSignatures are verified (cryptographic validity) and reported on `source.signatures`.\n", "parameters": [ { "$ref": "#/components/parameters/Validate" }, { "$ref": "#/components/parameters/Relations" }, { "$ref": "#/components/parameters/Provenance" }, { "$ref": "#/components/parameters/EuTrust" }, { "$ref": "#/components/parameters/Filename" } ], "requestBody": { "$ref": "#/components/requestBodies/InvoiceFile" }, "responses": { "200": { "description": "Every document in the file converted.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/inspect": { "post": { "tags": [ "Conversion" ], "operationId": "inspect", "summary": "Unwrap a file and identify every XML document in it", "description": "Like `convert`, without parsing: the envelope steps, SHA-256 and the detected format of each document.", "parameters": [ { "$ref": "#/components/parameters/Filename" } ], "requestBody": { "$ref": "#/components/requestBodies/InvoiceFile" }, "responses": { "200": { "description": "The file was unwrapped; `documents` may be empty, with the reasons in `skipped`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/TooLarge" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/detect": { "post": { "tags": [ "Conversion" ], "operationId": "detect", "summary": "Identify the format of one XML document", "description": "Detection only, for raw XML. Use `inspect` for anything that may be wrapped (PDF, ZIP, p7m, SBDH, SOAP).", "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } }, "text/xml": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "The detection. `kind` is `invoice` (with `format` and `details`), `other-document` (a known non-invoice) or `unknown`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectResult_Detection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/TooLarge" }, "500": { "$ref": "#/components/responses/Internal" } } } }, "/v1/formats": { "get": { "tags": [ "Registry" ], "operationId": "listFormats", "summary": "The format registry", "description": "Every format the converter detects, in detection order, with its parser family, countries and status.", "responses": { "200": { "description": "The registry. The same content is published as `schemas/formats.json`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormatList" } } } } } } }, "/v1/schemas/{name}": { "get": { "tags": [ "Registry" ], "operationId": "getSchema", "summary": "A JSON Schema of the response models", "description": "The draft 2020-12 JSON Schema for `canonical-invoice`, `convert-result` or `inspect-result` (the v1 files).", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "canonical-invoice", "convert-result", "inspect-result" ] } } ], "responses": { "200": { "description": "The schema document.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/schema+json": { "schema": { "$ref": "#/components/schemas/JsonSchemaDocument" } } } }, "404": { "description": "No such schema.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemGeneric" } } } } } } }, "/health": { "get": { "tags": [ "Operations" ], "operationId": "health", "summary": "Liveness check", "responses": { "200": { "description": "The server is up.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } } }, "components": { "parameters": { "Validate": { "name": "validate", "in": "query", "description": "Run the XSD, EN 16931 Schematron and CIUS layers (UBL and CII) and fill `source.validation`. Slower: it loads the validators. When every invoice fails a layer the answer is a `validation-failed` problem that still carries the result.", "schema": { "type": "boolean", "default": false } }, "Relations": { "name": "relations", "in": "query", "description": "Fill `lineRoles` and `relations` (headings, descriptions, markups and discounts between lines).", "schema": { "type": "boolean", "default": false } }, "Provenance": { "name": "provenance", "in": "query", "description": "Fill `source.provenance` (canonical path to source XPath). Roughly doubles the size of `source`.", "schema": { "type": "boolean", "default": false } }, "EuTrust": { "name": "euTrust", "in": "query", "description": "Check signers against the server's snapshot of the EU trusted lists (`source.signatures[].euTrust`). A server started without a snapshot answers 503 `validator-unavailable`.", "schema": { "type": "boolean", "default": false } }, "Filename": { "name": "filename", "in": "query", "description": "The name the file had when received. Used as a hint (extension) for the unwrapping; optional.", "schema": { "type": "string", "maxLength": 255 } } }, "headers": { "CacheControl": { "description": "Always `no-store` for per-request results; `public` for the registry endpoints.", "required": true, "schema": { "type": "string" } } }, "requestBodies": { "InvoiceFile": { "required": true, "description": "The file as received. As `multipart/form-data` the file is the part named `file`; otherwise the raw body is the file, whatever its content type. Larger than the server's `maxFileBytes` (50 MiB by default) answers 413.", "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } }, "application/xml": { "schema": { "type": "string", "format": "binary" } }, "text/xml": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } }, "application/pkcs7-mime": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } }, "responses": { "BadRequest": { "description": "The request or the file is unsafe or malformed (exit code 2), or a query parameter is invalid.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemUnsafe" }, { "$ref": "#/components/schemas/ProblemGeneric" } ] } } } }, "TooLarge": { "description": "The body, or something unpacked from it, exceeds a limit (`maxFileBytes`, `maxEntries`, `maxUnpackedBytes`...).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemUnsafe" } } } }, "Unprocessable": { "description": "The file was read but did not convert cleanly. `type` says why; `result` has everything that was found.", "content": { "application/problem+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemUnsupported" }, { "$ref": "#/components/schemas/ProblemValidationFailed" }, { "$ref": "#/components/schemas/ProblemPartial" } ] } } } }, "Internal": { "description": "An internal error (exit code 7).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemInternal" } } } }, "Unavailable": { "description": "Validation or the trusted-list snapshot was requested and cannot run (exit code 6).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemValidatorUnavailable" } } } } }, "schemas": { "Problem": { "type": "object", "description": "An RFC 9457 problem document.", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "instance": { "type": "string" }, "exitCode": { "type": "integer", "description": "The exit code the command line reports for the same condition." }, "result": { "description": "The conversion result, when a file was parsed before the problem arose.", "$ref": "#/components/schemas/ConvertResult" } } }, "ProblemGeneric": { "description": "A problem with no specific category (`about:blank`): unknown route or schema, wrong method, bad query value.", "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "properties": { "type": { "const": "about:blank" } } } ] }, "ProblemUnsafe": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "exitCode" ], "properties": { "type": { "const": "https://alexcatdad.github.io/eu-einvoice-canonical/problems/#unsafe-or-malformed" }, "status": { "enum": [ 400, 413 ] }, "exitCode": { "const": 2 } } } ] }, "ProblemUnsupported": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "exitCode", "result" ], "properties": { "type": { "const": "https://alexcatdad.github.io/eu-einvoice-canonical/problems/#unsupported" }, "status": { "const": 422 }, "exitCode": { "const": 3 } } } ] }, "ProblemValidationFailed": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "exitCode", "result" ], "properties": { "type": { "const": "https://alexcatdad.github.io/eu-einvoice-canonical/problems/#validation-failed" }, "status": { "const": 422 }, "exitCode": { "const": 4 } } } ] }, "ProblemPartial": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "exitCode", "result" ], "properties": { "type": { "const": "https://alexcatdad.github.io/eu-einvoice-canonical/problems/#partial" }, "status": { "const": 422 }, "exitCode": { "const": 5 } } } ] }, "ProblemValidatorUnavailable": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "exitCode" ], "properties": { "type": { "const": "https://alexcatdad.github.io/eu-einvoice-canonical/problems/#validator-unavailable" }, "status": { "const": 503 }, "exitCode": { "const": 6 } } } ] }, "ProblemInternal": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "exitCode" ], "properties": { "type": { "const": "https://alexcatdad.github.io/eu-einvoice-canonical/problems/#internal" }, "status": { "const": 500 }, "exitCode": { "const": 7 } } } ] }, "FormatInfo": { "type": "object", "required": [ "id", "name", "family", "countries", "status", "phase", "notes" ], "properties": { "id": { "$ref": "#/components/schemas/CanonicalInvoice_FormatId" }, "name": { "type": "string" }, "family": { "type": "string", "description": "The parser family that maps the format to the canonical model." }, "countries": { "type": "array", "description": "ISO 3166 country codes, or `EU` for formats used everywhere.", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "current", "legacy", "unverified" ] }, "phase": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "Suggested build order: 1 EN 16931 syntaxes, 2 national formats in active use, 3 legacy." }, "notes": { "type": "string" } } }, "FormatList": { "type": "object", "required": [ "formats" ], "properties": { "formats": { "type": "array", "items": { "$ref": "#/components/schemas/FormatInfo" } } } }, "JsonSchemaDocument": { "type": "object", "required": [ "$schema", "$id" ], "properties": { "$schema": { "const": "https://json-schema.org/draft/2020-12/schema" }, "$id": { "type": "string", "format": "uri" } } }, "Health": { "type": "object", "required": [ "status", "version", "schemaVersion" ], "properties": { "status": { "const": "ok" }, "version": { "type": "string", "description": "The package version (semver)." }, "schemaVersion": { "type": "string", "description": "The major version of the JSON Schemas and of this API path prefix, e.g. `v1`." } } }, "InspectResult": { "title": "InspectResult", "type": "object", "properties": { "fileSha256": { "type": "string" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/InspectResult_InspectedDocument" } }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/InspectResult_Skipped" }, "description": "Everything in the file that did not become a document, with the reason (DOCTYPE, size limits, detached signatures...)." } }, "required": [ "fileSha256", "documents", "skipped" ] }, "InspectResult_Detection": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "invoice" }, "format": { "$ref": "#/components/schemas/InspectResult_FormatDef" }, "details": { "$ref": "#/components/schemas/InspectResult_MatchDetails" }, "probe": { "$ref": "#/components/schemas/InspectResult_XmlProbe" } }, "required": [ "kind", "format", "details", "probe" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "other-document" }, "label": { "type": "string" }, "probe": { "$ref": "#/components/schemas/InspectResult_XmlProbe" } }, "required": [ "kind", "label", "probe" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "unknown" }, "reason": { "type": "string" }, "probe": { "anyOf": [ { "$ref": "#/components/schemas/InspectResult_XmlProbe" }, { "type": "null" } ] } }, "required": [ "kind", "reason", "probe" ] } ] }, "InspectResult_EnvelopeStep": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "zip", "pdf-attachment", "cms-p7m", "base64", "sbdh", "soap", "xml" ] }, "name": { "type": "string", "description": "Entry name, attachment name or other locator." } }, "required": [ "kind" ], "description": "One unwrapping step between the received file and the parsed XML." }, "InspectResult_FormatDef": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "family": { "$ref": "#/components/schemas/InspectResult_ParserFamily" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO country codes, or 'EU' for formats used everywhere." }, "status": { "$ref": "#/components/schemas/InspectResult_FormatStatus" }, "phase": { "type": "number", "enum": [ 1, 2, 3 ], "description": "Suggested build order: 1 = EN 16931 syntaxes, 2 = national formats in active use, 3 = legacy." }, "notes": { "type": "string" } }, "required": [ "id", "name", "family", "countries", "status", "phase", "notes" ] }, "InspectResult_FormatStatus": { "type": "string", "enum": [ "current", "legacy", "unverified" ], "description": "- current: in active use for invoices you will receive.\n- legacy: superseded but still sent by some senders; parse best-effort.\n- unverified: detection rule not confirmed against a real file; check before relying on it." }, "InspectResult_InspectedDocument": { "type": "object", "properties": { "payload": { "type": "object", "properties": { "encoding": { "type": "string" }, "envelope": { "type": "array", "items": { "$ref": "#/components/schemas/InspectResult_EnvelopeStep" } }, "filename": { "type": "string", "description": "Name of the innermost file (zip entry, PDF attachment, or the received file)." }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/InspectResult_SignatureInfo" } }, "fromPdf": { "type": "boolean" }, "sha256": { "type": "string", "description": "SHA-256 (hex) of the XML payload, UTF-8 encoded." }, "byteLength": { "type": "number", "description": "Size of the XML payload in bytes, UTF-8 encoded." }, "siblingEntries": { "type": "array", "items": { "type": "string" }, "description": "Names of the other files in the ZIP this payload came from (ISDOCX attachments); only set for ZIP members." } }, "required": [ "encoding", "envelope", "signatures", "fromPdf", "sha256", "byteLength" ] }, "detection": { "$ref": "#/components/schemas/InspectResult_Detection" } }, "required": [ "payload", "detection" ] }, "InspectResult_MatchDetails": { "type": "object", "properties": { "version": { "type": "string" }, "profile": { "type": "string" } } }, "InspectResult_ParserFamily": { "type": "string", "enum": [ "ubl", "cii", "zugferd1", "svefaktura", "fatturapa", "ksef", "facturae", "isdoc", "ebinterface", "finvoice", "teappsxml", "e-arve", "eslog", "mydata", "cfdi" ] }, "InspectResult_SignatureInfo": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CAdES", "XAdES", "XMLDSig", "PAdES", "detached" ] }, "verified": { "type": "boolean", "description": "Cryptographic validity only: the signature value matches the signed content and the signer certificate's key. true = valid, false = invalid (see `reason`), undefined = could not be checked. This says nothing about who the signer is; see `trust`." }, "signer": { "type": "string", "description": "Common name of the signer certificate." }, "certificate": { "type": "object", "properties": { "subject": { "type": "string" }, "issuer": { "type": "string" }, "serial": { "type": "string" }, "notBefore": { "type": "string" }, "notAfter": { "type": "string" } }, "required": [ "subject", "issuer", "serial", "notBefore", "notAfter" ], "description": "Signer certificate details, as carried in the signature." }, "signedAt": { "type": "string", "description": "Signing time (ISO 8601) from signed attributes / XAdES SigningTime, when the signature protects it." }, "reason": { "type": "string", "description": "Why `verified` is false, or why it could not be determined." }, "trust": { "type": "string", "enum": [ "not-checked", "trusted", "untrusted" ], "description": "'not-checked' unless trust anchors were configured: a valid signature is not a trusted signer." }, "trustReason": { "type": "string" }, "euTrust": { "type": "object", "properties": { "qualified": { "type": "boolean", "description": "The signer chains to a CA/QC service whose status was granted at the signing time." }, "status": { "type": "string", "enum": [ "qualified", "not-qualified", "not-listed" ] }, "evaluatedAt": { "type": "string", "description": "The instant the service status was evaluated at: the signing time, or now when the signature carries none." }, "signingTimeKnown": { "type": "boolean" }, "service": { "type": "object", "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "territory": { "type": "string" }, "statusAtSigning": { "type": "string" }, "currentStatus": { "type": "string" }, "statusFrom": { "type": "string" } }, "required": [ "provider", "name", "territory", "statusAtSigning", "currentStatus", "statusFrom" ] }, "snapshot": { "type": "object", "properties": { "fetchedAt": { "type": "string" }, "nextUpdate": { "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "fetchedAt", "stale" ], "description": "`stale`: the snapshot is past its earliest next-update date, so the lists may have changed since." }, "reason": { "type": "string" } }, "required": [ "qualified", "status", "evaluatedAt", "signingTimeKnown", "snapshot" ], "description": "Present when an EU trusted-list snapshot was passed (`euTrust` option): the qualified-service check of the signer." } }, "required": [ "type" ] }, "InspectResult_Skipped": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "reason" ] }, "InspectResult_XmlProbe": { "type": "object", "properties": { "rootName": { "type": "string" }, "rootNs": { "type": "string" }, "rootAttrs": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Root attributes by local name (versione, Version, version...)." }, "nsDecls": { "type": "array", "items": { "type": "string" }, "description": "Every namespace URI declared on the root element." }, "values": { "type": "object", "properties": { "ublCustomizationId": { "type": "string" }, "ublProfileId": { "type": "string" }, "ublVersionId": { "type": "string" }, "ciiGuidelineId": { "type": "string" }, "ciiBusinessProcessId": { "type": "string" }, "zf1GuidelineId": { "type": "string" }, "ksefFormCode": { "type": "string" }, "eArveVersion": { "type": "string" }, "facturaeSchemaVersion": { "type": "string" }, "facturaeModality": { "type": "string" }, "fatturaTipoDocumento": { "type": "string" }, "isdocDocumentType": { "type": "string" }, "finvoiceTypeCode": { "type": "string" }, "myDataInvoiceType": { "type": "string" }, "myDataRequestedInvoiceType": { "type": "string" } }, "description": "Header values found, trimmed. First occurrence wins." }, "valueAttrs": { "type": "object", "properties": { "ublCustomizationId": { "type": "object", "additionalProperties": { "type": "string" } }, "ublProfileId": { "type": "object", "additionalProperties": { "type": "string" } }, "ublVersionId": { "type": "object", "additionalProperties": { "type": "string" } }, "ciiGuidelineId": { "type": "object", "additionalProperties": { "type": "string" } }, "ciiBusinessProcessId": { "type": "object", "additionalProperties": { "type": "string" } }, "zf1GuidelineId": { "type": "object", "additionalProperties": { "type": "string" } }, "ksefFormCode": { "type": "object", "additionalProperties": { "type": "string" } }, "eArveVersion": { "type": "object", "additionalProperties": { "type": "string" } }, "facturaeSchemaVersion": { "type": "object", "additionalProperties": { "type": "string" } }, "facturaeModality": { "type": "object", "additionalProperties": { "type": "string" } }, "fatturaTipoDocumento": { "type": "object", "additionalProperties": { "type": "string" } }, "isdocDocumentType": { "type": "object", "additionalProperties": { "type": "string" } }, "finvoiceTypeCode": { "type": "object", "additionalProperties": { "type": "string" } }, "myDataInvoiceType": { "type": "object", "additionalProperties": { "type": "string" } }, "myDataRequestedInvoiceType": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Attributes of the elements at the target paths (e.g. KSeF kodSystemowy)." }, "hasDoctype": { "type": "boolean", "description": "The document has a DOCTYPE declaration. Inbound e-invoices never need one; treat as hostile." }, "error": { "type": "string", "description": "Parse error, if the document is not well-formed up to the point read." } }, "required": [ "rootName", "rootNs", "rootAttrs", "nsDecls", "values", "valueAttrs", "hasDoctype" ] }, "CanonicalInvoice": { "title": "CanonicalInvoice", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "invoice" }, "typeCode": { "$ref": "#/components/schemas/CanonicalInvoice_InvoiceTypeCode" }, "id": { "type": "string" }, "issueDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "issueTime": { "$ref": "#/components/schemas/CanonicalInvoice_IsoTime" }, "nationalType": { "$ref": "#/components/schemas/CanonicalInvoice_NationalTypeCode" }, "selfBilled": { "type": "boolean" }, "currency": { "$ref": "#/components/schemas/CanonicalInvoice_CurrencyCode" }, "taxCurrency": { "$ref": "#/components/schemas/CanonicalInvoice_CurrencyCode" }, "exchangeRate": { "type": "object", "properties": { "rate": { "$ref": "#/components/schemas/CanonicalInvoice_Decimal" }, "date": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" } }, "required": [ "rate" ], "description": "Not EN as a single term: exchange rate the source used to state VAT in the tax currency." }, "taxPointDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "vatPointDateCode": { "type": "string" }, "dueDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "buyerReference": { "type": "string" }, "projectRef": { "type": "string" }, "contractRef": { "type": "string" }, "purchaseOrderRef": { "type": "string" }, "salesOrderRef": { "type": "string" }, "receivingAdviceRef": { "type": "string" }, "despatchAdviceRef": { "type": "string" }, "tenderRef": { "type": "string" }, "invoicedObjectId": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "accountingRef": { "type": "string" }, "paymentTerms": { "type": "string" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "subjectCode": { "type": "string" }, "text": { "type": "string" } }, "required": [ "text" ] } }, "businessProcess": { "type": "string" }, "specificationId": { "type": "string" }, "precedingInvoices": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_PrecedingInvoiceRef" } }, "correction": { "$ref": "#/components/schemas/CanonicalInvoice_Correction" }, "invoicePeriod": { "$ref": "#/components/schemas/CanonicalInvoice_Period" }, "seller": { "$ref": "#/components/schemas/CanonicalInvoice_Seller" }, "buyer": { "$ref": "#/components/schemas/CanonicalInvoice_Party" }, "payee": { "$ref": "#/components/schemas/CanonicalInvoice_Payee" }, "taxRepresentative": { "$ref": "#/components/schemas/CanonicalInvoice_TaxRepresentative" }, "additionalParties": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_AdditionalParty" } }, "delivery": { "$ref": "#/components/schemas/CanonicalInvoice_Delivery" }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_PaymentInstructions" } }, "paymentSchedule": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_PaymentInstallment" } }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_AllowanceCharge" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_AllowanceCharge" } }, "totals": { "$ref": "#/components/schemas/CanonicalInvoice_Totals" }, "vatBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_VatBreakdown" } }, "otherTaxes": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_OtherTax" } }, "withholdings": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Withholding" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Attachment" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Line" } }, "lineRoles": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CanonicalInvoice_LineRole" }, "description": "Line id -> role. Only with `convert(..., { relations: true })`. Never changes `lines` or `totals`." }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_LineRelation" } }, "clearance": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_ClearanceInfo" } }, "extensions": { "$ref": "#/components/schemas/CanonicalInvoice_CountryExtensions" }, "source": { "$ref": "#/components/schemas/CanonicalInvoice_SourceMeta" } }, "required": [ "additionalParties", "allowances", "attachments", "buyer", "charges", "clearance", "currency", "extensions", "id", "issueDate", "kind", "lines", "notes", "otherTaxes", "paymentSchedule", "payments", "precedingInvoices", "selfBilled", "seller", "source", "specificationId", "totals", "typeCode", "vatBreakdown", "withholdings" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "creditNote" }, "typeCode": { "$ref": "#/components/schemas/CanonicalInvoice_CreditNoteTypeCode" }, "id": { "type": "string" }, "issueDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "issueTime": { "$ref": "#/components/schemas/CanonicalInvoice_IsoTime" }, "nationalType": { "$ref": "#/components/schemas/CanonicalInvoice_NationalTypeCode" }, "selfBilled": { "type": "boolean" }, "currency": { "$ref": "#/components/schemas/CanonicalInvoice_CurrencyCode" }, "taxCurrency": { "$ref": "#/components/schemas/CanonicalInvoice_CurrencyCode" }, "exchangeRate": { "type": "object", "properties": { "rate": { "$ref": "#/components/schemas/CanonicalInvoice_Decimal" }, "date": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" } }, "required": [ "rate" ], "description": "Not EN as a single term: exchange rate the source used to state VAT in the tax currency." }, "taxPointDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "vatPointDateCode": { "type": "string" }, "dueDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "buyerReference": { "type": "string" }, "projectRef": { "type": "string" }, "contractRef": { "type": "string" }, "purchaseOrderRef": { "type": "string" }, "salesOrderRef": { "type": "string" }, "receivingAdviceRef": { "type": "string" }, "despatchAdviceRef": { "type": "string" }, "tenderRef": { "type": "string" }, "invoicedObjectId": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "accountingRef": { "type": "string" }, "paymentTerms": { "type": "string" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "subjectCode": { "type": "string" }, "text": { "type": "string" } }, "required": [ "text" ] } }, "businessProcess": { "type": "string" }, "specificationId": { "type": "string" }, "precedingInvoices": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_PrecedingInvoiceRef" } }, "correction": { "$ref": "#/components/schemas/CanonicalInvoice_Correction" }, "invoicePeriod": { "$ref": "#/components/schemas/CanonicalInvoice_Period" }, "seller": { "$ref": "#/components/schemas/CanonicalInvoice_Seller" }, "buyer": { "$ref": "#/components/schemas/CanonicalInvoice_Party" }, "payee": { "$ref": "#/components/schemas/CanonicalInvoice_Payee" }, "taxRepresentative": { "$ref": "#/components/schemas/CanonicalInvoice_TaxRepresentative" }, "additionalParties": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_AdditionalParty" } }, "delivery": { "$ref": "#/components/schemas/CanonicalInvoice_Delivery" }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_PaymentInstructions" } }, "paymentSchedule": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_PaymentInstallment" } }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_AllowanceCharge" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_AllowanceCharge" } }, "totals": { "$ref": "#/components/schemas/CanonicalInvoice_Totals" }, "vatBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_VatBreakdown" } }, "otherTaxes": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_OtherTax" } }, "withholdings": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Withholding" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Attachment" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Line" } }, "lineRoles": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CanonicalInvoice_LineRole" }, "description": "Line id -> role. Only with `convert(..., { relations: true })`. Never changes `lines` or `totals`." }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_LineRelation" } }, "clearance": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_ClearanceInfo" } }, "extensions": { "$ref": "#/components/schemas/CanonicalInvoice_CountryExtensions" }, "source": { "$ref": "#/components/schemas/CanonicalInvoice_SourceMeta" } }, "required": [ "additionalParties", "allowances", "attachments", "buyer", "charges", "clearance", "currency", "extensions", "id", "issueDate", "kind", "lines", "notes", "otherTaxes", "paymentSchedule", "payments", "precedingInvoices", "selfBilled", "seller", "source", "specificationId", "totals", "typeCode", "vatBreakdown", "withholdings" ] } ] }, "CanonicalInvoice_AdditionalParty": { "type": "object", "properties": { "role": { "type": "string" }, "sourceRole": { "type": "string", "description": "Role code as written in the source, e.g. 'PL:Rola:5', 'IT:SoggettoEmittente:TZ'." }, "party": { "$ref": "#/components/schemas/CanonicalInvoice_Party" } }, "required": [ "role", "party" ], "description": "Parties in roles EN 16931 does not model: KSeF Podmiot3 (factor, internal recipient, additional buyer, issuer on behalf of the seller, payer, VAT-group member...), FatturaPA TerzoIntermediarioOSoggettoEmittente, Facturae third party, e-arve FactorParty, eSLOG NAD roles. Payee and tax representative stay in their EN fields." }, "CanonicalInvoice_Address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "line3": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "countrySubdivision": { "type": "string" }, "countryCode": { "$ref": "#/components/schemas/CanonicalInvoice_CountryCode" } } }, "CanonicalInvoice_AeExtension": { "type": "object", "properties": { "transactionTypeCode": { "type": "string", "description": "The eight transaction-type flags as sent (ProfileExecutionID), e.g. '00001000'." }, "transactionTypes": { "type": "array", "items": { "type": "string" }, "description": "Names of the flags that are set: freeTradeZone, deemedSupply, profitMarginScheme, summaryInvoice, continuousSupply, agentBilling, ecommerce, exports." }, "uuid": { "type": "string" }, "sellerTin": { "type": "string" }, "buyerTin": { "type": "string" }, "sellerRegistrationType": { "type": "string", "description": "Legal registration identifier type and issuing authority (TL trade licence, EID Emirates ID, PAS passport, CD cabinet decision)." }, "sellerRegistrationAuthority": { "type": "string" }, "buyerRegistrationType": { "type": "string" }, "buyerRegistrationAuthority": { "type": "string" }, "taxExchangeRate": { "type": "object", "properties": { "sourceCurrency": { "type": "string" }, "targetCurrency": { "type": "string" }, "rate": { "$ref": "#/components/schemas/CanonicalInvoice_Decimal" } }, "required": [ "sourceCurrency", "targetCurrency", "rate" ] }, "billingFrequency": { "type": "string", "description": "Frequency of billing (InvoicePeriod description)." } }, "required": [ "transactionTypes" ], "description": "United Arab Emirates (PINT AE)." }, "CanonicalInvoice_AllowanceCharge": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "baseAmount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "percentage": { "$ref": "#/components/schemas/CanonicalInvoice_Percentage" }, "reason": { "type": "string" }, "reasonCode": { "$ref": "#/components/schemas/CanonicalInvoice_AllowanceChargeReasonCode" }, "vat": { "$ref": "#/components/schemas/CanonicalInvoice_VatInfo" } }, "required": [ "amount" ] }, "CanonicalInvoice_AllowanceChargeReasonCode": { "type": "string", "examples": [ "41", "42", "60", "62", "63", "64", "65", "66", "67", "68", "70", "71", "88", "95", "100", "102", "103", "104", "105", "AA", "AAA", "ABL", "ADR", "ADT", "FC", "FI", "LA", "ZZZ" ], "description": "UNCL 5189 (allowances) and UNCL 7161 (charges)." }, "CanonicalInvoice_Amount": { "$ref": "#/components/schemas/CanonicalInvoice_Decimal", "description": "Monetary amount. EN 16931 allows at most 2 decimals at document level; lines may carry more in some national formats." }, "CanonicalInvoice_AtExtension": { "type": "object", "properties": { "ebInterfaceVersion": { "type": "string" }, "documentType": { "type": "string" }, "orderReferenceRequiredByFederalGovernment": { "type": "string" } }, "description": "Austria, ebInterface." }, "CanonicalInvoice_Attachment": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "embedded" }, "id": { "type": "string" }, "description": { "type": "string" }, "mimeCode": { "type": "string" }, "filename": { "type": "string" }, "base64": { "type": "string" } }, "required": [ "kind", "id", "mimeCode", "filename", "base64" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "external" }, "id": { "type": "string" }, "description": { "type": "string" }, "uri": { "type": "string" } }, "required": [ "kind", "id", "uri" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reference" }, "id": { "type": "string" }, "description": { "type": "string" }, "typeCode": { "type": "string" }, "schemeId": { "type": "string" } }, "required": [ "kind", "id" ] } ] }, "CanonicalInvoice_AuNzExtension": { "type": "object", "properties": { "abn": { "type": "string" }, "nzbn": { "type": "string" }, "gstRegistrationNumber": { "type": "string" }, "buyerAbn": { "type": "string" }, "buyerNzbn": { "type": "string" }, "buyerGstRegistrationNumber": { "type": "string" }, "gstCategories": { "type": "array", "items": { "type": "string" } } }, "required": [ "gstCategories" ], "description": "Australia and New Zealand (PINT A-NZ, one specification for both; stored under `au` or `nz` by seller country)." }, "CanonicalInvoice_CheckStatus": { "type": "string", "enum": [ "passed", "failed", "not-run", "unavailable" ] }, "CanonicalInvoice_ClearanceAuthority": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "IT:SDI", "PL:KSEF", "RO:SPV", "HR:FISK", "GR:MYDATA", "FR:PPF", "PT:AT", "ES:VERIFACTU", "HU:NAV" ] } ] }, "CanonicalInvoice_ClearanceInfo": { "type": "object", "properties": { "authority": { "$ref": "#/components/schemas/CanonicalInvoice_ClearanceAuthority" }, "documentId": { "type": "string", "description": "Authority-issued ID: SdI IdentificativoSdI, KSeF number, ANAF index, MARK..." }, "secondaryId": { "type": "string", "description": "Second ID if the authority issues two (ANAF upload index vs download ID, myDATA UID vs MARK)." }, "receivedAt": { "type": "string" }, "status": { "type": "string" }, "qrPayload": { "type": "string", "description": "QR code payload or URL printed on the visual (PT, GR, PL, ES, SA: base64 TLV)." }, "counter": { "type": "string", "description": "Invoice counter in the issuer's chain (SA ICV)." }, "previousHash": { "type": "string", "description": "Hash of the previous invoice in the issuer's chain (SA PIH), as carried." }, "hash": { "type": "string", "description": "Hash of this invoice as carried in the document (SA invoice hash), not recomputed." }, "certificateNumber": { "type": "string", "description": "Number of the authority's certificate that stamped the document (CFDI NoCertificadoSAT)." }, "stamp": { "type": "string", "description": "The stamp as written: the authority's stamp over the document (CFDI SelloSAT, not verified) or the signature value on the invoice (SA, base64)." }, "intermediary": { "type": "string", "description": "Authorised intermediary that submitted the document to the authority (CFDI PAC, RfcProvCertif)." } }, "required": [ "authority" ] }, "CanonicalInvoice_Contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } } }, "CanonicalInvoice_Correction": { "type": "object", "properties": { "reason": { "type": "string" }, "reasonCode": { "type": "string" }, "method": { "type": "string" }, "period": { "$ref": "#/components/schemas/CanonicalInvoice_Period" } }, "description": "Why and how a corrective document corrects (KSeF KOR, Facturae rectificativa, ISDOC 2/3...)." }, "CanonicalInvoice_CountryCode": { "type": "string", "examples": [ "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE" ], "description": "ISO 3166-1 alpha-2. EU member states listed; Greece is 'GR' (EL is the VAT prefix only)." }, "CanonicalInvoice_CountryExtensions": { "type": "object", "properties": { "it": { "$ref": "#/components/schemas/CanonicalInvoice_ItExtension" }, "pl": { "$ref": "#/components/schemas/CanonicalInvoice_PlExtension" }, "es": { "$ref": "#/components/schemas/CanonicalInvoice_EsExtension" }, "hr": { "$ref": "#/components/schemas/CanonicalInvoice_HrExtension" }, "gr": { "$ref": "#/components/schemas/CanonicalInvoice_GrExtension" }, "pt": { "$ref": "#/components/schemas/CanonicalInvoice_PtExtension" }, "fr": { "$ref": "#/components/schemas/CanonicalInvoice_FrExtension" }, "de": { "$ref": "#/components/schemas/CanonicalInvoice_DeExtension" }, "cz": { "$ref": "#/components/schemas/CanonicalInvoice_CzExtension" }, "at": { "$ref": "#/components/schemas/CanonicalInvoice_AtExtension" }, "fi": { "$ref": "#/components/schemas/CanonicalInvoice_FiExtension" }, "ee": { "$ref": "#/components/schemas/CanonicalInvoice_EeExtension" }, "sg": { "$ref": "#/components/schemas/CanonicalInvoice_SgExtension" }, "au": { "$ref": "#/components/schemas/CanonicalInvoice_AuNzExtension" }, "nz": { "$ref": "#/components/schemas/CanonicalInvoice_AuNzExtension" }, "jp": { "$ref": "#/components/schemas/CanonicalInvoice_JpExtension" }, "my": { "$ref": "#/components/schemas/CanonicalInvoice_MyExtension" }, "ae": { "$ref": "#/components/schemas/CanonicalInvoice_AeExtension" }, "sa": { "$ref": "#/components/schemas/CanonicalInvoice_SaExtension" }, "mx": { "$ref": "#/components/schemas/CanonicalInvoice_MxExtension" } } }, "CanonicalInvoice_CreditNoteTypeCode": { "type": "string", "examples": [ "381", "396", "261", "262", "81", "83", "532" ], "description": "UNCL 1001 document type codes used for credit notes (BT-3)." }, "CanonicalInvoice_CreditTransfer": { "type": "object", "properties": { "accountId": { "type": "string" }, "accountName": { "type": "string" }, "serviceProviderId": { "type": "string" } }, "required": [ "accountId" ] }, "CanonicalInvoice_CurrencyCode": { "type": "string", "examples": [ "EUR", "SEK", "DKK", "PLN", "CZK", "HUF", "RON", "BGN", "NOK", "CHF", "GBP", "USD" ], "description": "ISO 4217 currency code." }, "CanonicalInvoice_CzExtension": { "type": "object", "properties": { "documentType": { "type": "string" }, "variableSymbol": { "type": "string" }, "constantSymbol": { "type": "string" }, "specificSymbol": { "type": "string" } }, "description": "Czechia, ISDOC." }, "CanonicalInvoice_Decimal": { "type": "string", "pattern": "^[+-]?\\d+(\\.\\d+)?$", "description": "Plain decimal string: optional sign, digits, optional fraction. No exponent, no grouping." }, "CanonicalInvoice_DeExtension": { "type": "object", "properties": { "xrechnungVersion": { "type": "string" }, "zugferdProfile": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "MINIMUM", "BASIC WL", "BASIC", "EN 16931", "EXTENDED", "XRECHNUNG" ] } ] } }, "description": "Germany: XRechnung / ZUGFeRD. Leitweg-ID itself is BT-10 (`buyerReference`)." }, "CanonicalInvoice_Delivery": { "type": "object", "properties": { "partyName": { "type": "string" }, "locationId": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "actualDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "address": { "$ref": "#/components/schemas/CanonicalInvoice_Address" } } }, "CanonicalInvoice_EeExtension": { "type": "object", "properties": { "invoiceType": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "DEB", "CRE" ] } ] }, "factoring": { "type": "boolean" } }, "description": "Estonia, e-arve." }, "CanonicalInvoice_EnvelopeStep": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "zip", "pdf-attachment", "cms-p7m", "base64", "sbdh", "soap", "xml" ] }, "name": { "type": "string", "description": "Entry name, attachment name or other locator." } }, "required": [ "kind" ], "description": "One unwrapping step between the received file and the parsed XML." }, "CanonicalInvoice_EsExtension": { "type": "object", "properties": { "facturaeVersion": { "type": "string" }, "invoiceClass": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "OO", "OR", "OC", "CO", "CR", "CC" ] } ] }, "invoiceDocumentType": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "FC", "FA", "AF" ] } ] }, "batchId": { "type": "string" }, "administrativeCentres": { "type": "array", "items": { "type": "object", "properties": { "roleCode": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "roleCode", "code" ] }, "description": "DIR3 administrative centres (public sector routing): role 01 oficina contable, 02 órgano gestor, 03 unidad tramitadora." } }, "description": "Spain, Facturae." }, "CanonicalInvoice_FiExtension": { "type": "object", "properties": { "invoiceTypeCode": { "type": "string" }, "epiReference": { "type": "string" } }, "description": "Finland, Finvoice / TEAPPSXML." }, "CanonicalInvoice_FormatId": { "type": "string", "enum": [ "xrechnung-ubl", "nlcius-ubl", "cius-ro", "cius-pt", "hr-cius", "fr-ctc-ubl", "oioubl-3", "pl-pef", "peppol-bis3", "peppol-bis3-selfbilling", "pint-sg", "pint-aunz", "pint-jp", "pint-my", "pint-ae", "pint-om", "pint-eu", "peppol-pint", "zatca-ubl", "ubl-be", "en16931-ubl", "peppol-bis2", "oioubl-2", "ubl-unknown", "xrechnung-cii", "nlcius-cii", "fr-ctc-cii", "facturx", "en16931-cii", "cii-unknown", "zugferd-1", "fatturapa", "fatturapa-semplificata", "ksef", "facturae", "isdoc", "ebinterface", "ebinterface-2", "finvoice", "teappsxml", "e-arve", "eslog-2", "eslog-1", "svefaktura-1", "gr-mydata", "mx-cfdi" ], "description": "Identifier of a detected e-invoice format." }, "CanonicalInvoice_FrExtension": { "type": "object", "properties": { "profile": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "EN16931", "EXTENDED-CTC-FR", "BASICWL", "EXTENDED" ] } ] }, "billingFramework": { "type": "string" }, "operationCategory": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "goods", "services", "mixed" ] } ] } }, "description": "France, 2026 reform (XP Z12-012)." }, "CanonicalInvoice_GrExtension": { "type": "object", "properties": { "invoiceType": { "type": "string" }, "classifications": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "category": { "type": "string" }, "amount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" } }, "required": [ "type", "category", "amount" ] } } }, "description": "Greece, myDATA." }, "CanonicalInvoice_HrExtension": { "type": "object", "properties": { "issueTime": { "$ref": "#/components/schemas/CanonicalInvoice_IsoTime" }, "copyIndicator": { "type": "boolean" }, "operatorName": { "type": "string" }, "operatorOib": { "type": "string" } }, "description": "Croatia, HR-CIUS with HR extensions." }, "CanonicalInvoice_Identifier": { "type": "object", "properties": { "value": { "type": "string" }, "schemeId": { "$ref": "#/components/schemas/CanonicalInvoice_SchemeId", "description": "ICD / EAS code, or a national label such as 'PL:NIP'." } }, "required": [ "value" ] }, "CanonicalInvoice_InvoiceTypeCode": { "type": "string", "examples": [ "380", "383", "384", "386", "389", "326", "388", "393", "875", "876", "877" ], "description": "UNCL 1001 document type codes used for invoices (BT-3)." }, "CanonicalInvoice_IsoDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, no time zone." }, "CanonicalInvoice_IsoTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?$", "description": "hh:mm:ss, optionally with a UTC offset." }, "CanonicalInvoice_Item": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "sellerId": { "type": "string" }, "buyerId": { "type": "string" }, "standardId": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "classifications": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "listId": { "type": "string" }, "listVersion": { "type": "string" } }, "required": [ "code", "listId" ] } }, "originCountry": { "$ref": "#/components/schemas/CanonicalInvoice_CountryCode" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } } }, "required": [ "name", "classifications", "attributes" ] }, "CanonicalInvoice_ItExtension": { "type": "object", "properties": { "transmissionFormat": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "FPA12", "FPR12", "FSM10" ] } ] }, "recipientCode": { "type": "string" }, "recipientPec": { "type": "string" }, "transmissionSequence": { "type": "string" }, "taxRegime": { "type": "string" }, "vatChargeability": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "I", "D", "S" ] } ] }, "stampDuty": { "type": "object", "properties": { "virtual": { "type": "boolean" }, "amount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" } }, "required": [ "virtual" ] }, "pensionFunds": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "rate": { "$ref": "#/components/schemas/CanonicalInvoice_Percentage" }, "amount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "taxableAmount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "vatRate": { "$ref": "#/components/schemas/CanonicalInvoice_Percentage" }, "subjectToWithholding": { "type": "boolean" }, "nature": { "type": "string" } }, "required": [ "type", "amount" ] } }, "cup": { "type": "string" }, "cig": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "art73": { "type": "boolean" } }, "description": "Italy, FatturaPA. Fields that have no EN or generic equivalent." }, "CanonicalInvoice_JpExtension": { "type": "object", "properties": { "qualifiedInvoiceIssuerNumber": { "type": "string", "description": "Seller's qualified invoice issuer registration number: 'T' + 13 digits." }, "buyerRegistrationNumber": { "type": "string" } }, "description": "Japan (PINT JP, Peppol e-invoice for the qualified invoice system)." }, "CanonicalInvoice_Line": { "type": "object", "properties": { "id": { "type": "string" }, "note": { "type": "string" }, "objectId": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "quantity": { "$ref": "#/components/schemas/CanonicalInvoice_Quantity" }, "unitCode": { "$ref": "#/components/schemas/CanonicalInvoice_UnitCode" }, "unitText": { "type": "string", "description": "Unit as written in the source when it was free text ('st', 'kpl', 'szt.', 'ks')." }, "netAmount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "orderLineRef": { "type": "string" }, "accountingRef": { "type": "string" }, "period": { "$ref": "#/components/schemas/CanonicalInvoice_Period" }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_AllowanceCharge" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_AllowanceCharge" } }, "price": { "$ref": "#/components/schemas/CanonicalInvoice_Price" }, "vat": { "$ref": "#/components/schemas/CanonicalInvoice_VatInfo" }, "item": { "$ref": "#/components/schemas/CanonicalInvoice_Item" }, "subjectToWithholding": { "type": "boolean", "description": "Not EN: line is subject to withholding (FatturaPA Ritenuta = SI)." }, "otherTaxes": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_OtherTax" }, "description": "Non-VAT taxes stated per line (Facturae lines can carry IVA + recargo de equivalencia)." }, "withholdings": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Withholding" }, "description": "Withholdings stated per line (Facturae TaxesWithheld on InvoiceLine)." }, "correctionState": { "type": "string", "enum": [ "delta", "before", "after" ], "description": "How a corrective document expresses this line. KSeF corrections either list differences, or list each line twice: the state before (StanPrzed = 1) and after. Undefined for ordinary invoices." }, "subLines": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Line" }, "description": "Sub-lines (XRechnung extension, Factur-X EXTENDED, France EXTENDED-CTC-FR, ISDOC). Totals come from the parent." }, "national": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "description": "Line-level national data (PL GTU codes and procedure, IT AltriDatiGestionali...)." } }, "required": [ "id", "netAmount", "allowances", "charges", "item" ] }, "CanonicalInvoice_LineRelation": { "type": "object", "properties": { "from": { "type": "string", "description": "Line id (BT-126) of the line that heads, adjusts or refers to the others." }, "to": { "type": "array", "items": { "type": "string" } }, "type": { "$ref": "#/components/schemas/CanonicalInvoice_LineRelationType" }, "rate": { "$ref": "#/components/schemas/CanonicalInvoice_Percentage", "description": "Percentage stated in the line text, for `markup` and `discount`." }, "method": { "type": "string", "enum": [ "rule", "arithmetic", "model" ], "description": "How it was found. Only `model` is a guess by a language model; `rule` and `arithmetic` are deterministic." }, "confidence": { "type": "string", "enum": [ "proven", "likely", "review" ], "description": "`proven`: the arithmetic matches exactly and uniquely. `likely`: stated in the text or structure of the invoice. `review`: only a hint (shared ids, model output); do not act on it without a human. Absent for structural rules that cannot be wrong, such as a heading over the lines that follow it." } }, "required": [ "from", "to", "type", "method" ] }, "CanonicalInvoice_LineRelationType": { "type": "string", "enum": [ "heading", "markup", "discount", "allowance-base", "note-reference", "same-item", "same-order-line" ] }, "CanonicalInvoice_LineRole": { "type": "string", "enum": [ "item", "heading", "description", "surcharge", "discount", "freight", "labour", "other" ], "description": "What a line is for. `item` is anything sold; `heading` and `description` carry text only (zero quantity, price and amount); the rest adjust or add to other lines." }, "CanonicalInvoice_MxExtension": { "type": "object", "properties": { "cfdiVersion": { "type": "string" }, "series": { "type": "string" }, "folio": { "type": "string" }, "placeOfIssue": { "type": "string", "description": "Postal code of the place of issue (LugarExpedicion). The issuer's own address is not in a CFDI." }, "exportation": { "type": "string" }, "confirmation": { "type": "string" }, "paymentMethod": { "type": "string", "description": "MetodoPago: 'PUE' paid in one payment, 'PPD' in instalments or deferred." }, "paymentForm": { "type": "string" }, "issuer": { "type": "object", "properties": { "taxRegime": { "type": "string" }, "sealCertificateNumber": { "type": "string" }, "seal": { "type": "string" } } }, "receiver": { "type": "object", "properties": { "taxRegime": { "type": "string" }, "fiscalPostalCode": { "type": "string" }, "cfdiUse": { "type": "string" }, "taxResidence": { "type": "string" } } }, "globalInformation": { "type": "object", "properties": { "periodicity": { "type": "string" }, "months": { "type": "string" }, "year": { "type": "string" } }, "description": "InformacionGlobal: invoice summarising sales to the general public." }, "subTotal": { "$ref": "#/components/schemas/CanonicalInvoice_Amount", "description": "Sum of the line discounts and the pre-discount subtotal as the CFDI states them (SubTotal, Descuento)." }, "discount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" } }, "description": "Mexico, CFDI 3.3 / 4.0. Fields with no EN or generic equivalent; codes are SAT catalogue keys." }, "CanonicalInvoice_MyExtension": { "type": "object", "properties": { "tin": { "type": "string" }, "buyerTin": { "type": "string" }, "sstRegistrationNumber": { "type": "string" }, "buyerSstRegistrationNumber": { "type": "string" }, "businessRegistrationNumber": { "type": "string" }, "msicCode": { "type": "string" }, "msicDescription": { "type": "string" }, "freeTradeAgreement": { "type": "string" }, "certifiedExporterNumber": { "type": "string" }, "customsForm2": { "type": "string" }, "customsImportForms": { "type": "array", "items": { "type": "string" } }, "originalDocumentUuid": { "type": "string", "description": "LHDN unique identifier of the document this one corrects." }, "taxCategories": { "type": "array", "items": { "type": "string" } } }, "required": [ "customsImportForms", "taxCategories" ], "description": "Malaysia (PINT MY, MyInvois). TIN travels in a PartyTaxScheme with scheme GST; SST registration in the VAT scheme." }, "CanonicalInvoice_NationalTypeCode": { "type": "object", "properties": { "scheme": { "type": "string" }, "code": { "type": "string" }, "label": { "type": "string" } }, "required": [ "scheme", "code" ], "description": "A document type in the source format's own code list, kept next to the mapped UNCL 1001 code." }, "CanonicalInvoice_OtherTax": { "type": "object", "properties": { "scheme": { "type": "string" }, "taxableAmount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "rate": { "$ref": "#/components/schemas/CanonicalInvoice_Percentage" }, "amount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "includedInTotal": { "type": "boolean", "description": "True if the amount is already included in `totals.taxInclusive`." }, "inTaxExclusive": { "type": "boolean", "description": "True if the amount is also already inside `totals.taxExclusive`, because the source charges it as a line or a charge (IT stamp duty as an N1 line). When false or absent, an `includedInTotal` amount sits on top of BT-109 + BT-110 (ES recargo de equivalencia)." } }, "required": [ "scheme", "amount", "includedInTotal" ], "description": "Taxes that are not VAT and not withholding, and that EN 16931 cannot express: ES recargo de equivalencia, IT stamp duty (bollo), excise or environmental fees stated as taxes, IGIC/IPSI when a source keeps them apart from VAT." }, "CanonicalInvoice_Party": { "type": "object", "properties": { "name": { "type": "string" }, "tradingName": { "type": "string" }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" } }, "legalRegistrationId": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "vatId": { "type": "string" }, "nationalTaxIds": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "description": "National tax ID that is not the VAT number and not the company register ID: IT codice fiscale, PL NIP (when no VAT prefix), ES NIF, HR OIB, GR AFM, CZ IČO. Several national formats identify parties only by this." }, "endpoint": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "address": { "$ref": "#/components/schemas/CanonicalInvoice_Address" }, "contact": { "$ref": "#/components/schemas/CanonicalInvoice_Contact" } }, "required": [ "identifiers", "nationalTaxIds" ] }, "CanonicalInvoice_Payee": { "type": "object", "properties": { "name": { "type": "string" }, "identifier": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "legalRegistrationId": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" } }, "required": [ "name" ] }, "CanonicalInvoice_PaymentInstallment": { "type": "object", "properties": { "dueDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "amount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "description": { "type": "string" }, "paymentIndex": { "type": "number", "description": "Index into `payments` when the installment names its own means/account." } }, "description": "One due date in a payment schedule. EN 16931 has a single due date (BT-9); FatturaPA (DettaglioPagamento), Facturae (Installment) and KSeF (TerminPlatnosci) can list several, with or without amounts and with or without their own account." }, "CanonicalInvoice_PaymentInstructions": { "type": "object", "properties": { "meansCode": { "$ref": "#/components/schemas/CanonicalInvoice_PaymentMeansCode" }, "meansText": { "type": "string" }, "nationalMeansCode": { "type": "string", "description": "Means code in the source code list (FatturaPA 'MP05', Facturae '04', KSeF '6'...)." }, "remittanceInformation": { "type": "string" }, "creditTransfers": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_CreditTransfer" } }, "card": { "type": "object", "properties": { "primaryAccountNumber": { "type": "string" }, "holderName": { "type": "string" }, "network": { "type": "string" } }, "required": [ "primaryAccountNumber" ] }, "directDebit": { "type": "object", "properties": { "mandateId": { "type": "string" }, "creditorId": { "type": "string" }, "debitedAccountId": { "type": "string" } } } }, "required": [ "meansCode", "creditTransfers" ] }, "CanonicalInvoice_PaymentMeansCode": { "type": "string", "examples": [ "1", "10", "20", "30", "31", "42", "48", "49", "54", "55", "57", "58", "59", "68", "97", "ZZZ" ], "description": "UNCL 4461 payment means (BT-81)." }, "CanonicalInvoice_Percentage": { "$ref": "#/components/schemas/CanonicalInvoice_Decimal" }, "CanonicalInvoice_Period": { "type": "object", "properties": { "start": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "end": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" } } }, "CanonicalInvoice_PlExtension": { "type": "object", "properties": { "invoiceKind": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "VAT", "KOR", "ZAL", "ROZ", "UPR", "KOR_ZAL", "KOR_ROZ" ] } ] }, "schemaVariant": { "type": "string" }, "splitPayment": { "type": "boolean" }, "cashAccounting": { "type": "boolean" }, "selfBilling": { "type": "boolean" }, "reverseCharge": { "type": "boolean" }, "exemptionBasis": { "type": "string" }, "marginScheme": { "type": "string" }, "buyerIsLocalGovernmentUnit": { "type": "boolean" }, "buyerIsVatGroupMember": { "type": "boolean" }, "paid": { "type": "boolean" }, "paidDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" } }, "description": "Poland, KSeF FA(2)/FA(3)." }, "CanonicalInvoice_PrecedingInvoiceRef": { "type": "object", "properties": { "id": { "type": "string" }, "issueDate": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" }, "clearanceId": { "type": "string", "description": "Clearance ID of the referenced invoice (KSeF number, SdI ID, CFDI UUID...)." }, "relationType": { "type": "string", "description": "How this document relates to the referenced one, in the source code list (CFDI TipoRelacion '01' = credit note of the related document, '04' = substitution...)." } }, "required": [ "id" ] }, "CanonicalInvoice_Price": { "type": "object", "properties": { "net": { "$ref": "#/components/schemas/CanonicalInvoice_UnitPrice" }, "discount": { "$ref": "#/components/schemas/CanonicalInvoice_UnitPrice" }, "gross": { "$ref": "#/components/schemas/CanonicalInvoice_UnitPrice" }, "baseQuantity": { "$ref": "#/components/schemas/CanonicalInvoice_Quantity" }, "baseQuantityUnit": { "$ref": "#/components/schemas/CanonicalInvoice_UnitCode" } }, "required": [ "net" ] }, "CanonicalInvoice_PtExtension": { "type": "object", "properties": { "atcud": { "type": "string" }, "documentHash": { "type": "string" }, "invoiceType": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "FT", "FS", "FR", "NC", "ND" ] } ] } }, "description": "Portugal." }, "CanonicalInvoice_Quantity": { "$ref": "#/components/schemas/CanonicalInvoice_Decimal" }, "CanonicalInvoice_SaAddress": { "type": "object", "properties": { "buildingNumber": { "type": "string" }, "plotIdentification": { "type": "string" }, "district": { "type": "string" } } }, "CanonicalInvoice_SaExtension": { "type": "object", "properties": { "invoiceSubtype": { "type": "string", "enum": [ "standard", "simplified" ] }, "transactionCode": { "type": "string", "description": "InvoiceTypeCode/@name as sent: NNPNESB." }, "thirdParty": { "type": "boolean" }, "nominal": { "type": "boolean" }, "exports": { "type": "boolean" }, "summary": { "type": "boolean" }, "selfBilled": { "type": "boolean" }, "uuid": { "type": "string" }, "counter": { "type": "string" }, "previousInvoiceHash": { "type": "string" }, "invoiceHash": { "type": "string", "description": "Digest of the signed invoice as carried in the XAdES signature (reference 'invoiceSignedData')." }, "stamp": { "type": "object", "properties": { "signatureValue": { "type": "string" }, "certificate": { "type": "string" }, "signedAt": { "type": "string" } } }, "qr": { "$ref": "#/components/schemas/CanonicalInvoice_SaQr" }, "hashCheck": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "match", "mismatch", "not-checked" ] }, "computed": { "type": "string" }, "carried": { "type": "string" }, "qr": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "status", "computed" ], "description": "Our own recomputation of the invoice hash against what the document carries. Never fails the conversion." }, "sellerAddress": { "$ref": "#/components/schemas/CanonicalInvoice_SaAddress" }, "buyerAddress": { "$ref": "#/components/schemas/CanonicalInvoice_SaAddress" }, "hijriDates": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "hijri": { "type": "string" }, "gregorian": { "$ref": "#/components/schemas/CanonicalInvoice_IsoDate" } }, "required": [ "field", "hijri", "gregorian" ] }, "description": "Dates sent in the Hijri calendar and the Gregorian date they were converted to (tabular calendar, may be off by a day)." } }, "required": [ "hijriDates" ], "description": "Saudi Arabia, ZATCA (KSA UBL profile, FATOORA)." }, "CanonicalInvoice_SaQr": { "type": "object", "properties": { "sellerName": { "type": "string" }, "vatNumber": { "type": "string" }, "timestamp": { "type": "string" }, "total": { "$ref": "#/components/schemas/CanonicalInvoice_Decimal" }, "vatTotal": { "$ref": "#/components/schemas/CanonicalInvoice_Decimal" }, "invoiceHash": { "type": "string" }, "signature": { "type": "string" }, "publicKey": { "type": "string" }, "certificateSignature": { "type": "string" } }, "description": "The ZATCA QR code (TLV, tags 1-9). Tags 1-5 are text, 6 is the base64 invoice hash, 7-9 are base64 of binary values." }, "CanonicalInvoice_SchemeId": { "type": "string", "examples": [ "0002", "0007", "0009", "0060", "0088", "0096", "0106", "0160", "0184", "0190", "0192", "0201", "0204", "0208", "0210", "0211", "0216", "9914", "9920", "9925", "9926", "9928", "9929", "9930", "9931", "9933", "9934", "9935", "9937", "9938", "9939", "9943", "9944", "9945", "9946", "9947", "9949", "9950", "9957", "EM", "PL:NIP", "IT:CF", "ES:NIF", "CZ:ICO", "HR:OIB", "GR:AFM", "PT:NIF", "RO:CIF", "HU:ADOSZAM", "EE:REGCODE", "SI:DAVCNA" ], "description": "Identifier schemes: ISO/IEC 6523 ICD codes (party, item and location IDs) and Peppol EAS codes (electronic addresses, BT-34/BT-49). Only codes whose meaning is certain are listed. Check the current EAS list before relying on a code: Peppol BIS 3.0.21 removed 14 EAS codes." }, "CanonicalInvoice_Seller": { "type": "object", "properties": { "name": { "type": "string" }, "tradingName": { "type": "string" }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" } }, "legalRegistrationId": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "vatId": { "type": "string" }, "nationalTaxIds": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "description": "National tax ID that is not the VAT number and not the company register ID: IT codice fiscale, PL NIP (when no VAT prefix), ES NIF, HR OIB, GR AFM, CZ IČO. Several national formats identify parties only by this." }, "endpoint": { "$ref": "#/components/schemas/CanonicalInvoice_Identifier" }, "address": { "$ref": "#/components/schemas/CanonicalInvoice_Address" }, "contact": { "$ref": "#/components/schemas/CanonicalInvoice_Contact" }, "taxRegistrationId": { "type": "string" }, "additionalLegalInfo": { "type": "string" } }, "required": [ "identifiers", "nationalTaxIds" ] }, "CanonicalInvoice_SgExtension": { "type": "object", "properties": { "sellerUen": { "type": "string" }, "buyerUen": { "type": "string" }, "gstRegistrationNumber": { "type": "string" }, "buyerGstRegistrationNumber": { "type": "string" }, "gstCategories": { "type": "array", "items": { "type": "string" } } }, "required": [ "gstCategories" ], "description": "Peppol PINT (non-EU). GST is carried as a VAT-like scheme: `vatId` of a party holds the GST (or, in Japan, qualified-invoice) registration number, and the extension repeats it under its national name. Category codes in `vatBreakdown` stay as sent; the codes used are listed here for the jurisdictions (SG, MY) whose code lists are not UNCL 5305." }, "CanonicalInvoice_SignatureInfo": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CAdES", "XAdES", "XMLDSig", "PAdES", "detached" ] }, "verified": { "type": "boolean", "description": "Cryptographic validity only: the signature value matches the signed content and the signer certificate's key. true = valid, false = invalid (see `reason`), undefined = could not be checked. This says nothing about who the signer is; see `trust`." }, "signer": { "type": "string", "description": "Common name of the signer certificate." }, "certificate": { "type": "object", "properties": { "subject": { "type": "string" }, "issuer": { "type": "string" }, "serial": { "type": "string" }, "notBefore": { "type": "string" }, "notAfter": { "type": "string" } }, "required": [ "subject", "issuer", "serial", "notBefore", "notAfter" ], "description": "Signer certificate details, as carried in the signature." }, "signedAt": { "type": "string", "description": "Signing time (ISO 8601) from signed attributes / XAdES SigningTime, when the signature protects it." }, "reason": { "type": "string", "description": "Why `verified` is false, or why it could not be determined." }, "trust": { "type": "string", "enum": [ "not-checked", "trusted", "untrusted" ], "description": "'not-checked' unless trust anchors were configured: a valid signature is not a trusted signer." }, "trustReason": { "type": "string" }, "euTrust": { "type": "object", "properties": { "qualified": { "type": "boolean", "description": "The signer chains to a CA/QC service whose status was granted at the signing time." }, "status": { "type": "string", "enum": [ "qualified", "not-qualified", "not-listed" ] }, "evaluatedAt": { "type": "string", "description": "The instant the service status was evaluated at: the signing time, or now when the signature carries none." }, "signingTimeKnown": { "type": "boolean" }, "service": { "type": "object", "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "territory": { "type": "string" }, "statusAtSigning": { "type": "string" }, "currentStatus": { "type": "string" }, "statusFrom": { "type": "string" } }, "required": [ "provider", "name", "territory", "statusAtSigning", "currentStatus", "statusFrom" ] }, "snapshot": { "type": "object", "properties": { "fetchedAt": { "type": "string" }, "nextUpdate": { "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "fetchedAt", "stale" ], "description": "`stale`: the snapshot is past its earliest next-update date, so the lists may have changed since." }, "reason": { "type": "string" } }, "required": [ "qualified", "status", "evaluatedAt", "signingTimeKnown", "snapshot" ], "description": "Present when an EU trusted-list snapshot was passed (`euTrust` option): the qualified-service check of the signer." } }, "required": [ "type" ] }, "CanonicalInvoice_SourceMeta": { "type": "object", "properties": { "format": { "$ref": "#/components/schemas/CanonicalInvoice_FormatId" }, "formatVersion": { "type": "string" }, "syntaxDocumentType": { "type": "string" }, "rootNamespace": { "type": "string" }, "specificationId": { "type": "string" }, "profileId": { "type": "string" }, "envelope": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_EnvelopeStep" }, "description": "Path from the received file to this XML, e.g. [{kind:'zip'}, {kind:'cms-p7m'}]." }, "fileSha256": { "type": "string", "description": "SHA-256 of the file as received, and of the XML payload this invoice came from." }, "payloadSha256": { "type": "string" }, "indexInFile": { "type": "number", "description": "Position and path inside a multi-invoice file (FatturaPA lot, Facturae batch, e-arve)." }, "fragmentPath": { "type": "string" }, "encoding": { "type": "string" }, "filename": { "type": "string" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalInvoice_SignatureInfo" } }, "unmapped": { "type": "object", "additionalProperties": { "type": "string" } }, "derived": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "rule": { "type": "string" } }, "required": [ "field", "rule" ] } }, "valueOrigins": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CanonicalInvoice_ValueOrigin" }, "description": "Canonical JSON Pointer -> origin. Partial coverage; defaults are placeholders, not source assertions. No raw XML." }, "provenance": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional field-level provenance: canonical path -> source XPath (e.g. '/totals/payable' -> '/Invoice/cac:LegalMonetaryTotal/cbc:PayableAmount')." }, "validation": { "$ref": "#/components/schemas/CanonicalInvoice_ValidationSummary" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" }, "field": { "type": "string", "description": "Canonical JSON Pointer, when a specific value is affected." } }, "required": [ "code", "message" ] } } }, "required": [ "format", "syntaxDocumentType", "rootNamespace", "envelope", "fileSha256", "payloadSha256", "signatures", "unmapped", "derived", "warnings" ] }, "CanonicalInvoice_TaxRepresentative": { "type": "object", "properties": { "name": { "type": "string" }, "vatId": { "type": "string" }, "address": { "$ref": "#/components/schemas/CanonicalInvoice_Address" } }, "required": [ "name", "vatId", "address" ] }, "CanonicalInvoice_Totals": { "type": "object", "properties": { "lineNetTotal": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "allowanceTotal": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "chargeTotal": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "taxExclusive": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "vatTotal": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "vatTotalInTaxCurrency": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "taxInclusive": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "prepaid": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "rounding": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "withholdingTotal": { "$ref": "#/components/schemas/CanonicalInvoice_Amount", "description": "Not EN: sum of `withholdings`." }, "splitPaymentVat": { "$ref": "#/components/schemas/CanonicalInvoice_Amount", "description": "Not EN: VAT the buyer pays to the tax authority instead of the seller (IT split payment, EsigibilitaIVA = S). The VAT stays in `vatTotal`." }, "payable": { "$ref": "#/components/schemas/CanonicalInvoice_Amount", "description": "BT-115: amount the buyer has to pay. payable = taxInclusive - prepaid + rounding - withholdingTotal - splitPaymentVat (the last two are 0 for every EN-based source)." } }, "required": [ "lineNetTotal", "taxExclusive", "taxInclusive", "payable" ] }, "CanonicalInvoice_UnitCode": { "type": "string", "examples": [ "C62", "H87", "EA", "XPP", "HUR", "DAY", "MON", "ANN", "KGM", "TNE", "LTR", "MTR", "MTK", "MTQ", "KWH", "KMT", "SET", "LS" ], "description": "UN/ECE Recommendation 20 / 21 unit codes (BT-130)." }, "CanonicalInvoice_UnitPrice": { "$ref": "#/components/schemas/CanonicalInvoice_Decimal" }, "CanonicalInvoice_ValidationSummary": { "type": "object", "properties": { "parse": { "$ref": "#/components/schemas/CanonicalInvoice_CheckStatus" }, "schema": { "$ref": "#/components/schemas/CanonicalInvoice_CheckStatus" }, "semantic": { "$ref": "#/components/schemas/CanonicalInvoice_CheckStatus" }, "profile": { "$ref": "#/components/schemas/CanonicalInvoice_CheckStatus" }, "signature": { "$ref": "#/components/schemas/CanonicalInvoice_CheckStatus" }, "clearance": { "$ref": "#/components/schemas/CanonicalInvoice_CheckStatus" }, "bundles": { "type": "object", "properties": { "schema": { "type": "string" }, "semantic": { "type": "string" }, "profile": { "type": "string" } }, "description": "Validator bundle used per layer, e.g. { profile: 'peppol-billing-3.0.21' }." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string" }, "ruleId": { "type": "string" }, "severity": { "type": "string", "enum": [ "fatal", "warning", "info" ] }, "message": { "type": "string" }, "path": { "type": "string" } }, "required": [ "layer", "severity", "message" ] } } }, "required": [ "parse", "schema", "semantic", "profile", "signature", "clearance", "bundles", "findings" ], "description": "Validation results, kept per layer so a failure in one never reads as a pass in another (a valid signature says nothing about the schema, and the reverse). 'unavailable' means the validator could not run, which is not the same as the document failing." }, "CanonicalInvoice_ValueOrigin": { "type": "string", "enum": [ "source", "derived", "defaulted" ], "description": "Origin of a canonical value; absence of an entry means unrecorded, never implicitly source-supplied." }, "CanonicalInvoice_VatBreakdown": { "type": "object", "properties": { "taxableAmount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "taxAmount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "categoryCode": { "$ref": "#/components/schemas/CanonicalInvoice_VatCategoryCode" }, "rate": { "$ref": "#/components/schemas/CanonicalInvoice_Percentage" }, "exemptionReason": { "type": "string" }, "exemptionReasonCode": { "type": "string" }, "taxAmountInTaxCurrency": { "$ref": "#/components/schemas/CanonicalInvoice_Amount", "description": "Not EN: per-rate VAT in the tax currency (KSeF P_14_xW, Facturae TaxAmount/EquivalentInEuros)." }, "nationalCode": { "type": "string" } }, "required": [ "taxableAmount", "taxAmount", "categoryCode" ] }, "CanonicalInvoice_VatCategoryCode": { "type": "string", "examples": [ "S", "Z", "E", "AE", "K", "G", "O", "L", "M", "B" ], "description": "UNCL 5305 VAT category (BT-118, BT-151)." }, "CanonicalInvoice_VatInfo": { "type": "object", "properties": { "categoryCode": { "$ref": "#/components/schemas/CanonicalInvoice_VatCategoryCode" }, "rate": { "$ref": "#/components/schemas/CanonicalInvoice_Percentage" }, "nationalCode": { "type": "string", "description": "Source code that drove the category: 'IT:N6.2', 'PL:P_12:oo', 'ES:E2'..." }, "exemptionReason": { "type": "string" } }, "required": [ "categoryCode" ] }, "CanonicalInvoice_Withholding": { "type": "object", "properties": { "scheme": { "type": "string" }, "taxableAmount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "rate": { "$ref": "#/components/schemas/CanonicalInvoice_Percentage" }, "amount": { "$ref": "#/components/schemas/CanonicalInvoice_Amount" }, "reasonCode": { "type": "string" } }, "required": [ "scheme", "amount" ], "description": "Withholding taxes deducted by the buyer: IT ritenuta d'acconto / previdenziale, ES retención IRPF, PT retenção na fonte. EN 16931 has no term for these." }, "ConvertResult": { "title": "ConvertResult", "type": "object", "properties": { "fileSha256": { "type": "string" }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_ConvertOutcome" }, "description": "One outcome per XML document found in the file. Empty when nothing usable was found; see `skipped`." }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Skipped" } } }, "required": [ "fileSha256", "outcomes", "skipped" ] }, "ConvertResult_AdditionalParty": { "type": "object", "properties": { "role": { "type": "string" }, "sourceRole": { "type": "string", "description": "Role code as written in the source, e.g. 'PL:Rola:5', 'IT:SoggettoEmittente:TZ'." }, "party": { "$ref": "#/components/schemas/ConvertResult_Party" } }, "required": [ "role", "party" ], "description": "Parties in roles EN 16931 does not model: KSeF Podmiot3 (factor, internal recipient, additional buyer, issuer on behalf of the seller, payer, VAT-group member...), FatturaPA TerzoIntermediarioOSoggettoEmittente, Facturae third party, e-arve FactorParty, eSLOG NAD roles. Payee and tax representative stay in their EN fields." }, "ConvertResult_Address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "line3": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "countrySubdivision": { "type": "string" }, "countryCode": { "$ref": "#/components/schemas/ConvertResult_CountryCode" } } }, "ConvertResult_AeExtension": { "type": "object", "properties": { "transactionTypeCode": { "type": "string", "description": "The eight transaction-type flags as sent (ProfileExecutionID), e.g. '00001000'." }, "transactionTypes": { "type": "array", "items": { "type": "string" }, "description": "Names of the flags that are set: freeTradeZone, deemedSupply, profitMarginScheme, summaryInvoice, continuousSupply, agentBilling, ecommerce, exports." }, "uuid": { "type": "string" }, "sellerTin": { "type": "string" }, "buyerTin": { "type": "string" }, "sellerRegistrationType": { "type": "string", "description": "Legal registration identifier type and issuing authority (TL trade licence, EID Emirates ID, PAS passport, CD cabinet decision)." }, "sellerRegistrationAuthority": { "type": "string" }, "buyerRegistrationType": { "type": "string" }, "buyerRegistrationAuthority": { "type": "string" }, "taxExchangeRate": { "type": "object", "properties": { "sourceCurrency": { "type": "string" }, "targetCurrency": { "type": "string" }, "rate": { "$ref": "#/components/schemas/ConvertResult_Decimal" } }, "required": [ "sourceCurrency", "targetCurrency", "rate" ] }, "billingFrequency": { "type": "string", "description": "Frequency of billing (InvoicePeriod description)." } }, "required": [ "transactionTypes" ], "description": "United Arab Emirates (PINT AE)." }, "ConvertResult_AllowanceCharge": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "baseAmount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "percentage": { "$ref": "#/components/schemas/ConvertResult_Percentage" }, "reason": { "type": "string" }, "reasonCode": { "$ref": "#/components/schemas/ConvertResult_AllowanceChargeReasonCode" }, "vat": { "$ref": "#/components/schemas/ConvertResult_VatInfo" } }, "required": [ "amount" ] }, "ConvertResult_AllowanceChargeReasonCode": { "type": "string", "examples": [ "41", "42", "60", "62", "63", "64", "65", "66", "67", "68", "70", "71", "88", "95", "100", "102", "103", "104", "105", "AA", "AAA", "ABL", "ADR", "ADT", "FC", "FI", "LA", "ZZZ" ], "description": "UNCL 5189 (allowances) and UNCL 7161 (charges)." }, "ConvertResult_Amount": { "$ref": "#/components/schemas/ConvertResult_Decimal", "description": "Monetary amount. EN 16931 allows at most 2 decimals at document level; lines may carry more in some national formats." }, "ConvertResult_AtExtension": { "type": "object", "properties": { "ebInterfaceVersion": { "type": "string" }, "documentType": { "type": "string" }, "orderReferenceRequiredByFederalGovernment": { "type": "string" } }, "description": "Austria, ebInterface." }, "ConvertResult_Attachment": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "embedded" }, "id": { "type": "string" }, "description": { "type": "string" }, "mimeCode": { "type": "string" }, "filename": { "type": "string" }, "base64": { "type": "string" } }, "required": [ "kind", "id", "mimeCode", "filename", "base64" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "external" }, "id": { "type": "string" }, "description": { "type": "string" }, "uri": { "type": "string" } }, "required": [ "kind", "id", "uri" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reference" }, "id": { "type": "string" }, "description": { "type": "string" }, "typeCode": { "type": "string" }, "schemeId": { "type": "string" } }, "required": [ "kind", "id" ] } ] }, "ConvertResult_AuNzExtension": { "type": "object", "properties": { "abn": { "type": "string" }, "nzbn": { "type": "string" }, "gstRegistrationNumber": { "type": "string" }, "buyerAbn": { "type": "string" }, "buyerNzbn": { "type": "string" }, "buyerGstRegistrationNumber": { "type": "string" }, "gstCategories": { "type": "array", "items": { "type": "string" } } }, "required": [ "gstCategories" ], "description": "Australia and New Zealand (PINT A-NZ, one specification for both; stored under `au` or `nz` by seller country)." }, "ConvertResult_CanonicalInvoice": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "invoice" }, "typeCode": { "$ref": "#/components/schemas/ConvertResult_InvoiceTypeCode" }, "id": { "type": "string" }, "issueDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "issueTime": { "$ref": "#/components/schemas/ConvertResult_IsoTime" }, "nationalType": { "$ref": "#/components/schemas/ConvertResult_NationalTypeCode" }, "selfBilled": { "type": "boolean" }, "currency": { "$ref": "#/components/schemas/ConvertResult_CurrencyCode" }, "taxCurrency": { "$ref": "#/components/schemas/ConvertResult_CurrencyCode" }, "exchangeRate": { "type": "object", "properties": { "rate": { "$ref": "#/components/schemas/ConvertResult_Decimal" }, "date": { "$ref": "#/components/schemas/ConvertResult_IsoDate" } }, "required": [ "rate" ], "description": "Not EN as a single term: exchange rate the source used to state VAT in the tax currency." }, "taxPointDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "vatPointDateCode": { "type": "string" }, "dueDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "buyerReference": { "type": "string" }, "projectRef": { "type": "string" }, "contractRef": { "type": "string" }, "purchaseOrderRef": { "type": "string" }, "salesOrderRef": { "type": "string" }, "receivingAdviceRef": { "type": "string" }, "despatchAdviceRef": { "type": "string" }, "tenderRef": { "type": "string" }, "invoicedObjectId": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "accountingRef": { "type": "string" }, "paymentTerms": { "type": "string" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "subjectCode": { "type": "string" }, "text": { "type": "string" } }, "required": [ "text" ] } }, "businessProcess": { "type": "string" }, "specificationId": { "type": "string" }, "precedingInvoices": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_PrecedingInvoiceRef" } }, "correction": { "$ref": "#/components/schemas/ConvertResult_Correction" }, "invoicePeriod": { "$ref": "#/components/schemas/ConvertResult_Period" }, "seller": { "$ref": "#/components/schemas/ConvertResult_Seller" }, "buyer": { "$ref": "#/components/schemas/ConvertResult_Party" }, "payee": { "$ref": "#/components/schemas/ConvertResult_Payee" }, "taxRepresentative": { "$ref": "#/components/schemas/ConvertResult_TaxRepresentative" }, "additionalParties": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_AdditionalParty" } }, "delivery": { "$ref": "#/components/schemas/ConvertResult_Delivery" }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_PaymentInstructions" } }, "paymentSchedule": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_PaymentInstallment" } }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_AllowanceCharge" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_AllowanceCharge" } }, "totals": { "$ref": "#/components/schemas/ConvertResult_Totals" }, "vatBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_VatBreakdown" } }, "otherTaxes": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_OtherTax" } }, "withholdings": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Withholding" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Attachment" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Line" } }, "lineRoles": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ConvertResult_LineRole" }, "description": "Line id -> role. Only with `convert(..., { relations: true })`. Never changes `lines` or `totals`." }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_LineRelation" } }, "clearance": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_ClearanceInfo" } }, "extensions": { "$ref": "#/components/schemas/ConvertResult_CountryExtensions" }, "source": { "$ref": "#/components/schemas/ConvertResult_SourceMeta" } }, "required": [ "additionalParties", "allowances", "attachments", "buyer", "charges", "clearance", "currency", "extensions", "id", "issueDate", "kind", "lines", "notes", "otherTaxes", "paymentSchedule", "payments", "precedingInvoices", "selfBilled", "seller", "source", "specificationId", "totals", "typeCode", "vatBreakdown", "withholdings" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "creditNote" }, "typeCode": { "$ref": "#/components/schemas/ConvertResult_CreditNoteTypeCode" }, "id": { "type": "string" }, "issueDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "issueTime": { "$ref": "#/components/schemas/ConvertResult_IsoTime" }, "nationalType": { "$ref": "#/components/schemas/ConvertResult_NationalTypeCode" }, "selfBilled": { "type": "boolean" }, "currency": { "$ref": "#/components/schemas/ConvertResult_CurrencyCode" }, "taxCurrency": { "$ref": "#/components/schemas/ConvertResult_CurrencyCode" }, "exchangeRate": { "type": "object", "properties": { "rate": { "$ref": "#/components/schemas/ConvertResult_Decimal" }, "date": { "$ref": "#/components/schemas/ConvertResult_IsoDate" } }, "required": [ "rate" ], "description": "Not EN as a single term: exchange rate the source used to state VAT in the tax currency." }, "taxPointDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "vatPointDateCode": { "type": "string" }, "dueDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "buyerReference": { "type": "string" }, "projectRef": { "type": "string" }, "contractRef": { "type": "string" }, "purchaseOrderRef": { "type": "string" }, "salesOrderRef": { "type": "string" }, "receivingAdviceRef": { "type": "string" }, "despatchAdviceRef": { "type": "string" }, "tenderRef": { "type": "string" }, "invoicedObjectId": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "accountingRef": { "type": "string" }, "paymentTerms": { "type": "string" }, "notes": { "type": "array", "items": { "type": "object", "properties": { "subjectCode": { "type": "string" }, "text": { "type": "string" } }, "required": [ "text" ] } }, "businessProcess": { "type": "string" }, "specificationId": { "type": "string" }, "precedingInvoices": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_PrecedingInvoiceRef" } }, "correction": { "$ref": "#/components/schemas/ConvertResult_Correction" }, "invoicePeriod": { "$ref": "#/components/schemas/ConvertResult_Period" }, "seller": { "$ref": "#/components/schemas/ConvertResult_Seller" }, "buyer": { "$ref": "#/components/schemas/ConvertResult_Party" }, "payee": { "$ref": "#/components/schemas/ConvertResult_Payee" }, "taxRepresentative": { "$ref": "#/components/schemas/ConvertResult_TaxRepresentative" }, "additionalParties": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_AdditionalParty" } }, "delivery": { "$ref": "#/components/schemas/ConvertResult_Delivery" }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_PaymentInstructions" } }, "paymentSchedule": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_PaymentInstallment" } }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_AllowanceCharge" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_AllowanceCharge" } }, "totals": { "$ref": "#/components/schemas/ConvertResult_Totals" }, "vatBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_VatBreakdown" } }, "otherTaxes": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_OtherTax" } }, "withholdings": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Withholding" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Attachment" } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Line" } }, "lineRoles": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ConvertResult_LineRole" }, "description": "Line id -> role. Only with `convert(..., { relations: true })`. Never changes `lines` or `totals`." }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_LineRelation" } }, "clearance": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_ClearanceInfo" } }, "extensions": { "$ref": "#/components/schemas/ConvertResult_CountryExtensions" }, "source": { "$ref": "#/components/schemas/ConvertResult_SourceMeta" } }, "required": [ "additionalParties", "allowances", "attachments", "buyer", "charges", "clearance", "currency", "extensions", "id", "issueDate", "kind", "lines", "notes", "otherTaxes", "paymentSchedule", "payments", "precedingInvoices", "selfBilled", "seller", "source", "specificationId", "totals", "typeCode", "vatBreakdown", "withholdings" ] } ] }, "ConvertResult_CheckStatus": { "type": "string", "enum": [ "passed", "failed", "not-run", "unavailable" ] }, "ConvertResult_ClearanceAuthority": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "IT:SDI", "PL:KSEF", "RO:SPV", "HR:FISK", "GR:MYDATA", "FR:PPF", "PT:AT", "ES:VERIFACTU", "HU:NAV" ] } ] }, "ConvertResult_ClearanceInfo": { "type": "object", "properties": { "authority": { "$ref": "#/components/schemas/ConvertResult_ClearanceAuthority" }, "documentId": { "type": "string", "description": "Authority-issued ID: SdI IdentificativoSdI, KSeF number, ANAF index, MARK..." }, "secondaryId": { "type": "string", "description": "Second ID if the authority issues two (ANAF upload index vs download ID, myDATA UID vs MARK)." }, "receivedAt": { "type": "string" }, "status": { "type": "string" }, "qrPayload": { "type": "string", "description": "QR code payload or URL printed on the visual (PT, GR, PL, ES, SA: base64 TLV)." }, "counter": { "type": "string", "description": "Invoice counter in the issuer's chain (SA ICV)." }, "previousHash": { "type": "string", "description": "Hash of the previous invoice in the issuer's chain (SA PIH), as carried." }, "hash": { "type": "string", "description": "Hash of this invoice as carried in the document (SA invoice hash), not recomputed." }, "certificateNumber": { "type": "string", "description": "Number of the authority's certificate that stamped the document (CFDI NoCertificadoSAT)." }, "stamp": { "type": "string", "description": "The stamp as written: the authority's stamp over the document (CFDI SelloSAT, not verified) or the signature value on the invoice (SA, base64)." }, "intermediary": { "type": "string", "description": "Authorised intermediary that submitted the document to the authority (CFDI PAC, RfcProvCertif)." } }, "required": [ "authority" ] }, "ConvertResult_Contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } } }, "ConvertResult_ConvertOutcome": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_CanonicalInvoice" } }, "detection": { "$ref": "#/components/schemas/ConvertResult_Detection" }, "payload": { "type": "object", "properties": { "encoding": { "type": "string" }, "envelope": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_EnvelopeStep" } }, "filename": { "type": "string", "description": "Name of the innermost file (zip entry, PDF attachment, or the received file)." }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_SignatureInfo" } }, "fromPdf": { "type": "boolean" }, "sha256": { "type": "string", "description": "SHA-256 (hex) of the XML payload, UTF-8 encoded." }, "byteLength": { "type": "number", "description": "Size of the XML payload in bytes, UTF-8 encoded." }, "siblingEntries": { "type": "array", "items": { "type": "string" }, "description": "Names of the other files in the ZIP this payload came from (ISDOCX attachments); only set for ZIP members." } }, "required": [ "encoding", "envelope", "signatures", "fromPdf", "sha256", "byteLength" ] } }, "required": [ "status", "invoices", "detection", "payload" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "not-an-invoice" }, "detection": { "$ref": "#/components/schemas/ConvertResult_Detection" }, "payload": { "type": "object", "properties": { "encoding": { "type": "string" }, "envelope": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_EnvelopeStep" } }, "filename": { "type": "string", "description": "Name of the innermost file (zip entry, PDF attachment, or the received file)." }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_SignatureInfo" } }, "fromPdf": { "type": "boolean" }, "sha256": { "type": "string", "description": "SHA-256 (hex) of the XML payload, UTF-8 encoded." }, "byteLength": { "type": "number", "description": "Size of the XML payload in bytes, UTF-8 encoded." }, "siblingEntries": { "type": "array", "items": { "type": "string" }, "description": "Names of the other files in the ZIP this payload came from (ISDOCX attachments); only set for ZIP members." } }, "required": [ "encoding", "envelope", "signatures", "fromPdf", "sha256", "byteLength" ] } }, "required": [ "status", "detection", "payload" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unsupported" }, "detection": { "$ref": "#/components/schemas/ConvertResult_Detection" }, "payload": { "type": "object", "properties": { "encoding": { "type": "string" }, "envelope": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_EnvelopeStep" } }, "filename": { "type": "string", "description": "Name of the innermost file (zip entry, PDF attachment, or the received file)." }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_SignatureInfo" } }, "fromPdf": { "type": "boolean" }, "sha256": { "type": "string", "description": "SHA-256 (hex) of the XML payload, UTF-8 encoded." }, "byteLength": { "type": "number", "description": "Size of the XML payload in bytes, UTF-8 encoded." }, "siblingEntries": { "type": "array", "items": { "type": "string" }, "description": "Names of the other files in the ZIP this payload came from (ISDOCX attachments); only set for ZIP members." } }, "required": [ "encoding", "envelope", "signatures", "fromPdf", "sha256", "byteLength" ] }, "reason": { "type": "string" } }, "required": [ "status", "detection", "payload", "reason" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "detection": { "$ref": "#/components/schemas/ConvertResult_Detection" }, "payload": { "type": "object", "properties": { "encoding": { "type": "string" }, "envelope": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_EnvelopeStep" } }, "filename": { "type": "string", "description": "Name of the innermost file (zip entry, PDF attachment, or the received file)." }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_SignatureInfo" } }, "fromPdf": { "type": "boolean" }, "sha256": { "type": "string", "description": "SHA-256 (hex) of the XML payload, UTF-8 encoded." }, "byteLength": { "type": "number", "description": "Size of the XML payload in bytes, UTF-8 encoded." }, "siblingEntries": { "type": "array", "items": { "type": "string" }, "description": "Names of the other files in the ZIP this payload came from (ISDOCX attachments); only set for ZIP members." } }, "required": [ "encoding", "envelope", "signatures", "fromPdf", "sha256", "byteLength" ] }, "error": { "type": "string" } }, "required": [ "status", "detection", "payload", "error" ] } ] }, "ConvertResult_Correction": { "type": "object", "properties": { "reason": { "type": "string" }, "reasonCode": { "type": "string" }, "method": { "type": "string" }, "period": { "$ref": "#/components/schemas/ConvertResult_Period" } }, "description": "Why and how a corrective document corrects (KSeF KOR, Facturae rectificativa, ISDOC 2/3...)." }, "ConvertResult_CountryCode": { "type": "string", "examples": [ "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE" ], "description": "ISO 3166-1 alpha-2. EU member states listed; Greece is 'GR' (EL is the VAT prefix only)." }, "ConvertResult_CountryExtensions": { "type": "object", "properties": { "it": { "$ref": "#/components/schemas/ConvertResult_ItExtension" }, "pl": { "$ref": "#/components/schemas/ConvertResult_PlExtension" }, "es": { "$ref": "#/components/schemas/ConvertResult_EsExtension" }, "hr": { "$ref": "#/components/schemas/ConvertResult_HrExtension" }, "gr": { "$ref": "#/components/schemas/ConvertResult_GrExtension" }, "pt": { "$ref": "#/components/schemas/ConvertResult_PtExtension" }, "fr": { "$ref": "#/components/schemas/ConvertResult_FrExtension" }, "de": { "$ref": "#/components/schemas/ConvertResult_DeExtension" }, "cz": { "$ref": "#/components/schemas/ConvertResult_CzExtension" }, "at": { "$ref": "#/components/schemas/ConvertResult_AtExtension" }, "fi": { "$ref": "#/components/schemas/ConvertResult_FiExtension" }, "ee": { "$ref": "#/components/schemas/ConvertResult_EeExtension" }, "sg": { "$ref": "#/components/schemas/ConvertResult_SgExtension" }, "au": { "$ref": "#/components/schemas/ConvertResult_AuNzExtension" }, "nz": { "$ref": "#/components/schemas/ConvertResult_AuNzExtension" }, "jp": { "$ref": "#/components/schemas/ConvertResult_JpExtension" }, "my": { "$ref": "#/components/schemas/ConvertResult_MyExtension" }, "ae": { "$ref": "#/components/schemas/ConvertResult_AeExtension" }, "sa": { "$ref": "#/components/schemas/ConvertResult_SaExtension" }, "mx": { "$ref": "#/components/schemas/ConvertResult_MxExtension" } } }, "ConvertResult_CreditNoteTypeCode": { "type": "string", "examples": [ "381", "396", "261", "262", "81", "83", "532" ], "description": "UNCL 1001 document type codes used for credit notes (BT-3)." }, "ConvertResult_CreditTransfer": { "type": "object", "properties": { "accountId": { "type": "string" }, "accountName": { "type": "string" }, "serviceProviderId": { "type": "string" } }, "required": [ "accountId" ] }, "ConvertResult_CurrencyCode": { "type": "string", "examples": [ "EUR", "SEK", "DKK", "PLN", "CZK", "HUF", "RON", "BGN", "NOK", "CHF", "GBP", "USD" ], "description": "ISO 4217 currency code." }, "ConvertResult_CzExtension": { "type": "object", "properties": { "documentType": { "type": "string" }, "variableSymbol": { "type": "string" }, "constantSymbol": { "type": "string" }, "specificSymbol": { "type": "string" } }, "description": "Czechia, ISDOC." }, "ConvertResult_Decimal": { "type": "string", "pattern": "^[+-]?\\d+(\\.\\d+)?$", "description": "Plain decimal string: optional sign, digits, optional fraction. No exponent, no grouping." }, "ConvertResult_DeExtension": { "type": "object", "properties": { "xrechnungVersion": { "type": "string" }, "zugferdProfile": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "MINIMUM", "BASIC WL", "BASIC", "EN 16931", "EXTENDED", "XRECHNUNG" ] } ] } }, "description": "Germany: XRechnung / ZUGFeRD. Leitweg-ID itself is BT-10 (`buyerReference`)." }, "ConvertResult_Delivery": { "type": "object", "properties": { "partyName": { "type": "string" }, "locationId": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "actualDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "address": { "$ref": "#/components/schemas/ConvertResult_Address" } } }, "ConvertResult_Detection": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "invoice" }, "format": { "$ref": "#/components/schemas/ConvertResult_FormatDef" }, "details": { "$ref": "#/components/schemas/ConvertResult_MatchDetails" }, "probe": { "$ref": "#/components/schemas/ConvertResult_XmlProbe" } }, "required": [ "kind", "format", "details", "probe" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "other-document" }, "label": { "type": "string" }, "probe": { "$ref": "#/components/schemas/ConvertResult_XmlProbe" } }, "required": [ "kind", "label", "probe" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "unknown" }, "reason": { "type": "string" }, "probe": { "anyOf": [ { "$ref": "#/components/schemas/ConvertResult_XmlProbe" }, { "type": "null" } ] } }, "required": [ "kind", "reason", "probe" ] } ] }, "ConvertResult_EeExtension": { "type": "object", "properties": { "invoiceType": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "DEB", "CRE" ] } ] }, "factoring": { "type": "boolean" } }, "description": "Estonia, e-arve." }, "ConvertResult_EnvelopeStep": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "zip", "pdf-attachment", "cms-p7m", "base64", "sbdh", "soap", "xml" ] }, "name": { "type": "string", "description": "Entry name, attachment name or other locator." } }, "required": [ "kind" ], "description": "One unwrapping step between the received file and the parsed XML." }, "ConvertResult_EsExtension": { "type": "object", "properties": { "facturaeVersion": { "type": "string" }, "invoiceClass": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "OO", "OR", "OC", "CO", "CR", "CC" ] } ] }, "invoiceDocumentType": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "FC", "FA", "AF" ] } ] }, "batchId": { "type": "string" }, "administrativeCentres": { "type": "array", "items": { "type": "object", "properties": { "roleCode": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "roleCode", "code" ] }, "description": "DIR3 administrative centres (public sector routing): role 01 oficina contable, 02 órgano gestor, 03 unidad tramitadora." } }, "description": "Spain, Facturae." }, "ConvertResult_FiExtension": { "type": "object", "properties": { "invoiceTypeCode": { "type": "string" }, "epiReference": { "type": "string" } }, "description": "Finland, Finvoice / TEAPPSXML." }, "ConvertResult_FormatDef": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "family": { "$ref": "#/components/schemas/ConvertResult_ParserFamily" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO country codes, or 'EU' for formats used everywhere." }, "status": { "$ref": "#/components/schemas/ConvertResult_FormatStatus" }, "phase": { "type": "number", "enum": [ 1, 2, 3 ], "description": "Suggested build order: 1 = EN 16931 syntaxes, 2 = national formats in active use, 3 = legacy." }, "notes": { "type": "string" } }, "required": [ "id", "name", "family", "countries", "status", "phase", "notes" ] }, "ConvertResult_FormatId": { "type": "string", "enum": [ "xrechnung-ubl", "nlcius-ubl", "cius-ro", "cius-pt", "hr-cius", "fr-ctc-ubl", "oioubl-3", "pl-pef", "peppol-bis3", "peppol-bis3-selfbilling", "pint-sg", "pint-aunz", "pint-jp", "pint-my", "pint-ae", "pint-om", "pint-eu", "peppol-pint", "zatca-ubl", "ubl-be", "en16931-ubl", "peppol-bis2", "oioubl-2", "ubl-unknown", "xrechnung-cii", "nlcius-cii", "fr-ctc-cii", "facturx", "en16931-cii", "cii-unknown", "zugferd-1", "fatturapa", "fatturapa-semplificata", "ksef", "facturae", "isdoc", "ebinterface", "ebinterface-2", "finvoice", "teappsxml", "e-arve", "eslog-2", "eslog-1", "svefaktura-1", "gr-mydata", "mx-cfdi" ], "description": "Identifier of a detected e-invoice format." }, "ConvertResult_FormatStatus": { "type": "string", "enum": [ "current", "legacy", "unverified" ], "description": "- current: in active use for invoices you will receive.\n- legacy: superseded but still sent by some senders; parse best-effort.\n- unverified: detection rule not confirmed against a real file; check before relying on it." }, "ConvertResult_FrExtension": { "type": "object", "properties": { "profile": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "EN16931", "EXTENDED-CTC-FR", "BASICWL", "EXTENDED" ] } ] }, "billingFramework": { "type": "string" }, "operationCategory": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "goods", "services", "mixed" ] } ] } }, "description": "France, 2026 reform (XP Z12-012)." }, "ConvertResult_GrExtension": { "type": "object", "properties": { "invoiceType": { "type": "string" }, "classifications": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "category": { "type": "string" }, "amount": { "$ref": "#/components/schemas/ConvertResult_Amount" } }, "required": [ "type", "category", "amount" ] } } }, "description": "Greece, myDATA." }, "ConvertResult_HrExtension": { "type": "object", "properties": { "issueTime": { "$ref": "#/components/schemas/ConvertResult_IsoTime" }, "copyIndicator": { "type": "boolean" }, "operatorName": { "type": "string" }, "operatorOib": { "type": "string" } }, "description": "Croatia, HR-CIUS with HR extensions." }, "ConvertResult_Identifier": { "type": "object", "properties": { "value": { "type": "string" }, "schemeId": { "$ref": "#/components/schemas/ConvertResult_SchemeId", "description": "ICD / EAS code, or a national label such as 'PL:NIP'." } }, "required": [ "value" ] }, "ConvertResult_InvoiceTypeCode": { "type": "string", "examples": [ "380", "383", "384", "386", "389", "326", "388", "393", "875", "876", "877" ], "description": "UNCL 1001 document type codes used for invoices (BT-3)." }, "ConvertResult_IsoDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD, no time zone." }, "ConvertResult_IsoTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})?$", "description": "hh:mm:ss, optionally with a UTC offset." }, "ConvertResult_Item": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "sellerId": { "type": "string" }, "buyerId": { "type": "string" }, "standardId": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "classifications": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "listId": { "type": "string" }, "listVersion": { "type": "string" } }, "required": [ "code", "listId" ] } }, "originCountry": { "$ref": "#/components/schemas/ConvertResult_CountryCode" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } } }, "required": [ "name", "classifications", "attributes" ] }, "ConvertResult_ItExtension": { "type": "object", "properties": { "transmissionFormat": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "FPA12", "FPR12", "FSM10" ] } ] }, "recipientCode": { "type": "string" }, "recipientPec": { "type": "string" }, "transmissionSequence": { "type": "string" }, "taxRegime": { "type": "string" }, "vatChargeability": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "I", "D", "S" ] } ] }, "stampDuty": { "type": "object", "properties": { "virtual": { "type": "boolean" }, "amount": { "$ref": "#/components/schemas/ConvertResult_Amount" } }, "required": [ "virtual" ] }, "pensionFunds": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "rate": { "$ref": "#/components/schemas/ConvertResult_Percentage" }, "amount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "taxableAmount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "vatRate": { "$ref": "#/components/schemas/ConvertResult_Percentage" }, "subjectToWithholding": { "type": "boolean" }, "nature": { "type": "string" } }, "required": [ "type", "amount" ] } }, "cup": { "type": "string" }, "cig": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "art73": { "type": "boolean" } }, "description": "Italy, FatturaPA. Fields that have no EN or generic equivalent." }, "ConvertResult_JpExtension": { "type": "object", "properties": { "qualifiedInvoiceIssuerNumber": { "type": "string", "description": "Seller's qualified invoice issuer registration number: 'T' + 13 digits." }, "buyerRegistrationNumber": { "type": "string" } }, "description": "Japan (PINT JP, Peppol e-invoice for the qualified invoice system)." }, "ConvertResult_Line": { "type": "object", "properties": { "id": { "type": "string" }, "note": { "type": "string" }, "objectId": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "quantity": { "$ref": "#/components/schemas/ConvertResult_Quantity" }, "unitCode": { "$ref": "#/components/schemas/ConvertResult_UnitCode" }, "unitText": { "type": "string", "description": "Unit as written in the source when it was free text ('st', 'kpl', 'szt.', 'ks')." }, "netAmount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "orderLineRef": { "type": "string" }, "accountingRef": { "type": "string" }, "period": { "$ref": "#/components/schemas/ConvertResult_Period" }, "allowances": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_AllowanceCharge" } }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_AllowanceCharge" } }, "price": { "$ref": "#/components/schemas/ConvertResult_Price" }, "vat": { "$ref": "#/components/schemas/ConvertResult_VatInfo" }, "item": { "$ref": "#/components/schemas/ConvertResult_Item" }, "subjectToWithholding": { "type": "boolean", "description": "Not EN: line is subject to withholding (FatturaPA Ritenuta = SI)." }, "otherTaxes": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_OtherTax" }, "description": "Non-VAT taxes stated per line (Facturae lines can carry IVA + recargo de equivalencia)." }, "withholdings": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Withholding" }, "description": "Withholdings stated per line (Facturae TaxesWithheld on InvoiceLine)." }, "correctionState": { "type": "string", "enum": [ "delta", "before", "after" ], "description": "How a corrective document expresses this line. KSeF corrections either list differences, or list each line twice: the state before (StanPrzed = 1) and after. Undefined for ordinary invoices." }, "subLines": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Line" }, "description": "Sub-lines (XRechnung extension, Factur-X EXTENDED, France EXTENDED-CTC-FR, ISDOC). Totals come from the parent." }, "national": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "description": "Line-level national data (PL GTU codes and procedure, IT AltriDatiGestionali...)." } }, "required": [ "id", "netAmount", "allowances", "charges", "item" ] }, "ConvertResult_LineRelation": { "type": "object", "properties": { "from": { "type": "string", "description": "Line id (BT-126) of the line that heads, adjusts or refers to the others." }, "to": { "type": "array", "items": { "type": "string" } }, "type": { "$ref": "#/components/schemas/ConvertResult_LineRelationType" }, "rate": { "$ref": "#/components/schemas/ConvertResult_Percentage", "description": "Percentage stated in the line text, for `markup` and `discount`." }, "method": { "type": "string", "enum": [ "rule", "arithmetic", "model" ], "description": "How it was found. Only `model` is a guess by a language model; `rule` and `arithmetic` are deterministic." }, "confidence": { "type": "string", "enum": [ "proven", "likely", "review" ], "description": "`proven`: the arithmetic matches exactly and uniquely. `likely`: stated in the text or structure of the invoice. `review`: only a hint (shared ids, model output); do not act on it without a human. Absent for structural rules that cannot be wrong, such as a heading over the lines that follow it." } }, "required": [ "from", "to", "type", "method" ] }, "ConvertResult_LineRelationType": { "type": "string", "enum": [ "heading", "markup", "discount", "allowance-base", "note-reference", "same-item", "same-order-line" ] }, "ConvertResult_LineRole": { "type": "string", "enum": [ "item", "heading", "description", "surcharge", "discount", "freight", "labour", "other" ], "description": "What a line is for. `item` is anything sold; `heading` and `description` carry text only (zero quantity, price and amount); the rest adjust or add to other lines." }, "ConvertResult_MatchDetails": { "type": "object", "properties": { "version": { "type": "string" }, "profile": { "type": "string" } } }, "ConvertResult_MxExtension": { "type": "object", "properties": { "cfdiVersion": { "type": "string" }, "series": { "type": "string" }, "folio": { "type": "string" }, "placeOfIssue": { "type": "string", "description": "Postal code of the place of issue (LugarExpedicion). The issuer's own address is not in a CFDI." }, "exportation": { "type": "string" }, "confirmation": { "type": "string" }, "paymentMethod": { "type": "string", "description": "MetodoPago: 'PUE' paid in one payment, 'PPD' in instalments or deferred." }, "paymentForm": { "type": "string" }, "issuer": { "type": "object", "properties": { "taxRegime": { "type": "string" }, "sealCertificateNumber": { "type": "string" }, "seal": { "type": "string" } } }, "receiver": { "type": "object", "properties": { "taxRegime": { "type": "string" }, "fiscalPostalCode": { "type": "string" }, "cfdiUse": { "type": "string" }, "taxResidence": { "type": "string" } } }, "globalInformation": { "type": "object", "properties": { "periodicity": { "type": "string" }, "months": { "type": "string" }, "year": { "type": "string" } }, "description": "InformacionGlobal: invoice summarising sales to the general public." }, "subTotal": { "$ref": "#/components/schemas/ConvertResult_Amount", "description": "Sum of the line discounts and the pre-discount subtotal as the CFDI states them (SubTotal, Descuento)." }, "discount": { "$ref": "#/components/schemas/ConvertResult_Amount" } }, "description": "Mexico, CFDI 3.3 / 4.0. Fields with no EN or generic equivalent; codes are SAT catalogue keys." }, "ConvertResult_MyExtension": { "type": "object", "properties": { "tin": { "type": "string" }, "buyerTin": { "type": "string" }, "sstRegistrationNumber": { "type": "string" }, "buyerSstRegistrationNumber": { "type": "string" }, "businessRegistrationNumber": { "type": "string" }, "msicCode": { "type": "string" }, "msicDescription": { "type": "string" }, "freeTradeAgreement": { "type": "string" }, "certifiedExporterNumber": { "type": "string" }, "customsForm2": { "type": "string" }, "customsImportForms": { "type": "array", "items": { "type": "string" } }, "originalDocumentUuid": { "type": "string", "description": "LHDN unique identifier of the document this one corrects." }, "taxCategories": { "type": "array", "items": { "type": "string" } } }, "required": [ "customsImportForms", "taxCategories" ], "description": "Malaysia (PINT MY, MyInvois). TIN travels in a PartyTaxScheme with scheme GST; SST registration in the VAT scheme." }, "ConvertResult_NationalTypeCode": { "type": "object", "properties": { "scheme": { "type": "string" }, "code": { "type": "string" }, "label": { "type": "string" } }, "required": [ "scheme", "code" ], "description": "A document type in the source format's own code list, kept next to the mapped UNCL 1001 code." }, "ConvertResult_OtherTax": { "type": "object", "properties": { "scheme": { "type": "string" }, "taxableAmount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "rate": { "$ref": "#/components/schemas/ConvertResult_Percentage" }, "amount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "includedInTotal": { "type": "boolean", "description": "True if the amount is already included in `totals.taxInclusive`." }, "inTaxExclusive": { "type": "boolean", "description": "True if the amount is also already inside `totals.taxExclusive`, because the source charges it as a line or a charge (IT stamp duty as an N1 line). When false or absent, an `includedInTotal` amount sits on top of BT-109 + BT-110 (ES recargo de equivalencia)." } }, "required": [ "scheme", "amount", "includedInTotal" ], "description": "Taxes that are not VAT and not withholding, and that EN 16931 cannot express: ES recargo de equivalencia, IT stamp duty (bollo), excise or environmental fees stated as taxes, IGIC/IPSI when a source keeps them apart from VAT." }, "ConvertResult_ParserFamily": { "type": "string", "enum": [ "ubl", "cii", "zugferd1", "svefaktura", "fatturapa", "ksef", "facturae", "isdoc", "ebinterface", "finvoice", "teappsxml", "e-arve", "eslog", "mydata", "cfdi" ] }, "ConvertResult_Party": { "type": "object", "properties": { "name": { "type": "string" }, "tradingName": { "type": "string" }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Identifier" } }, "legalRegistrationId": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "vatId": { "type": "string" }, "nationalTaxIds": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "description": "National tax ID that is not the VAT number and not the company register ID: IT codice fiscale, PL NIP (when no VAT prefix), ES NIF, HR OIB, GR AFM, CZ IČO. Several national formats identify parties only by this." }, "endpoint": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "address": { "$ref": "#/components/schemas/ConvertResult_Address" }, "contact": { "$ref": "#/components/schemas/ConvertResult_Contact" } }, "required": [ "identifiers", "nationalTaxIds" ] }, "ConvertResult_Payee": { "type": "object", "properties": { "name": { "type": "string" }, "identifier": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "legalRegistrationId": { "$ref": "#/components/schemas/ConvertResult_Identifier" } }, "required": [ "name" ] }, "ConvertResult_PaymentInstallment": { "type": "object", "properties": { "dueDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "amount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "description": { "type": "string" }, "paymentIndex": { "type": "number", "description": "Index into `payments` when the installment names its own means/account." } }, "description": "One due date in a payment schedule. EN 16931 has a single due date (BT-9); FatturaPA (DettaglioPagamento), Facturae (Installment) and KSeF (TerminPlatnosci) can list several, with or without amounts and with or without their own account." }, "ConvertResult_PaymentInstructions": { "type": "object", "properties": { "meansCode": { "$ref": "#/components/schemas/ConvertResult_PaymentMeansCode" }, "meansText": { "type": "string" }, "nationalMeansCode": { "type": "string", "description": "Means code in the source code list (FatturaPA 'MP05', Facturae '04', KSeF '6'...)." }, "remittanceInformation": { "type": "string" }, "creditTransfers": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_CreditTransfer" } }, "card": { "type": "object", "properties": { "primaryAccountNumber": { "type": "string" }, "holderName": { "type": "string" }, "network": { "type": "string" } }, "required": [ "primaryAccountNumber" ] }, "directDebit": { "type": "object", "properties": { "mandateId": { "type": "string" }, "creditorId": { "type": "string" }, "debitedAccountId": { "type": "string" } } } }, "required": [ "meansCode", "creditTransfers" ] }, "ConvertResult_PaymentMeansCode": { "type": "string", "examples": [ "1", "10", "20", "30", "31", "42", "48", "49", "54", "55", "57", "58", "59", "68", "97", "ZZZ" ], "description": "UNCL 4461 payment means (BT-81)." }, "ConvertResult_Percentage": { "$ref": "#/components/schemas/ConvertResult_Decimal" }, "ConvertResult_Period": { "type": "object", "properties": { "start": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "end": { "$ref": "#/components/schemas/ConvertResult_IsoDate" } } }, "ConvertResult_PlExtension": { "type": "object", "properties": { "invoiceKind": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "VAT", "KOR", "ZAL", "ROZ", "UPR", "KOR_ZAL", "KOR_ROZ" ] } ] }, "schemaVariant": { "type": "string" }, "splitPayment": { "type": "boolean" }, "cashAccounting": { "type": "boolean" }, "selfBilling": { "type": "boolean" }, "reverseCharge": { "type": "boolean" }, "exemptionBasis": { "type": "string" }, "marginScheme": { "type": "string" }, "buyerIsLocalGovernmentUnit": { "type": "boolean" }, "buyerIsVatGroupMember": { "type": "boolean" }, "paid": { "type": "boolean" }, "paidDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" } }, "description": "Poland, KSeF FA(2)/FA(3)." }, "ConvertResult_PrecedingInvoiceRef": { "type": "object", "properties": { "id": { "type": "string" }, "issueDate": { "$ref": "#/components/schemas/ConvertResult_IsoDate" }, "clearanceId": { "type": "string", "description": "Clearance ID of the referenced invoice (KSeF number, SdI ID, CFDI UUID...)." }, "relationType": { "type": "string", "description": "How this document relates to the referenced one, in the source code list (CFDI TipoRelacion '01' = credit note of the related document, '04' = substitution...)." } }, "required": [ "id" ] }, "ConvertResult_Price": { "type": "object", "properties": { "net": { "$ref": "#/components/schemas/ConvertResult_UnitPrice" }, "discount": { "$ref": "#/components/schemas/ConvertResult_UnitPrice" }, "gross": { "$ref": "#/components/schemas/ConvertResult_UnitPrice" }, "baseQuantity": { "$ref": "#/components/schemas/ConvertResult_Quantity" }, "baseQuantityUnit": { "$ref": "#/components/schemas/ConvertResult_UnitCode" } }, "required": [ "net" ] }, "ConvertResult_PtExtension": { "type": "object", "properties": { "atcud": { "type": "string" }, "documentHash": { "type": "string" }, "invoiceType": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "FT", "FS", "FR", "NC", "ND" ] } ] } }, "description": "Portugal." }, "ConvertResult_Quantity": { "$ref": "#/components/schemas/ConvertResult_Decimal" }, "ConvertResult_SaAddress": { "type": "object", "properties": { "buildingNumber": { "type": "string" }, "plotIdentification": { "type": "string" }, "district": { "type": "string" } } }, "ConvertResult_SaExtension": { "type": "object", "properties": { "invoiceSubtype": { "type": "string", "enum": [ "standard", "simplified" ] }, "transactionCode": { "type": "string", "description": "InvoiceTypeCode/@name as sent: NNPNESB." }, "thirdParty": { "type": "boolean" }, "nominal": { "type": "boolean" }, "exports": { "type": "boolean" }, "summary": { "type": "boolean" }, "selfBilled": { "type": "boolean" }, "uuid": { "type": "string" }, "counter": { "type": "string" }, "previousInvoiceHash": { "type": "string" }, "invoiceHash": { "type": "string", "description": "Digest of the signed invoice as carried in the XAdES signature (reference 'invoiceSignedData')." }, "stamp": { "type": "object", "properties": { "signatureValue": { "type": "string" }, "certificate": { "type": "string" }, "signedAt": { "type": "string" } } }, "qr": { "$ref": "#/components/schemas/ConvertResult_SaQr" }, "hashCheck": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "match", "mismatch", "not-checked" ] }, "computed": { "type": "string" }, "carried": { "type": "string" }, "qr": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "status", "computed" ], "description": "Our own recomputation of the invoice hash against what the document carries. Never fails the conversion." }, "sellerAddress": { "$ref": "#/components/schemas/ConvertResult_SaAddress" }, "buyerAddress": { "$ref": "#/components/schemas/ConvertResult_SaAddress" }, "hijriDates": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "hijri": { "type": "string" }, "gregorian": { "$ref": "#/components/schemas/ConvertResult_IsoDate" } }, "required": [ "field", "hijri", "gregorian" ] }, "description": "Dates sent in the Hijri calendar and the Gregorian date they were converted to (tabular calendar, may be off by a day)." } }, "required": [ "hijriDates" ], "description": "Saudi Arabia, ZATCA (KSA UBL profile, FATOORA)." }, "ConvertResult_SaQr": { "type": "object", "properties": { "sellerName": { "type": "string" }, "vatNumber": { "type": "string" }, "timestamp": { "type": "string" }, "total": { "$ref": "#/components/schemas/ConvertResult_Decimal" }, "vatTotal": { "$ref": "#/components/schemas/ConvertResult_Decimal" }, "invoiceHash": { "type": "string" }, "signature": { "type": "string" }, "publicKey": { "type": "string" }, "certificateSignature": { "type": "string" } }, "description": "The ZATCA QR code (TLV, tags 1-9). Tags 1-5 are text, 6 is the base64 invoice hash, 7-9 are base64 of binary values." }, "ConvertResult_SchemeId": { "type": "string", "examples": [ "0002", "0007", "0009", "0060", "0088", "0096", "0106", "0160", "0184", "0190", "0192", "0201", "0204", "0208", "0210", "0211", "0216", "9914", "9920", "9925", "9926", "9928", "9929", "9930", "9931", "9933", "9934", "9935", "9937", "9938", "9939", "9943", "9944", "9945", "9946", "9947", "9949", "9950", "9957", "EM", "PL:NIP", "IT:CF", "ES:NIF", "CZ:ICO", "HR:OIB", "GR:AFM", "PT:NIF", "RO:CIF", "HU:ADOSZAM", "EE:REGCODE", "SI:DAVCNA" ], "description": "Identifier schemes: ISO/IEC 6523 ICD codes (party, item and location IDs) and Peppol EAS codes (electronic addresses, BT-34/BT-49). Only codes whose meaning is certain are listed. Check the current EAS list before relying on a code: Peppol BIS 3.0.21 removed 14 EAS codes." }, "ConvertResult_Seller": { "type": "object", "properties": { "name": { "type": "string" }, "tradingName": { "type": "string" }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Identifier" } }, "legalRegistrationId": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "vatId": { "type": "string" }, "nationalTaxIds": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "description": "National tax ID that is not the VAT number and not the company register ID: IT codice fiscale, PL NIP (when no VAT prefix), ES NIF, HR OIB, GR AFM, CZ IČO. Several national formats identify parties only by this." }, "endpoint": { "$ref": "#/components/schemas/ConvertResult_Identifier" }, "address": { "$ref": "#/components/schemas/ConvertResult_Address" }, "contact": { "$ref": "#/components/schemas/ConvertResult_Contact" }, "taxRegistrationId": { "type": "string" }, "additionalLegalInfo": { "type": "string" } }, "required": [ "identifiers", "nationalTaxIds" ] }, "ConvertResult_SgExtension": { "type": "object", "properties": { "sellerUen": { "type": "string" }, "buyerUen": { "type": "string" }, "gstRegistrationNumber": { "type": "string" }, "buyerGstRegistrationNumber": { "type": "string" }, "gstCategories": { "type": "array", "items": { "type": "string" } } }, "required": [ "gstCategories" ], "description": "Peppol PINT (non-EU). GST is carried as a VAT-like scheme: `vatId` of a party holds the GST (or, in Japan, qualified-invoice) registration number, and the extension repeats it under its national name. Category codes in `vatBreakdown` stay as sent; the codes used are listed here for the jurisdictions (SG, MY) whose code lists are not UNCL 5305." }, "ConvertResult_SignatureInfo": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CAdES", "XAdES", "XMLDSig", "PAdES", "detached" ] }, "verified": { "type": "boolean", "description": "Cryptographic validity only: the signature value matches the signed content and the signer certificate's key. true = valid, false = invalid (see `reason`), undefined = could not be checked. This says nothing about who the signer is; see `trust`." }, "signer": { "type": "string", "description": "Common name of the signer certificate." }, "certificate": { "type": "object", "properties": { "subject": { "type": "string" }, "issuer": { "type": "string" }, "serial": { "type": "string" }, "notBefore": { "type": "string" }, "notAfter": { "type": "string" } }, "required": [ "subject", "issuer", "serial", "notBefore", "notAfter" ], "description": "Signer certificate details, as carried in the signature." }, "signedAt": { "type": "string", "description": "Signing time (ISO 8601) from signed attributes / XAdES SigningTime, when the signature protects it." }, "reason": { "type": "string", "description": "Why `verified` is false, or why it could not be determined." }, "trust": { "type": "string", "enum": [ "not-checked", "trusted", "untrusted" ], "description": "'not-checked' unless trust anchors were configured: a valid signature is not a trusted signer." }, "trustReason": { "type": "string" }, "euTrust": { "type": "object", "properties": { "qualified": { "type": "boolean", "description": "The signer chains to a CA/QC service whose status was granted at the signing time." }, "status": { "type": "string", "enum": [ "qualified", "not-qualified", "not-listed" ] }, "evaluatedAt": { "type": "string", "description": "The instant the service status was evaluated at: the signing time, or now when the signature carries none." }, "signingTimeKnown": { "type": "boolean" }, "service": { "type": "object", "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "territory": { "type": "string" }, "statusAtSigning": { "type": "string" }, "currentStatus": { "type": "string" }, "statusFrom": { "type": "string" } }, "required": [ "provider", "name", "territory", "statusAtSigning", "currentStatus", "statusFrom" ] }, "snapshot": { "type": "object", "properties": { "fetchedAt": { "type": "string" }, "nextUpdate": { "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "fetchedAt", "stale" ], "description": "`stale`: the snapshot is past its earliest next-update date, so the lists may have changed since." }, "reason": { "type": "string" } }, "required": [ "qualified", "status", "evaluatedAt", "signingTimeKnown", "snapshot" ], "description": "Present when an EU trusted-list snapshot was passed (`euTrust` option): the qualified-service check of the signer." } }, "required": [ "type" ] }, "ConvertResult_Skipped": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "reason" ] }, "ConvertResult_SourceMeta": { "type": "object", "properties": { "format": { "$ref": "#/components/schemas/ConvertResult_FormatId" }, "formatVersion": { "type": "string" }, "syntaxDocumentType": { "type": "string" }, "rootNamespace": { "type": "string" }, "specificationId": { "type": "string" }, "profileId": { "type": "string" }, "envelope": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_EnvelopeStep" }, "description": "Path from the received file to this XML, e.g. [{kind:'zip'}, {kind:'cms-p7m'}]." }, "fileSha256": { "type": "string", "description": "SHA-256 of the file as received, and of the XML payload this invoice came from." }, "payloadSha256": { "type": "string" }, "indexInFile": { "type": "number", "description": "Position and path inside a multi-invoice file (FatturaPA lot, Facturae batch, e-arve)." }, "fragmentPath": { "type": "string" }, "encoding": { "type": "string" }, "filename": { "type": "string" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ConvertResult_SignatureInfo" } }, "unmapped": { "type": "object", "additionalProperties": { "type": "string" } }, "derived": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "rule": { "type": "string" } }, "required": [ "field", "rule" ] } }, "valueOrigins": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ConvertResult_ValueOrigin" }, "description": "Canonical JSON Pointer -> origin. Partial coverage; defaults are placeholders, not source assertions. No raw XML." }, "provenance": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional field-level provenance: canonical path -> source XPath (e.g. '/totals/payable' -> '/Invoice/cac:LegalMonetaryTotal/cbc:PayableAmount')." }, "validation": { "$ref": "#/components/schemas/ConvertResult_ValidationSummary" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" }, "field": { "type": "string", "description": "Canonical JSON Pointer, when a specific value is affected." } }, "required": [ "code", "message" ] } } }, "required": [ "format", "syntaxDocumentType", "rootNamespace", "envelope", "fileSha256", "payloadSha256", "signatures", "unmapped", "derived", "warnings" ] }, "ConvertResult_TaxRepresentative": { "type": "object", "properties": { "name": { "type": "string" }, "vatId": { "type": "string" }, "address": { "$ref": "#/components/schemas/ConvertResult_Address" } }, "required": [ "name", "vatId", "address" ] }, "ConvertResult_Totals": { "type": "object", "properties": { "lineNetTotal": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "allowanceTotal": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "chargeTotal": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "taxExclusive": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "vatTotal": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "vatTotalInTaxCurrency": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "taxInclusive": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "prepaid": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "rounding": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "withholdingTotal": { "$ref": "#/components/schemas/ConvertResult_Amount", "description": "Not EN: sum of `withholdings`." }, "splitPaymentVat": { "$ref": "#/components/schemas/ConvertResult_Amount", "description": "Not EN: VAT the buyer pays to the tax authority instead of the seller (IT split payment, EsigibilitaIVA = S). The VAT stays in `vatTotal`." }, "payable": { "$ref": "#/components/schemas/ConvertResult_Amount", "description": "BT-115: amount the buyer has to pay. payable = taxInclusive - prepaid + rounding - withholdingTotal - splitPaymentVat (the last two are 0 for every EN-based source)." } }, "required": [ "lineNetTotal", "taxExclusive", "taxInclusive", "payable" ] }, "ConvertResult_UnitCode": { "type": "string", "examples": [ "C62", "H87", "EA", "XPP", "HUR", "DAY", "MON", "ANN", "KGM", "TNE", "LTR", "MTR", "MTK", "MTQ", "KWH", "KMT", "SET", "LS" ], "description": "UN/ECE Recommendation 20 / 21 unit codes (BT-130)." }, "ConvertResult_UnitPrice": { "$ref": "#/components/schemas/ConvertResult_Decimal" }, "ConvertResult_ValidationSummary": { "type": "object", "properties": { "parse": { "$ref": "#/components/schemas/ConvertResult_CheckStatus" }, "schema": { "$ref": "#/components/schemas/ConvertResult_CheckStatus" }, "semantic": { "$ref": "#/components/schemas/ConvertResult_CheckStatus" }, "profile": { "$ref": "#/components/schemas/ConvertResult_CheckStatus" }, "signature": { "$ref": "#/components/schemas/ConvertResult_CheckStatus" }, "clearance": { "$ref": "#/components/schemas/ConvertResult_CheckStatus" }, "bundles": { "type": "object", "properties": { "schema": { "type": "string" }, "semantic": { "type": "string" }, "profile": { "type": "string" } }, "description": "Validator bundle used per layer, e.g. { profile: 'peppol-billing-3.0.21' }." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string" }, "ruleId": { "type": "string" }, "severity": { "type": "string", "enum": [ "fatal", "warning", "info" ] }, "message": { "type": "string" }, "path": { "type": "string" } }, "required": [ "layer", "severity", "message" ] } } }, "required": [ "parse", "schema", "semantic", "profile", "signature", "clearance", "bundles", "findings" ], "description": "Validation results, kept per layer so a failure in one never reads as a pass in another (a valid signature says nothing about the schema, and the reverse). 'unavailable' means the validator could not run, which is not the same as the document failing." }, "ConvertResult_ValueOrigin": { "type": "string", "enum": [ "source", "derived", "defaulted" ], "description": "Origin of a canonical value; absence of an entry means unrecorded, never implicitly source-supplied." }, "ConvertResult_VatBreakdown": { "type": "object", "properties": { "taxableAmount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "taxAmount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "categoryCode": { "$ref": "#/components/schemas/ConvertResult_VatCategoryCode" }, "rate": { "$ref": "#/components/schemas/ConvertResult_Percentage" }, "exemptionReason": { "type": "string" }, "exemptionReasonCode": { "type": "string" }, "taxAmountInTaxCurrency": { "$ref": "#/components/schemas/ConvertResult_Amount", "description": "Not EN: per-rate VAT in the tax currency (KSeF P_14_xW, Facturae TaxAmount/EquivalentInEuros)." }, "nationalCode": { "type": "string" } }, "required": [ "taxableAmount", "taxAmount", "categoryCode" ] }, "ConvertResult_VatCategoryCode": { "type": "string", "examples": [ "S", "Z", "E", "AE", "K", "G", "O", "L", "M", "B" ], "description": "UNCL 5305 VAT category (BT-118, BT-151)." }, "ConvertResult_VatInfo": { "type": "object", "properties": { "categoryCode": { "$ref": "#/components/schemas/ConvertResult_VatCategoryCode" }, "rate": { "$ref": "#/components/schemas/ConvertResult_Percentage" }, "nationalCode": { "type": "string", "description": "Source code that drove the category: 'IT:N6.2', 'PL:P_12:oo', 'ES:E2'..." }, "exemptionReason": { "type": "string" } }, "required": [ "categoryCode" ] }, "ConvertResult_Withholding": { "type": "object", "properties": { "scheme": { "type": "string" }, "taxableAmount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "rate": { "$ref": "#/components/schemas/ConvertResult_Percentage" }, "amount": { "$ref": "#/components/schemas/ConvertResult_Amount" }, "reasonCode": { "type": "string" } }, "required": [ "scheme", "amount" ], "description": "Withholding taxes deducted by the buyer: IT ritenuta d'acconto / previdenziale, ES retención IRPF, PT retenção na fonte. EN 16931 has no term for these." }, "ConvertResult_XmlProbe": { "type": "object", "properties": { "rootName": { "type": "string" }, "rootNs": { "type": "string" }, "rootAttrs": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Root attributes by local name (versione, Version, version...)." }, "nsDecls": { "type": "array", "items": { "type": "string" }, "description": "Every namespace URI declared on the root element." }, "values": { "type": "object", "properties": { "ublCustomizationId": { "type": "string" }, "ublProfileId": { "type": "string" }, "ublVersionId": { "type": "string" }, "ciiGuidelineId": { "type": "string" }, "ciiBusinessProcessId": { "type": "string" }, "zf1GuidelineId": { "type": "string" }, "ksefFormCode": { "type": "string" }, "eArveVersion": { "type": "string" }, "facturaeSchemaVersion": { "type": "string" }, "facturaeModality": { "type": "string" }, "fatturaTipoDocumento": { "type": "string" }, "isdocDocumentType": { "type": "string" }, "finvoiceTypeCode": { "type": "string" }, "myDataInvoiceType": { "type": "string" }, "myDataRequestedInvoiceType": { "type": "string" } }, "description": "Header values found, trimmed. First occurrence wins." }, "valueAttrs": { "type": "object", "properties": { "ublCustomizationId": { "type": "object", "additionalProperties": { "type": "string" } }, "ublProfileId": { "type": "object", "additionalProperties": { "type": "string" } }, "ublVersionId": { "type": "object", "additionalProperties": { "type": "string" } }, "ciiGuidelineId": { "type": "object", "additionalProperties": { "type": "string" } }, "ciiBusinessProcessId": { "type": "object", "additionalProperties": { "type": "string" } }, "zf1GuidelineId": { "type": "object", "additionalProperties": { "type": "string" } }, "ksefFormCode": { "type": "object", "additionalProperties": { "type": "string" } }, "eArveVersion": { "type": "object", "additionalProperties": { "type": "string" } }, "facturaeSchemaVersion": { "type": "object", "additionalProperties": { "type": "string" } }, "facturaeModality": { "type": "object", "additionalProperties": { "type": "string" } }, "fatturaTipoDocumento": { "type": "object", "additionalProperties": { "type": "string" } }, "isdocDocumentType": { "type": "object", "additionalProperties": { "type": "string" } }, "finvoiceTypeCode": { "type": "object", "additionalProperties": { "type": "string" } }, "myDataInvoiceType": { "type": "object", "additionalProperties": { "type": "string" } }, "myDataRequestedInvoiceType": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Attributes of the elements at the target paths (e.g. KSeF kodSystemowy)." }, "hasDoctype": { "type": "boolean", "description": "The document has a DOCTYPE declaration. Inbound e-invoices never need one; treat as hostile." }, "error": { "type": "string", "description": "Parse error, if the document is not well-formed up to the point read." } }, "required": [ "rootName", "rootNs", "rootAttrs", "nsDecls", "values", "valueAttrs", "hasDoctype" ] } } } }