{ "openapi": "3.1.0", "info": { "title": "Invoice Converter Externe API", "version": "1.20.0", "x-last-updated": "2026-10-02", "description": "Zet factuurdocumenten (PDF, DOCX, TXT) of gestructureerde factuurgegevens uit uw ERP-, facturatie- of CRM-systeem om naar gevalideerde e-facturen in XRechnung, ZUGFeRD/Factur-X, EN 16931, UBL of CII.\n\n**Basis-URL** `https://www.invoice-converter.com/api/v1` · **Authenticatie** `Authorization: Bearer ` · **Contract** OpenAPI 3.1 (dit document)\n\nDeze pagina is de volledige documentatie: de handleidingsecties hieronder beschrijven de werkwijze, en de secties over endpoints en schema's vermelden elk veld, elke waarde en elk antwoord.\n\n## Overzicht\n\nDe API zet per verzoek één factuur om naar een gevalideerde e-factuur. Elke conversie is asynchroon:\n\n1. **Omzetten.** `POST /invoices:convert` (PDF-, DOCX- of TXT-document) of `POST /invoices:convert-structured` (uw factuurgegevens plus een drager-PDF). Antwoord: `202` met `task_id`.\n2. **Opvragen.** `GET /tasks/{task_id}` tot `status` gelijk is aan `completed` of `failed`.\n3. **Downloaden.** `GET /tasks/{task_id}/result?download=xml|pdf`. Optioneel: `GET /tasks/{task_id}/validation-report?download=html|xml`.\n\nEen taak is alleen voltooid als het artefact de validatie voor het gevraagde profiel heeft doorstaan. Er is geen conceptuitvoer en geen uitvoer waarin waarschuwingen worden genegeerd. V1 heeft geen webhooks, geen batch-endpoint en geen endpoint dat taken oplijst.\n\n| Endpoint | Doel | Aanvraaglimiet per API-sleutel |\n|---|---|---|\n| `POST /invoices:convert` | Een document omzetten | 30/min, 500/u |\n| `POST /invoices:convert-structured` | Gestructureerde gegevens omzetten | 30/min, 500/u |\n| `GET /tasks/{task_id}` | Taakstatus | 60/min, 1.500/u |\n| `GET /tasks/{task_id}/result` | Het artefact downloaden | 60/min, 1.000/u |\n| `GET /tasks/{task_id}/validation-report` | Het validatierapport downloaden | 30/min, 500/u |\n\n## Authenticatie en toegang\n\n- Header: `Authorization: Bearer `.\n- Sleutels zijn live-sleutels per tenant met het voorvoegsel `icp_...`. Maak, roteer en trek ze in op de profielpagina met een actief Enterprise-abonnement. Een aparte goedkeuring is niet nodig.\n- Bewaar sleutels op uw server. Zet ze nooit in browser- of mobiele code, logs of tickets.\n- Ontbrekend token: `401 AUTHENTICATION_REQUIRED`. Onbekende of ingetrokken sleutel: `401 INVALID_API_KEY`. Geldige sleutel zonder API-toegang: `403 API_NOT_ENABLED_FOR_TENANT`. Sleutel van een verwijderd account: `410 ACCOUNT_DELETED` (de verwijdering is definitief; probeer het niet opnieuw).\n\n## Snelstart\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\nDe body van de `202` bevat `task_id`, `status` (`pending` of `processing`), `status_url` en `primary_result_url`. Baseer uw logica op `status`, niet op `message`. Sla `X-Correlation-ID` uit elk antwoord op; support heeft deze waarde nodig. Een statusantwoord voor een voltooide taak (ingekort):\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\nBij `failed` bevat `error` een samenvatting (tekenreeks of object); roep `/result` aan voor de getypeerde fout.\n\n## Formaten en profielen\n\n`format` is verplicht en bepaalt de syntaxis en de container. `profile` is optioneel en bepaalt de regelset. Laat u `profile` weg, dan geldt de standaardwaarde van het formaat.\n\n| `format` | Toegestane `profile` | Standaard | `download=xml` | `download=pdf` |\n|---|---|---|---|---|\n| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | gerenderde PDF (best effort) |\n| `EN16931` | `EN16931` | `EN16931` | UBL | gerenderde PDF (best effort) |\n| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | gerenderde PDF (best effort) |\n| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | gerenderde PDF (best effort) |\n| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hybride ZUGFeRD/Factur-X-PDF |\n\n- `format` en `profile` zijn niet hoofdlettergevoelig. Aliassen: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`.\n- Een profiel dat niet bij het formaat staat: `422 OUTPUT_PROFILE_CONFLICT`. Een onbekende profielnaam: `422 INVALID_PROFILE` met `details.allowed_profiles`.\n- Bij XML-formaten is `download=xml` het primaire artefact. De PDF-weergave is een extra gemak en kan ontbreken.\n- `format=ZUGFERD` vereist een PDF als bron. Een DOCX- of TXT-upload wordt bij het uploaden geweigerd met `422 ZUGFERD_SOURCE_PDF_REQUIRED`.\n- `jurisdiction` (ISO 3166-1 alpha-2), `transaction_scope` (`B2B`, `B2G`, `B2C`) en `delivery_channel` (`PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN`) zijn optionele contexthints. Geef voor Duitse B2G- of Peppol-stromen de context van de aanroeper mee bij het uploaden. Een ongeldige waarde geeft `422 UPLOAD_FAILED`.\n\n## Documentconversie\n\n`POST /invoices:convert`, `multipart/form-data`:\n\n- `file` (verplicht): `.pdf`, `.docx` of `.txt`. Eén factuur per bestand. Een document met meerdere facturen mislukt met `500 TASK_FAILED`, `details.code=MULTIPLE_INVOICES_IN_DOCUMENT`.\n- `format` (verplicht), `profile`, contextvelden zoals hierboven.\n- `client_reference` (≤ 200 tekens) of de alias `external_invoice_id`, en `source_system` (≤ 100 tekens): worden teruggegeven in de `202` en in de taakstatus.\n- `use_embedded_xml` (standaard `false`): ingesloten Factur-X/ZUGFeRD/XRechnung-XML in een PDF wordt genegeerd, tenzij deze waarde `true` is.\n- `email_input`: optionele instructies in vrije tekst voor de extractie (alleen PDF, ≤ 10.000 tekens, niet samen met `use_embedded_xml=true`).\n- `use_seller_master_data` en `seller_master_data`: zie *Stamgegevens van de verkoper*.\n\nDe extractie leest het document. Ze verzint geen juridische, fiscale, routerings-, bank- of kopersreferentiegegevens. Ontbreken verplichte gegevens, dan mislukt de taak en geeft `/result` `422 VALIDATION_FAILED` terug.\n\n## Gestructureerde factuurgegevens\n\n`POST /invoices:convert-structured` zet gegevens uit uw ERP-, facturatie- of CRM-systeem om (bijvoorbeeld Salesforce).\n\n- `pdf_file` (verplicht): de drager-PDF. Bij `ZUGFERD` wordt de gevalideerde XML erin ingesloten; bij XML-formaten wordt hij als originele PDF opgeslagen. **Hij levert nooit factuurgegevens.**\n- `data_file` (verplicht, herhaalbaar; aliassen `data_files`, `data_files[]`): `.json`, `.csv`, `.xml`, `.xlsx` of `.txt`, samen ≤ 2 MB.\n- `format`, `profile`, context-, klantreferentie- en verkoperstamgegevensvelden zoals bij documentconversie. `email_input` en `use_embedded_xml` worden niet geaccepteerd.\n\n### Deterministische versus geïnterpreteerde toewijzing\n\n| Invoer | Toewijzing | Resultaat |\n|---|---|---|\n| **Eén** JSON-`data_file` in het canonieke factuur-JSON-formaat, op het hoogste niveau of verpakt in `invoice_data` | Deterministisch, geen AI | Dezelfde invoer, dezelfde uitvoer |\n| Eén UBL 2.1 Invoice- of CII D16B-XML-bestand | Deterministisch, geen AI | Bestaande parser voor factuur-XML |\n| Meerdere consistente canonieke JSON-`data_file`-delen | Deterministisch samenvoegen, geen AI | Afzonderlijke velden en regels worden gecombineerd |\n| CSV, XLSX, TXT, andere XML, eigen of platte JSON, of delen met gemengde formaten | AI-toewijzing | Werkt met duidelijke labels; niet deterministisch |\n\nStuur voor een herhaalbare integratie één canoniek JSON-bestand:\n\n- JSON Schema: \n- Voorbeeld (Duitse B2G-XRechnung, doorstaat de controles voor EN 16931, XRechnung en strikte ZUGFeRD): \n\nHet formaat gebruikt de elementnamen van UBL 2.1 / EN 16931. Het canonieke pad wordt herkend als ten minste 3 van de sleutels op het hoogste niveau `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, `AccountingSupplierParty`, `AccountingCustomerParty`, `TaxTotal`, `LegalMonetaryTotal`, `InvoiceLine` aanwezig zijn, waaronder `ID`, `InvoiceLine` of `LegalMonetaryTotal`.\n\nOnbekende velden in canonieke JSON geven `400 INVALID_UPLOAD` voordat de taak wordt aangemaakt. `details.unknown_paths` toont maximaal 100 betrokken JSON-paden; `details.unknown_path_count` geeft het totaal. Verwijder niet-gedeclareerde velden in plaats van erop te rekenen dat ze worden weggegooid.\n\nDe AI-toewijzing krijgt de opdracht geen ontbrekende velden te verzinnen. Ontbrekende gegevens laten de validatie daarom mislukken in plaats van te worden geraden.\n\n**Gesplitste exports.** Herhaal `data_file` voor één factuur die over meerdere bestanden is verdeeld (bijvoorbeeld kop en regels). Stuur één verzoek per factuur.\n\n- Elk deel moet hetzelfde factuurnummer bevatten in een kolom of sleutel met de naam `invoice number`, `invoice no`, `invoice no.`, `invoice id`, `rechnungsnr`, `rechnungsnr.`, `rechnung nr`, `rechnung nr.`, `belegnr` of `belegnr.`.\n- Namen zijn niet hoofdlettergevoelig, en `_` en `-` gelden als spaties, dus `Invoice_Number` werkt. `document no` en `document number` zijn een zwakkere terugvaloptie.\n- camelCase-namen zoals `invoiceNumber` en Salesforce-API-namen zoals `Invoice_Number__c` worden herkend.\n- Een ontbrekend of tegenstrijdig nummer geeft `400 INVALID_UPLOAD` met `details.reason` `bundle_invoice_id_missing` of `bundle_invoice_id_mismatch`.\n\nCanonieke JSON-delen gebruiken dezelfde `ID` op het hoogste niveau. Elk deel moet voldoen aan de bovenstaande canonieke herkenningsregel. Regels vereisen binnen elk deel unieke, expliciete `InvoiceLine[].ID`-waarden. Identieke herhaalde regels tussen delen worden ontdubbeld; tegenstrijdige waarden of verschillende regels met dezelfde ID geven `400 INVALID_UPLOAD`, `details.reason=canonical_bundle_conflict` en `details.path`. De server kiest geen tegenstrijdige waarde en berekent totalen niet opnieuw. Een null-waarde geldt als ontbrekend wanneer een ander deel het gegeven aanlevert.\n\n\n### Verplichte gegevens\n\n| Altijd | Voor XRechnung (ook `UBL`/`CII` met profiel `XRECHNUNG`, en `ZUGFERD_XRECHNUNG`) | Voor strikte ZUGFeRD |\n|---|---|---|\n| `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, naam van verkoper en koper, btw-uitsplitsing, totalen, ten minste één regel | `BuyerReference` (Leitweg-ID, BR-DE-15); `PaymentMeans` (BR-DE-1); naam, telefoon en e-mail van de contactpersoon van de verkoper (BR-DE-2/5/6/7); plaats en postcode van verkoper en koper; `EndpointID` van verkoper en koper met `@schemeID`; btw-`Percent` per subtotaal; btw-identificatienummer of fiscaal nummer van de verkoper | Een leverdatum, een factuurperiode of regelperioden; waar van toepassing een leverland |\n\nOntbrekende gegevens beëindigen de taak als `failed`; `/result` geeft `422 VALIDATION_FAILED` terug met `details.items[]` (`field`, `rule_id`, `severity`, `source`, `suggestion`).\n\n### Meestgebruikte JSON-paden\n\n`AccountingSupplierParty.Party` wordt afgekort als `Seller`, `AccountingCustomerParty.Party` als `Buyer`. XR = verplicht voor XRechnung.\n\n| JSON-pad | EN 16931 | XR |\n|---|---|---|\n| `ID` | BT-1 | ja |\n| `IssueDate` | BT-2 | ja |\n| `InvoiceTypeCode` (bijvoorbeeld `380` handelsfactuur) | BT-3 | ja |\n| `DocumentCurrencyCode` | BT-5 | ja |\n| `DueDate` | BT-9 | – |\n| `BuyerReference` | BT-10 | ja |\n| `OrderReference.ID` | BT-13 | – |\n| `InvoicePeriod.StartDate` / `.EndDate` | BT-73 / BT-74 | – |\n| `PaymentTerms.Note` | BT-20 | – |\n| `Seller.PartyLegalEntity.RegistrationName` | BT-27 | ja |\n| `Seller.PartyTaxScheme.CompanyID` (btw-identificatienummer) | BT-31 | ja¹ |\n| `Seller.EndpointID` (`#text`, `@schemeID`) | BT-34 | ja |\n| `Seller.PostalAddress.StreetName` | BT-35 | – |\n| `Seller.PostalAddress.CityName` / `.PostalZone` | BT-37 / BT-38 | ja |\n| `Seller.PostalAddress.Country.IdentificationCode` | BT-40 | ja |\n| `Seller.Contact.Name` / `.Telephone` / `.ElectronicMail` | BT-41 / BT-42 / BT-43 | ja |\n| `Buyer.PartyLegalEntity.RegistrationName` | BT-44 | ja |\n| `Buyer.EndpointID` (`#text`, `@schemeID`) | BT-49 | ja |\n| `Buyer.PostalAddress.CityName` / `.PostalZone` | BT-52 / BT-53 | ja |\n| `Buyer.PostalAddress.Country.IdentificationCode` | BT-55 | ja |\n| `Delivery.ActualDeliveryDate` | BT-72 | – |\n| `PaymentMeans.PaymentMeansCode` | BT-81 | ja |\n| `PaymentMeans.PayeeFinancialAccount.ID` (IBAN) | BT-84 | bij overboeking |\n| `TaxTotal.TaxAmount` | BT-110 | ja |\n| `TaxTotal.TaxSubtotal[].TaxableAmount` / `.TaxAmount` | BT-116 / BT-117 | ja |\n| `TaxTotal.TaxSubtotal[].TaxCategory.ID` / `.Percent` | BT-118 / BT-119 | ja |\n| `LegalMonetaryTotal.LineExtensionAmount` / `.TaxExclusiveAmount` | BT-106 / BT-109 | ja |\n| `LegalMonetaryTotal.TaxInclusiveAmount` / `.PayableAmount` | BT-112 / BT-115 | ja |\n| `InvoiceLine[].ID` / `.InvoicedQuantity` / `.unitCode` | BT-126 / BT-129 / BT-130 | ja |\n| `InvoiceLine[].LineExtensionAmount` | BT-131 | ja |\n| `InvoiceLine[].Price.PriceAmount` | BT-146 | ja |\n| `InvoiceLine[].Item.Name` | BT-153 | ja |\n| `InvoiceLine[].Item.ClassifiedTaxCategory.ID` / `.Percent` | BT-151 / BT-152 | ja |\n\n¹ Btw-identificatienummer van de verkoper (BT-31) of fiscaal nummer (BT-32, `PartyTaxScheme` met `TaxScheme.ID` `FC`).\n\n## Stamgegevens van de verkoper\n\n`seller_master_data` is een tekenreeks met een JSON-object. Deze geldt alleen als `use_seller_master_data=true`; ontbreekt de vlag, dan geldt de standaardinstelling van het account. Sleutels: `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` of `58`), `payment_iban`, `payment_bic`, `payment_account_name`, `payment_terms_note`. Het OpenAPI-schema `SellerMasterData` geeft voor elke sleutel de EN 16931-term.\n\n- Elke meegegeven waarde vervangt de geëxtraheerde verkopers- of betaalwaarde. Ontbrekende sleutels laten de factuur ongewijzigd.\n- `electronic_address` en `electronic_address_scheme` horen bij elkaar: stuur beide of geen van beide.\n- Ongeldige JSON, onbekende sleutels of een onvolledig paar: `400 INVALID_SELLER_MASTER_DATA`.\n\n## Idempotentie en opnieuw proberen\n\n- `Idempotency-Key` is verplicht op beide POST-endpoints. Formaat: 1–200 tekens, eerste teken een letter of cijfer, daarna letters, cijfers, `.`, `_`, `:` of `-` (`^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`). Een goede sleutel is uw factuur-ID plus een versie, bijvoorbeeld `sf-a0B5g00000XyZ12-v1`.\n- Bereik: tenant en endpoint, niet de afzonderlijke API-sleutel. Records worden 24 uur bewaard.\n- Gebruik bij elke nieuwe poging dezelfde sleutel **en** dezelfde payload. Een herhaling geeft de oorspronkelijke `202` terug met `Idempotency-Replayed: true` en zonder tweede afrekening.\n- **Eén sleutel, één taak.** Zodra een upload is geaccepteerd, geeft elke nieuwe poging met dezelfde sleutel en payload die taak terug: dezelfde `task_id` en dezelfde `202`-body. Dit geldt ook als u het eerste antwoord niet hebt ontvangen, of een `5xx` hebt ontvangen nadat de taak was geaccepteerd. Een nieuwe poging start nooit een tweede taak en reserveert of rekent nooit een tweede eenheid af.\n- Verzoeken met dezelfde sleutel worden na elkaar verwerkt: de andere krijgen `409 IDEMPOTENCY_IN_PROGRESS`. Een nieuwe poging nadat de taak is mislukt, geeft die mislukte taak terug; gebruik een nieuwe sleutel om het opnieuw te proberen.\n- Dezelfde sleutel met een andere payload: `409 IDEMPOTENCY_CONFLICT`. Het eerste verzoek loopt nog: `409 IDEMPOTENCY_IN_PROGRESS` (probeer het later opnieuw met dezelfde sleutel). De oorspronkelijke taak is al verwijderd: `409 IDEMPOTENCY_REPLAY_EXPIRED` (nieuwe sleutel).\n- Een `429` of een `5xx` opnieuw proberen met dezelfde sleutel is veilig: die antwoorden blokkeren de sleutel niet. Een nieuwe poging met dezelfde sleutel rekent nooit twee keer af: als er al een taak was geaccepteerd, geeft ze die taak terug; anders wordt de upload opnieuw uitgevoerd. Een `5xx` alleen zegt niet of een taak is geaccepteerd, dus probeer het altijd opnieuw met dezelfde sleutel.\n\n## Limieten, polling en pieken\n\n**Aanvraaglimieten** gelden per API-sleutel, met één bucket per endpoint (tabel in *Overzicht*), in vaste vensters per kalenderminuut en kalenderuur. Een geweigerd verzoek telt niet mee. `429 RATE_LIMITED` bevat `Retry-After`, `X-RateLimit-Limit-Minute`, `X-RateLimit-Limit-Hour` en `details.minute_count`, `hour_count`, `limit_minute`, `limit_hour`. Geslaagde antwoorden bevatten geen quotaheaders.\n\n**Polling.** Eerste statusaanroep ongeveer 20 s na de `202`, daarna na 20, 30, 45 en 60 s, en vervolgens elke 60 s. Stop bij `completed` of `failed`. De meeste conversies zijn binnen twee minuten klaar. De server laat een taak mislukken na 5 minuten zonder voortgang of na 15 minuten in totaal; stel de time-out van uw client daarom in op ongeveer 16 minuten.\n\n**Grootte.** De twee uploadpaden op `www.invoice-converter.com` gaan rechtstreeks naar de backend, zonder Vercel Function. Standaardlimieten: bronbestand `file` of drager `pdf_file` ≤ 20.000.000 bytes (20 MB); `data_file`-delen samen ≤ 2.000.000 bytes (2 MB). De volledige multipart-body heeft 1.000.000 extra bytes: 21 MB voor documenten, 23 MB voor gestructureerde uploads. Maximaal 20 bestandsdelen en 50 tekstvelden (`400 INVALID_UPLOAD`). Een overschreden bestands- of bodylimiet geeft JSON `413 PAYLOAD_TOO_LARGE` met `details.limit_bytes`. Authenticatie gebeurt vóór toelating van de body. Infrastructuurfouten kunnen nog een antwoord zonder JSON geven.\n\n**Pieken** (bijvoorbeeld honderden terugkerende facturen op de eerste dag van de maand): geaccepteerde taken wachten in een gedeelde verwerkingswachtrij. API-uploads gebruiken samen maximaal de helft van de ingestelde plaatsen per backendproces, naar beneden afgerond. De standaardwachtrij met acht plaatsen accepteert vier API-taken en laat vier plaatsen vrij voor web of andere kanalen. Dit beschermt de toelatingscapaciteit; het belooft geen verwerkingssnelheid of prioriteit. Een volle wachtrij of API-aandeel geeft `503 SERVER_BUSY` met `Retry-After: 15` voordat een conversieratelimietplaats wordt verbruikt of een eenheid wordt gereserveerd. Herhalingen van geaccepteerde taken hebben geen extra plaats nodig. Aanbevolen clientpatroon:\n\n1. Houd een wachtrij aan de clientzijde met ongeveer 2–4 gelijktijdige conversies; pas deze aan bij `SERVER_BUSY`.\n2. Wacht bij `429` en `503 SERVER_BUSY` volgens `Retry-After` en probeer opnieuw met **dezelfde** `Idempotency-Key`.\n3. Vraag elke taak op met de bovenstaande backoff; start de volgende conversie wanneer er één klaar is. V1 heeft geen voltooiingswebhook, batch- of takenlijsteindpunt.\n\n## Fouten\n\nElke JSON-fout bevat `code`, `message`, `correlation_id` en meestal `details`. Baseer uw logica op `code`; bij `500 TASK_FAILED` ook op `details.code` en `details.retryable`. `details.type` is meestal aanwezig, maar niet altijd. Baseer uw logica nooit alleen op de HTTP-status of op `message`.\n\nDe volledige catalogus (elke code met HTTP-status, regel voor opnieuw proberen en actie) staat onder `ErrorEnvelope.code` in de OpenAPI-referentie. De codes die u het vaakst tegenkomt:\n\n| Code | HTTP | Opnieuw proberen? | Actie |\n|---|---|---|---|\n| `AUTHENTICATION_REQUIRED`, `INVALID_API_KEY` | 401 | nee | Corrigeer de sleutel. |\n| `ACCOUNT_DELETED` | 410 | nee | Het account van deze sleutel is verwijderd. De verwijdering is definitief. |\n| `IDEMPOTENCY_KEY_REQUIRED`, `INVALID_IDEMPOTENCY_KEY` | 400 | nee | Stuur een geldige `Idempotency-Key`. |\n| `FORMAT_REQUIRED` / `INVALID_FORMAT` | 400 / 422 | nee | Stuur een ondersteund `format`. |\n| `OUTPUT_PROFILE_CONFLICT`, `INVALID_PROFILE` | 422 | nee | Gebruik een profiel uit de tabel of laat het weg. |\n| `INVALID_UPLOAD` | 400 / 415 | nee | Corrigeer de multipart-body, het bestandstype of de factuurnummers van de gesplitste export. |\n| `FUNCTION_PAYLOAD_TOO_LARGE` (platte tekst) / `PAYLOAD_TOO_LARGE` | 413 | nee | Stuur een kleiner verzoek. |\n| `INSUFFICIENT_API_CREDITS` | 402 | nee | Koop tegoed of wacht op de volgende maand. |\n| `IDEMPOTENCY_IN_PROGRESS` | 409 | zelfde sleutel | Probeer het na korte tijd opnieuw. |\n| `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED` | 409 | nee | Gebruik een nieuwe sleutel. |\n| `RATE_LIMITED` | 429 | zelfde sleutel | Wacht `Retry-After` af. |\n| `SERVER_BUSY` | 503 | zelfde sleutel | Verwerkingswachtrij vol. Wacht `Retry-After` af. |\n| `UPLOAD_FAILED` | 503 / 500 | zelfde sleutel | De upload is niet geaccepteerd, of wel geaccepteerd maar het eerste antwoord kon niet opnieuw worden opgebouwd. Probeer het opnieuw met backoff en dezelfde sleutel. |\n| `UPLOAD_FAILED` | 422 | nee | Ongeldige `jurisdiction`, `transaction_scope` of `delivery_channel`. |\n| `TASK_NOT_READY` | 202 | opvragen | Blijf de status opvragen. |\n| `VALIDATION_FAILED` | 422 | nee | Corrigeer de gegevens (`details.items`) en start dan een nieuwe conversie. |\n| `TASK_FAILED` | 500 | als `details.retryable` | Lees `details.code`. Opnieuw te proberen: nieuwe conversie met een nieuwe sleutel. |\n| `AUTHORITATIVE_VALIDATION_UNAVAILABLE` | 503 | ja | Probeer dezelfde download later opnieuw. |\n| `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 503 | nieuwe taak | Start een nieuwe conversie. |\n| `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 | nee | Escaleer met de correlatie-ID. |\n| `TASK_NOT_FOUND` | 404 | nee | Onbekende taak, taak van een andere tenant, of verwijderd na 24 uur. |\n| `PROXY_ERROR` | 502 / 504 | zelfde sleutel | Probeer het opnieuw met backoff. |\n\nRedenen voor `500 TASK_FAILED` in `details.code`: `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `SCHEMA_PARSE_FAILED`, `ARTIFACT_PARITY_FAILED` (definitief); `SOURCE_TEXT_UNAVAILABLE`, `PROVIDER_ERROR` (volg `details.retryable`). Een mislukte taak blijft mislukt: herstel alleen met een nieuwe conversie en een nieuwe sleutel.\n\n## Resultaten, bewijzen en het validatierapport\n\n- `/result` haalt alleen op. Het geeft alleen `200` terug voor een opgeslagen artefact met een actueel validatiebewijs.\n- Leg de antwoordheaders vast: `X-Correlation-ID`, `X-Artifact-Sha256` (hash van de geleverde bytes), `X-Validation-Proof-Id`, `X-Artifact-State` (`compliant`), `X-Validation-State` (`passed`).\n- `/validation-report?download=html|xml` (verplichte parameter) geeft het rapport terug dat aan het geleverde artefact is gekoppeld: het KoSIT-rapport, of bij Factur-X een `validation-evidence`-XML met `source=\"facturx_php\"`. Factur-X-bewijs toont alleen de validatie van de opgeslagen XML aan, niet de getrouwheid aan de bron of de PDF/A-conformiteit. Op dit endpoint is `X-Artifact-Sha256` de hash van het gevalideerde resultaatartefact, niet van het rapport. Geen rapport voor het actuele artefact: `404 VALIDATION_REPORT_NOT_FOUND`.\n- `result_artifacts..state` in de taakstatus: `cached`, `not_ready`, `validation_failed`, `dependency_failed`, `artifact_generation_rerun_required`, `artifact_invariant_failed`.\n\n## Bewaartermijn, facturering en archivering\n\n- **Bewaartermijn.** Taken, artefacten en idempotentierecords worden 24 uur na het einde van de taak verwijderd. Daarna geeft elk taak-endpoint `404 TASK_NOT_FOUND` terug. Bewijs voor kwaliteitsborging volgt de bewaartermijnen in sectie 9 van de [verwerkersovereenkomst](https://www.invoice-converter.com/nl/dpa).\n- **Facturering.** Elke geaccepteerde conversie verbruikt één eenheid. Enterprise omvat 100 eenheden per kalendermaand, gedeeld met E-mailimport. Extra eenheden gebruiken prepaid tegoed: 100 voor EUR 50, 200 voor EUR 100, 500 voor EUR 250, 1.000 voor EUR 400. Herhalingen, mislukte conversies en alle taakaanroepen zijn gratis. Als niets een eenheid dekt: `402 INSUFFICIENT_API_CREDITS` (twee vormen van `details`, zie het OpenAPI-antwoord `PaymentRequired`).\n- **Archivering.** Stel uw archiefpakket samen tijdens de verwerking, niet achteraf: originele PDF, gegenereerde XML of hybride PDF, validatierapport en een metagegevensrecord met `task_id`, `client_reference`, formaat/profiel, `X-Artifact-Sha256`, `X-Validation-Proof-Id`, `X-Validation-Report-Proof-Id`, `created_at`/`completed_at` en correlatie-ID's.\n\n## Support en contract\n\n- Contact: `contact@invoice-converter.com`. Vermeld de `X-Correlation-ID`.\n- De API wordt geleverd onder de standaardvoorwaarden en de verwerkersovereenkomst, en onder een eventueel Enterprise-bestelformulier. Er geldt geen SLA voor beschikbaarheid, verwerkingstijd of support, tenzij een bestelformulier dat vermeldt.\n- Slechte brondocumenten en randgevallen vereisen menselijke controle. Houd uw eigen proces aan voor uitzonderingen, correctie, levering en archivering.\n- API-toegang is bedoeld voor gebruik binnen uw eigen bedrijf. Doorverkoop, white-label-gebruik of gebruik als servicebureau vereist een partnerovereenkomst.\n\n## Referentiebestanden\n\n- OpenAPI 3.1: \n- Postman-collectie: (stel `base_url`, `api_key`, `idempotency_key` in)\n- JSON Schema en voorbeeld voor gestructureerde factuurgegevens: zie *Gestructureerde factuurgegevens*\n- Factuurkanaal via e-mail: \n- Deze documentatie als Markdown (voor LLM's en offline lezen): ", "contact": { "name": "Invoice Converter-support", "email": "contact@invoice-converter.com", "url": "https://www.invoice-converter.com/nl/developer-api" } }, "servers": [ { "url": "https://www.invoice-converter.com/api/v1", "description": "Productie" } ], "security": [ { "HTTPBearer": [] } ], "tags": [ { "name": "Conversion", "description": "Start een asynchrone conversie. Elk geaccepteerd verzoek verbruikt één factureringseenheid; idempotente herhalingen en mislukte conversies niet.", "x-displayName": "Conversie" }, { "name": "Tasks", "description": "Vraag de taakstatus op en download het gevalideerde resultaat en het validatierapport. Deze aanroepen zijn gratis, maar er gelden aanvraaglimieten.", "x-displayName": "Taken" } ], "paths": { "/invoices:convert": { "post": { "tags": [ "Conversion" ], "summary": "Een factuurdocument omzetten", "operationId": "convertInvoice", "description": "Upload één factuurdocument en start een strikte conversie.\n\n- `file`: `.pdf`, `.docx` of `.txt`, één factuur per bestand. Bronbestand ≤ 20 MB (20.000.000 bytes); volledige multipart-body ≤ 21 MB.\n- `format` is verplicht; `profile` is optioneel (standaard per formaat, zie hieronder).\n- Ingesloten XML in een PDF wordt genegeerd, tenzij `use_embedded_xml=true`.\n- Aanvraaglimiet: 30/min en 500/u per API-sleutel.\n\n| `format` | Toegestane `profile` | Standaard | `download=xml` | `download=pdf` |\n|---|---|---|---|---|\n| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | gerenderde PDF (best effort) |\n| `EN16931` | `EN16931` | `EN16931` | UBL | gerenderde PDF (best effort) |\n| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | gerenderde PDF (best effort) |\n| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | gerenderde PDF (best effort) |\n| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hybride 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": "Geaccepteerd. Vraag `status_url` op. Een nieuwe poging met dezelfde Idempotency-Key en dezelfde payload geeft de taak terug die al was geaccepteerd: dezelfde task_id en dezelfde 202-body, met de header Idempotency-Replayed: true. Dit geldt ook als het eerste antwoord verloren ging of een 5xx was nadat de taak was geaccepteerd, en nadat de taak is mislukt. Er wordt nooit een tweede taak gestart en nooit een tweede eenheid gereserveerd of afgerekend.", "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": "Gestructureerde factuurgegevens omzetten", "operationId": "convertStructuredInvoice", "description": "Zet factuurgegevens uit uw systeem om. `data_file` is de enige gegevensbron; `pdf_file` is alleen de drager (bij ZUGFeRD ingesloten, anders als originele PDF opgeslagen).\n\n- **Deterministisch:** één JSON-`data_file` in het formaat `StructuredInvoiceData`, consistente canonieke JSON-delen of één UBL 2.1 Invoice-/CII D16B-XML-bestand worden zonder AI toegewezen ([schema](https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json), [voorbeeld](https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json)).\n- **Geïnterpreteerd:** CSV, XLSX, TXT, andere XML, eigen JSON en delen met gemengde formaten gebruiken AI-toewijzing, waarbij ontbrekende velden leeg blijven.\n- Gesplitste exports: herhaal `data_file`; alle delen vereisen hetzelfde factuurnummer. Kolommen zoals `Invoice Number`, `Rechnungsnr`, `invoiceNumber` en `Invoice_Number__c` worden herkend; canonieke JSON gebruikt `ID`.\n- Canonieke JSON: onbekende velden geven `400 INVALID_UPLOAD` met `details.unknown_paths`; tegenstrijdige bundelwaarden geven `details.reason=canonical_bundle_conflict` en `details.path`. Regels vereisen binnen elk deel unieke, expliciete `InvoiceLine[].ID`-waarden.\n- Limieten: `pdf_file` ≤ 20 MB, `data_file`-delen samen ≤ 2 MB, volledige multipart-body ≤ 23 MB. Aanvraaglimiet: 30/min en 500/u per API-sleutel.\n- De regels voor `format` en `profile` zijn dezelfde als bij `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": "Geaccepteerd. Vraag `status_url` op. Een nieuwe poging met dezelfde Idempotency-Key en dezelfde payload geeft de taak terug die al was geaccepteerd: dezelfde task_id en dezelfde 202-body, met de header Idempotency-Replayed: true. Dit geldt ook als het eerste antwoord verloren ging of een 5xx was nadat de taak was geaccepteerd, en nadat de taak is mislukt. Er wordt nooit een tweede taak gestart en nooit een tweede eenheid gereserveerd of afgerekend.", "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": "Taakstatus opvragen", "operationId": "getTaskStatus", "description": "Geeft de taakstatus terug. Vraag op tot `status` gelijk is aan `completed` of `failed`.\n\n- Backoff: eerste aanroep ~20 s na de `202`, daarna 20, 30, 45, 60 s, vervolgens elke 60 s. Stop na ~16 min.\n- `completed`: download via `primary_result_url`. `failed`: roep `/result` aan voor de getypeerde fout.\n- Onbekende taak, of meer dan 24 uur na voltooiing: `404 TASK_NOT_FOUND`.\n- Aanvraaglimiet: 60/min en 1.500/u per API-sleutel.", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" }, { "$ref": "#/components/parameters/IncludeValidationReportHtmlQuery" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "responses": { "200": { "description": "Actuele taakstatus.", "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": "Het resultaat downloaden", "operationId": "getTaskResult", "description": "Download het gevalideerde artefact. Alleen ophalen: bij deze aanroep wordt niets gegenereerd, gerepareerd of gevalideerd.\n\n- `download=xml`: UBL (`XRECHNUNG`, `EN16931`, `UBL`) of CII (`CII`, `ZUGFERD`). Bij XML-formaten altijd het primaire artefact.\n- `download=pdf`: hybride ZUGFeRD/Factur-X-PDF bij `ZUGFERD`; een best-effort-weergave bij de andere formaten.\n- Tijdens de verwerking: `202 TASK_NOT_READY`. Mislukte taak: de getypeerde fout ervan (`422 VALIDATION_FAILED`, `500 TASK_FAILED`, `503 ...`).\n- Aanvraaglimiet: 60/min en 1.000/u per API-sleutel.", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" }, { "$ref": "#/components/parameters/DownloadQuery" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "responses": { "200": { "description": "De bytes van het artefact. De `X-*`-headers beschrijven de geleverde bytes; leg ze vast voor uw archief.", "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": "Het validatierapport downloaden", "operationId": "getTaskValidationReport", "description": "Download het validatierapport dat aan het geleverde artefact is gekoppeld.\n\n- `download=html` voor mensen; `download=xml` voor het KoSIT-rapport, of Factur-X-`validation-evidence`-XML (`source=\"facturx_php\"`, geen KoSIT-formaat).\n- De `X-Artifact-*`-headers beschrijven het gevalideerde resultaatartefact, niet de bytes van het rapport.\n- Factur-X-bewijs toont alleen de validatie van de opgeslagen XML aan, niet de getrouwheid aan de bron of de PDF/A-conformiteit.\n- Aanvraaglimiet: 30/min en 500/u per API-sleutel.", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" }, { "$ref": "#/components/parameters/ValidationReportDownloadQuery" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "responses": { "200": { "description": "Het rapport.", "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 van het gevalideerde resultaatartefact (aangeduid door `X-Report-Source-Artifact-Format`), niet van de bytes van het rapport. Gebruik deze waarde niet als controlesom voor het rapport.", "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": "Taak van het rapport.", "schema": { "type": "string", "format": "uuid" } }, "X-Validation-Report-Proof-Id": { "description": "Bewijsrecord dat het rapport leverde. Gelijk aan `X-Validation-Proof-Id` bij XML-artefacten.", "schema": { "type": "string" } }, "X-Validation-Report-Content-Type": { "description": "Mediatype van het rapport.", "schema": { "type": "string" } }, "X-Validation-Report-Format": { "description": "Geretourneerd rapportformaat.", "schema": { "type": "string", "enum": [ "html", "xml" ] } }, "X-Validation-Report-Source": { "description": "Herkomst van het rapport, bijvoorbeeld `artifact`, `embedded_xml` of `source_xml`.", "schema": { "type": "string" } }, "X-Report-Source-Artifact-Format": { "description": "Resultaatartefact waaraan het rapport is gekoppeld.", "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-sleutel (`icp_...`) van de profielpagina. Bewaar deze aan serverzijde. Ontbreekt → `401 AUTHENTICATION_REQUIRED`; onbekend of ingetrokken → `401 INVALID_API_KEY`." } }, "parameters": { "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Verplicht op beide POST-endpoints. Gebruik bij elke nieuwe poging dezelfde sleutel met dezelfde payload; een herhaling geeft de oorspronkelijke `202` terug zonder tweede afrekening. Bereik: tenant + endpoint, 24 uur bewaard. Ontbreekt → `400 IDEMPOTENCY_KEY_REQUIRED`; ongeldig formaat → `400 INVALID_IDEMPOTENCY_KEY`; dezelfde sleutel met een andere 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": "Optionele UUID voor tracering. Een ontbrekende waarde of een waarde die geen UUID is, wordt vervangen door een UUID die de server genereert. Wordt teruggegeven in de antwoordheader `X-Correlation-ID`; vermeld deze bij support.", "schema": { "type": "string", "format": "uuid" } }, "TaskIdPath": { "name": "task_id", "in": "path", "required": true, "description": "`task_id` uit het `202`-antwoord. Geen UUID → `400 BAD_REQUEST`.", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "DownloadQuery": { "name": "download", "in": "query", "required": true, "description": "Te downloaden artefact (niet hoofdlettergevoelig). Ontbreekt → `400 DOWNLOAD_FORMAT_REQUIRED`; andere waarden → `400 INVALID_DOWNLOAD_FORMAT`.", "schema": { "type": "string", "enum": [ "xml", "pdf" ] }, "example": "xml" }, "ValidationReportDownloadQuery": { "name": "download", "in": "query", "required": true, "description": "`html` voor een leesbaar rapport, `xml` voor het machineleesbare rapport. Ontbreekt → `400 DOWNLOAD_FORMAT_REQUIRED`; andere waarden → `400 INVALID_DOWNLOAD_FORMAT`.", "schema": { "type": "string", "enum": [ "html", "xml" ] }, "example": "html" }, "IncludeValidationReportHtmlQuery": { "name": "include_validation_report_html", "in": "query", "required": false, "description": "`true` voegt de opgeschoonde HTML van het validatierapport toe als `validation_report_html`. Andere waarden dan `true`/`false` → `400 INVALID_QUERY_PARAMETER`.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } }, "headers": { "XCorrelationId": { "description": "Trace-ID van dit verzoek. Log deze en vermeld deze bij support.", "schema": { "type": "string", "format": "uuid" } }, "IdempotencyReplayed": { "description": "`true` als het antwoord een herhaling is van een eerder verzoek met dezelfde Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "RetryAfter": { "description": "Aantal seconden dat u moet wachten vóór de volgende poging. Wordt verstuurd bij 429 en bij 503 SERVER_BUSY.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitLimitMinute": { "description": "Limiet per minuut van de bucket van dit endpoint. Wordt alleen bij 429 verstuurd.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitLimitHour": { "description": "Limiet per uur van de bucket van dit endpoint. Wordt alleen bij 429 verstuurd.", "schema": { "type": "integer", "minimum": 1 } }, "ContentDisposition": { "description": "Bestandsnaam van de bijlage, bijvoorbeeld `attachment; filename=invoice.xml`.", "schema": { "type": "string" } }, "CacheControlNoStore": { "description": "Altijd `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ] } }, "XArtifactSha256": { "description": "SHA-256 van de geleverde bytes van het artefact.", "schema": { "type": "string" } }, "XValidationProofId": { "description": "Bewijsrecord dat het artefact aan zijn validatierun koppelt.", "schema": { "type": "string" } }, "XArtifactProofId": { "description": "Bewijsrecord op artefactniveau.", "schema": { "type": "string" } }, "XArtifactState": { "description": "Conformiteitsstatus van het artefact. Altijd `compliant` bij een geleverd API-artefact.", "schema": { "type": "string", "enum": [ "compliant", "warning_only", "cannot_guarantee", "blocked" ] } }, "XValidationState": { "description": "Validatie-uitkomst. Altijd `passed` bij een geleverd API-artefact.", "schema": { "type": "string", "enum": [ "passed", "failed_overridable", "failed_blocking", "not_validated" ] } }, "XProofStatus": { "description": "Actualiteit van het bewijs.", "schema": { "type": "string" } }, "XValidatorBundleId": { "description": "Regelpakket van de validator dat voor het bewijs is gebruikt.", "schema": { "type": "string" } }, "AllowConversionPath": { "description": "Toegestane methoden.", "schema": { "type": "string", "enum": [ "POST, OPTIONS" ] } }, "AllowTaskPath": { "description": "Toegestane methoden.", "schema": { "type": "string", "enum": [ "GET, OPTIONS" ] } } }, "responses": { "BadRequest": { "description": "Ongeldig verzoek. Niet opnieuw proberen: corrigeer het verzoek. Zie `ErrorEnvelope.code` voor alle 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": "Authenticatie mislukt. Niet opnieuw proberen.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "WWW-Authenticate": { "description": "Altijd `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`. Niet opnieuw proberen: koop een prepaid tegoedpakket of wacht op het volgende maandtegoed. Twee vormen van `details`; lees de sleutels die aanwezig zijn.", "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`. Niet opnieuw proberen: neem contact op met 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`: conversiepaden accepteren POST; OPTIONS geeft 204. De backend geeft bij niet-ondersteunde methoden een JSON-fout met `correlation_id`. HEAD geeft geen 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`: taakpaden accepteren alleen GET. Wordt door de edge-proxy verstuurd, dus de body bevat geen `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": "Idempotentieconflict. `IDEMPOTENCY_IN_PROGRESS`: probeer dezelfde sleutel na korte tijd opnieuw (een vastgelopen claim wordt na 15 min vrijgegeven). `IDEMPOTENCY_CONFLICT` en `IDEMPOTENCY_REPLAY_EXPIRED`: gebruik een nieuwe sleutel.", "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": "Verzoek te groot. Niet opnieuw proberen: stuur een kleiner verzoek. Uploads gaan rechtstreeks naar de backend. Bestands- en multipart-bodylimieten geven JSON `413 PAYLOAD_TOO_LARGE` met `details.limit_bytes`. Standaardlimieten: bron- of dragerbestand 20 MB, gestructureerde gegevensdelen samen 2 MB; volledige multipart-body 21 MB voor documenten of 23 MB voor gestructureerde uploads (inclusief 1 MB extra ruimte).", "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`: stuur `multipart/form-data`. Niet opnieuw proberen.", "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": "Validatie van de upload of van een verzoekoptie mislukt. Niet opnieuw proberen: corrigeer het verzoek. Codes: `INVALID_FORMAT`, `INVALID_PROFILE`, `OUTPUT_PROFILE_CONFLICT`, `OUTPUT_PROFILE_REQUIRED`, `UPLOAD_FAILED` (ongeldige contextwaarde), `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`. Opnieuw te proberen: wacht `Retry-After` seconden en probeer het opnieuw met dezelfde Idempotency-Key. Limieten gelden per API-sleutel en endpoint, in vaste vensters per kalenderminuut en kalenderuur. Geweigerde verzoeken tellen niet mee.", "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": "Tijdelijk niet beschikbaar. Probeer het opnieuw met dezelfde Idempotency-Key. `SERVER_BUSY`: de verwerkingswachtrij is vol; wacht `Retry-After` seconden. `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `API_CREDIT_SERVICE_UNAVAILABLE`, `UPLOAD_FAILED` (andere fout bij het accepteren): probeer het opnieuw met 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": "Tijdelijk niet beschikbaar. Probeer het opnieuw met backoff: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Start in plaats daarvan een NIEUWE conversie: `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": "Fout aan serverzijde. Een 500 is standaard niet opnieuw te proberen. `TASK_FAILED`: lees `details.code`; alleen `details.retryable: true` staat een nieuwe poging toe, en alleen als NIEUWE conversie met een nieuwe Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: escaleer. `UPLOAD_FAILED` bij het uploaden: probeer het opnieuw met dezelfde sleutel.", "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`: de edge kon de backend niet bereiken. Probeer het opnieuw met backoff en dezelfde 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`: de backend antwoordde niet op tijd. Probeer het opnieuw met backoff en dezelfde 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`: nog in verwerking. De body is een foutenvelop, geen bestand. Blijf de taakstatus opvragen.", "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`: onbekende taak, taak van een andere tenant, of 24 uur na voltooiing verwijderd. Niet opnieuw proberen.", "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`: onbekende taak, taak van een andere tenant, of 24 uur na voltooiing verwijderd. `404 TASK_RESULT_FAILED`: de taak bestaat, maar de resultaatgegevens zijn niet beschikbaar; escaleer met de correlatie-ID. Niet opnieuw proberen.", "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` (onbekende of verlopen taak) of `404 VALIDATION_REPORT_NOT_FOUND` (geen rapport gekoppeld aan het actuele artefact; `details.reason`). Niet opnieuw proberen.", "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": "De factuur kan niet worden uitgegeven. Niet opnieuw proberen: corrigeer de gegevens en start een nieuwe conversie. 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 Leitweg-ID 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 Leitweg-ID / BuyerReference." } ] } } }, "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. De API-sleutel authenticeert nog, maar het bijbehorende account is verwijderd. De verwijdering is definitief, dus het antwoord is 410 Gone op elk pad dat dit meldt. Niet opnieuw proberen. Een ingetrokken sleutel geeft in plaats daarvan 401 INVALID_API_KEY terug.", "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": "Het factuurdocument: `.pdf`, `.docx` of `.txt`, één factuur per bestand. `.doc`, `.rtf` en afbeeldingen worden geweigerd (`400 INVALID_UPLOAD`). `format=ZUGFERD` vereist een PDF (`422 ZUGFERD_SOURCE_PDF_REQUIRED`)." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Gewenst uitvoerformaat. Verplicht; er is geen standaardwaarde. Niet hoofdlettergevoelig. Ontbreekt → `400 FORMAT_REQUIRED`; onbekend → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Regelset waartegen het artefact wordt gevalideerd. Optioneel: elk `format` heeft een standaardwaarde (zie de tabel bij de operatie). Niet hoofdlettergevoelig. Aliassen: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Niet toegestaan voor dit formaat → `422 OUTPUT_PROFILE_CONFLICT`; onbekende naam → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "Land van de transactie volgens ISO 3166-1 alpha-2, bijvoorbeeld `DE`. Optionele context. Ongeldig → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "Optionele contexthint. Ongeldig → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "Optionele contexthint: `EMAIL_PDF` voor levering als hybride PDF, `DIRECT_XML` voor directe XML-integratie, `PEPPOL` voor levering via het netwerk. Ongeldig → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Uw factuur- of opdrachtreferentie. Wordt teruggegeven in de 202 en in de taakstatus. Geen stuurtekens. `external_invoice_id` wordt als alias geaccepteerd; worden beide verstuurd, dan moeten ze overeenkomen, anders `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Label van het aanroepende ERP- of facturatiesysteem. Wordt teruggegeven in de 202 en in de taakstatus.", "examples": [ "salesforce" ] }, "use_embedded_xml": { "type": "boolean", "default": false, "description": "Gebruik in de PDF ingesloten Factur-X/ZUGFeRD/XRechnung-XML als bron voor de extractie. Standaard `false`: de ingesloten XML wordt genegeerd en het zichtbare document wordt gelezen." }, "email_input": { "type": "string", "maxLength": 10000, "description": "Instructies in vrije tekst voor de extractie, in elke taal (alleen bij een PDF-bron). Niet te combineren met `use_embedded_xml=true`. Maakt deel uit van de idempotentie-identiteit. Ongeldig → `400 INVALID_EMAIL_INPUT`.", "examples": [ "Use purchase order number PO-42." ] }, "use_seller_master_data": { "type": "boolean", "description": "Stamgegevens van de verkoper toepassen. Weggelaten: de standaardinstelling van het account geldt. `false`: opgeslagen verkopersgegevens voor dit verzoek negeren. `true`: opgeslagen gegevens en `seller_master_data` toepassen." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "Tekenreeks met een JSON-object (schema: `SellerMasterData`). Wordt alleen toegepast als `use_seller_master_data=true`. Elke meegegeven waarde vervangt de geëxtraheerde verkopers- of betaalwaarde; ontbrekende sleutels laten de factuur ongewijzigd. Ongeldig → `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": "Drager-PDF. Bij `ZUGFERD` wordt de gevalideerde XML erin ingesloten; bij XML-formaten wordt hij als originele PDF opgeslagen. Hij levert nooit factuurgegevens." }, "data_file": { "oneOf": [ { "type": "string", "format": "binary" }, { "type": "array", "minItems": 1, "items": { "type": "string", "format": "binary" } } ], "description": "Factuurgegevens: `.json`, `.csv`, `.xml`, `.xlsx` of `.txt` (in totaal ≤ 2 MB). Canonieke JSON (op het hoogste niveau of verpakt in `invoice_data`), consistente canonieke JSON-delen en één UBL 2.1 Invoice-/CII D16B-XML-bestand worden zonder AI toegewezen; andere formaten gebruiken AI-toewijzing. Onbekende canonieke velden en tegenstrijdige bundelgegevens geven `400 INVALID_UPLOAD`. Herhaal het deel voor één factuur die over meerdere bestanden is verdeeld; alle delen vereisen hetzelfde factuurnummer en canonieke regels vereisen unieke, expliciete IDs. Schema: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json. De veldnamen `data_files` en `data_files[]` worden als alias geaccepteerd." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Gewenst uitvoerformaat. Verplicht; er is geen standaardwaarde. Niet hoofdlettergevoelig. Ontbreekt → `400 FORMAT_REQUIRED`; onbekend → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Regelset waartegen het artefact wordt gevalideerd. Optioneel: elk `format` heeft een standaardwaarde (zie de tabel bij de operatie). Niet hoofdlettergevoelig. Aliassen: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Niet toegestaan voor dit formaat → `422 OUTPUT_PROFILE_CONFLICT`; onbekende naam → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "Land van de transactie volgens ISO 3166-1 alpha-2, bijvoorbeeld `DE`. Optionele context. Ongeldig → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "Optionele contexthint. Ongeldig → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "Optionele contexthint: `EMAIL_PDF` voor levering als hybride PDF, `DIRECT_XML` voor directe XML-integratie, `PEPPOL` voor levering via het netwerk. Ongeldig → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Uw factuur- of opdrachtreferentie. Wordt teruggegeven in de 202 en in de taakstatus. Geen stuurtekens. `external_invoice_id` wordt als alias geaccepteerd; worden beide verstuurd, dan moeten ze overeenkomen, anders `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Label van het aanroepende ERP- of facturatiesysteem. Wordt teruggegeven in de 202 en in de taakstatus.", "examples": [ "salesforce" ] }, "use_seller_master_data": { "type": "boolean", "description": "Stamgegevens van de verkoper toepassen. Weggelaten: de standaardinstelling van het account geldt. `false`: opgeslagen verkopersgegevens voor dit verzoek negeren. `true`: opgeslagen gegevens en `seller_master_data` toepassen." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "Tekenreeks met een JSON-object (schema: `SellerMasterData`). Wordt alleen toegepast als `use_seller_master_data=true`. Elke meegegeven waarde vervangt de geëxtraheerde verkopers- of betaalwaarde; ontbrekende sleutels laten de factuur ongewijzigd. Ongeldig → `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" }, "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": "Canonieke factuur-JSON voor POST /api/v1/invoices:convert-structured. De elementnamen volgen UBL 2.1 / EN 16931. Stuur één factuur als één JSON-data_file, op het hoogste niveau of verpakt in een 'invoice_data'-object; dit formaat wordt zonder AI-interpretatie toegewezen. Voor herkenning zijn ten minste 3 van de sleutels op het hoogste niveau ID, IssueDate, InvoiceTypeCode, DocumentCurrencyCode, AccountingSupplierParty, AccountingCustomerParty, TaxTotal, LegalMonetaryTotal, InvoiceLine nodig, waaronder ID, InvoiceLine of LegalMonetaryTotal. Downloaden: 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": "Standaardgegevens van de verkoper, verstuurd als JSON-tekenreeks in het formulierveld `seller_master_data`. Elke sleutel is optioneel. `electronic_address` en `electronic_address_scheme` horen bij elkaar: stuur beide of geen van beide.", "properties": { "business_name": { "type": "string", "maxLength": 240, "description": "Juridische naam (BT-27)." }, "trading_name": { "type": "string", "maxLength": 240, "description": "Handelsnaam (BT-28)." }, "street": { "type": "string", "description": "Straat en huisnummer (BT-35)." }, "additional_address": { "type": "string", "description": "Extra adresregel (BT-36)." }, "postal_code": { "type": "string", "description": "Postcode (BT-38)." }, "city": { "type": "string", "description": "Plaats (BT-37)." }, "country": { "type": "string", "description": "Landcode volgens ISO 3166-1 alpha-2 (BT-40).", "examples": [ "DE" ] }, "vat_id": { "type": "string", "description": "Btw-identificatienummer (BT-31).", "examples": [ "DE123456789" ] }, "tax_number": { "type": "string", "description": "Fiscaal registratienummer (BT-32)." }, "electronic_address": { "type": "string", "description": "Elektronisch adres (BT-34). Vereist `electronic_address_scheme`." }, "electronic_address_scheme": { "type": "string", "description": "EAS-schema van het elektronische adres, bijvoorbeeld `EM` of `0204`." }, "contact_name": { "type": "string", "description": "Contactpersoon (BT-41)." }, "contact_email": { "type": "string", "description": "E-mailadres van de contactpersoon (BT-43)." }, "contact_phone": { "type": "string", "description": "Telefoonnummer van de contactpersoon (BT-42)." }, "payment_means_code": { "type": "string", "enum": [ "30", "42", "58" ], "description": "Code van de betaalwijze voor overboeking (BT-81): 30 overboeking, 42 betaling op bankrekening, 58 SEPA-overboeking." }, "payment_iban": { "type": "string", "description": "IBAN van de rekening van de begunstigde (BT-84)." }, "payment_bic": { "type": "string", "description": "BIC van de bank van de begunstigde (BT-86)." }, "payment_account_name": { "type": "string", "description": "Naam van de rekening van de begunstigde (BT-85)." }, "payment_terms_note": { "type": "string", "description": "Betalingsvoorwaarden als tekst (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": "Gebruik deze bij alle taakaanroepen." }, "status": { "type": "string", "enum": [ "pending", "processing" ], "description": "`pending`: in de wachtrij. `processing`: gestart." }, "message": { "type": "string", "description": "Leesbare bevestiging. Baseer hier geen logica op." }, "filename": { "type": [ "string", "null" ], "description": "Bestandsnaam van het geüploade document (of van de drager-PDF)." }, "pdf_filename": { "type": [ "string", "null" ], "description": "Bestandsnaam van de drager-PDF (gestructureerd endpoint)." }, "data_filename": { "type": [ "string", "null" ], "description": "Naam van het eerste gegevensbestand (gestructureerd endpoint)." }, "data_filenames": { "type": "array", "items": { "type": "string" }, "description": "Namen van alle gegevensbestanden (gestructureerd endpoint)." }, "data_file_count": { "type": "integer", "minimum": 1, "description": "Aantal gegevensbestanden (gestructureerd endpoint)." }, "file_size": { "type": "integer", "minimum": 0, "description": "Totaal aantal geaccepteerde bytes." }, "pdf_file_size": { "type": "integer", "minimum": 0, "description": "Bytes van de drager-PDF (gestructureerd endpoint)." }, "data_file_size": { "type": "integer", "minimum": 0, "description": "Bytes van de gegevensbestanden in totaal (gestructureerd endpoint)." }, "correlation_id": { "type": "string", "format": "uuid" }, "status_url": { "type": "string", "description": "Relatieve URL om op te vragen." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "Gebruikelijke download voor het gevraagde formaat: `pdf` bij ZUGFERD, anders `xml`." }, "primary_result_url": { "type": "string", "description": "Relatieve resultaat-URL met `download=`." }, "client_reference": { "type": "string", "description": "Teruggave van `client_reference`." }, "source_system": { "type": "string", "description": "Teruggave van `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`: in de wachtrij. `processing`: loopt. `completed`: er is een gevalideerd artefact. `failed`: definitief, geen artefact." }, "progress": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100, "description": "Globale voortgang in procent. Niet gebruiken voor timing." }, "created_at": { "type": "string", "format": "date-time", "description": "Tijdstip waarop de taak werd geaccepteerd (UTC)." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Tijdstip waarop de taak `completed` of `failed` bereikte (UTC)." }, "filename": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "object", "null" ], "additionalProperties": true, "description": "Samenvatting van de fout als `status=failed`: een melding of een object met `code`, `message`, `retryable`. Ter informatie; `/result` geeft de getypeerde foutenvelop terug." }, "correlation_id": { "type": "string", "format": "uuid", "description": "Trace-ID van deze statusaanroep." }, "client_reference": { "type": [ "string", "null" ], "description": "Teruggave van `client_reference`." }, "source_system": { "type": [ "string", "null" ], "description": "Teruggave van `source_system`." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "Gebruikelijke download voor het gevraagde formaat." }, "primary_result_url": { "type": "string", "description": "Relatieve resultaat-URL." }, "result_artifacts": { "$ref": "#/components/schemas/ResultArtifacts" }, "validation_report_html": { "$ref": "#/components/schemas/ValidationReportHtmlStatus" } }, "additionalProperties": false }, "ResultArtifacts": { "type": "object", "description": "Downloadgereedheid per artefact.", "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`: te downloaden. `not_ready`: nog niet gemaakt. `validation_failed`: blokkerend probleem in de gegevens of de bron-PDF. `dependency_failed`: storing van validator of opslag. `artifact_generation_rerun_required`: start een nieuwe conversie. `artifact_invariant_failed`: escaleer met de correlatie-ID." }, "download_url": { "type": "string", "description": "Relatieve 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": "Conformiteitsstatus. `compliant` bij elk geleverd API-artefact." }, "validation_state": { "type": "string", "enum": [ "passed", "failed_overridable", "failed_blocking", "not_validated" ], "description": "Validatie-uitkomst. `passed` bij elk geleverd API-artefact." } }, "additionalProperties": false }, "ValidationReportHtmlStatus": { "type": "object", "description": "Alleen aanwezig met `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": "Opgeschoonde HTML van het rapport; serverpaden zijn verwijderd." }, "source": { "type": "string", "description": "Bijvoorbeeld `artifact`, `embedded_xml` of `source_xml`." }, "source_result_format": { "type": "string", "enum": [ "xml", "pdf" ] }, "reason": { "type": "string", "description": "Waarom er geen rapport beschikbaar is, bijvoorbeeld `task_not_completed`, `proof_not_found`, `artifact_not_current`." } }, "additionalProperties": false }, "ErrorEnvelope": { "type": "object", "description": "Elke JSON-fout. Baseer uw logica op `code`; bij `500 TASK_FAILED` ook op `details.code` en `details.retryable`. Probeer een schrijfaanroep alleen opnieuw met dezelfde 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 · nee · Stuur `Authorization: Bearer `.", "INVALID_API_KEY": "401 · nee · De sleutel is onbekend, ingetrokken of ongeldig. Corrigeer of roteer de sleutel.", "API_NOT_ENABLED_FOR_TENANT": "403 · nee · De sleutel is geldig, maar het account heeft geen toegang tot de Externe API. Neem contact op met support.", "ACCOUNT_DELETED": "410 · nee · Het account van deze API-sleutel is verwijderd. De verwijdering is definitief. Een ingetrokken sleutel geeft `INVALID_API_KEY` terug.", "INSUFFICIENT_API_CREDITS": "402 · nee · Het maandtegoed en het prepaid tegoed zijn op. Koop een tegoedpakket of wacht op de volgende maand. Twee vormen van `details`.", "AUTH_SERVICE_UNAVAILABLE": "503 · ja · Authenticatie is tijdelijk niet beschikbaar. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.", "PLAN_TIER_CHECK_FAILED": "503 · ja · Abonnement of API-toegang kon niet worden gecontroleerd. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.", "RATE_LIMIT_SERVICE_UNAVAILABLE": "503 · ja · De dienst voor aanvraaglimieten is niet beschikbaar. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.", "API_CREDIT_SERVICE_UNAVAILABLE": "503 · ja · De controle van tegoed en maandtegoed is niet beschikbaar. Probeer de upload opnieuw met dezelfde Idempotency-Key.", "RATE_LIMITED": "429 · ja · Wacht `Retry-After` seconden en probeer het dan opnieuw met dezelfde Idempotency-Key.", "IDEMPOTENCY_KEY_REQUIRED": "400 · nee · Stuur een `Idempotency-Key`-header op beide POST-endpoints.", "INVALID_IDEMPOTENCY_KEY": "400 · nee · Gebruik 1–200 tekens die overeenkomen met `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`.", "IDEMPOTENCY_IN_PROGRESS": "409 · ja · Het eerste verzoek met deze sleutel loopt nog. Probeer dezelfde sleutel na korte tijd opnieuw.", "IDEMPOTENCY_CONFLICT": "409 · nee · De sleutel is met een andere payload gebruikt. Gebruik een nieuwe sleutel voor een nieuwe payload.", "IDEMPOTENCY_REPLAY_EXPIRED": "409 · nee · De bewaartermijn van 24 uur van de oorspronkelijke taak is verstreken. Start een nieuwe conversie met een nieuwe sleutel.", "FORMAT_REQUIRED": "400 · nee · Stuur `format` bij elk conversieverzoek.", "INVALID_FORMAT": "422 · nee · Stuur een van XRECHNUNG, ZUGFERD, EN16931, UBL, CII.", "INVALID_PROFILE": "422 · nee · Onbekende profielnaam. `details.allowed_profiles` vermeldt de toegestane waarden.", "OUTPUT_PROFILE_CONFLICT": "422 · nee · Het profiel is niet toegestaan voor dit `format`. Stuur een compatibel profiel of laat het weg.", "OUTPUT_PROFILE_REQUIRED": "422 · nee · Defensief; V1 kiest voor elk formaat een standaardprofiel, dus deze code wordt niet verwacht.", "CLIENT_REFERENCE_CONFLICT": "400 · nee · `client_reference` en `external_invoice_id` verschillen. Stuur er één, of in beide dezelfde waarde.", "INVALID_CLIENT_METADATA": "400 · nee · Houd `client_reference`/`external_invoice_id` ≤ 200 en `source_system` ≤ 100 tekens, zonder stuurtekens.", "INVALID_SELLER_MASTER_DATA": "400 · nee · Stuur `seller_master_data` als tekenreeks met een JSON-object met ondersteunde sleutels; stuur `electronic_address` en `electronic_address_scheme` samen.", "INVALID_EMBEDDED_XML_POLICY": "400 · nee · Stuur `use_embedded_xml` als `true` of `false`, of laat het weg.", "INVALID_EMAIL_INPUT": "400 · nee · Stuur `email_input` één keer, ≤ 10.000 tekens, alleen bij een PDF-bron, niet met `use_embedded_xml=true`, nooit bij convert-structured.", "INVALID_UPLOAD": "400/415 · nee · Corrigeer de upload: multipart/form-data, ondersteund bestandstype, ≤ 20 bestandsdelen en 50 velden, één factuurnummer in alle `data_file`-delen (`details.reason`).", "PAYLOAD_TOO_LARGE": "413 · nee · Een bestand, het totaal van `data_file` of de multipart-body overschrijdt zijn backendlimiet. Controleer `details.limit_bytes`; stuur een kleiner verzoek.", "UPLOAD_FAILED": "422 · nee: ongeldige waarde voor `jurisdiction`/`transaction_scope`/`delivery_channel`. 500/503 · ja: de upload is niet geaccepteerd, of wel geaccepteerd maar het eerste antwoord kon niet opnieuw worden opgebouwd. Probeer het opnieuw met backoff en dezelfde Idempotency-Key; de nieuwe poging geeft de geaccepteerde taak terug.", "SERVER_BUSY": "503 · ja · De verwerkingswachtrij is vol. Wacht `Retry-After` seconden (15) en probeer het dan opnieuw met dezelfde Idempotency-Key.", "ZUGFERD_SOURCE_PDF_REQUIRED": "422 · nee · `format=ZUGFERD` vereist een PDF als bron. Upload een PDF of kies een XML-formaat.", "METHOD_NOT_ALLOWED": "405 · nee · Gebruik POST op conversiepaden en GET op taakpaden (zie `Allow`).", "NOT_FOUND": "404 · nee · Onbekend pad onder /api/v1.", "BAD_REQUEST": "400 · nee · `task_id` moet een UUID zijn.", "INVALID_QUERY_PARAMETER": "400 · nee · Stuur `include_validation_report_html` als `true` of `false`.", "DOWNLOAD_FORMAT_REQUIRED": "400 · nee · Stuur de verplichte queryparameter `download`.", "INVALID_DOWNLOAD_FORMAT": "400 · nee · Gebruik `download=xml|pdf` op /result en `download=html|xml` op /validation-report.", "TASK_NOT_READY": "202 · opvragen · De taak loopt nog. Blijf de taakstatus opvragen met backoff.", "TASK_NOT_FOUND": "404 · nee · Onbekende taak, taak van een andere tenant, of 24 uur na voltooiing verwijderd. Alle taak-endpoints.", "TASK_STATUS_FAILED": "5xx · ja · De status kon niet worden gelezen. Probeer het opvragen opnieuw met backoff.", "TASK_RESULT_FAILED": "404/5xx · alleen 5xx · Het resultaat kon niet worden gelezen (bijvoorbeeld door ontbrekende taakmetagegevens). Probeer een 5xx opnieuw met backoff; escaleer een 404 met de correlatie-ID.", "TASK_FAILED": "500 · alleen als `details.retryable` true is · Lees `details.code`. Fouten die opnieuw te proberen zijn, vereisen een NIEUWE conversie met een nieuwe Idempotency-Key.", "VALIDATION_FAILED": "422 · nee · Blokkerende validatiefouten. Corrigeer de gegevens (`details.items`) en start een nieuwe conversie.", "PROFILE_MISMATCH": "422 · nee · Het opgeslagen document vermeldt een ander profiel. Start een nieuwe conversie met het juiste profiel.", "ZUGFERD_SOURCE_PDF_INCOMPATIBLE": "422 · nee · De bron-PDF kan geen strikte PDF/A-3-hybride dragen. Normaliseer de PDF of gebruik `download=xml`.", "ZUGFERD_CII_CONVERSION_FAILED": "422/500 · nee · De hybride CII-conversie is mislukt. Escaleer met de correlatie-ID.", "ZUGFERD_PDF_GENERATION_FAILED": "500 · nee · Het genereren van de hybride PDF is mislukt. Escaleer met de correlatie-ID.", "XML_GENERATION_FAILED": "500 · ja, met backoff · Verouderd pad voor generatie op aanvraag; niet verwacht bij strikte API-taken.", "PDF_GENERATION_FAILED": "500 · ja, met backoff · Verouderd pad voor generatie op aanvraag; niet verwacht bij strikte API-taken.", "AUTHORITATIVE_VALIDATION_UNAVAILABLE": "503 · ja · De validator is tijdelijk niet beschikbaar. Probeer dezelfde download later opnieuw.", "ARTIFACT_GENERATION_RERUN_REQUIRED": "503 · nieuwe taak · Het genereren van het artefact is mislukt na nieuwe pogingen door de server. Start een nieuwe conversie.", "EXTRACTION_INCOMPLETE_GROUP_FAILURE": "503 · nieuwe taak · Extractiegroepen zijn mislukt (`details.failed_groups`). Start een nieuwe conversie.", "INTERNAL_ARTIFACT_INVARIANT_FAILED": "500 · nee · Voltooide taak zonder veilig opgeslagen artefact. Escaleer met de correlatie-ID.", "VALIDATION_REPORT_NOT_FOUND": "404 · nee · Er is geen rapport gekoppeld aan het actuele artefact (`details.reason`).", "VALIDATION_REPORT_FAILED": "4xx/5xx · alleen 5xx · Het ophalen van het rapport is mislukt. Probeer een tijdelijke 5xx opnieuw met backoff.", "PROXY_ERROR": "502/504 · ja · Transportfout tussen edge en backend. Probeer het opnieuw met backoff en dezelfde Idempotency-Key." }, "description": "Machineleesbare foutcode. Opbouw van elke beschrijving: HTTP-status · opnieuw proberen? · actie." }, "message": { "type": "string", "description": "Leesbare tekst. Niet parsen." }, "correlation_id": { "type": "string", "format": "uuid", "description": "Vermeld deze bij support." }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "additionalProperties": false }, "EdgeError": { "type": "object", "description": "Fout die de edge-proxy verstuurt voordat het verzoek de API bereikt (`404 NOT_FOUND`, `405 METHOD_NOT_ALLOWED`). Geen `correlation_id`.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "METHOD_NOT_ALLOWED" ] }, "message": { "type": "string" } } }, "ErrorDetails": { "type": "object", "description": "Gestructureerde context. De sleutels hangen af van de code; onbekende sleutels kunnen voorkomen. `type` is meestal aanwezig, maar niet altijd (bijvoorbeeld `{\"field\": \"download\"}`, `INVALID_UPLOAD`, `413`); baseer uw logica daarom op de `code` van de envelop.", "properties": { "type": { "type": "string", "description": "Soort detail, bijvoorbeeld `validation`, `rate_limit`, `idempotency_conflict`, `idempotency_in_progress`, `profile_mismatch`, `context`, `dependency`, `artifact_generation`, `validation_report`, `message`." }, "code": { "type": "string", "description": "Onderliggende foutcode. Bij `500 TASK_FAILED` is dit de reden; zie `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": "Definitief. Het document bevat meer dan één factuur. Splits het en zet elke factuur afzonderlijk om.", "NO_INVOICE_DETECTED": "Definitief. Het document is geen factuur. Stuur het door naar een medewerker.", "INSUFFICIENT_INVOICE_SIGNAL": "Definitief. Te weinig factuurgegevens. Stuur een betere bron of gebruik convert-structured.", "SOURCE_TEXT_UNAVAILABLE": "Zie `retryable`. false: geen leesbare tekst (upload een tekst-PDF of een duidelijkere scan). true: OCR was tijdelijk niet beschikbaar; start een nieuwe conversie.", "SCHEMA_PARSE_FAILED": "Definitief voor deze poging. Start een nieuwe conversie; escaleer als het zich herhaalt.", "ARTIFACT_PARITY_FAILED": "Definitief. Het artefact kwam niet overeen met de definitieve factuurgegevens. Escaleer met de correlatie-ID.", "PROVIDER_ERROR": "Zie `retryable`. true: start na enige tijd een nieuwe conversie. `classification=provider_context_too_large`: stuur een kleiner document." } }, "retryable": { "type": "boolean", "description": "Doorslaggevend als aanwezig. `true` bij `TASK_FAILED`: start een NIEUWE conversie met een nieuwe Idempotency-Key." }, "can_review": { "type": "boolean" }, "classification": { "type": "string", "description": "Bijvoorbeeld `multiple_invoices`, `not_invoice`, `provider_context_too_large`." }, "category": { "type": "string" }, "recovery_hint": { "type": "string", "description": "Leesbare volgende stap." }, "same_task_retryable": { "type": "boolean", "description": "`false`: dezelfde taak kan niet herstellen; start een nieuwe conversie." }, "recovery": { "type": "string", "description": "Bijvoorbeeld `start_new_conversion`." }, "dependency": { "type": "string" }, "stage": { "type": "string" }, "failed_groups": { "type": "array", "items": { "type": "string" }, "description": "Mislukte extractiegroepen bij `EXTRACTION_INCOMPLETE_GROUP_FAILURE`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationDetail" }, "description": "Blokkerende problemen bij `VALIDATION_FAILED`." }, "field": { "type": "string", "description": "Betreffend verzoekveld, bijvoorbeeld `download` of `file`." }, "reason": { "type": "string", "description": "Nadere reden, bijvoorbeeld `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": "Toegestane profielen bij de profielfouten." }, "minute_count": { "type": "integer" }, "hour_count": { "type": "integer" }, "limit_minute": { "type": "integer" }, "limit_hour": { "type": "integer" }, "limit_bytes": { "type": "integer", "description": "Groottelimiet bij `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": "Eén blokkerend validatieprobleem.", "properties": { "field": { "type": [ "string", "null" ], "description": "Pad van het factuurveld, bijvoorbeeld `BuyerReference`." }, "rule_id": { "type": [ "string", "null" ], "description": "Regel-ID, bijvoorbeeld `BR-DE-15`." }, "severity": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "suggestion": { "type": [ "string", "null" ], "description": "Wat te corrigeren is." }, "message": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "InsufficientApiCreditsPrepaidError": { "type": "object", "description": "402-vorm voor accounts met alleen prepaid tegoed.", "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": "Resterend prepaid tegoed." }, "minimum_purchase": { "type": "integer", "description": "Kleinste tegoedpakket (100)." } }, "additionalProperties": true } }, "additionalProperties": false }, "InsufficientApiCreditsAllowanceError": { "type": "object", "description": "402-vorm voor accounts met een afgedwongen maandtegoed.", "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": "Resterend maandtegoed deze maand." }, "credit_remaining": { "type": [ "integer", "null" ], "description": "Resterend prepaid tegoed, of null." }, "shortfall": { "type": "integer", "description": "Niet gedekte eenheden." }, "minimum_purchase": { "type": "integer", "description": "Kleinste tegoedpakket (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_AllowanceCharge": { "additionalProperties": false, "description": "Korting of toeslag op documentniveau (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": "Procentpunten van de bron precies zoals afgedrukt. 30% is 30, nooit 0,3; 0,3% blijft 0,3. Zet procentpunten nooit om naar decimale factoren.", "title": "Multiplierfactornumeric" }, "BaseAmount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Baseamount" }, "Amount": { "anyOf": [ { "minimum": 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": "Btw-categorie voor korting/toeslag op documentniveau (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 } }, "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_FinancialInstitutionBranch": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "FinancialInstitutionBranch", "type": "object" }, "StructuredInvoice_InvoiceLine": { "additionalProperties": false, "properties": { "ID": { "description": "Regel-ID: gebruik het exacte positienummer van de oorspronkelijke factuur (bijv. '1.1.30', '10', '001'). Val alleen terug op een doorlopende nummering '1', '2', '3' als er geen expliciete ID's zijn. NIET de artikelnaam.", "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": [ { "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, "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: Verwijzing naar een eerdere factuur (bijv. bij een Schlussrechnung die naar Abschlagsrechnungen verwijst)", "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: Fiscaal vertegenwoordiger van de verkoper\nVerplicht als btw-codes S, Z, E, AE, K, G, L, M worden gebruikt\nen noch BT-31 noch BT-32 is opgegeven (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: Postadres van de fiscaal vertegenwoordiger van de verkoper", "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" } } } }