{ "openapi": "3.1.0", "info": { "title": "Invoice Converter External API", "version": "1.21.0", "x-last-updated": "2026-10-08", "description": "Convert invoice documents (PDF, DOCX, TXT) or structured invoice data from your ERP, billing, or CRM system into validated XRechnung, ZUGFeRD/Factur-X, EN 16931, UBL, or CII e-invoices.\n\n**Base URL** `https://www.invoice-converter.com/api/v1` · **Auth** `Authorization: Bearer ` · **Contract** OpenAPI 3.1 (this document)\n\nThis page is the complete documentation: the guide sections below explain the flow, and the endpoint and schema sections list every field, value, and response.\n\n## Overview\n\nThe API converts one invoice per request into a validated e-invoice. Every conversion is asynchronous:\n\n1. **Convert.** `POST /invoices:convert` (PDF, DOCX, or TXT document) or `POST /invoices:convert-structured` (your invoice data plus a carrier PDF). Response: `202` with `task_id`.\n2. **Poll.** `GET /tasks/{task_id}` until `status` is `completed` or `failed`.\n3. **Download.** `GET /tasks/{task_id}/result?download=xml|pdf`. Optional: `GET /tasks/{task_id}/validation-report?download=html|xml`.\n\nA task completes only when the artifact passed validation for the requested profile. There is no draft or warning-override output. V1 has no webhooks, no batch endpoint, and no task-list endpoint.\n\n| Endpoint | Purpose | Rate limit per API key |\n|---|---|---|\n| `POST /invoices:convert` | Convert a document | 30/min, 500/h |\n| `POST /invoices:convert-structured` | Convert structured data | 30/min, 500/h |\n| `GET /tasks/{task_id}` | Task status | 60/min, 1,500/h |\n| `GET /tasks/{task_id}/result` | Download the artifact | 60/min, 1,000/h |\n| `GET /tasks/{task_id}/validation-report` | Download the validation report | 30/min, 500/h |\n\n## Authentication and access\n\n- Header: `Authorization: Bearer `.\n- Keys are tenant-scoped live credentials with the prefix `icp_...`. Create, rotate, and revoke them on the profile page with an active Enterprise subscription. No separate approval is necessary.\n- Keep keys on your server. Never put them in browser or mobile code, logs, or tickets.\n- Missing token: `401 AUTHENTICATION_REQUIRED`. Unknown or revoked key: `401 INVALID_API_KEY`. Valid key without API access: `403 API_NOT_ENABLED_FOR_TENANT`. Key of a deleted account: `410 ACCOUNT_DELETED` (the deletion is permanent; do not retry).\n\n## Quickstart\n\n```bash\n# 1. Convert\ncurl -X POST 'https://www.invoice-converter.com/api/v1/invoices:convert' \\\n -H 'Authorization: Bearer ' \\\n -H 'Idempotency-Key: erp-inv-2026-0001' \\\n -F 'file=@invoice.pdf' \\\n -F 'format=XRECHNUNG' \\\n -F 'client_reference=ERP-2026-0001'\n\n# 2. Poll (first call about 20 s later)\ncurl 'https://www.invoice-converter.com/api/v1/tasks/' \\\n -H 'Authorization: Bearer '\n\n# 3. Download\ndownload_tmp=$(mktemp) || exit 1\ndownload_meta=$(curl --silent --show-error --output \"$download_tmp\" \\\n --write-out '%{http_code} %{content_type}' --dump-header headers.txt \\\n 'https://www.invoice-converter.com/api/v1/tasks//result?download=xml' \\\n -H 'Authorization: Bearer ') || { rm -f \"$download_tmp\"; exit 1; }\ncase \"$download_meta\" in\n '200 application/xml'|'200 application/xml;'*|'200 text/xml'|'200 text/xml;'*)\n mv \"$download_tmp\" invoice.xml ;;\n *)\n rm -f \"$download_tmp\"\n printf 'Download not saved (%s). Continue polling on 202.\\n' \"$download_meta\" >&2\n exit 1 ;;\nesac\n```\n\nThe `202` body contains `task_id`, `status` (`pending` or `processing`), `status_url`, and `primary_result_url`. Branch on `status`, not on `message`. Store `X-Correlation-ID` from every response; support needs it. A completed status response (abridged):\n\n```json\n{\n \"task_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"completed\",\n \"progress\": 100,\n \"created_at\": \"2026-09-30T08:00:00+00:00\",\n \"completed_at\": \"2026-09-30T08:01:12+00:00\",\n \"error\": null,\n \"client_reference\": \"ERP-2026-0001\",\n \"primary_result_url\": \"/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml\",\n \"result_artifacts\": {\n \"xml\": { \"state\": \"cached\", \"artifact_state\": \"compliant\", \"validation_state\": \"passed\" }\n }\n}\n```\n\nFor `failed`, `error` holds a summary (string or object); call `/result` for the typed error.\n\n## Formats and profiles\n\n`format` is required and selects the syntax and container. `profile` is optional and selects the rule set. If you omit `profile`, the default for the format applies.\n\n| `format` | Accepted `profile` | Default | `download=xml` | `download=pdf` |\n|---|---|---|---|---|\n| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | rendered PDF (best effort) |\n| `EN16931` | `EN16931` | `EN16931` | UBL | rendered PDF (best effort) |\n| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | rendered PDF (best effort) |\n| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | rendered PDF (best effort) |\n| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hybrid ZUGFeRD/Factur-X PDF |\n\n- `format` and `profile` are case-insensitive. Aliases: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`.\n- A profile not listed for the format: `422 OUTPUT_PROFILE_CONFLICT`. An unknown profile name: `422 INVALID_PROFILE` with `details.allowed_profiles`.\n- For XML formats, `download=xml` is the primary artifact. The PDF rendering is a convenience and can be unavailable.\n- `format=ZUGFERD` needs a PDF source. A DOCX or TXT upload is rejected at upload time with `422 ZUGFERD_SOURCE_PDF_REQUIRED`.\n- `jurisdiction` (ISO 3166-1 alpha-2), `transaction_scope` (`B2B`, `B2G`, `B2C`), and `delivery_channel` (`PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN`) are optional context hints. For German B2G or Peppol flows, provide the caller context on upload. An invalid value returns `422 UPLOAD_FAILED`.\n\n## Document conversion\n\n`POST /invoices:convert`, `multipart/form-data`:\n\n- `file` (required): `.pdf`, `.docx`, or `.txt`. One invoice per file. A document with several invoices fails with `500 TASK_FAILED`, `details.code=MULTIPLE_INVOICES_IN_DOCUMENT`.\n- `format` (required), `profile`, context fields as above.\n- `client_reference` (≤ 200 chars) or its alias `external_invoice_id`, and `source_system` (≤ 100 chars): echoed on the `202` and on task status.\n- `use_embedded_xml` (default `false`): embedded Factur-X/ZUGFeRD/XRechnung XML in a PDF is ignored unless this is `true`.\n- `email_input`: optional free-text instructions for the extraction (PDF only, ≤ 10,000 chars, not with `use_embedded_xml=true`).\n- `use_seller_master_data` and `seller_master_data`: see *Seller master data*.\n\nThe extraction reads the document. It does not invent legal, tax, routing, bank, or buyer-reference data. If mandatory data is missing, the task fails and `/result` returns `422 VALIDATION_FAILED`.\n\n## Structured invoice data\n\n`POST /invoices:convert-structured` converts data from your ERP, billing, or CRM system (for example Salesforce).\n\n- `pdf_file` (required): the carrier PDF. For `ZUGFERD` the validated XML is embedded into it; for XML formats it is stored as the original PDF. **It never supplies invoice data.**\n- `data_file` (required, repeatable; aliases `data_files`, `data_files[]`): `.json`, `.csv`, `.xml`, `.xlsx`, or `.txt`, together ≤ 2 MB.\n- `format`, `profile`, context, client-reference, and seller-master-data fields as for document conversion. `email_input` and `use_embedded_xml` are not accepted.\n\n### Deterministic versus interpreted mapping\n\n| Input | Mapping | Result |\n|---|---|---|\n| **One** JSON `data_file` in the canonical invoice JSON shape, at the top level or wrapped in `invoice_data` | Deterministic, no AI | Same input, same output |\n| One UBL 2.1 Invoice or CII D16B XML file | Deterministic, no AI | Existing invoice XML parser |\n| Several consistent canonical JSON `data_file` parts | Deterministic merge, no AI | Disjoint fields and lines are combined |\n| CSV, XLSX, TXT, other XML, custom or flat JSON, or mixed-format parts | AI mapping | Works with clear labels; not deterministic |\n\nFor a repeatable integration, send one canonical JSON file:\n\n- JSON Schema: \n- Example (German B2G XRechnung, passes EN 16931, XRechnung, and strict ZUGFeRD checks): \n\nThe shape uses UBL 2.1 / EN 16931 element names. The canonical path is detected when at least 3 of the top-level keys `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, `AccountingSupplierParty`, `AccountingCustomerParty`, `TaxTotal`, `LegalMonetaryTotal`, `InvoiceLine` are present, including `ID`, `InvoiceLine`, or `LegalMonetaryTotal`.\n\nUnknown fields in canonical JSON return `400 INVALID_UPLOAD` before task creation. `details.unknown_paths` lists up to 100 offending JSON paths; `details.unknown_path_count` gives the total. Remove undeclared fields instead of relying on them being discarded.\n\nThe AI mapping is told not to invent missing fields. Missing data therefore fails validation instead of being guessed.\n\n**Split exports.** For one invoice split across files (for example header and lines), repeat `data_file`. Send one request per invoice.\n\n- Every part must contain the same invoice number in a column or key named `invoice number`, `invoice no`, `invoice no.`, `invoice id`, `rechnungsnr`, `rechnungsnr.`, `rechnung nr`, `rechnung nr.`, `belegnr`, or `belegnr.`.\n- Names are case-insensitive, and `_` and `-` count as spaces, so `Invoice_Number` works. `document no` and `document number` are a weaker fallback.\n- camelCase names such as `invoiceNumber` and Salesforce API names such as `Invoice_Number__c` are recognized.\n- A missing or conflicting number returns `400 INVALID_UPLOAD` with `details.reason` `bundle_invoice_id_missing` or `bundle_invoice_id_mismatch`.\n\nCanonical JSON parts use the same top-level `ID`. Each part must meet the canonical detection rule above. Lines need unique explicit `InvoiceLine[].ID` values within each part. Identical repeated lines across parts are deduplicated; conflicting values or different lines with the same ID return `400 INVALID_UPLOAD`, `details.reason=canonical_bundle_conflict`, and `details.path`. The server does not choose one conflicting value or recalculate totals. A null value is treated as absent when another part supplies the fact.\n\n### Required data\n\n| Always | For XRechnung (also `UBL`/`CII` with profile `XRECHNUNG`, and `ZUGFERD_XRECHNUNG`) | For strict ZUGFeRD |\n|---|---|---|\n| `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, seller and buyer name, VAT breakdown, totals, at least one line | `BuyerReference` (Leitweg-ID, BR-DE-15); `PaymentMeans` (BR-DE-1); seller contact name, phone, e-mail (BR-DE-2/5/6/7); seller and buyer city and post code; seller and buyer `EndpointID` with `@schemeID`; VAT `Percent` per subtotal; seller VAT ID or tax number | A delivery date, an invoice period, or line periods; a delivery country where applicable |\n\nMissing data ends the task as `failed`; `/result` returns `422 VALIDATION_FAILED` with `details.items[]` (`field`, `rule_id`, `severity`, `source`, `suggestion`).\n\n### Most-used JSON paths\n\n`AccountingSupplierParty.Party` is abbreviated as `Seller`, `AccountingCustomerParty.Party` as `Buyer`. XR = required for XRechnung.\n\n| JSON path | EN 16931 | XR |\n|---|---|---|\n| `ID` | BT-1 | yes |\n| `IssueDate` | BT-2 | yes |\n| `InvoiceTypeCode` (for example `380` commercial invoice) | BT-3 | yes |\n| `DocumentCurrencyCode` | BT-5 | yes |\n| `DueDate` | BT-9 | – |\n| `BuyerReference` | BT-10 | yes |\n| `OrderReference.ID` | BT-13 | – |\n| `InvoicePeriod.StartDate` / `.EndDate` | BT-73 / BT-74 | – |\n| `PaymentTerms.Note` | BT-20 | – |\n| `Seller.PartyLegalEntity.RegistrationName` | BT-27 | yes |\n| `Seller.PartyTaxScheme.CompanyID` (VAT ID) | BT-31 | yes¹ |\n| `Seller.EndpointID` (`#text`, `@schemeID`) | BT-34 | yes |\n| `Seller.PostalAddress.StreetName` | BT-35 | – |\n| `Seller.PostalAddress.CityName` / `.PostalZone` | BT-37 / BT-38 | yes |\n| `Seller.PostalAddress.Country.IdentificationCode` | BT-40 | yes |\n| `Seller.Contact.Name` / `.Telephone` / `.ElectronicMail` | BT-41 / BT-42 / BT-43 | yes |\n| `Buyer.PartyLegalEntity.RegistrationName` | BT-44 | yes |\n| `Buyer.EndpointID` (`#text`, `@schemeID`) | BT-49 | yes |\n| `Buyer.PostalAddress.CityName` / `.PostalZone` | BT-52 / BT-53 | yes |\n| `Buyer.PostalAddress.Country.IdentificationCode` | BT-55 | yes |\n| `Delivery.ActualDeliveryDate` | BT-72 | – |\n| `PaymentMeans.PaymentMeansCode` | BT-81 | yes |\n| `PaymentMeans.PayeeFinancialAccount.ID` (IBAN) | BT-84 | for credit transfer |\n| `TaxTotal.TaxAmount` | BT-110 | yes |\n| `TaxTotal.TaxSubtotal[].TaxableAmount` / `.TaxAmount` | BT-116 / BT-117 | yes |\n| `TaxTotal.TaxSubtotal[].TaxCategory.ID` / `.Percent` | BT-118 / BT-119 | yes |\n| `LegalMonetaryTotal.LineExtensionAmount` / `.TaxExclusiveAmount` | BT-106 / BT-109 | yes |\n| `LegalMonetaryTotal.TaxInclusiveAmount` / `.PayableAmount` | BT-112 / BT-115 | yes |\n| `InvoiceLine[].ID` / `.InvoicedQuantity` / `.unitCode` | BT-126 / BT-129 / BT-130 | yes |\n| `InvoiceLine[].LineExtensionAmount` | BT-131 | yes |\n| `InvoiceLine[].Price.PriceAmount` | BT-146 | yes |\n| `InvoiceLine[].Item.Name` | BT-153 | yes |\n| `InvoiceLine[].Item.ClassifiedTaxCategory.ID` / `.Percent` | BT-151 / BT-152 | yes |\n\n¹ Seller VAT ID (BT-31) or tax number (BT-32, `PartyTaxScheme` with `TaxScheme.ID` `FC`).\n\n## Seller master data\n\n`seller_master_data` is a JSON object string. It applies only when `use_seller_master_data=true`; when the flag is omitted, the account default applies. Keys: `business_name`, `trading_name`, `street`, `additional_address`, `postal_code`, `city`, `country`, `vat_id`, `tax_number`, `electronic_address`, `electronic_address_scheme`, `contact_name`, `contact_email`, `contact_phone`, `payment_means_code` (`30`, `42`, or `58`), `payment_iban`, `payment_bic`, `payment_account_name`, `payment_terms_note`. The OpenAPI schema `SellerMasterData` gives the EN 16931 term of each key.\n\n- Every supplied value replaces the extracted seller or payment value. Absent keys leave the invoice unchanged.\n- `electronic_address` and `electronic_address_scheme` are a pair: send both or neither.\n- Invalid JSON, unknown keys, or an incomplete pair: `400 INVALID_SELLER_MASTER_DATA`.\n\n## Idempotency and retries\n\n- `Idempotency-Key` is required on both POST endpoints. Format: 1–200 characters, first character a letter or digit, then letters, digits, `.`, `_`, `:`, or `-` (`^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`). A good key is your invoice ID plus a version, for example `sf-a0B5g00000XyZ12-v1`.\n- Scope: tenant and endpoint, not the individual API key. Records are kept 24 hours.\n- Reuse the same key **and** the same payload on every retry. A replay returns the original `202` with `Idempotency-Replayed: true` and no second charge.\n- **One key, one task.** Once an upload is accepted, every retry with the same key and payload returns that task: the same `task_id` and the same `202` body. This is also true when you did not receive the first response, or received a `5xx` after the task was accepted. A retry never starts a second task and never reserves or charges a second unit.\n- Requests with the same key run one at a time: the others get `409 IDEMPOTENCY_IN_PROGRESS`. A retry after the task failed returns that failed task; to try again, use a new key.\n- The same key with a different payload: `409 IDEMPOTENCY_CONFLICT`. The first request still running: `409 IDEMPOTENCY_IN_PROGRESS` (retry the same key later). The original task already deleted: `409 IDEMPOTENCY_REPLAY_EXPIRED` (new key).\n- Retrying `429` or a `5xx` with the same key is safe: those responses do not block the key. A retry with the same key never charges twice: when a task was already accepted, it returns that task; otherwise it runs the upload again. A `5xx` alone does not tell whether a task was accepted, so always retry with the same key.\n\n## Limits, polling, and bursts\n\n**Rate limits** are per API key, one bucket per endpoint (table in *Overview*), in fixed calendar-minute and calendar-hour windows. A refused request does not count. `429 RATE_LIMITED` carries `Retry-After`, `X-RateLimit-Limit-Minute`, `X-RateLimit-Limit-Hour`, and `details.minute_count`, `hour_count`, `limit_minute`, `limit_hour`. Successful responses carry no quota headers.\n\n**Polling.** First status call about 20 s after the `202`, then after 20, 30, 45, and 60 s, then every 60 s. Stop on `completed` or `failed`. Most conversions finish within two minutes. The server fails a task after 5 minutes without progress or 15 minutes in total, so set your client timeout to about 16 minutes.\n\n**Size.** The two upload paths at `www.invoice-converter.com` route directly to the backend, without a Vercel Function. Default limits: source `file` or carrier `pdf_file` ≤ 20,000,000 bytes (20 MB); `data_file` parts ≤ 2,000,000 bytes (2 MB) total. Whole multipart bodies allow 1,000,000 bytes of overhead: 21 MB for document uploads, 23 MB for structured uploads. At most 20 file parts and 50 text fields (`400 INVALID_UPLOAD`). Exceeding a file or body limit returns JSON `413 PAYLOAD_TOO_LARGE` with `details.limit_bytes`. Authentication runs before body admission. Infrastructure failures can still return a non-JSON response.\n\n**Bursts** (for example hundreds of recurring invoices on the first of the month): accepted tasks wait in a shared processing queue. API uploads collectively use at most half its configured slots per backend process, rounded down. The default eight-slot queue admits four API tasks and leaves four slots for web or other channels. This protects admission capacity; it does not promise processing speed or priority. A full queue or API share returns `503 SERVER_BUSY` with `Retry-After: 15` before consuming a conversion rate slot or reserving a unit. Accepted-task replays do not need another queue slot. Recommended client pattern:\n\n1. Keep a client-side queue with about 2–4 conversions in flight; adapt to `SERVER_BUSY`.\n2. On `429` and `503 SERVER_BUSY`, wait `Retry-After`, then retry with the **same** `Idempotency-Key`.\n3. Poll each task with the backoff above; start the next conversion when one finishes. V1 has no completion webhook, batch, or task-list endpoint.\n\n## Errors\n\nEvery JSON error has `code`, `message`, `correlation_id`, and usually `details`. Branch on `code`; for `500 TASK_FAILED` also on `details.code` and `details.retryable`. `details.type` is usually present, but not always. Never branch on the HTTP status or `message` alone.\n\nThe complete catalog (every code with HTTP status, retry rule, and action) is `ErrorEnvelope.code` in the OpenAPI reference. The codes you meet most:\n\n| Code | HTTP | Retry? | Action |\n|---|---|---|---|\n| `AUTHENTICATION_REQUIRED`, `INVALID_API_KEY` | 401 | no | Fix the key. |\n| `ACCOUNT_DELETED` | 410 | no | The account of this key was deleted. The deletion is permanent. |\n| `IDEMPOTENCY_KEY_REQUIRED`, `INVALID_IDEMPOTENCY_KEY` | 400 | no | Send a valid `Idempotency-Key`. |\n| `FORMAT_REQUIRED` / `INVALID_FORMAT` | 400 / 422 | no | Send a supported `format`. |\n| `OUTPUT_PROFILE_CONFLICT`, `INVALID_PROFILE` | 422 | no | Use a profile from the table or omit it. |\n| `INVALID_UPLOAD` | 400 / 415 | no | Fix the multipart body, file type, or split-export invoice numbers. |\n| `FUNCTION_PAYLOAD_TOO_LARGE` (plain text) / `PAYLOAD_TOO_LARGE` | 413 | no | Send a smaller request. |\n| `INSUFFICIENT_API_CREDITS` | 402 | no | Buy credits or wait for the next month. |\n| `IDEMPOTENCY_IN_PROGRESS` | 409 | same key | Retry after a short delay. |\n| `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED` | 409 | no | Use a new key. |\n| `RATE_LIMITED` | 429 | same key | Wait `Retry-After`. |\n| `SERVER_BUSY` | 503 | same key | Processing queue full. Wait `Retry-After`. |\n| `UPLOAD_FAILED` | 503 / 500 | same key | The upload was not accepted, or it was accepted but its first response could not be rebuilt. Retry with backoff and the same key. |\n| `UPLOAD_FAILED` | 422 | no | Invalid `jurisdiction`, `transaction_scope`, or `delivery_channel`. |\n| `TASK_NOT_READY` | 202 | poll | Keep polling status. |\n| `VALIDATION_FAILED` | 422 | no | Correct the data (`details.items`), then convert again. |\n| `TASK_FAILED` | 500 | if `details.retryable` | Read `details.code`. Retryable: new conversion with a new key. |\n| `AUTHORITATIVE_VALIDATION_UNAVAILABLE` | 503 | yes | Retry the same download later. |\n| `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 503 | new task | Start a new conversion. |\n| `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 | no | Escalate with the correlation ID. |\n| `TASK_NOT_FOUND` | 404 | no | Unknown task, another tenant's task, or deleted after 24 h. |\n| `PROXY_ERROR` | 502 / 504 | same key | Retry with backoff. |\n\n`500 TASK_FAILED` reasons in `details.code`: `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `SCHEMA_PARSE_FAILED`, `ARTIFACT_PARITY_FAILED` (terminal); `SOURCE_TEXT_UNAVAILABLE`, `PROVIDER_ERROR` (follow `details.retryable`). A failed task stays failed: recover only with a new conversion and a new key.\n\n## Results, proofs, and the validation report\n\n- `/result` is pure retrieval. It returns `200` only for a stored artifact with a current validation proof.\n- Record the response headers: `X-Correlation-ID`, `X-Artifact-Sha256` (hash of the delivered bytes), `X-Validation-Proof-Id`, `X-Artifact-State` (`compliant`), `X-Validation-State` (`passed`).\n- `/validation-report?download=html|xml` (required parameter) returns the report bound to the delivered artifact: the KoSIT report, or for Factur-X a `validation-evidence` XML with `source=\"facturx_php\"`. Factur-X evidence proves the stored XML validation only, not source fidelity or PDF/A conformance. On this endpoint `X-Artifact-Sha256` is the hash of the validated result artifact, not of the report. No report for the current artifact: `404 VALIDATION_REPORT_NOT_FOUND`.\n- `result_artifacts..state` on task status: `cached`, `not_ready`, `validation_failed`, `dependency_failed`, `artifact_generation_rerun_required`, `artifact_invariant_failed`.\n\n## Retention, billing, and archiving\n\n- **Retention.** Tasks, artifacts, and idempotency records are deleted 24 hours after the task finishes. After that, every task endpoint returns `404 TASK_NOT_FOUND`. Quality-assurance evidence follows the retention schedule in section 9 of the [Data Processing Agreement](https://www.invoice-converter.com/en/dpa).\n- **Billing.** Each accepted conversion uses one unit. Enterprise includes 100 units per calendar month, shared with Email Import. Further units use prepaid credits: 100 for EUR 50, 200 for EUR 100, 500 for EUR 250, 1,000 for EUR 400. Replays, failed conversions, and all task calls are free. When nothing covers a unit: `402 INSUFFICIENT_API_CREDITS` (two `details` shapes, see the OpenAPI `PaymentRequired` response).\n- **Archiving.** Build your archive package during the flow, not later: original PDF, generated XML or hybrid PDF, validation report, and a metadata record with `task_id`, `client_reference`, format/profile, `X-Artifact-Sha256`, `X-Validation-Proof-Id`, `X-Validation-Report-Proof-Id`, `created_at`/`completed_at`, and correlation IDs.\n\n## Support and contract\n\n- Contact: `contact@invoice-converter.com`. Quote the `X-Correlation-ID`.\n- The API is provided under the standard Terms and DPA and any Enterprise order form. No uptime, processing-time, or support SLA applies unless an order form says so.\n- Poor source documents and edge cases need human review. Keep your own process for exceptions, correction, delivery, and archiving.\n- API access is for your own business use. Resale, white-label, or service-bureau use needs a partner agreement.\n\n## Reference artifacts\n\n- OpenAPI 3.1: \n- Postman collection: (set `base_url`, `api_key`, `idempotency_key`)\n- Structured invoice JSON Schema and example: see *Structured invoice data*\n- Email invoice channel: \n- This documentation as Markdown (for LLMs and offline reading): \n", "contact": { "name": "Invoice Converter support", "email": "contact@invoice-converter.com", "url": "https://www.invoice-converter.com/en/developer-api" } }, "servers": [ { "url": "https://www.invoice-converter.com/api/v1", "description": "Production" } ], "security": [ { "HTTPBearer": [] } ], "tags": [ { "name": "Conversion", "description": "Start an asynchronous conversion. Each accepted request uses one billing unit; idempotent replays and failed conversions do not.", "x-displayName": "Conversion" }, { "name": "Tasks", "description": "Poll task status and download the validated result and its validation report. These calls are free but rate-limited.", "x-displayName": "Tasks" } ], "paths": { "/invoices:convert": { "post": { "tags": [ "Conversion" ], "summary": "Convert an invoice document", "operationId": "convertInvoice", "description": "Upload one invoice document and start a strict conversion.\n\n- `file`: `.pdf`, `.docx`, or `.txt`, one invoice per file. Source file ≤ 20 MB (20,000,000 bytes); whole multipart body ≤ 21 MB.\n- `format` is required; `profile` is optional (default per format below).\n- Embedded XML in a PDF is ignored unless `use_embedded_xml=true`.\n- Rate limit: 30/min and 500/h per API key.\n\n| `format` | Accepted `profile` | Default | `download=xml` | `download=pdf` |\n|---|---|---|---|---|\n| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | rendered PDF (best effort) |\n| `EN16931` | `EN16931` | `EN16931` | UBL | rendered PDF (best effort) |\n| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | rendered PDF (best effort) |\n| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | rendered PDF (best effort) |\n| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hybrid ZUGFeRD/Factur-X PDF |", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ConvertInvoiceRequest" }, "encoding": { "file": { "contentType": "application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/plain" }, "seller_master_data": { "contentType": "application/json" } } } } }, "responses": { "202": { "description": "Accepted. Poll `status_url`. A retry with the same Idempotency-Key and the same payload returns the task that was already accepted: the same task_id and the same 202 body, with the header Idempotency-Replayed: true. This is also true when the first response was lost or was a 5xx after the task was accepted, and after the task failed. It never starts a second task and never reserves or charges a second unit.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertAcceptedResponse" }, "example": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending", "message": "PDF accepted. Strict conversion started.", "filename": "invoice.pdf", "file_size": 245832, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "client_reference": "ERP-2026-0001", "source_system": "salesforce" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowedConversionPath" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UploadFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ConvertServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } }, "/invoices:convert-structured": { "post": { "tags": [ "Conversion" ], "summary": "Convert structured invoice data", "operationId": "convertStructuredInvoice", "description": "Convert invoice data from your system. `data_file` is the only data source; `pdf_file` is only the carrier (embedded for ZUGFeRD, stored as the original PDF otherwise).\n\n- **Deterministic:** one JSON `data_file` in the `StructuredInvoiceData` shape, consistent canonical JSON parts, or one UBL 2.1 Invoice / CII D16B XML file maps without AI ([schema](https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json), [example](https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json)).\n- **Interpreted:** CSV, XLSX, TXT, other XML, custom JSON, and mixed-format parts use AI mapping, which leaves missing fields empty.\n- Split exports: repeat `data_file`; all parts need the same invoice number. Columns such as `Invoice Number`, `Rechnungsnr`, `invoiceNumber`, and `Invoice_Number__c` are recognized; canonical JSON uses `ID`.\n- Canonical JSON: unknown fields return `400 INVALID_UPLOAD` with `details.unknown_paths`; conflicting bundle values return `details.reason=canonical_bundle_conflict` and `details.path`. Lines require unique explicit `InvoiceLine[].ID` values within each part.\n- Limits: `pdf_file` ≤ 20 MB, `data_file` parts ≤ 2 MB total, whole multipart body ≤ 23 MB. Rate limit: 30/min and 500/h per API key.\n- `format` and `profile` rules are the same as for `POST /invoices:convert`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ConvertStructuredInvoiceRequest" }, "encoding": { "pdf_file": { "contentType": "application/pdf" }, "data_file": { "contentType": "application/json, text/csv, application/xml, text/xml, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/plain" }, "seller_master_data": { "contentType": "application/json" } } } } }, "responses": { "202": { "description": "Accepted. Poll `status_url`. A retry with the same Idempotency-Key and the same payload returns the task that was already accepted: the same task_id and the same 202 body, with the header Idempotency-Replayed: true. This is also true when the first response was lost or was a 5xx after the task was accepted, and after the task failed. It never starts a second task and never reserves or charges a second unit.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertAcceptedResponse" }, "example": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending", "message": "PDF and structured data accepted. Strict conversion started.", "filename": "invoice.pdf", "pdf_filename": "invoice.pdf", "data_filename": "invoice.json", "data_filenames": [ "invoice.json" ], "data_file_count": 1, "file_size": 249832, "pdf_file_size": 245832, "data_file_size": 4000, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "client_reference": "ERP-2026-0001", "source_system": "salesforce" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowedConversionPath" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UploadFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ConvertServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } }, "/tasks/{task_id}": { "get": { "tags": [ "Tasks" ], "summary": "Get task status", "operationId": "getTaskStatus", "description": "Return the task state. Poll until `status` is `completed` or `failed`.\n\n- Backoff: first call ~20 s after the `202`, then 20, 30, 45, 60 s, then every 60 s. Stop after ~16 min.\n- `completed`: download from `primary_result_url`. `failed`: call `/result` for the typed error.\n- Unknown task, or more than 24 h after completion: `404 TASK_NOT_FOUND`.\n- Rate limit: 60/min and 1,500/h per API key.", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" }, { "$ref": "#/components/parameters/IncludeValidationReportHtmlQuery" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "responses": { "200": { "description": "Current task state.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStatusResponse" }, "examples": { "pending": { "summary": "Queued", "value": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending", "progress": 0, "created_at": "2026-09-30T08:00:00+00:00", "completed_at": null, "filename": "invoice.pdf", "error": null, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "client_reference": "ERP-2026-0001", "source_system": "salesforce", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "result_artifacts": { "xml": { "state": "not_ready", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml" }, "pdf": { "state": "not_ready", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=pdf" } } } }, "completed": { "summary": "Completed", "value": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "progress": 100, "created_at": "2026-09-30T08:00:00+00:00", "completed_at": "2026-09-30T08:01:12+00:00", "filename": "invoice.pdf", "error": null, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "client_reference": "ERP-2026-0001", "source_system": "salesforce", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "result_artifacts": { "xml": { "state": "cached", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "content_type": "application/xml", "filename": "invoice.xml", "bytes": 18572, "artifact_state": "compliant", "validation_state": "passed" }, "pdf": { "state": "cached", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=pdf", "content_type": "application/pdf", "filename": "invoice.pdf", "bytes": 245832, "artifact_state": "compliant", "validation_state": "passed" } } } }, "failed": { "summary": "Failed (call /result for the typed error)", "value": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "failed", "progress": 100, "created_at": "2026-09-30T08:00:00+00:00", "completed_at": "2026-09-30T08:00:41+00:00", "filename": "invoice.pdf", "error": { "code": "MULTIPLE_INVOICES_IN_DOCUMENT", "classification": "multiple_invoices", "message": "Document contains multiple invoices", "category": "extraction", "retryable": false, "can_review": false, "recovery_hint": "Split the PDF into one file per invoice and start a separate conversion for each invoice." }, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "client_reference": "ERP-2026-0001", "source_system": "salesforce", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "result_artifacts": { "xml": { "state": "validation_failed", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml" }, "pdf": { "state": "validation_failed", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=pdf" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TaskNotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowedTaskPath" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } }, "/tasks/{task_id}/result": { "get": { "tags": [ "Tasks" ], "summary": "Download the result", "operationId": "getTaskResult", "description": "Download the validated artifact. Pure retrieval: nothing is generated, repaired, or validated on this call.\n\n- `download=xml`: UBL (`XRECHNUNG`, `EN16931`, `UBL`) or CII (`CII`, `ZUGFERD`). Always the primary artifact for XML formats.\n- `download=pdf`: hybrid ZUGFeRD/Factur-X PDF for `ZUGFERD`; a best-effort rendering for the other formats.\n- While processing: `202 TASK_NOT_READY`. Failed task: its typed error (`422 VALIDATION_FAILED`, `500 TASK_FAILED`, `503 ...`).\n- Rate limit: 60/min and 1,000/h per API key.", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" }, { "$ref": "#/components/parameters/DownloadQuery" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "responses": { "200": { "description": "The artifact bytes. The `X-*` headers describe the delivered bytes; record them for your archive.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" }, "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" }, "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "X-Artifact-Sha256": { "$ref": "#/components/headers/XArtifactSha256" }, "X-Validation-Proof-Id": { "$ref": "#/components/headers/XValidationProofId" }, "X-Artifact-Proof-Id": { "$ref": "#/components/headers/XArtifactProofId" }, "X-Artifact-State": { "$ref": "#/components/headers/XArtifactState" }, "X-Validation-State": { "$ref": "#/components/headers/XValidationState" }, "X-Proof-Status": { "$ref": "#/components/headers/XProofStatus" }, "X-Validator-Bundle-Id": { "$ref": "#/components/headers/XValidatorBundleId" } }, "content": { "application/xml": { "schema": { "type": "string" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "202": { "$ref": "#/components/responses/TaskNotReady" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TaskResultNotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowedTaskPath" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } }, "/tasks/{task_id}/validation-report": { "get": { "tags": [ "Tasks" ], "summary": "Download the validation report", "operationId": "getTaskValidationReport", "description": "Download the validation report bound to the delivered artifact.\n\n- `download=html` for people; `download=xml` for the KoSIT report, or Factur-X `validation-evidence` XML (`source=\"facturx_php\"`, not KoSIT format).\n- The `X-Artifact-*` headers describe the validated result artifact, not the report bytes.\n- Factur-X evidence proves stored XML validation only, not source fidelity or PDF/A conformance.\n- Rate limit: 30/min and 500/h per API key.", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" }, { "$ref": "#/components/parameters/ValidationReportDownloadQuery" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "responses": { "200": { "description": "The report.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" }, "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" }, "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "X-Artifact-Sha256": { "description": "SHA-256 of the validated result artifact (named by `X-Report-Source-Artifact-Format`), not of the report bytes. Do not checksum the report with it.", "schema": { "type": "string" } }, "X-Validation-Proof-Id": { "$ref": "#/components/headers/XValidationProofId" }, "X-Artifact-Proof-Id": { "$ref": "#/components/headers/XArtifactProofId" }, "X-Artifact-State": { "$ref": "#/components/headers/XArtifactState" }, "X-Validation-State": { "$ref": "#/components/headers/XValidationState" }, "X-Proof-Status": { "$ref": "#/components/headers/XProofStatus" }, "X-Validator-Bundle-Id": { "$ref": "#/components/headers/XValidatorBundleId" }, "X-Task-Id": { "description": "Task of the report.", "schema": { "type": "string", "format": "uuid" } }, "X-Validation-Report-Proof-Id": { "description": "Proof record that supplied the report. Equals `X-Validation-Proof-Id` for XML artifacts.", "schema": { "type": "string" } }, "X-Validation-Report-Content-Type": { "description": "Media type of the report.", "schema": { "type": "string" } }, "X-Validation-Report-Format": { "description": "Returned report format.", "schema": { "type": "string", "enum": [ "html", "xml" ] } }, "X-Validation-Report-Source": { "description": "Where the report came from, for example `artifact`, `embedded_xml`, or `source_xml`.", "schema": { "type": "string" } }, "X-Report-Source-Artifact-Format": { "description": "Result artifact the report is bound to.", "schema": { "type": "string", "enum": [ "xml", "pdf" ] } } }, "content": { "text/html": { "schema": { "type": "string" } }, "application/xml": { "schema": { "type": "string" } } } }, "202": { "$ref": "#/components/responses/TaskNotReady" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ValidationReportNotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowedTaskPath" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } } }, "components": { "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "icp_... API key", "description": "Live API key (`icp_...`) from the profile page. Keep it server-side. Missing → `401 AUTHENTICATION_REQUIRED`; unknown or revoked → `401 INVALID_API_KEY`." } }, "parameters": { "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required on both POST endpoints. Reuse the same key with the same payload on every retry; a replay returns the original `202` without a second charge. Scope: tenant + endpoint, kept 24 h. Missing → `400 IDEMPOTENCY_KEY_REQUIRED`; malformed → `400 INVALID_IDEMPOTENCY_KEY`; same key with another payload → `409 IDEMPOTENCY_CONFLICT`.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$" }, "example": "sf-a0B5g00000XyZ12-v1" }, "XCorrelationIdHeader": { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "Optional UUID for tracing. A missing or non-UUID value is replaced by a server-generated UUID. Returned in the `X-Correlation-ID` response header; quote it to support.", "schema": { "type": "string", "format": "uuid" } }, "TaskIdPath": { "name": "task_id", "in": "path", "required": true, "description": "`task_id` from the `202` response. Not a UUID → `400 BAD_REQUEST`.", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "DownloadQuery": { "name": "download", "in": "query", "required": true, "description": "Artifact to download (case-insensitive). Missing → `400 DOWNLOAD_FORMAT_REQUIRED`; other values → `400 INVALID_DOWNLOAD_FORMAT`.", "schema": { "type": "string", "enum": [ "xml", "pdf" ] }, "example": "xml" }, "ValidationReportDownloadQuery": { "name": "download", "in": "query", "required": true, "description": "`html` for a readable report, `xml` for the machine-readable report. Missing → `400 DOWNLOAD_FORMAT_REQUIRED`; other values → `400 INVALID_DOWNLOAD_FORMAT`.", "schema": { "type": "string", "enum": [ "html", "xml" ] }, "example": "html" }, "IncludeValidationReportHtmlQuery": { "name": "include_validation_report_html", "in": "query", "required": false, "description": "`true` adds the sanitized validation report HTML as `validation_report_html`. Other values than `true`/`false` → `400 INVALID_QUERY_PARAMETER`.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } }, "headers": { "XCorrelationId": { "description": "Trace ID of this request. Log it and quote it to support.", "schema": { "type": "string", "format": "uuid" } }, "IdempotencyReplayed": { "description": "`true` when the response is a replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "RetryAfter": { "description": "Seconds to wait before the next attempt. Sent on 429 and on 503 SERVER_BUSY.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitLimitMinute": { "description": "Per-minute limit of this endpoint bucket. Sent on 429 only.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitLimitHour": { "description": "Per-hour limit of this endpoint bucket. Sent on 429 only.", "schema": { "type": "integer", "minimum": 1 } }, "ContentDisposition": { "description": "Attachment filename, for example `attachment; filename=invoice.xml`.", "schema": { "type": "string" } }, "CacheControlNoStore": { "description": "Always `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ] } }, "XArtifactSha256": { "description": "SHA-256 of the delivered artifact bytes.", "schema": { "type": "string" } }, "XValidationProofId": { "description": "Proof record that binds the artifact to its validation run.", "schema": { "type": "string" } }, "XArtifactProofId": { "description": "Artifact-level proof record.", "schema": { "type": "string" } }, "XArtifactState": { "description": "Compliance standing of the artifact. Always `compliant` on a delivered API artifact.", "schema": { "type": "string", "enum": [ "compliant", "warning_only", "cannot_guarantee", "blocked" ] } }, "XValidationState": { "description": "Validation outcome. Always `passed` on a delivered API artifact.", "schema": { "type": "string", "enum": [ "passed", "failed_overridable", "failed_blocking", "not_validated" ] } }, "XProofStatus": { "description": "Freshness of the proof.", "schema": { "type": "string" } }, "XValidatorBundleId": { "description": "Validator rule pack used for the proof.", "schema": { "type": "string" } }, "AllowConversionPath": { "description": "Allowed methods.", "schema": { "type": "string", "enum": [ "POST, OPTIONS" ] } }, "AllowTaskPath": { "description": "Allowed methods.", "schema": { "type": "string", "enum": [ "GET, OPTIONS" ] } } }, "responses": { "BadRequest": { "description": "Invalid request. Not retryable: fix the request. See `ErrorEnvelope.code` for all 400 codes.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "idempotencyKeyRequired": { "summary": "Missing Idempotency-Key", "value": { "code": "IDEMPOTENCY_KEY_REQUIRED", "message": "Idempotency-Key header is required for write endpoints", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "downloadRequired": { "summary": "Missing download parameter", "value": { "code": "DOWNLOAD_FORMAT_REQUIRED", "message": "download query parameter is required. Supported values: xml, pdf.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "field": "download" } } }, "bundleInvoiceIdMismatch": { "summary": "Split data_file parts carry different invoice numbers", "value": { "code": "INVALID_UPLOAD", "message": "Structured data bundle contains multiple invoice IDs", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "reason": "bundle_invoice_id_mismatch", "invoice_ids": [ "INV-HEADER", "INV-LINE" ], "files": { "invoice-header.xlsx": [ "INV-HEADER" ], "invoice-lines.xlsx": [ "INV-LINE" ] } } } }, "badTaskId": { "summary": "task_id is not a UUID", "value": { "code": "BAD_REQUEST", "message": "task_id must be a valid UUID", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "Unauthorized": { "description": "Authentication failed. Not retryable.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "WWW-Authenticate": { "description": "Always `Bearer`.", "schema": { "type": "string", "enum": [ "Bearer" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missingToken": { "summary": "No bearer token", "value": { "code": "AUTHENTICATION_REQUIRED", "message": "Authorization bearer token is required", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "invalidKey": { "summary": "Unknown or revoked key", "value": { "code": "INVALID_API_KEY", "message": "Invalid API key", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "PaymentRequired": { "description": "`402 INSUFFICIENT_API_CREDITS`. Not retryable: buy a prepaid credit package or wait for the next monthly allowance. Two `details` shapes; read the keys that are present.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError" }, { "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError" } ] }, "examples": { "prepaidOnly": { "summary": "Prepaid-only account without credits", "value": { "code": "INSUFFICIENT_API_CREDITS", "message": "Prepaid API credits are required for External API conversions", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "context", "remaining": 0, "minimum_purchase": 100 } } }, "allowanceExhausted": { "summary": "Included allowance and credits used up", "value": { "code": "INSUFFICIENT_API_CREDITS", "message": "Included API allowance is exhausted and prepaid API credits are required", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "context", "included_remaining": 0, "credit_remaining": 0, "shortfall": 1, "minimum_purchase": 100 } } } } } } }, "Forbidden": { "description": "`403 API_NOT_ENABLED_FOR_TENANT`. Not retryable: contact support.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notEnabled": { "summary": "No API access", "value": { "code": "API_NOT_ENABLED_FOR_TENANT", "message": "External API is not enabled", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "MethodNotAllowedConversionPath": { "description": "`405 METHOD_NOT_ALLOWED`: conversion paths accept POST; OPTIONS returns 204. The backend returns a JSON error with `correlation_id` for unsupported methods. HEAD returns no body.", "headers": { "Allow": { "$ref": "#/components/headers/AllowConversionPath" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeError" }, "example": { "code": "METHOD_NOT_ALLOWED", "message": "Use POST for this endpoint." } } } }, "MethodNotAllowedTaskPath": { "description": "`405 METHOD_NOT_ALLOWED`: task paths accept GET only. Sent by the edge proxy, so the body has no `correlation_id`.", "headers": { "Allow": { "$ref": "#/components/headers/AllowTaskPath" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeError" }, "example": { "code": "METHOD_NOT_ALLOWED", "message": "Use GET for this endpoint." } } } }, "Conflict": { "description": "Idempotency conflict. `IDEMPOTENCY_IN_PROGRESS`: retry the same key after a short delay (a stuck claim is released after 15 min). `IDEMPOTENCY_CONFLICT` and `IDEMPOTENCY_REPLAY_EXPIRED`: use a new key.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "inProgress": { "summary": "Retry the same key later", "value": { "code": "IDEMPOTENCY_IN_PROGRESS", "message": "Request with this idempotency key is already being processed", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "idempotency_in_progress", "state": "in_progress" } } }, "conflict": { "summary": "Same key, different payload", "value": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency key was already used with a different payload", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "idempotency_conflict", "reason": "different_payload_for_same_key" } } }, "replayExpired": { "summary": "Original task past retention", "value": { "code": "IDEMPOTENCY_REPLAY_EXPIRED", "message": "The original conversion task for this idempotency key is no longer available. Start a new conversion with a new Idempotency-Key.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "context", "reason": "task_expired_or_removed", "task_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "PayloadTooLarge": { "description": "Request too large. Not retryable: send a smaller request. Uploads route directly to the backend. File and multipart body limits return JSON `413 PAYLOAD_TOO_LARGE` with `details.limit_bytes`. Default limits: source or carrier file 20 MB, structured data parts 2 MB total; whole multipart body 21 MB for document uploads or 23 MB for structured uploads (including 1 MB overhead).", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "code": "PAYLOAD_TOO_LARGE", "message": "Uploaded data_file payload exceeds max allowed total size (2000000 bytes)", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "limit_bytes": 2000000, "received_bytes": 2150000 } } }, "text/plain": { "schema": { "type": "string" }, "example": "Request Entity Too Large\n\nFUNCTION_PAYLOAD_TOO_LARGE" } } }, "UnsupportedMediaType": { "description": "`415 INVALID_UPLOAD`: send `multipart/form-data`. Not retryable.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notMultipart": { "summary": "JSON body instead of multipart", "value": { "code": "INVALID_UPLOAD", "message": "Unable to parse multipart request body. Send multipart/form-data with a file field named 'file'.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "expected_content_type": "multipart/form-data", "required_file_field": "file", "received_content_type": "application/json", "docs_url": "https://www.invoice-converter.com/en/developer-api" } } } } } } }, "UploadFailed": { "description": "Upload or request option validation failed. Not retryable: correct the request. Codes: `INVALID_FORMAT`, `INVALID_PROFILE`, `OUTPUT_PROFILE_CONFLICT`, `OUTPUT_PROFILE_REQUIRED`, `UPLOAD_FAILED` (invalid context value), `ZUGFERD_SOURCE_PDF_REQUIRED`.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalidProfile": { "summary": "Unknown profile name", "value": { "code": "INVALID_PROFILE", "message": "Invalid profile.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "profile": "XRECHNUNG_2024", "allowed_profiles": [ "EN16931", "PEPPOL", "XRECHNUNG", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ] } } }, "invalidContext": { "summary": "Unknown delivery_channel", "value": { "code": "UPLOAD_FAILED", "message": "Invalid delivery_channel. Allowed values: DIRECT_XML, EMAIL_PDF, PEPPOL, PORTAL, UNKNOWN.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "zugferdNeedsPdf": { "summary": "format=ZUGFERD with a DOCX/TXT source", "value": { "code": "ZUGFERD_SOURCE_PDF_REQUIRED", "message": "ZUGFeRD PDF output requires a PDF source upload. Upload a PDF source or request CII, EN16931, UBL, or XRechnung XML output for DOCX/TXT input.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "field": "file", "format": "ZUGFERD", "reason": "source_document_is_not_pdf", "received_source_format": "docx", "required_source_format": "pdf", "xml_only_formats": [ "CII", "EN16931", "UBL", "XRECHNUNG" ] } } } } } } }, "TooManyRequests": { "description": "`429 RATE_LIMITED`. Retryable: wait `Retry-After` seconds and retry with the same Idempotency-Key. Limits are per API key and endpoint, in fixed calendar-minute and calendar-hour windows. Refused requests do not count.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/XRateLimitLimitMinute" }, "X-RateLimit-Limit-Hour": { "$ref": "#/components/headers/XRateLimitLimitHour" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rateLimited": { "summary": "Minute bucket of the convert endpoint exhausted", "value": { "code": "RATE_LIMITED", "message": "Rate limit exceeded", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "rate_limit", "minute_count": 30, "hour_count": 212, "limit_minute": 30, "limit_hour": 500 } } } } } } }, "ConvertServiceUnavailable": { "description": "Temporarily unavailable. Retry with the same Idempotency-Key. `SERVER_BUSY`: the processing queue is full; wait `Retry-After` seconds. `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `API_CREDIT_SERVICE_UNAVAILABLE`, `UPLOAD_FAILED` (other acceptance failure): retry with backoff.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "serverBusy": { "summary": "Processing queue full (wait Retry-After, same key)", "value": { "code": "SERVER_BUSY", "message": "PDF processing queue is full. Please retry shortly.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "uploadNotAccepted": { "summary": "Upload not accepted (retry with the same key)", "value": { "code": "UPLOAD_FAILED", "message": "Failed to upload invoice", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ServiceUnavailable": { "description": "Temporarily unavailable. Retry with backoff: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Start a NEW conversion instead: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validatorUnavailable": { "summary": "Validator unavailable (retry the download)", "value": { "code": "AUTHORITATIVE_VALIDATION_UNAVAILABLE", "message": "Authoritative validation is temporarily unavailable. Retry later.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "extractionIncomplete": { "summary": "Start a new conversion", "value": { "code": "EXTRACTION_INCOMPLETE_GROUP_FAILURE", "message": "Invoice extraction was incomplete. Start a new conversion to retry.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "dependency", "code": "EXTRACTION_INCOMPLETE_GROUP_FAILURE", "dependency": "parallel_extraction", "stage": "extraction", "retryable": true, "same_task_retryable": false, "recovery": "start_new_conversion", "failed_groups": [ "line_items", "payment" ] } } } } } } }, "InternalError": { "description": "Server-side failure. A 500 is not retryable by default. `TASK_FAILED`: read `details.code`; only `details.retryable: true` allows a retry, and only as a NEW conversion with a new Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: escalate. `UPLOAD_FAILED` on upload: retry with the same key.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "multipleInvoices": { "summary": "Terminal: split the document", "value": { "code": "TASK_FAILED", "message": "The conversion failed before a compliant artifact could be issued.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "code": "MULTIPLE_INVOICES_IN_DOCUMENT", "classification": "multiple_invoices", "message": "Document contains multiple invoices", "category": "extraction", "retryable": false, "can_review": false, "recovery_hint": "Split the PDF into one file per invoice and start a separate conversion for each invoice." } } }, "providerError": { "summary": "Retryable as a new conversion", "value": { "code": "TASK_FAILED", "message": "The conversion failed before a compliant artifact could be issued.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "code": "PROVIDER_ERROR", "message": "Extraction provider timed out", "category": "extraction", "retryable": true, "can_review": false, "recovery_hint": "Retry the extraction. The provider timed out before returning structured data." } } }, "invariantFailed": { "summary": "Escalate", "value": { "code": "INTERNAL_ARTIFACT_INVARIANT_FAILED", "message": "The completed task has no safe stored artifact for the requested download.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ProxyErrorBadGateway": { "description": "`502 PROXY_ERROR`: the edge could not reach the backend. Retry with backoff and the same Idempotency-Key.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "proxyError": { "summary": "Transport failure", "value": { "code": "PROXY_ERROR", "message": "Proxy request failed", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ProxyErrorGatewayTimeout": { "description": "`504 PROXY_ERROR`: the backend did not answer in time. Retry with backoff and the same Idempotency-Key.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "proxyTimeout": { "summary": "Transport timeout", "value": { "code": "PROXY_ERROR", "message": "Upstream timeout", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "TaskNotReady": { "description": "`202 TASK_NOT_READY`: still processing. The body is an error envelope, not a file. Keep polling task status.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notReady": { "summary": "Still processing", "value": { "code": "TASK_NOT_READY", "message": "Strict conversion is still processing. No validated artifact is available yet.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "TaskNotFound": { "description": "`404 TASK_NOT_FOUND`: unknown task, another tenant's task, or deleted 24 h after completion. Not retryable.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notFound": { "summary": "Unknown or expired task", "value": { "code": "TASK_NOT_FOUND", "message": "Task not found", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "TaskResultNotFound": { "description": "`404 TASK_NOT_FOUND`: unknown task, another tenant's task, or deleted 24 h after completion. `404 TASK_RESULT_FAILED`: the task exists but its result data is unavailable; escalate with the correlation ID. Not retryable.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notFound": { "summary": "Unknown or expired task", "value": { "code": "TASK_NOT_FOUND", "message": "Task not found", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "resultUnavailable": { "summary": "Result data unavailable", "value": { "code": "TASK_RESULT_FAILED", "message": "Task metadata unavailable for file download", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ValidationReportNotFound": { "description": "`404 TASK_NOT_FOUND` (unknown or expired task) or `404 VALIDATION_REPORT_NOT_FOUND` (no report bound to the current artifact; `details.reason`). Not retryable.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "reportNotFound": { "summary": "No report for the current artifact", "value": { "code": "VALIDATION_REPORT_NOT_FOUND", "message": "No validation report is available for the current validated artifact.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "validation_report", "reason": "proof_not_found" } } }, "taskNotFound": { "summary": "Unknown task", "value": { "code": "TASK_NOT_FOUND", "message": "Task not found", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ValidationFailed": { "description": "The invoice cannot be issued. Not retryable: correct the data and start a new conversion. Codes: `VALIDATION_FAILED` (`details.items`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validationFailed": { "summary": "Missing buyer reference (BT-10) for XRechnung", "value": { "code": "VALIDATION_FAILED", "message": "The conversion failed validation. No compliant artifact was issued.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "validation", "items": [ { "field": "BuyerReference", "rule_id": "BR-DE-15", "severity": "error", "source": "task-result-download", "suggestion": "Provide the buyer reference (BT-10). For a German public-sector recipient, use its Leitweg-ID." } ] } } }, "sourcePdfIncompatible": { "summary": "Source PDF cannot carry the hybrid", "value": { "code": "ZUGFERD_SOURCE_PDF_INCOMPATIBLE", "message": "The source PDF is not compatible with strict ZUGFeRD generation.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "artifact_generation", "stage": "zugferd_pdf_merge", "bridge_status": 422 } } } } } } }, "Gone": { "description": "410 ACCOUNT_DELETED. The API key still authenticates, but its account was deleted. The deletion is permanent, so the response is 410 Gone on every path that reports it. Not retryable. A revoked key returns 401 INVALID_API_KEY instead.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "code": "ACCOUNT_DELETED", "message": "The account for this API key was deleted", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } }, "schemas": { "ConvertInvoiceRequest": { "type": "object", "required": [ "file", "format" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The invoice document: `.pdf`, `.docx`, or `.txt`, one invoice per file. `.doc`, `.rtf`, and images are rejected (`400 INVALID_UPLOAD`). `format=ZUGFERD` needs a PDF (`422 ZUGFERD_SOURCE_PDF_REQUIRED`)." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Target output format. Required; there is no default. Matched case-insensitively. Missing → `400 FORMAT_REQUIRED`; unknown → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Rule set the artifact is validated against. Optional: each `format` has a default (see the operation table). Matched case-insensitively. Aliases: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Not accepted for this format → `422 OUTPUT_PROFILE_CONFLICT`; unknown name → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "ISO 3166-1 alpha-2 country of the transaction, for example `DE`. Optional context. Invalid → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "Optional context hint. Invalid → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "Optional context hint: `EMAIL_PDF` for hybrid PDF delivery, `DIRECT_XML` for direct XML integration, `PEPPOL` for network delivery. Invalid → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Your invoice or job reference. Echoed on the 202 and on task status. No control characters. `external_invoice_id` is accepted as an alias; if both are sent they must match, else `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Label of the calling ERP or billing system. Echoed on the 202 and on task status.", "examples": [ "salesforce" ] }, "use_embedded_xml": { "type": "boolean", "default": false, "description": "Use Factur-X/ZUGFeRD/XRechnung XML embedded in the PDF as the extraction source. Default `false`: the embedded XML is ignored and the visible document is read." }, "email_input": { "type": "string", "maxLength": 10000, "description": "Free-text instructions for the extraction, in any language (PDF source only). Not combinable with `use_embedded_xml=true`. Part of the idempotency identity. Invalid → `400 INVALID_EMAIL_INPUT`.", "examples": [ "Use purchase order number PO-42." ] }, "use_seller_master_data": { "type": "boolean", "description": "Apply seller master data. Omitted: the account default applies. `false`: ignore saved seller data for this request. `true`: apply saved data and `seller_master_data`." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "JSON object string (schema: `SellerMasterData`). Applied only when `use_seller_master_data=true`. Each supplied value replaces the extracted seller or payment value; absent keys leave the invoice unchanged. Invalid → `400 INVALID_SELLER_MASTER_DATA`.", "examples": [ "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}" ] } }, "additionalProperties": false }, "ConvertStructuredInvoiceRequest": { "type": "object", "required": [ "pdf_file", "data_file", "format" ], "properties": { "pdf_file": { "type": "string", "format": "binary", "description": "Carrier PDF. For `ZUGFERD` the validated XML is embedded into it; for XML formats it is stored as the original PDF. It never supplies invoice data." }, "data_file": { "oneOf": [ { "type": "string", "format": "binary" }, { "type": "array", "minItems": 1, "items": { "type": "string", "format": "binary" } } ], "description": "Invoice data: `.json`, `.csv`, `.xml`, `.xlsx`, or `.txt` (≤ 2 MB total). Canonical JSON (top level or wrapped in `invoice_data`), consistent canonical JSON parts, and one UBL 2.1 Invoice / CII D16B XML file map without AI; other formats use AI mapping. Unknown canonical fields and conflicting bundle facts return `400 INVALID_UPLOAD`. Repeat the part for one invoice split across files; all parts need the same invoice number, and canonical lines need unique explicit IDs. Schema: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json. The field names `data_files` and `data_files[]` are accepted as aliases." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Target output format. Required; there is no default. Matched case-insensitively. Missing → `400 FORMAT_REQUIRED`; unknown → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Rule set the artifact is validated against. Optional: each `format` has a default (see the operation table). Matched case-insensitively. Aliases: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Not accepted for this format → `422 OUTPUT_PROFILE_CONFLICT`; unknown name → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "ISO 3166-1 alpha-2 country of the transaction, for example `DE`. Optional context. Invalid → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "Optional context hint. Invalid → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "Optional context hint: `EMAIL_PDF` for hybrid PDF delivery, `DIRECT_XML` for direct XML integration, `PEPPOL` for network delivery. Invalid → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Your invoice or job reference. Echoed on the 202 and on task status. No control characters. `external_invoice_id` is accepted as an alias; if both are sent they must match, else `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Label of the calling ERP or billing system. Echoed on the 202 and on task status.", "examples": [ "salesforce" ] }, "use_seller_master_data": { "type": "boolean", "description": "Apply seller master data. Omitted: the account default applies. `false`: ignore saved seller data for this request. `true`: apply saved data and `seller_master_data`." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "JSON object string (schema: `SellerMasterData`). Applied only when `use_seller_master_data=true`. Each supplied value replaces the extracted seller or payment value; absent keys leave the invoice unchanged. Invalid → `400 INVALID_SELLER_MASTER_DATA`.", "examples": [ "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}" ] } }, "additionalProperties": false }, "StructuredInvoiceData": { "additionalProperties": false, "properties": { "CustomizationID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Customizationid" }, "ProfileID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Profileid" }, "ID": { "title": "Id", "type": "string" }, "IssueDate": { "title": "Issuedate", "type": "string" }, "DueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Duedate" }, "TaxCurrencyCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxcurrencycode" }, "TaxPointDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxpointdate" }, "InvoicePeriod": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod" }, { "type": "null" } ], "default": null }, "InvoiceTypeCode": { "title": "Invoicetypecode", "type": "string" }, "DocumentCurrencyCode": { "title": "Documentcurrencycode", "type": "string" }, "OrderReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_OrderReference" }, { "type": "null" } ], "default": null }, "SalesOrderReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_SalesOrderReference" }, { "type": "null" } ], "default": null }, "ContractDocumentReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_ContractDocumentReference" }, { "type": "null" } ], "default": null }, "ProjectReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_ProjectReference" }, { "type": "null" } ], "default": null }, "TenderOrLotReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TenderOrLotReference" }, { "type": "null" } ], "default": null }, "DespatchDocumentReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Despatchdocumentreference" }, "PrecedingInvoiceReference": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_PrecedingInvoiceReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Precedinginvoicereference" }, "AdditionalDocumentReference": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_AdditionalDocumentReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Additionaldocumentreference" }, "AdvancePaymentSettlement": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_AdvancePaymentSettlementRow" }, "maxItems": 200, "type": "array" }, { "type": "null" } ], "default": null, "title": "Advancepaymentsettlement" }, "AllowanceCharge": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" }, "AccountingSupplierParty": { "$ref": "#/components/schemas/StructuredInvoice_AccountingSupplierParty" }, "AccountingCustomerParty": { "$ref": "#/components/schemas/StructuredInvoice_AccountingCustomerParty" }, "PayeeParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeParty" }, { "type": "null" } ], "default": null }, "TaxRepresentativeParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativeParty" }, { "type": "null" } ], "default": null }, "Delivery": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Delivery" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_Delivery" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Delivery" }, "DeliveryTerms": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryTerms" }, { "type": "null" } ], "default": null }, "PaymentMeans": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Paymentmeans" }, "PaymentTerms": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentTerms" }, { "type": "null" } ], "default": null }, "TaxTotal": { "$ref": "#/components/schemas/StructuredInvoice_TaxTotal" }, "LegalMonetaryTotal": { "$ref": "#/components/schemas/StructuredInvoice_LegalMonetaryTotal" }, "InvoiceLine": { "items": { "$ref": "#/components/schemas/StructuredInvoice_InvoiceLine" }, "title": "Invoiceline", "type": "array" }, "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "BuyerReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Buyerreference" }, "BuyerAccountingReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Buyeraccountingreference" } }, "required": [ "ID", "IssueDate", "InvoiceTypeCode", "DocumentCurrencyCode", "AccountingSupplierParty", "AccountingCustomerParty", "TaxTotal", "LegalMonetaryTotal", "InvoiceLine" ], "title": "Invoice Converter structured invoice JSON", "type": "object", "description": "Canonical invoice JSON for POST /api/v1/invoices:convert-structured. Element names follow UBL 2.1 / EN 16931. Send one invoice as one JSON data_file, either at the top level or wrapped in an 'invoice_data' object; this shape is mapped without AI interpretation. Detection needs at least 3 of the top-level keys ID, IssueDate, InvoiceTypeCode, DocumentCurrencyCode, AccountingSupplierParty, AccountingCustomerParty, TaxTotal, LegalMonetaryTotal, InvoiceLine, including ID, InvoiceLine, or LegalMonetaryTotal. Downloadable: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json", "examples": [ { "ID": "RE-2026-00123", "IssueDate": "2026-09-30", "DueDate": "2026-10-30", "InvoiceTypeCode": "380", "DocumentCurrencyCode": "EUR", "BuyerReference": "04011000-1234512345-06", "OrderReference": { "ID": "PO-4711" }, "InvoicePeriod": { "StartDate": "2026-09-01", "EndDate": "2026-09-30" }, "Note": "Monthly subscription September 2026", "AccountingSupplierParty": { "Party": { "EndpointID": { "#text": "billing@seller.example", "@schemeID": "EM" }, "PartyName": { "Name": "Seller GmbH" }, "PostalAddress": { "StreetName": "Hauptstraße 1", "CityName": "Berlin", "PostalZone": "10115", "Country": { "IdentificationCode": "DE" } }, "PartyTaxScheme": { "CompanyID": "DE123456789", "TaxScheme": { "ID": "VAT" } }, "PartyLegalEntity": { "RegistrationName": "Seller GmbH", "CompanyID": "HRB 12345" }, "Contact": { "Name": "Erika Muster", "Telephone": "+49 30 123456", "ElectronicMail": "erika@seller.example" } } }, "AccountingCustomerParty": { "Party": { "EndpointID": { "#text": "04011000-1234512345-06", "@schemeID": "0204" }, "PartyName": { "Name": "Buyer AG" }, "PostalAddress": { "StreetName": "Marktplatz 5", "CityName": "München", "PostalZone": "80331", "Country": { "IdentificationCode": "DE" } }, "PartyTaxScheme": { "CompanyID": "DE987654321", "TaxScheme": { "ID": "VAT" } }, "PartyLegalEntity": { "RegistrationName": "Buyer AG" } } }, "Delivery": { "ActualDeliveryDate": "2026-09-30", "DeliveryLocation": { "Address": { "StreetName": "Marktplatz 5", "CityName": "München", "PostalZone": "80331", "Country": { "IdentificationCode": "DE" } } } }, "PaymentMeans": { "PaymentMeansCode": "58", "PaymentID": "RE-2026-00123", "PayeeFinancialAccount": { "ID": "DE02120300000000202051", "Name": "Seller GmbH", "FinancialInstitutionBranch": { "ID": "BYLADEM1001" } } }, "PaymentTerms": { "Note": "Zahlbar innerhalb von 30 Tagen ohne Abzug", "NetDays": 30 }, "TaxTotal": { "TaxAmount": "285.00", "TaxSubtotal": [ { "TaxableAmount": "1500.00", "TaxAmount": "285.00", "TaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } } ] }, "LegalMonetaryTotal": { "LineExtensionAmount": "1500.00", "TaxExclusiveAmount": "1500.00", "TaxInclusiveAmount": "1785.00", "PayableAmount": "1785.00" }, "InvoiceLine": [ { "ID": "1", "InvoicedQuantity": 10, "unitCode": "HUR", "LineExtensionAmount": "1200.00", "Item": { "Name": "Consulting", "SellersItemIdentification": { "ID": "SRV-01" }, "ClassifiedTaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } }, "Price": { "PriceAmount": "120.00" } }, { "ID": "2", "InvoicedQuantity": 2, "unitCode": "C62", "LineExtensionAmount": "300.00", "Item": { "Name": "Software licence", "ClassifiedTaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } }, "Price": { "PriceAmount": "150.00" } } ] } ] }, "SellerMasterData": { "type": "object", "description": "Seller defaults sent as the JSON string form field `seller_master_data`. Every key is optional. `electronic_address` and `electronic_address_scheme` are a pair: send both or neither.", "properties": { "business_name": { "type": "string", "maxLength": 240, "description": "Legal name (BT-27)." }, "trading_name": { "type": "string", "maxLength": 240, "description": "Trading name (BT-28)." }, "street": { "type": "string", "description": "Street and number (BT-35)." }, "additional_address": { "type": "string", "description": "Additional address line (BT-36)." }, "postal_code": { "type": "string", "description": "Post code (BT-38)." }, "city": { "type": "string", "description": "City (BT-37)." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (BT-40).", "examples": [ "DE" ] }, "vat_id": { "type": "string", "description": "VAT identifier (BT-31).", "examples": [ "DE123456789" ] }, "tax_number": { "type": "string", "description": "Tax registration number (BT-32)." }, "electronic_address": { "type": "string", "description": "Electronic address (BT-34). Requires `electronic_address_scheme`." }, "electronic_address_scheme": { "type": "string", "description": "EAS scheme of the electronic address, for example `EM` or `0204`." }, "contact_name": { "type": "string", "description": "Contact person (BT-41)." }, "contact_email": { "type": "string", "description": "Contact e-mail (BT-43)." }, "contact_phone": { "type": "string", "description": "Contact telephone (BT-42)." }, "payment_means_code": { "type": "string", "enum": [ "30", "42", "58" ], "description": "Credit transfer payment means code (BT-81): 30 credit transfer, 42 payment to bank account, 58 SEPA credit transfer." }, "payment_iban": { "type": "string", "description": "IBAN of the payee account (BT-84)." }, "payment_bic": { "type": "string", "description": "BIC of the payee bank (BT-86)." }, "payment_account_name": { "type": "string", "description": "Payee account name (BT-85)." }, "payment_terms_note": { "type": "string", "description": "Payment terms text (BT-20)." } }, "additionalProperties": false, "examples": [ { "business_name": "Seller GmbH", "street": "Hauptstraße 1", "postal_code": "10115", "city": "Berlin", "country": "DE", "vat_id": "DE123456789", "electronic_address": "billing@seller.example", "electronic_address_scheme": "EM", "contact_name": "Erika Muster", "contact_email": "erika@seller.example", "contact_phone": "+49 30 123456", "payment_means_code": "58", "payment_iban": "DE02120300000000202051" } ] }, "ConvertAcceptedResponse": { "type": "object", "required": [ "task_id", "status", "correlation_id" ], "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Use it for all task calls." }, "status": { "type": "string", "enum": [ "pending", "processing" ], "description": "`pending`: queued. `processing`: started." }, "message": { "type": "string", "description": "Human-readable confirmation. Do not branch on it." }, "filename": { "type": [ "string", "null" ], "description": "Uploaded document (or carrier PDF) filename." }, "pdf_filename": { "type": [ "string", "null" ], "description": "Carrier PDF filename (structured endpoint)." }, "data_filename": { "type": [ "string", "null" ], "description": "First data file name (structured endpoint)." }, "data_filenames": { "type": "array", "items": { "type": "string" }, "description": "All data file names (structured endpoint)." }, "data_file_count": { "type": "integer", "minimum": 1, "description": "Number of data files (structured endpoint)." }, "file_size": { "type": "integer", "minimum": 0, "description": "Total accepted bytes." }, "pdf_file_size": { "type": "integer", "minimum": 0, "description": "Carrier PDF bytes (structured endpoint)." }, "data_file_size": { "type": "integer", "minimum": 0, "description": "Data file bytes in total (structured endpoint)." }, "correlation_id": { "type": "string", "format": "uuid" }, "status_url": { "type": "string", "description": "Relative URL to poll." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "Usual download for the requested format: `pdf` for ZUGFERD, else `xml`." }, "primary_result_url": { "type": "string", "description": "Relative result URL with `download=`." }, "client_reference": { "type": "string", "description": "Echo of `client_reference`." }, "source_system": { "type": "string", "description": "Echo of `source_system`." } }, "additionalProperties": false }, "TaskStatusResponse": { "type": "object", "required": [ "task_id", "status", "correlation_id" ], "properties": { "task_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "`pending`: queued. `processing`: running. `completed`: a validated artifact exists. `failed`: terminal, no artifact." }, "progress": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100, "description": "Rough progress in percent. Do not use for timing." }, "created_at": { "type": "string", "format": "date-time", "description": "When the task was accepted (UTC)." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the task reached `completed` or `failed` (UTC)." }, "filename": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "object", "null" ], "additionalProperties": true, "description": "Failure summary when `status=failed`: a message or an object with `code`, `message`, `retryable`. Informational; `/result` returns the typed error envelope." }, "correlation_id": { "type": "string", "format": "uuid", "description": "Trace ID of this status call." }, "client_reference": { "type": [ "string", "null" ], "description": "Echo of `client_reference`." }, "source_system": { "type": [ "string", "null" ], "description": "Echo of `source_system`." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "Usual download for the requested format." }, "primary_result_url": { "type": "string", "description": "Relative result URL." }, "result_artifacts": { "$ref": "#/components/schemas/ResultArtifacts" }, "validation_report_html": { "$ref": "#/components/schemas/ValidationReportHtmlStatus" } }, "additionalProperties": false }, "ResultArtifacts": { "type": "object", "description": "Download readiness per artifact.", "properties": { "xml": { "$ref": "#/components/schemas/ResultArtifactStatus" }, "pdf": { "$ref": "#/components/schemas/ResultArtifactStatus" } }, "additionalProperties": false }, "ResultArtifactStatus": { "type": "object", "required": [ "state", "download_url" ], "properties": { "state": { "type": "string", "enum": [ "cached", "not_ready", "validation_failed", "dependency_failed", "artifact_generation_rerun_required", "artifact_invariant_failed" ], "description": "`cached`: downloadable. `not_ready`: not produced yet. `validation_failed`: blocking data or source-PDF issue. `dependency_failed`: validator/storage outage. `artifact_generation_rerun_required`: start a new conversion. `artifact_invariant_failed`: escalate with the correlation ID." }, "download_url": { "type": "string", "description": "Relative download URL." }, "content_type": { "type": "string" }, "filename": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 }, "artifact_state": { "type": "string", "enum": [ "compliant", "warning_only", "cannot_guarantee", "blocked" ], "description": "Compliance standing. `compliant` on every delivered API artifact." }, "validation_state": { "type": "string", "enum": [ "passed", "failed_overridable", "failed_blocking", "not_validated" ], "description": "Validation outcome. `passed` on every delivered API artifact." } }, "additionalProperties": false }, "ValidationReportHtmlStatus": { "type": "object", "description": "Present only with `include_validation_report_html=true`.", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "content_type": { "type": "string", "enum": [ "text/html; charset=utf-8" ] }, "html": { "type": "string", "description": "Sanitized report HTML; server paths are redacted." }, "source": { "type": "string", "description": "For example `artifact`, `embedded_xml`, or `source_xml`." }, "source_result_format": { "type": "string", "enum": [ "xml", "pdf" ] }, "reason": { "type": "string", "description": "Why no report is available, for example `task_not_completed`, `proof_not_found`, `artifact_not_current`." } }, "additionalProperties": false }, "ErrorEnvelope": { "type": "object", "description": "Every JSON error. Branch on `code`; for `500 TASK_FAILED` also on `details.code` and `details.retryable`. Retry a write only with the same Idempotency-Key.", "required": [ "code", "message", "correlation_id" ], "properties": { "code": { "type": "string", "enum": [ "AUTHENTICATION_REQUIRED", "INVALID_API_KEY", "API_NOT_ENABLED_FOR_TENANT", "ACCOUNT_DELETED", "INSUFFICIENT_API_CREDITS", "AUTH_SERVICE_UNAVAILABLE", "PLAN_TIER_CHECK_FAILED", "RATE_LIMIT_SERVICE_UNAVAILABLE", "API_CREDIT_SERVICE_UNAVAILABLE", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_REPLAY_EXPIRED", "FORMAT_REQUIRED", "INVALID_FORMAT", "INVALID_PROFILE", "OUTPUT_PROFILE_CONFLICT", "OUTPUT_PROFILE_REQUIRED", "CLIENT_REFERENCE_CONFLICT", "INVALID_CLIENT_METADATA", "INVALID_SELLER_MASTER_DATA", "INVALID_EMBEDDED_XML_POLICY", "INVALID_EMAIL_INPUT", "INVALID_UPLOAD", "PAYLOAD_TOO_LARGE", "UPLOAD_FAILED", "SERVER_BUSY", "ZUGFERD_SOURCE_PDF_REQUIRED", "METHOD_NOT_ALLOWED", "NOT_FOUND", "BAD_REQUEST", "INVALID_QUERY_PARAMETER", "DOWNLOAD_FORMAT_REQUIRED", "INVALID_DOWNLOAD_FORMAT", "TASK_NOT_READY", "TASK_NOT_FOUND", "TASK_STATUS_FAILED", "TASK_RESULT_FAILED", "TASK_FAILED", "VALIDATION_FAILED", "PROFILE_MISMATCH", "ZUGFERD_SOURCE_PDF_INCOMPATIBLE", "ZUGFERD_CII_CONVERSION_FAILED", "ZUGFERD_PDF_GENERATION_FAILED", "XML_GENERATION_FAILED", "PDF_GENERATION_FAILED", "AUTHORITATIVE_VALIDATION_UNAVAILABLE", "ARTIFACT_GENERATION_RERUN_REQUIRED", "EXTRACTION_INCOMPLETE_GROUP_FAILURE", "INTERNAL_ARTIFACT_INVARIANT_FAILED", "VALIDATION_REPORT_NOT_FOUND", "VALIDATION_REPORT_FAILED", "PROXY_ERROR" ], "x-enumDescriptions": { "AUTHENTICATION_REQUIRED": "401 · no · Send `Authorization: Bearer `.", "INVALID_API_KEY": "401 · no · The key is unknown, revoked, or malformed. Fix or rotate it.", "API_NOT_ENABLED_FOR_TENANT": "403 · no · The key is valid but the account has no External API access. Contact support.", "ACCOUNT_DELETED": "410 · no · The account of this API key was deleted. The deletion is permanent. A revoked key returns `INVALID_API_KEY`.", "INSUFFICIENT_API_CREDITS": "402 · no · Allowance and prepaid credits are used up. Buy a credit package or wait for the next month. Two `details` shapes.", "AUTH_SERVICE_UNAVAILABLE": "503 · yes · Authentication is temporarily unavailable. Retry with backoff and the same Idempotency-Key.", "PLAN_TIER_CHECK_FAILED": "503 · yes · Plan/API access could not be verified. Retry with backoff and the same Idempotency-Key.", "RATE_LIMIT_SERVICE_UNAVAILABLE": "503 · yes · The rate-limit service is unavailable. Retry with backoff and the same Idempotency-Key.", "API_CREDIT_SERVICE_UNAVAILABLE": "503 · yes · Credit/allowance verification is unavailable. Retry the upload with the same Idempotency-Key.", "RATE_LIMITED": "429 · yes · Wait `Retry-After` seconds, then retry with the same Idempotency-Key.", "IDEMPOTENCY_KEY_REQUIRED": "400 · no · Send an `Idempotency-Key` header on both POST endpoints.", "INVALID_IDEMPOTENCY_KEY": "400 · no · Use 1–200 chars matching `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`.", "IDEMPOTENCY_IN_PROGRESS": "409 · yes · The first request with this key is still running. Retry the same key after a short delay.", "IDEMPOTENCY_CONFLICT": "409 · no · The key was used with a different payload. Use a new key for a new payload.", "IDEMPOTENCY_REPLAY_EXPIRED": "409 · no · The original task is past its 24 h retention. Start a new conversion with a new key.", "FORMAT_REQUIRED": "400 · no · Send `format` on every conversion request.", "INVALID_FORMAT": "422 · no · Send one of XRECHNUNG, ZUGFERD, EN16931, UBL, CII.", "INVALID_PROFILE": "422 · no · Unknown profile name. `details.allowed_profiles` lists the accepted values.", "OUTPUT_PROFILE_CONFLICT": "422 · no · The profile is not accepted for this `format`. Send a compatible profile or omit it.", "OUTPUT_PROFILE_REQUIRED": "422 · no · Defensive; V1 defaults a profile for every format, so this is not expected.", "CLIENT_REFERENCE_CONFLICT": "400 · no · `client_reference` and `external_invoice_id` differ. Send one, or the same value in both.", "INVALID_CLIENT_METADATA": "400 · no · Keep `client_reference`/`external_invoice_id` ≤ 200 and `source_system` ≤ 100 chars, without control characters.", "INVALID_SELLER_MASTER_DATA": "400 · no · Send `seller_master_data` as a JSON object string with supported keys; send `electronic_address` and `electronic_address_scheme` together.", "INVALID_EMBEDDED_XML_POLICY": "400 · no · Send `use_embedded_xml` as `true` or `false`, or omit it.", "INVALID_EMAIL_INPUT": "400 · no · Send `email_input` once, ≤ 10,000 chars, PDF source only, not with `use_embedded_xml=true`, never on convert-structured.", "INVALID_UPLOAD": "400/415 · no · Fix the upload: multipart/form-data, supported file type, ≤ 20 file parts and 50 fields, one invoice number across all `data_file` parts (`details.reason`).", "PAYLOAD_TOO_LARGE": "413 · no · A file, the `data_file` total, or the multipart body exceeds its backend limit. Inspect `details.limit_bytes`; send a smaller request.", "UPLOAD_FAILED": "422 · no: invalid `jurisdiction`/`transaction_scope`/`delivery_channel` value. 500/503 · yes: the upload was not accepted, or it was accepted but its first response could not be rebuilt. Retry with backoff and the same Idempotency-Key; the retry returns the accepted task.", "SERVER_BUSY": "503 · yes · The processing queue is full. Wait `Retry-After` seconds (15), then retry with the same Idempotency-Key.", "ZUGFERD_SOURCE_PDF_REQUIRED": "422 · no · `format=ZUGFERD` needs a PDF source. Upload a PDF or choose an XML format.", "METHOD_NOT_ALLOWED": "405 · no · Use POST on conversion paths and GET on task paths (see `Allow`).", "NOT_FOUND": "404 · no · Unknown path under /api/v1.", "BAD_REQUEST": "400 · no · `task_id` must be a UUID.", "INVALID_QUERY_PARAMETER": "400 · no · Send `include_validation_report_html` as `true` or `false`.", "DOWNLOAD_FORMAT_REQUIRED": "400 · no · Send the required `download` query parameter.", "INVALID_DOWNLOAD_FORMAT": "400 · no · Use `download=xml|pdf` on /result and `download=html|xml` on /validation-report.", "TASK_NOT_READY": "202 · poll · The task is still running. Keep polling task status with backoff.", "TASK_NOT_FOUND": "404 · no · Unknown task, another tenant's task, or deleted 24 h after completion. All task endpoints.", "TASK_STATUS_FAILED": "5xx · yes · The status could not be read. Retry the poll with backoff.", "TASK_RESULT_FAILED": "404/5xx · 5xx only · The result could not be read (for example missing task metadata). Retry 5xx with backoff; escalate a 404 with the correlation ID.", "TASK_FAILED": "500 · only if `details.retryable` is true · Read `details.code`. Retryable failures need a NEW conversion with a new Idempotency-Key.", "VALIDATION_FAILED": "422 · no · Blocking validation errors. Correct the data (`details.items`) and start a new conversion.", "PROFILE_MISMATCH": "422 · no · The stored document declares another profile. Start a new conversion with the correct profile.", "ZUGFERD_SOURCE_PDF_INCOMPATIBLE": "422 · no · The source PDF cannot carry a strict PDF/A-3 hybrid. Normalize the PDF or use `download=xml`.", "ZUGFERD_CII_CONVERSION_FAILED": "422/500 · no · Hybrid CII conversion failed. Escalate with the correlation ID.", "ZUGFERD_PDF_GENERATION_FAILED": "500 · no · Hybrid PDF generation failed. Escalate with the correlation ID.", "XML_GENERATION_FAILED": "500 · yes, with backoff · Legacy on-demand generation path; not expected for strict API tasks.", "PDF_GENERATION_FAILED": "500 · yes, with backoff · Legacy on-demand generation path; not expected for strict API tasks.", "AUTHORITATIVE_VALIDATION_UNAVAILABLE": "503 · yes · The validator is temporarily unavailable. Retry the same download later.", "ARTIFACT_GENERATION_RERUN_REQUIRED": "503 · new task · Artifact generation failed after server retries. Start a new conversion.", "EXTRACTION_INCOMPLETE_GROUP_FAILURE": "503 · new task · Extraction groups failed (`details.failed_groups`). Start a new conversion.", "INTERNAL_ARTIFACT_INVARIANT_FAILED": "500 · no · Completed task without a safe stored artifact. Escalate with the correlation ID.", "VALIDATION_REPORT_NOT_FOUND": "404 · no · No report is bound to the current artifact (`details.reason`).", "VALIDATION_REPORT_FAILED": "4xx/5xx · 5xx only · Report retrieval failed. Retry transient 5xx with backoff.", "PROXY_ERROR": "502/504 · yes · Transport failure between edge and backend. Retry with backoff and the same Idempotency-Key." }, "description": "Machine-readable error code. Format of each description: HTTP status · retry? · action." }, "message": { "type": "string", "description": "Human-readable text. Do not parse it." }, "correlation_id": { "type": "string", "format": "uuid", "description": "Quote it to support." }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "additionalProperties": false }, "EdgeError": { "type": "object", "description": "Error sent by the edge proxy before the request reaches the API (`404 NOT_FOUND`, `405 METHOD_NOT_ALLOWED`). No `correlation_id`.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "METHOD_NOT_ALLOWED" ] }, "message": { "type": "string" } } }, "ErrorDetails": { "type": "object", "description": "Structured context. The keys depend on the code; unknown keys can appear. `type` is usually present but not always (for example `{\"field\": \"download\"}`, `INVALID_UPLOAD`, `413`), so branch on the envelope `code`.", "properties": { "type": { "type": "string", "description": "Detail family, for example `validation`, `rate_limit`, `idempotency_conflict`, `idempotency_in_progress`, `profile_mismatch`, `context`, `dependency`, `artifact_generation`, `validation_report`, `message`." }, "code": { "type": "string", "description": "Underlying failure code. On `500 TASK_FAILED` this is the reason; see `x-enumDescriptions`.", "examples": [ "MULTIPLE_INVOICES_IN_DOCUMENT", "NO_INVOICE_DETECTED", "INSUFFICIENT_INVOICE_SIGNAL", "SOURCE_TEXT_UNAVAILABLE", "SCHEMA_PARSE_FAILED", "ARTIFACT_PARITY_FAILED", "PROVIDER_ERROR" ], "x-enumDescriptions": { "MULTIPLE_INVOICES_IN_DOCUMENT": "Terminal. The document holds more than one invoice. Split it and convert each invoice separately.", "NO_INVOICE_DETECTED": "Terminal. The document is not an invoice. Route it to a person.", "INSUFFICIENT_INVOICE_SIGNAL": "Terminal. Too little invoice data. Send a better source or use convert-structured.", "SOURCE_TEXT_UNAVAILABLE": "See `retryable`. false: no readable text (upload a text PDF or a clearer scan). true: OCR was temporarily unavailable; start a new conversion.", "SCHEMA_PARSE_FAILED": "Terminal for this attempt. Start a new conversion; escalate if it repeats.", "ARTIFACT_PARITY_FAILED": "Terminal. The artifact did not match the final invoice data. Escalate with the correlation ID.", "PROVIDER_ERROR": "See `retryable`. true: start a new conversion after a delay. `classification=provider_context_too_large`: send a smaller document." } }, "retryable": { "type": "boolean", "description": "Authoritative where present. `true` on `TASK_FAILED`: start a NEW conversion with a new Idempotency-Key." }, "can_review": { "type": "boolean" }, "classification": { "type": "string", "description": "For example `multiple_invoices`, `not_invoice`, `provider_context_too_large`." }, "category": { "type": "string" }, "recovery_hint": { "type": "string", "description": "Human-readable next step." }, "same_task_retryable": { "type": "boolean", "description": "`false`: the same task cannot recover; start a new conversion." }, "recovery": { "type": "string", "description": "For example `start_new_conversion`." }, "dependency": { "type": "string" }, "stage": { "type": "string" }, "failed_groups": { "type": "array", "items": { "type": "string" }, "description": "Failed extraction groups on `EXTRACTION_INCOMPLETE_GROUP_FAILURE`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationDetail" }, "description": "Blocking issues on `VALIDATION_FAILED`." }, "field": { "type": "string", "description": "Offending request field, for example `download` or `file`." }, "reason": { "type": "string", "description": "Sub-reason, for example `bundle_invoice_id_missing`, `bundle_invoice_id_mismatch`, `different_payload_for_same_key`." }, "profile": { "type": "string" }, "format": { "type": "string" }, "allowed_profiles": { "type": "array", "items": { "type": "string" }, "description": "Accepted profiles on the profile errors." }, "minute_count": { "type": "integer" }, "hour_count": { "type": "integer" }, "limit_minute": { "type": "integer" }, "limit_hour": { "type": "integer" }, "limit_bytes": { "type": "integer", "description": "Size limit on `413 PAYLOAD_TOO_LARGE`." }, "declared_size": { "type": "integer" }, "received_bytes": { "type": "integer" }, "remaining": { "type": "integer" }, "included_remaining": { "type": "integer" }, "credit_remaining": { "type": [ "integer", "null" ] }, "shortfall": { "type": "integer" }, "minimum_purchase": { "type": "integer" }, "bridge_status": { "type": "integer" } }, "additionalProperties": true }, "ValidationDetail": { "type": "object", "description": "One blocking validation issue.", "properties": { "field": { "type": [ "string", "null" ], "description": "Invoice field path, for example `BuyerReference`." }, "rule_id": { "type": [ "string", "null" ], "description": "Rule ID, for example `BR-DE-15`." }, "severity": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "suggestion": { "type": [ "string", "null" ], "description": "What to correct." }, "message": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "InsufficientApiCreditsPrepaidError": { "type": "object", "description": "402 shape for prepaid-only accounts.", "required": [ "code", "message", "correlation_id", "details" ], "properties": { "code": { "type": "string", "const": "INSUFFICIENT_API_CREDITS" }, "message": { "type": "string" }, "correlation_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "required": [ "type", "remaining", "minimum_purchase" ], "properties": { "type": { "type": "string", "const": "context" }, "remaining": { "type": "integer", "description": "Prepaid credits left." }, "minimum_purchase": { "type": "integer", "description": "Smallest credit package (100)." } }, "additionalProperties": true } }, "additionalProperties": false }, "InsufficientApiCreditsAllowanceError": { "type": "object", "description": "402 shape for accounts with an enforced monthly allowance.", "required": [ "code", "message", "correlation_id", "details" ], "properties": { "code": { "type": "string", "const": "INSUFFICIENT_API_CREDITS" }, "message": { "type": "string" }, "correlation_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "required": [ "type", "included_remaining", "credit_remaining", "shortfall", "minimum_purchase" ], "properties": { "type": { "type": "string", "const": "context" }, "included_remaining": { "type": "integer", "description": "Allowance left this month." }, "credit_remaining": { "type": [ "integer", "null" ], "description": "Prepaid credits left, or null." }, "shortfall": { "type": "integer", "description": "Units not covered." }, "minimum_purchase": { "type": "integer", "description": "Smallest credit package (100)." } }, "additionalProperties": true } }, "additionalProperties": false }, "StructuredInvoice_AccountingCustomerParty": { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "AccountingCustomerParty", "type": "object" }, "StructuredInvoice_AccountingSupplierParty": { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "AccountingSupplierParty", "type": "object" }, "StructuredInvoice_AdditionalDocumentReference": { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "DocumentTypeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Documenttypecode" }, "DocumentDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Documentdescription" }, "Attachment": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Attachment" }, { "type": "null" } ], "default": null } }, "title": "AdditionalDocumentReference", "type": "object" }, "StructuredInvoice_AdvancePaymentSettlementRow": { "additionalProperties": false, "description": "One received advance payment that a cumulative final invoice deducts in BT-113.\n\nThe rows are not an EN 16931 group: the e-invoice carries them as a settlement-table PDF\nattachment (BG-24, ID \"advance-settlement\"). Give only values printed on the advance;\nVAT is never derived from the gross amount. The gross amounts must add up to BT-113.", "properties": { "ID": { "maxLength": 200, "minLength": 1, "title": "Id", "type": "string" }, "IssueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issuedate" }, "NetAmount": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Netamount" }, "TaxPercent": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Taxpercent" }, "TaxAmount": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxamount" }, "GrossAmount": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Grossamount" } }, "required": [ "ID", "GrossAmount" ], "title": "AdvancePaymentSettlementRow", "type": "object" }, "StructuredInvoice_AllowanceCharge": { "additionalProperties": false, "description": "Document-level allowance or charge (BG-20/BG-21)", "properties": { "ChargeIndicator": { "title": "Chargeindicator", "type": "boolean" }, "AllowanceChargeReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancechargereasoncode" }, "AllowanceChargeReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancechargereason" }, "MultiplierFactorNumeric": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Source percentage points exactly as printed. 30% is 30, never 0.3; 0.3% remains 0.3. Never convert percentage points to decimal factors.", "title": "Multiplierfactornumeric" }, "BaseAmount": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Baseamount" }, "Amount": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "TaxCategory": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceChargeTaxCategory" }, { "type": "null" } ], "default": null } }, "required": [ "ChargeIndicator", "Amount" ], "title": "AllowanceCharge", "type": "object" }, "StructuredInvoice_AllowanceChargeTaxCategory": { "additionalProperties": false, "description": "Tax category for document-level allowance/charge (BG-21)", "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "AllowanceChargeTaxCategory", "type": "object" }, "StructuredInvoice_Attachment": { "additionalProperties": false, "properties": { "EmbeddedDocumentBinaryObject": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_EmbeddedDocumentBinaryObject" }, { "type": "null" } ], "default": null }, "ExternalReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_ExternalReference" }, { "type": "null" } ], "default": null } }, "title": "Attachment", "type": "object" }, "StructuredInvoice_BuyersItemIdentification": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "BuyersItemIdentification", "type": "object" }, "StructuredInvoice_CardAccount": { "additionalProperties": false, "properties": { "PrimaryAccountNumberID": { "title": "Primaryaccountnumberid", "type": "string" }, "NetworkID": { "title": "Networkid", "type": "string" }, "HolderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Holdername" } }, "required": [ "PrimaryAccountNumberID", "NetworkID" ], "title": "CardAccount", "type": "object" }, "StructuredInvoice_ClassifiedTaxCategory": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxExemptionReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreasoncode" }, "TaxExemptionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreason" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "ClassifiedTaxCategory", "type": "object" }, "StructuredInvoice_CommodityClassification": { "additionalProperties": false, "properties": { "ItemClassificationCode": { "$ref": "#/components/schemas/StructuredInvoice_ItemClassificationCode" } }, "required": [ "ItemClassificationCode" ], "title": "CommodityClassification", "type": "object" }, "StructuredInvoice_Contact": { "additionalProperties": false, "properties": { "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "Telephone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Telephone" }, "ElectronicMail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Electronicmail" } }, "title": "Contact", "type": "object" }, "StructuredInvoice_ContractDocumentReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "ContractDocumentReference", "type": "object" }, "StructuredInvoice_Country": { "additionalProperties": false, "properties": { "IdentificationCode": { "title": "Identificationcode", "type": "string" } }, "required": [ "IdentificationCode" ], "title": "Country", "type": "object" }, "StructuredInvoice_Delivery": { "additionalProperties": false, "properties": { "ActualDeliveryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actualdeliverydate" }, "DeliveryLocation": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryLocation" }, { "type": "null" } ], "default": null }, "DeliveryParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Party" }, { "type": "null" } ], "default": null } }, "title": "Delivery", "type": "object" }, "StructuredInvoice_DeliveryAddress": { "additionalProperties": false, "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" }, "Country": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Country" }, { "type": "null" } ], "default": null } }, "title": "DeliveryAddress", "type": "object" }, "StructuredInvoice_DeliveryLocation": { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Id" }, "schemeID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Schemeid" }, "Address": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryAddress" }, { "type": "null" } ], "default": null } }, "title": "DeliveryLocation", "type": "object" }, "StructuredInvoice_DeliveryTerms": { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "SpecialTerms": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Specialterms" } }, "title": "DeliveryTerms", "type": "object" }, "StructuredInvoice_DespatchDocumentReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "DespatchDocumentReference", "type": "object" }, "StructuredInvoice_EmbeddedDocumentBinaryObject": { "additionalProperties": false, "properties": { "#text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "#Text" }, "mimeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mimecode" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" } }, "title": "EmbeddedDocumentBinaryObject", "type": "object" }, "StructuredInvoice_EndpointID": { "additionalProperties": false, "properties": { "#text": { "title": "#Text", "type": "string" }, "@schemeID": { "title": "@Schemeid", "type": "string" } }, "required": [ "#text", "@schemeID" ], "title": "EndpointID", "type": "object" }, "StructuredInvoice_ExternalReference": { "additionalProperties": false, "properties": { "URI": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Uri" } }, "title": "ExternalReference", "type": "object" }, "StructuredInvoice_FinancialInstitutionBranch": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "FinancialInstitutionBranch", "type": "object" }, "StructuredInvoice_InvoiceLine": { "additionalProperties": false, "properties": { "ID": { "description": "Line identifier - use the exact position number from the original invoice (e.g., '1.1.30', '10', '001'). Fall back to sequential '1', '2', '3' only when no explicit identifiers exist. NOT the item name.", "title": "Id", "type": "string" }, "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "InvoicedQuantity": { "title": "Invoicedquantity", "type": "number" }, "unitCode": { "title": "Unitcode", "type": "string" }, "LineExtensionAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Lineextensionamount" }, "PeriodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Periodstart" }, "PeriodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Periodend" }, "InvoicePeriod": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod" }, { "type": "null" } ], "default": null }, "OrderLineReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Orderlinereference" }, "Item": { "$ref": "#/components/schemas/StructuredInvoice_Item" }, "Price": { "$ref": "#/components/schemas/StructuredInvoice_Price" }, "AllowanceCharge": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" } }, "required": [ "ID", "InvoicedQuantity", "unitCode", "LineExtensionAmount", "Item", "Price" ], "title": "InvoiceLine", "type": "object" }, "StructuredInvoice_InvoicePeriod": { "additionalProperties": false, "properties": { "StartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Startdate" }, "EndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Enddate" }, "DescriptionCode": { "anyOf": [ { "enum": [ "3", "35", "432" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Descriptioncode" } }, "title": "InvoicePeriod", "type": "object" }, "StructuredInvoice_Item": { "additionalProperties": false, "properties": { "Description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "BuyersItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_BuyersItemIdentification" }, { "type": "null" } ], "default": null }, "SellersItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_SellersItemIdentification" }, { "type": "null" } ], "default": null }, "StandardItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_StandardItemIdentification" }, { "type": "null" } ], "default": null }, "OriginCountry": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_OriginCountry" }, { "type": "null" } ], "default": null }, "CommodityClassification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Commodityclassification" }, "ClassifiedTaxCategory": { "$ref": "#/components/schemas/StructuredInvoice_ClassifiedTaxCategory" } }, "required": [ "ClassifiedTaxCategory" ], "title": "Item", "type": "object" }, "StructuredInvoice_ItemClassificationCode": { "additionalProperties": false, "properties": { "#text": { "title": "#Text", "type": "string" }, "listID": { "title": "Listid", "type": "string" }, "listVersionID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Listversionid" } }, "required": [ "#text", "listID" ], "title": "ItemClassificationCode", "type": "object" }, "StructuredInvoice_LegalMonetaryTotal": { "additionalProperties": false, "properties": { "LineExtensionAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Lineextensionamount" }, "AllowanceTotalAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancetotalamount" }, "ChargeTotalAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Chargetotalamount" }, "TaxExclusiveAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxexclusiveamount" }, "TaxInclusiveAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxinclusiveamount" }, "PrepaidAmount": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prepaidamount" }, "PayableRoundingAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Payableroundingamount" }, "PayableAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Payableamount" } }, "required": [ "LineExtensionAmount", "TaxExclusiveAmount", "TaxInclusiveAmount", "PayableAmount" ], "title": "LegalMonetaryTotal", "type": "object" }, "StructuredInvoice_OrderReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" }, "IssueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issuedate" } }, "required": [ "ID" ], "title": "OrderReference", "type": "object" }, "StructuredInvoice_OriginCountry": { "additionalProperties": false, "properties": { "IdentificationCode": { "title": "Identificationcode", "type": "string" } }, "required": [ "IdentificationCode" ], "title": "OriginCountry", "type": "object" }, "StructuredInvoice_Party": { "additionalProperties": false, "properties": { "EndpointID": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_EndpointID" }, { "type": "null" } ], "default": null }, "PartyIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Partyidentification" }, "PartyName": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Partyname" }, "PostalAddress": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PostalAddress" }, { "type": "null" } ], "default": null }, "PartyTaxScheme": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Partytaxscheme" }, "PartyLegalEntity": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyLegalEntity" }, { "type": "null" } ], "default": null }, "Contact": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Contact" }, { "type": "null" } ], "default": null } }, "title": "Party", "type": "object" }, "StructuredInvoice_PartyIdentification": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "schemeID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Schemeid" } }, "required": [ "ID" ], "title": "PartyIdentification", "type": "object" }, "StructuredInvoice_PartyLegalEntity": { "additionalProperties": false, "properties": { "RegistrationName": { "title": "Registrationname", "type": "string" }, "CompanyID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Companyid" }, "CompanyLegalForm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Companylegalform" } }, "required": [ "RegistrationName" ], "title": "PartyLegalEntity", "type": "object" }, "StructuredInvoice_PartyTaxScheme": { "additionalProperties": false, "properties": { "CompanyID": { "title": "Companyid", "type": "string" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "CompanyID", "TaxScheme" ], "title": "PartyTaxScheme", "type": "object" }, "StructuredInvoice_PayeeFinancialAccount": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "FinancialInstitutionBranch": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_FinancialInstitutionBranch" }, { "type": "null" } ], "default": null } }, "required": [ "ID" ], "title": "PayeeFinancialAccount", "type": "object" }, "StructuredInvoice_PayeeParty": { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "PayeeParty", "type": "object" }, "StructuredInvoice_PaymentMandate": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "PayerFinancialAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount" }, { "type": "null" } ], "default": null } }, "required": [ "ID" ], "title": "PaymentMandate", "type": "object" }, "StructuredInvoice_PaymentMeans": { "additionalProperties": false, "properties": { "PaymentMeansCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentmeanscode" }, "PaymentID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentid" }, "PaymentChannelCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentchannelcode" }, "InstructionID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructionid" }, "InstructionNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructionnote" }, "PayeeFinancialAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount" }, { "type": "null" } ], "default": null }, "CardAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_CardAccount" }, { "type": "null" } ], "default": null }, "PaymentMandate": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentMandate" }, { "type": "null" } ], "default": null } }, "title": "PaymentMeans", "type": "object" }, "StructuredInvoice_PaymentTerms": { "additionalProperties": false, "properties": { "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "PenaltySurchargePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Penaltysurchargepercent" }, "Amount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Amount" }, "NetDays": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Netdays" }, "DiscountDays": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Discountdays" }, "DiscountPercent": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Discountpercent" }, "DiscountBaseAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Discountbaseamount" }, "ExplicitDueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Explicitduedate" } }, "title": "PaymentTerms", "type": "object" }, "StructuredInvoice_PostalAddress": { "additionalProperties": false, "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "Country": { "$ref": "#/components/schemas/StructuredInvoice_Country" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" } }, "required": [ "Country" ], "title": "PostalAddress", "type": "object" }, "StructuredInvoice_PrecedingInvoiceReference": { "additionalProperties": false, "description": "BG-3: Reference to a preceding invoice (e.g., for Schlussrechnung referencing Abschlagsrechnungen)", "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" }, "IssueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issuedate" } }, "required": [ "ID" ], "title": "PrecedingInvoiceReference", "type": "object" }, "StructuredInvoice_Price": { "additionalProperties": false, "properties": { "PriceAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Priceamount" }, "BaseQuantity": { "anyOf": [ { "type": "number" }, { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Basequantity" }, "AllowanceCharge": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" } }, "required": [ "PriceAmount" ], "title": "Price", "type": "object" }, "StructuredInvoice_ProjectReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "ProjectReference", "type": "object" }, "StructuredInvoice_SalesOrderReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "SalesOrderReference", "type": "object" }, "StructuredInvoice_SellersItemIdentification": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "SellersItemIdentification", "type": "object" }, "StructuredInvoice_StandardItemIdentification": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "schemeID": { "default": "0160", "title": "Schemeid", "type": "string" } }, "required": [ "ID" ], "title": "StandardItemIdentification", "type": "object" }, "StructuredInvoice_TaxCategory": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxExemptionReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreasoncode" }, "TaxExemptionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreason" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "TaxCategory", "type": "object" }, "StructuredInvoice_TaxRepresentativeParty": { "additionalProperties": false, "description": "BG-11: Seller Tax Representative Party\nRequired when tax codes S, Z, E, AE, K, G, L, M are used\nand neither BT-31 nor BT-32 is provided (BR-DE-16)", "properties": { "PartyName": { "minLength": 1, "title": "Partyname", "type": "string" }, "PostalAddress": { "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativePostalAddress" }, "PartyTaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" } }, "required": [ "PartyName", "PostalAddress", "PartyTaxScheme" ], "title": "TaxRepresentativeParty", "type": "object" }, "StructuredInvoice_TaxRepresentativePostalAddress": { "additionalProperties": false, "description": "BG-12: Seller Tax Representative Postal Address", "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" }, "Country": { "$ref": "#/components/schemas/StructuredInvoice_Country" } }, "required": [ "Country" ], "title": "TaxRepresentativePostalAddress", "type": "object" }, "StructuredInvoice_TaxScheme": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "TaxScheme", "type": "object" }, "StructuredInvoice_TaxSubtotal": { "additionalProperties": false, "properties": { "TaxableAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxableamount" }, "TaxAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxamount" }, "TaxCategory": { "$ref": "#/components/schemas/StructuredInvoice_TaxCategory" } }, "required": [ "TaxableAmount", "TaxAmount", "TaxCategory" ], "title": "TaxSubtotal", "type": "object" }, "StructuredInvoice_TaxTotal": { "additionalProperties": false, "properties": { "TaxAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxamount" }, "TaxSubtotal": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal" }, "type": "array" } ], "title": "Taxsubtotal" } }, "required": [ "TaxAmount", "TaxSubtotal" ], "title": "TaxTotal", "type": "object" }, "StructuredInvoice_TenderOrLotReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "TenderOrLotReference", "type": "object" } } } }