# Invoice Converter Externe API

Versie: 1.32.0 · Laatst bijgewerkt: 2026-11-20 · Basis-URL: `https://www.invoice-converter.com/api/v1`

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.

**Basis-URL** `https://www.invoice-converter.com/api/v1` · **Authenticatie** `Authorization: Bearer <api_key>` · **Contract** OpenAPI 3.1 (dit document)

Deze 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.

## Toegang en prijzen

Externe API V1 maakt van PDF-facturen of van de gegevens van uw ERP-, facturatie- of CRM-systeem XRechnung-, ZUGFeRD/Factur-X-, UBL- of CII-bestanden en levert een bestand pas na een geslaagde validatie. Een geslaagde validatie bewijst het formaat en de regels van de standaard, niet dat de gegevens met de bronfactuur overeenkomen. Plan uw eigen controle voor uitzonderingen.

Voor toegang is een Enterprise-abonnement nodig: € 50 per maand, of € 420 per jaar bij jaarlijkse facturering, excl. belastingen. [Enterprise starten](https://www.invoice-converter.com/nl/pricing)

- [API-sleutel maken](https://www.invoice-converter.com/nl/profile#api-access)
- [Handleiding e-mailimport](https://www.invoice-converter.com/nl/developer-api/email-invoices)
- [Handleiding batches](https://www.invoice-converter.com/nl/developer-api/bulk-runs)
- [Alle automatiseringskanalen vergelijken](https://www.invoice-converter.com/nl/automation)

## Overzicht

De API zet per verzoek één factuur om naar een gevalideerde e-factuur. Elke conversie is asynchroon:

1. **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`.
2. **Opvragen of op de webhook wachten.** `GET /tasks/{task_id}` tot `status` gelijk is aan `completed` of `failed`, of de ondertekende voltooiingsgebeurtenis ontvangen (zie *Webhooks*).
3. **Downloaden.** `GET /tasks/{task_id}/result?download=xml|pdf`. Optioneel: `GET /tasks/{task_id}/validation-report?download=html|xml`.

Een 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 batch-endpoint en geen endpoint dat taken oplijst.

| Endpoint | Doel | Aanvraaglimiet per API-sleutel |
|---|---|---|
| `POST /invoices:convert` | Een document omzetten | 30/min, 500/u |
| `POST /invoices:convert-structured` | Gestructureerde gegevens omzetten | 30/min, 500/u |
| `GET /tasks/{task_id}` | Taakstatus | 60/min, 1.500/u |
| `GET /tasks/{task_id}/result` | Het artefact downloaden | 60/min, 1.000/u |
| `GET /tasks/{task_id}/validation-report` | Het validatierapport downloaden | 30/min, 500/u |
| `GET /tasks/{task_id}/correction-result` | Gecorrigeerde factuur downloaden | 60/min, 1,000/h |
| `POST`, `GET`, `DELETE /webhook-endpoint` | Het webhook-endpoint registreren, lezen of verwijderen | 30/min, 300/u |
| `POST /webhook-endpoint:test` | Een testgebeurtenis versturen | 5/min, 50/u |

## Authenticatie en toegang

- Header: `Authorization: Bearer <api_key>`.
- 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.
- Bewaar sleutels op uw server. Zet ze nooit in browser- of mobiele code, logs of tickets.
- 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).

## Snelstart

```bash
# 1. Convert
curl -X POST 'https://www.invoice-converter.com/api/v1/invoices:convert' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Idempotency-Key: erp-inv-2026-0001' \
  -F 'file=@invoice.pdf' \
  -F 'format=XRECHNUNG' \
  -F 'client_reference=ERP-2026-0001'

# 2. Poll (first call about 20 s later)
curl 'https://www.invoice-converter.com/api/v1/tasks/<task_id>' \
  -H 'Authorization: Bearer <api_key>'

# 3. Download
download_tmp=$(mktemp) || exit 1
download_meta=$(curl --silent --show-error --output "$download_tmp" \
  --write-out '%{http_code} %{content_type}' --dump-header headers.txt \
  'https://www.invoice-converter.com/api/v1/tasks/<task_id>/result?download=xml' \
  -H 'Authorization: Bearer <api_key>') || { rm -f "$download_tmp"; exit 1; }
case "$download_meta" in
  '200 application/xml'|'200 application/xml;'*|'200 text/xml'|'200 text/xml;'*)
    mv "$download_tmp" invoice.xml ;;
  *)
    rm -f "$download_tmp"
    printf 'Download not saved (%s). Continue polling on 202.\n' "$download_meta" >&2
    exit 1 ;;
esac
```

De 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):

```json
{
  "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",
  "error": null,
  "client_reference": "ERP-2026-0001",
  "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml",
  "result_artifacts": {
    "xml": { "state": "cached", "artifact_state": "compliant", "validation_state": "passed" }
  }
}
```

Bij `failed` bevat `error` een samenvatting (tekenreeks of object); roep `/result` aan voor de getypeerde fout.

## Formaten en profielen

`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.

| `format` | Toegestane `profile` | Standaard | `download=xml` | `download=pdf` |
|---|---|---|---|---|
| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | gerenderde PDF (best effort) |
| `EN16931` | `EN16931` | `EN16931` | UBL | gerenderde PDF (best effort) |
| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | gerenderde PDF (best effort) |
| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | gerenderde PDF (best effort) |
| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hybride ZUGFeRD/Factur-X-PDF |

- `format` en `profile` zijn niet hoofdlettergevoelig. Aliassen: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`.
- Een profiel dat niet bij het formaat staat: `422 OUTPUT_PROFILE_CONFLICT`. Een onbekende profielnaam: `422 INVALID_PROFILE` met `details.allowed_profiles`.
- Bij XML-formaten is `download=xml` het primaire artefact. De PDF-weergave is een extra gemak en kan ontbreken.
- `format=ZUGFERD` vereist een PDF als bron. Een DOCX- of TXT-upload wordt bij het uploaden geweigerd met `422 ZUGFERD_SOURCE_PDF_REQUIRED`.
- `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`.

## Documentconversie

`POST /invoices:convert`, `multipart/form-data`:

- `file` (verplicht): `.pdf`, `.docx` of `.txt`. Eén factuur per bestand. Een document met meerdere facturen mislukt met `422 DOCUMENT_NOT_CONVERTIBLE`, `details.code=MULTIPLE_INVOICES_IN_DOCUMENT`.
- `format` (verplicht), `profile`, contextvelden zoals hierboven.
- `client_reference` (≤ 200 tekens) of de alias `external_invoice_id`, en `source_system` (≤ 100 tekens): worden teruggegeven in de `202` en in de taakstatus.
- `use_embedded_xml` (standaard `false`): ingesloten Factur-X/ZUGFeRD/XRechnung-XML in een PDF wordt genegeerd, tenzij deze waarde `true` is.
- `email_input`: optionele instructies in vrije tekst voor de extractie (alleen PDF, ≤ 10.000 tekens, niet samen met `use_embedded_xml=true`).
- `use_seller_master_data` en `seller_master_data`: zie *Stamgegevens van de verkoper*.

De extractie leest het document. Ze verzint geen juridische, fiscale, routerings-, bank- of kopersreferentiegegevens. Uitzondering voor XRechnung (profiel `XRECHNUNG` of `ZUGFERD_XRECHNUNG`): als noch de stamgegevens van de verkoper noch het document het elektronisch adres van de verkoper (BT-34) geven, en het document precies één e-mailadres van de verkoper vermeldt dat niet dat van de koper is, wordt dat adres BT-34 met schema `EM`. Peppol BIS-uitvoer neemt het nooit over. Ontbreken verplichte gegevens, dan mislukt de taak en geeft `/result` `422 VALIDATION_FAILED` terug.

## Gestructureerde factuurgegevens

`POST /invoices:convert-structured` zet gegevens uit uw ERP-, facturatie- of CRM-systeem om (bijvoorbeeld Salesforce).

- `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.**
- `data_file` (verplicht, herhaalbaar; aliassen `data_files`, `data_files[]`): `.json`, `.csv`, `.xml`, `.xlsx` of `.txt`, samen ≤ 2 MB.
- `format`, `profile`, context-, klantreferentie- en verkoperstamgegevensvelden zoals bij documentconversie. `email_input` en `use_embedded_xml` worden niet geaccepteerd.

### Deterministische versus geïnterpreteerde toewijzing

| Invoer | Toewijzing | Resultaat |
|---|---|---|
| **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 |
| Eén UBL 2.1 Invoice- of CII D16B-XML-bestand | Deterministisch, geen AI | Bestaande parser voor factuur-XML |
| Meerdere consistente canonieke JSON-`data_file`-delen | Deterministisch samenvoegen, geen AI | Afzonderlijke velden en regels worden gecombineerd |
| CSV, XLSX, TXT, andere XML, eigen of platte JSON, of delen met gemengde formaten | AI-toewijzing | Werkt met duidelijke labels; niet deterministisch |

Stuur voor een herhaalbare integratie één canoniek JSON-bestand:

- JSON Schema: <https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json>
- Voorbeeld (Duitse B2G-XRechnung, doorstaat de controles voor EN 16931, XRechnung en strikte ZUGFeRD): <https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json>

Het 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`.

Onbekende 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.

De AI-toewijzing krijgt de opdracht geen ontbrekende velden te verzinnen. Ontbrekende gegevens laten de validatie daarom mislukken in plaats van te worden geraden.

**Gesplitste exports.** Herhaal `data_file` voor één factuur die over meerdere bestanden is verdeeld (bijvoorbeeld kop en regels). Stuur één verzoek per factuur.

- 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.`.
- Namen zijn niet hoofdlettergevoelig, en `_` en `-` gelden als spaties, dus `Invoice_Number` werkt. `document no` en `document number` zijn een zwakkere terugvaloptie.
- camelCase-namen zoals `invoiceNumber` en Salesforce-API-namen zoals `Invoice_Number__c` worden herkend.
- Een ontbrekend of tegenstrijdig nummer geeft `400 INVALID_UPLOAD` met `details.reason` `bundle_invoice_id_missing` of `bundle_invoice_id_mismatch`.

Canonieke 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.

### Verplichte gegevens

| Altijd | Voor XRechnung (ook `UBL`/`CII` met profiel `XRECHNUNG`, en `ZUGFERD_XRECHNUNG`) | Voor strikte ZUGFeRD |
|---|---|---|
| `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 |

Ontbrekende gegevens beëindigen de taak als `failed`; `/result` geeft `422 VALIDATION_FAILED` terug met `details.items[]` (`field`, `business_term`, `rule_id`, `severity`, `source`, `message`, `suggestion`, en `proposal` voor een regel die alleen een bedrag vermeldt).

### Meestgebruikte JSON-paden

`AccountingSupplierParty.Party` wordt afgekort als `Seller`, `AccountingCustomerParty.Party` als `Buyer`. XR = verplicht voor XRechnung.

| JSON-pad | EN 16931 | XR |
|---|---|---|
| `ID` | BT-1 | ja |
| `IssueDate` | BT-2 | ja |
| `InvoiceTypeCode` (bijvoorbeeld `380` handelsfactuur) | BT-3 | ja |
| `DocumentCurrencyCode` | BT-5 | ja |
| `DueDate` | BT-9 | – |
| `BuyerReference` | BT-10 | ja |
| `OrderReference.ID` | BT-13 | – |
| `InvoicePeriod.StartDate` / `.EndDate` | BT-73 / BT-74 | – |
| `PaymentTerms.Note` | BT-20 | – |
| `Seller.PartyLegalEntity.RegistrationName` | BT-27 | ja |
| `Seller.PartyTaxScheme.CompanyID` (btw-identificatienummer) | BT-31 | ja¹ |
| `Seller.EndpointID` (`#text`, `@schemeID`) | BT-34 | ja |
| `Seller.PostalAddress.StreetName` | BT-35 | – |
| `Seller.PostalAddress.CityName` / `.PostalZone` | BT-37 / BT-38 | ja |
| `Seller.PostalAddress.Country.IdentificationCode` | BT-40 | ja |
| `Seller.Contact.Name` / `.Telephone` / `.ElectronicMail` | BT-41 / BT-42 / BT-43 | ja |
| `Buyer.PartyLegalEntity.RegistrationName` | BT-44 | ja |
| `Buyer.EndpointID` (`#text`, `@schemeID`) | BT-49 | ja |
| `Buyer.PostalAddress.CityName` / `.PostalZone` | BT-52 / BT-53 | ja |
| `Buyer.PostalAddress.Country.IdentificationCode` | BT-55 | ja |
| `Delivery.ActualDeliveryDate` | BT-72 | – |
| `PaymentMeans.PaymentMeansCode` | BT-81 | ja |
| `PaymentMeans.PayeeFinancialAccount.ID` (IBAN) | BT-84 | bij overboeking |
| `TaxTotal.TaxAmount` | BT-110 | ja |
| `TaxTotal.TaxSubtotal[].TaxableAmount` / `.TaxAmount` | BT-116 / BT-117 | ja |
| `TaxTotal.TaxSubtotal[].TaxCategory.ID` / `.Percent` | BT-118 / BT-119 | ja |
| `LegalMonetaryTotal.LineExtensionAmount` / `.TaxExclusiveAmount` | BT-106 / BT-109 | ja |
| `LegalMonetaryTotal.TaxInclusiveAmount` / `.PayableAmount` | BT-112 / BT-115 | ja |
| `InvoiceLine[].ID` / `.InvoicedQuantity` / `.unitCode` | BT-126 / BT-129 / BT-130 | ja |
| `InvoiceLine[].LineExtensionAmount` | BT-131 | ja |
| `InvoiceLine[].Price.PriceAmount` | BT-146 | ja |
| `InvoiceLine[].Item.Name` | BT-153 | ja |
| `InvoiceLine[].Item.ClassifiedTaxCategory.ID` / `.Percent` | BT-151 / BT-152 | ja |

¹ Btw-identificatienummer van de verkoper (BT-31) of fiscaal nummer (BT-32, `PartyTaxScheme` met `TaxScheme.ID` `FC`).

## Stamgegevens van de verkoper

`seller_master_data` is een tekenreeks met een JSON-object. Deze geldt alleen bij `use_seller_master_data=true`; zonder vlag geldt de accountinstelling. Het OpenAPI-schema `SellerMasterData` beschrijft de optionele velden en hun EN 16931-termen.

Overige optionele velden: `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`, `58`), `payment_terms_note`.

- Elke opgegeven waarde vervangt de overeenkomstige geëxtraheerde verkopers- of betaalwaarde. Een niet-lege lijst `payment_accounts` vervangt alle overschrijvingsrekeningen in opgeslagen volgorde. Geëxtraheerde IBAN-, BIC- en rekeningnaamwaarden voor die rekeningen worden genegeerd. Andere betaalwijzen behouden hun selectieregels.
- `payment_accounts` bevat maximaal 5 rekeningen met `iban` en optioneel `bic` en `account_name`. Elke IBAN moet geldig en uniek zijn; een opgegeven BIC moet geldig zijn. De scalaire velden `payment_iban`, `payment_bic` en `payment_account_name` vervallen: stuur de lijst.
- `electronic_address` en `electronic_address_scheme` horen bij elkaar: stuur beide of geen van beide.
- Een document met self-billing (typecode 261, 389 of 527) blijft zoals het is gelezen: de koper geeft het uit, verkoper en begunstigde zijn de tegenpartij, en verkopersstamgegevens vervangen niets. De bescherming van bankrekeningen weigert de IBAN niet wanneer het document de rekeninghouder als koper en een ander als verkoper noemt.
- Wanneer een ander document de rekeninghouder als koper en een ander als verkoper noemt, blijven de partijen zoals gelezen en stopt de omzetting voor controle (`party_roles_conflict_with_seller_profile`). Corrigeer de partijen, of kies type 389 als het om self-billing gaat.
- Ongeldige JSON, onbekende sleutels, ongeldige rekeningen, meer dan vijf rekeningen of een onvolledig paar: `400 INVALID_SELLER_MASTER_DATA`.

### Toegepaste waarden

Een voltooide taak vermeldt in `applied_values` elke waarde die de dienst heeft ingesteld in plaats van deze uit het document te lezen: waarden uit de stamgegevens van de verkoper en afgeleide waarden. Elke vermelding noemt het controleveld (`field`), de EN 16931-term (`business_term`), de bron `source` (`seller_master_data` of `derived`), een `code`, de uitgegeven waarde `value` en, wanneer een documentwaarde is vervangen, `previous_value`. Een opgeslagen waarde die gelijk is aan de documentwaarde wordt niet vermeld. De lijst is leeg wanneer niets is ingesteld. De lijst is alleen informatief en laat nooit een taak mislukken.

| `code` | Betekenis |
|---|---|
| `seller_master_data_filled` | Het document bevatte geen waarde; de opgeslagen waarde is gebruikt. |
| `seller_master_data_replaced` | De opgeslagen waarde heeft de documentwaarde in `previous_value` vervangen. |
| `seller_master_data_removed` | Een afgedrukte bankrekening zonder opgeslagen opvolger is verwijderd; `value` ontbreekt. |
| `delivery_country_derived_domestic_touchless`, `delivery_country_derived_from_buyer`, `delivery_country_from_matching_party_address` | Het leveringsland (BT-80) is afgeleid uit de adressen van de partijen. |
| `seller_endpoint_derived_from_printed_email_touchless` | Het elektronische adres van de verkoper (BT-34) is overgenomen van het afgedrukte e-mailadres van de verkoper. |

Er kunnen codes bijkomen; behandel een onbekende code als informatie.

## Idempotentie en opnieuw proberen

- `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`.
- Bereik: tenant en endpoint, niet de afzonderlijke API-sleutel. Records worden 24 uur bewaard.
- 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.
- **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.
- 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.
- 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). De sleutel is al gebruikt voor een voltooide conversie en de gegevens daarvan zijn na 24 uur verlopen: `409 IDEMPOTENCY_KEY_ALREADY_USED` (nieuwe sleutel).
- 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.

## Limieten, polling en pieken

**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.

**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.

**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.

**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:

1. Houd een wachtrij aan de clientzijde met ongeveer 2–4 gelijktijdige conversies; pas deze aan bij `SERVER_BUSY`.
2. Wacht bij `429` en `503 SERVER_BUSY` volgens `Retry-After` en probeer opnieuw met **dezelfde** `Idempotency-Key`.
3. Vraag elke taak op met de bovenstaande backoff of wacht op de webhookgebeurtenis; start de volgende conversie wanneer er één klaar is. V1 heeft geen batch- of takenlijsteindpunt.

## Webhooks

In plaats van te pollen registreert u één HTTPS-endpoint voor het bedrijf van uw API-sleutel. Wanneer een via deze API geaccepteerde conversie eindigt, stuurt de dienst een ondertekende `POST` met een kleine JSON-gebeurtenis. De gebeurtenis is een melding, niet het resultaat: download het resultaat zoals gewoonlijk met `GET /tasks/{task_id}/result`. Polling blijft werken en blijft de terugvaloptie.

**Registreren.** `POST /webhook-endpoint` met de JSON-body `{"url": "https://..."}` geeft `201` (of `200` als het endpoint wordt vervangen) met het ondertekeningsgeheim `secret`. Het secret verschijnt alleen in dit antwoord; bewaar het op uw server. Het verzoek opnieuw sturen vervangt de URL en roteert het secret. `GET /webhook-endpoint` toont de URL en de laatste aflevering, nooit het secret. `DELETE /webhook-endpoint` stopt alle afleveringen. `POST /webhook-endpoint:test` zet een `webhook.test`-gebeurtenis voor uw endpoint in de wachtrij.

**Gebeurtenissen.** `conversion.succeeded` (taak `completed`) en `conversion.failed` (taak `failed`; `data.error.code` is de code die `/result` teruggeeft). De body bevat `id`, `type`, `api_version`, `created_at` en `data` met `task_id`, `status`, `client_reference`, `source_system`, `format`, `profile`, `created_at`, `completed_at` en `error`. Hij bevat geen factuurgegevens en geen downloadlink.

```json
{"api_version":"v1","created_at":"2026-11-18T10:00:05+00:00","data":{"client_reference":"ERP-2026-0001","completed_at":"2026-11-18T10:00:04+00:00","created_at":"2026-11-18T09:58:51+00:00","error":null,"format":"XRECHNUNG","profile":"XRECHNUNG","source_system":null,"status":"completed","task_id":"550e8400-e29b-41d4-a716-446655440000"},"id":"evt_9b2f0c1e7a3d4e5f8a6b0c1d2e3f4a5b","type":"conversion.succeeded"}
```

**De handtekening controleren.** Elk verzoek bevat `X-Invoice-Converter-Signature: t=<unix seconds>,v1=<hex>`, `X-Invoice-Converter-Event-Id` en `X-Invoice-Converter-Event-Type`. Bereken HMAC-SHA256 over `<t>.<raw body>` met het volledige secret, inclusief het voorvoegsel `whsec_`, als sleutel. Vergelijk het resultaat in constante tijd met `v1` en weiger het verzoek wanneer `t` meer dan 5 minuten van uw klok afwijkt. Controleer de ruwe bytes voordat u de JSON parseert.

```python
import hashlib, hmac, time

def verify(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    timestamp = int(parts["t"])
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return abs(time.time() - timestamp) <= 300 and hmac.compare_digest(expected, parts["v1"])
```

**Aflevering en nieuwe pogingen.** Antwoord binnen 10 seconden met een willekeurige `2xx`; de dienst negeert de antwoordbody en volgt geen omleiding. Elke andere status, een time-out of een verbindingsfout telt als mislukte poging. De dienst probeert het tot 8 keer over ongeveer 23 uur (na ongeveer 1 min, 5 min, 30 min, 1 u, 3 u, 6 u en 12 u, met willekeurige spreiding) en geeft het daarna op. Aflevering gebeurt minstens één keer en zonder vaste volgorde: ontdubbel op `X-Invoice-Converter-Event-Id` en beschouw `GET /tasks/{task_id}` als de bron van waarheid.

**URL-regels.** `https` op poort 443 en een openbare DNS-naam, zonder IP-adres, gebruikersnaam, wachtwoord of fragment. De naam mag alleen naar openbare adressen verwijzen; dat wordt bij de registratie en opnieuw vóór elke aflevering gecontroleerd. Een geweigerde URL geeft `422 INVALID_WEBHOOK_URL` met `details.reason`.

## Fouten

Elke 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`.

De 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:

| Code | HTTP | Opnieuw proberen? | Actie |
|---|---|---|---|
| `AUTHENTICATION_REQUIRED`, `INVALID_API_KEY` | 401 | nee | Corrigeer de sleutel. |
| `ACCOUNT_DELETED` | 410 | nee | Het account van deze sleutel is verwijderd. De verwijdering is definitief. |
| `IDEMPOTENCY_KEY_REQUIRED`, `INVALID_IDEMPOTENCY_KEY` | 400 | nee | Stuur een geldige `Idempotency-Key`. |
| `FORMAT_REQUIRED` / `INVALID_FORMAT` | 400 / 422 | nee | Stuur een ondersteund `format`. |
| `OUTPUT_PROFILE_CONFLICT`, `INVALID_PROFILE` | 422 | nee | Gebruik een profiel uit de tabel of laat het weg. |
| `INVALID_UPLOAD` | 400 / 415 | nee | Corrigeer de multipart-body, het bestandstype of de factuurnummers van de gesplitste export. |
| `FUNCTION_PAYLOAD_TOO_LARGE` (platte tekst) / `PAYLOAD_TOO_LARGE` | 413 | nee | Stuur een kleiner verzoek. |
| `API_NOT_ENABLED_FOR_TENANT` | 403 | nee | Activeer API-toegang via `details.action_url`. |
| `INSUFFICIENT_API_CREDITS` | 402 | nee | Koop tegoed via `details.action_url` of wacht op de volgende maand. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | zelfde sleutel | Probeer het na korte tijd opnieuw. |
| `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED`, `IDEMPOTENCY_KEY_ALREADY_USED` | 409 | nee | Gebruik een nieuwe sleutel. |
| `RATE_LIMITED` | 429 | zelfde sleutel | Wacht `Retry-After` af. |
| `SERVER_BUSY` | 503 | zelfde sleutel | Verwerkingswachtrij vol. Wacht `Retry-After` af. |
| `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. |
| `UPLOAD_FAILED` | 422 | nee | Ongeldige `jurisdiction`, `transaction_scope` of `delivery_channel`. |
| `TASK_NOT_READY` | 202 | opvragen | Blijf de status opvragen. |
| `VALIDATION_FAILED` | 422 | nee | Corrigeer de gegevens (`details.items`) en start dan een nieuwe conversie. |
| `DOCUMENT_NOT_CONVERTIBLE` | 422 | nee | Corrigeer het brondocument (`details.recovery_hint`) en start dan een nieuwe conversie. |
| `TASK_FAILED` | 500 | als `details.retryable` | Lees `details.code`. Opnieuw te proberen: nieuwe conversie met een nieuwe sleutel. |
| `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 409 | nieuwe taak | De taak kan niet herstellen. Start een nieuwe conversie met een nieuwe sleutel. |
| `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 | nee | Escaleer met de correlatie-ID. |
| `TASK_NOT_FOUND` | 404 | nee | Onbekende taak, taak van een andere tenant, of verwijderd na 24 uur. |
| `PROXY_ERROR` | 502 / 504 | zelfde sleutel | Probeer het opnieuw met backoff. |

Redenen voor `500 TASK_FAILED` in `details.code`: `SCHEMA_PARSE_FAILED`, `ARTIFACT_PARITY_FAILED` (definitief); `SOURCE_TEXT_UNAVAILABLE`, `PROVIDER_ERROR` (volg `details.retryable`); `task_interrupted` (opnieuw te proberen: de server stopte voordat de conversie klaar was). Redenen voor `422 DOCUMENT_NOT_CONVERTIBLE`: `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `EMBEDDED_INVOICE_XML_INVALID`, `EMBEDDED_INVOICE_XML_UNREPRESENTABLE` en een niet opnieuw te proberen `SOURCE_TEXT_UNAVAILABLE` of `PROVIDER_ERROR` met `classification=provider_context_too_large`. `409 ARTIFACT_GENERATION_RERUN_REQUIRED` met `details.code=AUTHORITATIVE_VALIDATION_UNAVAILABLE`: de validator of een andere artefactafhankelijkheid bleef ook na nieuwe pogingen door de server onbeschikbaar. Een mislukte taak blijft mislukt. Een nieuwe automatische poging vereist een nieuwe conversie en een nieuwe sleutel; een handmatige correctie maakt een afzonderlijk, gekoppeld resultaat.

Bij mislukte taken opent `review_url` een correctie voor het betreffende bedrijf in de webapp. Meld u aan met toegang tot dat bedrijf. Bewaarde factuurgegevens openen in de editor; anders biedt de app een nieuwe upload aan. Een voltooide correctie staat in `correction`; de oorspronkelijke taak en `/result` behouden hun oorspronkelijke status. De oorspronkelijke bewaartermijn blijft gelden.

## Resultaten, bewijzen en het validatierapport

- `/result` haalt alleen op. Het geeft alleen `200` terug voor een opgeslagen artefact met een actueel validatiebewijs. Alleen taken die via `POST /invoices:convert` of `POST /invoices:convert-structured` zijn geaccepteerd, hebben een resultaat; voor elke andere taak van uw account geven `GET /tasks/{task_id}` en `/result` `404 TASK_NOT_FOUND` terug.
- 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`).
- `/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`.
- `result_artifacts.<xml|pdf>.state` in de taakstatus: `cached`, `not_ready`, `validation_failed`, `dependency_failed`, `artifact_generation_rerun_required`, `artifact_invariant_failed`.

## Bewaartermijn, facturering en archivering

- **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).
- **Facturering.** Elke geaccepteerde conversie verbruikt één eenheid. Enterprise omvat een tegoed dat wordt gedeeld met E-mailimport en bulkruns: 100 eenheden per kalendermaand bij maandelijkse facturering, of 1.200 eenheden per contractjaar bij jaarlijkse facturering, in één keer beschikbaar vanaf de eerste jaarbetaling (100 per maand tijdens de proefperiode). Niet-gebruikte eenheden vervallen aan het einde van de periode. 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, alle taakaanroepen en webhooks zijn gratis. Als niets een eenheid dekt: `402 INSUFFICIENT_API_CREDITS` (twee vormen van `details`, zie het OpenAPI-antwoord `PaymentRequired`).
- **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.

## Support en contract

- Contact: `contact@invoice-converter.com`. Vermeld de `X-Correlation-ID`.
- 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.
- Slechte brondocumenten en randgevallen vereisen menselijke controle. Houd uw eigen proces aan voor uitzonderingen, correctie, levering en archivering.
- API-toegang is bedoeld voor gebruik binnen uw eigen bedrijf. Doorverkoop, white-label-gebruik of gebruik als servicebureau vereist een partnerovereenkomst.

## Referentiebestanden

- OpenAPI 3.1: <https://www.invoice-converter.com/developer-api/v1/openapi.json>
- Postman-collectie: <https://www.invoice-converter.com/developer-api/v1/postman.json> (stel `base_url`, `api_key`, `idempotency_key` in)
- JSON Schema en voorbeeld voor gestructureerde factuurgegevens: zie *Gestructureerde factuurgegevens*
- Factuurkanaal via e-mail: <https://www.invoice-converter.com/nl/developer-api/email-invoices>
- Deze documentatie als Markdown (voor LLM's en offline lezen): <https://www.invoice-converter.com/nl/developer-api/md>

## Endpoints

### POST /invoices:convert — Een factuurdocument omzetten

Upload één factuurdocument en start een strikte conversie.

- `file`: `.pdf`, `.docx` of `.txt`, één factuur per bestand. Bronbestand ≤ 20 MB (20.000.000 bytes); volledige multipart-body ≤ 21 MB.
- `format` is verplicht; `profile` is optioneel (standaard per formaat, zie hieronder).
- Ingesloten XML in een PDF wordt genegeerd, tenzij `use_embedded_xml=true`.
- Aanvraaglimiet: 30/min en 500/u per API-sleutel.

| `format` | Toegestane `profile` | Standaard | `download=xml` | `download=pdf` |
|---|---|---|---|---|
| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | gerenderde PDF (best effort) |
| `EN16931` | `EN16931` | `EN16931` | UBL | gerenderde PDF (best effort) |
| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | gerenderde PDF (best effort) |
| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | gerenderde PDF (best effort) |
| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hybride ZUGFeRD/Factur-X-PDF |

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | ja | 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`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Verzoekbody** (`multipart/form-data`)

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `file` | string (binary) | ja | 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` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | ja | Gewenst uitvoerformaat. Verplicht; er is geen standaardwaarde. Niet hoofdlettergevoelig. Ontbreekt → `400 FORMAT_REQUIRED`; onbekend → `422 INVALID_FORMAT`. |
| `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` |  | 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`. |
| `jurisdiction` | string |  | Land van de transactie volgens ISO 3166-1 alpha-2, bijvoorbeeld `DE`. Optionele context. Ongeldig → `422 UPLOAD_FAILED`. |
| `transaction_scope` | string: `B2B`, `B2G`, `B2C` |  | Optionele contexthint. Ongeldig → `422 UPLOAD_FAILED`. |
| `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` |  | 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` | string |  | 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`. |
| `source_system` | string |  | Label van het aanroepende ERP- of facturatiesysteem. Wordt teruggegeven in de 202 en in de taakstatus. |
| `use_embedded_xml` | boolean |  | 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` | string |  | 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`. |
| `use_seller_master_data` | boolean |  | 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` | string |  | 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`. |

```json
{
  "$ref": "#/components/schemas/ConvertInvoiceRequest"
}
```

**Antwoorden**

- `202`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ConvertAcceptedResponse"
}
```

- `400`: Ongeldig verzoek. Niet opnieuw proberen: corrigeer het verzoek. Zie `ErrorEnvelope.code` voor alle 400-codes.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `402`: `402 INSUFFICIENT_API_CREDITS`. Niet opnieuw proberen: koop een prepaid tegoedpakket via `details.action_url` of wacht op de volgende tegoedperiode. Twee vormen van `details`; lees de sleutels die aanwezig zijn.

`application/json`

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError"
    },
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError"
    }
  ]
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: Idempotentieconflict. `IDEMPOTENCY_IN_PROGRESS`: probeer dezelfde sleutel na korte tijd opnieuw (een vastgelopen claim wordt na 15 min vrijgegeven). `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED` en `IDEMPOTENCY_KEY_ALREADY_USED`: gebruik een nieuwe sleutel.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `413`: 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).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

`text/plain`

```json
{
  "type": "string"
}
```

- `415`: `415 INVALID_UPLOAD`: stuur `multipart/form-data`. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: 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`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: de edge kon de backend niet bereiken. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: de backend antwoordde niet op tijd. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### POST /invoices:convert-structured — Gestructureerde factuurgegevens omzetten

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).

- **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)).
- **Geïnterpreteerd:** CSV, XLSX, TXT, andere XML, eigen JSON en delen met gemengde formaten gebruiken AI-toewijzing, waarbij ontbrekende velden leeg blijven.
- 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`.
- 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.
- 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.
- De regels voor `format` en `profile` zijn dezelfde als bij `POST /invoices:convert`.

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | ja | 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`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Verzoekbody** (`multipart/form-data`)

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `pdf_file` | string (binary) | ja | 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(string (binary), array of string (binary)) | ja | 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` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | ja | Gewenst uitvoerformaat. Verplicht; er is geen standaardwaarde. Niet hoofdlettergevoelig. Ontbreekt → `400 FORMAT_REQUIRED`; onbekend → `422 INVALID_FORMAT`. |
| `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` |  | 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`. |
| `jurisdiction` | string |  | Land van de transactie volgens ISO 3166-1 alpha-2, bijvoorbeeld `DE`. Optionele context. Ongeldig → `422 UPLOAD_FAILED`. |
| `transaction_scope` | string: `B2B`, `B2G`, `B2C` |  | Optionele contexthint. Ongeldig → `422 UPLOAD_FAILED`. |
| `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` |  | 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` | string |  | 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`. |
| `source_system` | string |  | Label van het aanroepende ERP- of facturatiesysteem. Wordt teruggegeven in de 202 en in de taakstatus. |
| `use_seller_master_data` | boolean |  | 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` | string |  | 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`. |

```json
{
  "$ref": "#/components/schemas/ConvertStructuredInvoiceRequest"
}
```

**Antwoorden**

- `202`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ConvertAcceptedResponse"
}
```

- `400`: Ongeldig verzoek. Niet opnieuw proberen: corrigeer het verzoek. Zie `ErrorEnvelope.code` voor alle 400-codes.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `402`: `402 INSUFFICIENT_API_CREDITS`. Niet opnieuw proberen: koop een prepaid tegoedpakket via `details.action_url` of wacht op de volgende tegoedperiode. Twee vormen van `details`; lees de sleutels die aanwezig zijn.

`application/json`

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError"
    },
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError"
    }
  ]
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: Idempotentieconflict. `IDEMPOTENCY_IN_PROGRESS`: probeer dezelfde sleutel na korte tijd opnieuw (een vastgelopen claim wordt na 15 min vrijgegeven). `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED` en `IDEMPOTENCY_KEY_ALREADY_USED`: gebruik een nieuwe sleutel.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `413`: 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).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

`text/plain`

```json
{
  "type": "string"
}
```

- `415`: `415 INVALID_UPLOAD`: stuur `multipart/form-data`. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: 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`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: de edge kon de backend niet bereiken. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: de backend antwoordde niet op tijd. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id} — Taakstatus opvragen

Geeft de taakstatus terug. Vraag op tot `status` gelijk is aan `completed` of `failed`.

- Backoff: eerste aanroep ~20 s na de `202`, daarna 20, 30, 45, 60 s, vervolgens elke 60 s. Stop na ~16 min.
- `completed`: download via `primary_result_url`. `failed`: roep `/result` aan voor de getypeerde fout.
- Onbekende taak, taak die niet via deze API is geaccepteerd (bijvoorbeeld een web-upload), of meer dan 24 uur na voltooiing: `404 TASK_NOT_FOUND`.
- Aanvraaglimiet: 60/min en 1.500/u per API-sleutel.

Bij mislukte taken opent `review_url` een correctie voor het betreffende bedrijf in de webapp. Meld u aan met toegang tot dat bedrijf. Bewaarde factuurgegevens openen in de editor; anders biedt de app een nieuwe upload aan. Een voltooide correctie staat in `correction`; de oorspronkelijke taak en `/result` behouden hun oorspronkelijke status. De oorspronkelijke bewaartermijn blijft gelden.

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | ja | `task_id` uit het `202`-antwoord. Geen UUID → `400 BAD_REQUEST`. |
| `include_validation_report_html` | query | string: `true`, `false` |  | `true` voegt de opgeschoonde HTML van het validatierapport toe als `validation_report_html`. Andere waarden dan `true`/`false` → `400 INVALID_QUERY_PARAMETER`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Antwoorden**

- `200`: Actuele taakstatus.

`application/json`

```json
{
  "$ref": "#/components/schemas/TaskStatusResponse"
}
```

- `400`: Ongeldig verzoek. Niet opnieuw proberen: corrigeer het verzoek. Zie `ErrorEnvelope.code` voor alle 400-codes.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 TASK_NOT_FOUND`: onbekende taak, taak van een andere tenant, taak die niet via deze API is geaccepteerd, of 24 uur na voltooiing verwijderd. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `405 METHOD_NOT_ALLOWED`: taakpaden accepteren alleen GET. Wordt door de edge-proxy verstuurd, dus de body bevat geen `correlation_id`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: de edge kon de backend niet bereiken. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Tijdelijk niet beschikbaar. Probeer het opnieuw met backoff: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: de backend antwoordde niet op tijd. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id}/result — Het resultaat downloaden

Download het gevalideerde artefact. Alleen ophalen: bij deze aanroep wordt niets gegenereerd, gerepareerd of gevalideerd.

- `download=xml`: UBL (`XRECHNUNG`, `EN16931`, `UBL`) of CII (`CII`, `ZUGFERD`). Bij XML-formaten altijd het primaire artefact.
- `download=pdf`: hybride ZUGFeRD/Factur-X-PDF bij `ZUGFERD`; een best-effort-weergave bij de andere formaten.
- Alleen taken die via de twee conversie-endpoints zijn geaccepteerd, hebben een resultaat. Elke andere taak (bijvoorbeeld een web-upload) geeft `404 TASK_NOT_FOUND` terug.
- Tijdens de verwerking: `202 TASK_NOT_READY`. Mislukte taak: de getypeerde fout ervan (`409 ARTIFACT_GENERATION_RERUN_REQUIRED`, `422 VALIDATION_FAILED`, `422 DOCUMENT_NOT_CONVERTIBLE`, `500 TASK_FAILED`).
- Aanvraaglimiet: 60/min en 1.000/u per API-sleutel.

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | ja | `task_id` uit het `202`-antwoord. Geen UUID → `400 BAD_REQUEST`. |
| `download` | query | string: `xml`, `pdf` | ja | Te downloaden artefact (niet hoofdlettergevoelig). Ontbreekt → `400 DOWNLOAD_FORMAT_REQUIRED`; andere waarden → `400 INVALID_DOWNLOAD_FORMAT`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Antwoorden**

- `200`: De bytes van het artefact. De `X-*`-headers beschrijven de geleverde bytes; leg ze vast voor uw archief.

`application/xml`

```json
{
  "type": "string"
}
```

`application/pdf`

```json
{
  "type": "string",
  "format": "binary"
}
```

- `202`: `202 TASK_NOT_READY`: nog in verwerking. De body is een foutenvelop, geen bestand. Blijf de taakstatus opvragen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `400`: Ongeldig verzoek. Niet opnieuw proberen: corrigeer het verzoek. Zie `ErrorEnvelope.code` voor alle 400-codes.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 TASK_NOT_FOUND`: onbekende taak, taak van een andere tenant, taak die niet via deze API is geaccepteerd, 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `405 METHOD_NOT_ALLOWED`: taakpaden accepteren alleen GET. Wordt door de edge-proxy verstuurd, dus de body bevat geen `correlation_id`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: `409`: de taak is om een tijdelijke reden mislukt en kan niet herstellen; deze aanvraag herhalen lukt nooit. Start een nieuwe conversie met een nieuwe Idempotency-Key. Codes: `ARTIFACT_GENERATION_RERUN_REQUIRED` (reden in `details.code`, bijvoorbeeld `AUTHORITATIVE_VALIDATION_UNAVAILABLE`), `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: De factuur kan niet worden uitgegeven. Niet opnieuw proberen: corrigeer de gegevens of het brondocument en start een nieuwe conversie. Codes: `VALIDATION_FAILED` (`details.items`), `DOCUMENT_NOT_CONVERTIBLE` (`details.code`, `details.recovery_hint`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`, `PROTECTED_BANK_DETAILS_MISMATCH` (`details.items`).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: de edge kon de backend niet bereiken. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Tijdelijk niet beschikbaar. Probeer het opnieuw met backoff: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: de backend antwoordde niet op tijd. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id}/validation-report — Het validatierapport downloaden

Download het validatierapport dat aan het geleverde artefact is gekoppeld.

- `download=html` voor mensen; `download=xml` voor het KoSIT-rapport, of Factur-X-`validation-evidence`-XML (`source="facturx_php"`, geen KoSIT-formaat).
- De `X-Artifact-*`-headers beschrijven het gevalideerde resultaatartefact, niet de bytes van het rapport.
- Factur-X-bewijs toont alleen de validatie van de opgeslagen XML aan, niet de getrouwheid aan de bron of de PDF/A-conformiteit.
- Aanvraaglimiet: 30/min en 500/u per API-sleutel.

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | ja | `task_id` uit het `202`-antwoord. Geen UUID → `400 BAD_REQUEST`. |
| `download` | query | string: `html`, `xml` | ja | `html` voor een leesbaar rapport, `xml` voor het machineleesbare rapport. Ontbreekt → `400 DOWNLOAD_FORMAT_REQUIRED`; andere waarden → `400 INVALID_DOWNLOAD_FORMAT`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Antwoorden**

- `200`: Het rapport.

`text/html`

```json
{
  "type": "string"
}
```

`application/xml`

```json
{
  "type": "string"
}
```

- `202`: `202 TASK_NOT_READY`: nog in verwerking. De body is een foutenvelop, geen bestand. Blijf de taakstatus opvragen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `400`: Ongeldig verzoek. Niet opnieuw proberen: corrigeer het verzoek. Zie `ErrorEnvelope.code` voor alle 400-codes.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `405 METHOD_NOT_ALLOWED`: taakpaden accepteren alleen GET. Wordt door de edge-proxy verstuurd, dus de body bevat geen `correlation_id`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: `409`: de taak is om een tijdelijke reden mislukt en kan niet herstellen; deze aanvraag herhalen lukt nooit. Start een nieuwe conversie met een nieuwe Idempotency-Key. Codes: `ARTIFACT_GENERATION_RERUN_REQUIRED` (reden in `details.code`, bijvoorbeeld `AUTHORITATIVE_VALIDATION_UNAVAILABLE`), `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: De factuur kan niet worden uitgegeven. Niet opnieuw proberen: corrigeer de gegevens of het brondocument en start een nieuwe conversie. Codes: `VALIDATION_FAILED` (`details.items`), `DOCUMENT_NOT_CONVERTIBLE` (`details.code`, `details.recovery_hint`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`, `PROTECTED_BANK_DETAILS_MISMATCH` (`details.items`).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: de edge kon de backend niet bereiken. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Tijdelijk niet beschikbaar. Probeer het opnieuw met backoff: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: de backend antwoordde niet op tijd. Probeer het opnieuw met backoff en dezelfde Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id}/correction-result — De gecorrigeerde factuur downloaden

Download de gekoppelde correctie nadat een bedrijfslid deze in de webeditor heeft afgerond. De oorspronkelijke API-sleutelrechten en bewaartermijn gelden. Downloaden verandert het oorspronkelijke resultaat niet en kost geen extra eenheid. Limiet: 60/min en 1,000/h.

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | ja | `task_id` uit het `202`-antwoord. Geen UUID → `400 BAD_REQUEST`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Antwoorden**

- `200`: Bestand van de gevalideerde gecorrigeerde factuur.

`application/xml`

```json
{
  "type": "string",
  "format": "binary"
}
```

`application/pdf`

```json
{
  "type": "string",
  "format": "binary"
}
```

- `400`: Ongeldig verzoek. Niet opnieuw proberen: corrigeer het verzoek. Zie `ErrorEnvelope.code` voor alle 400-codes.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: Correctie niet beschikbaar, verlopen, niet voltooid of niet meer geldig. Lees `code` voordat u opnieuw probeert.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `409`: Correctie niet beschikbaar, verlopen, niet voltooid of niet meer geldig. Lees `code` voordat u opnieuw probeert.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: Correctie niet beschikbaar, verlopen, niet voltooid of niet meer geldig. Lees `code` voordat u opnieuw probeert.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: Correctie niet beschikbaar, verlopen, niet voltooid of niet meer geldig. Lees `code` voordat u opnieuw probeert.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Correctie niet beschikbaar, verlopen, niet voltooid of niet meer geldig. Lees `code` voordat u opnieuw probeert.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /webhook-endpoint — Webhook-endpoint opvragen

Geeft de geregistreerde URL en het resultaat van de laatste afleverpoging terug. Het secret wordt nooit teruggegeven.

- Aanvraaglimiet: 30/min en 300/u per API-sleutel, gedeeld door `POST`, `GET`, `DELETE /webhook-endpoint`.

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Antwoorden**

- `200`: Het geregistreerde endpoint.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookEndpoint"
}
```

- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 WEBHOOK_ENDPOINT_NOT_FOUND`. Voor het bedrijf van de API-sleutel is geen endpoint geregistreerd.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Tijdelijk niet beschikbaar. Probeer opnieuw met backoff: `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### POST /webhook-endpoint — Webhook-endpoint registreren of vervangen

Registreert het HTTPS-endpoint dat de voltooiingsgebeurtenissen van het bedrijf van de API-sleutel ontvangt, of vervangt het. Het antwoord bevat het ondertekeningsgeheim `secret`; het wordt nooit opnieuw getoond.

- Een nieuw endpoint geeft `201`, een vervanging `200`. Een vervanging roteert het secret direct: gebeurtenissen die nog wachten, gaan naar de nieuwe URL en worden met het nieuwe secret ondertekend.
- De URL moet `https` op poort 443 gebruiken en een openbare DNS-host noemen (zie *Webhooks* in de gids); anders `422 INVALID_WEBHOOK_URL` met `details.reason`.
- Een `Idempotency-Key` is niet nodig. Een herhaalde aanroep vervangt het endpoint en roteert het secret opnieuw.
- Aanvraaglimiet: 30/min en 300/u per API-sleutel, gedeeld door `POST`, `GET`, `DELETE /webhook-endpoint`.

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Antwoorden**

- `200`: Het endpoint is vervangen en het secret geroteerd.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookEndpointCreated"
}
```

- `201`: Het endpoint is geregistreerd.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookEndpointCreated"
}
```

- `400`: Ongeldig verzoek. Niet opnieuw proberen: corrigeer het verzoek. Zie `ErrorEnvelope.code` voor alle 400-codes.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `413`: 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).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

`text/plain`

```json
{
  "type": "string"
}
```

- `422`: `422 INVALID_WEBHOOK_URL`. Niet opnieuw proberen: stuur een URL die de regels onder *Webhooks* volgt. `details.reason` noemt de regel: `scheme`, `port`, `userinfo`, `fragment`, `ip_literal`, `host`, `characters`, `length`, `syntax`, `dns_failed` of `address_not_allowed`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Tijdelijk niet beschikbaar. Probeer opnieuw met backoff: `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### DELETE /webhook-endpoint — Webhook-endpoint verwijderen

Verwijdert het endpoint en elke gebeurtenis die nog op aflevering wacht. Polling blijft werken.

- Aanvraaglimiet: 30/min en 300/u per API-sleutel, gedeeld door `POST`, `GET`, `DELETE /webhook-endpoint`.

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Antwoorden**

- `204`: Het endpoint is verwijderd.
- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 WEBHOOK_ENDPOINT_NOT_FOUND`. Voor het bedrijf van de API-sleutel is geen endpoint geregistreerd.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Tijdelijk niet beschikbaar. Probeer opnieuw met backoff: `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### POST /webhook-endpoint:test — Testgebeurtenis versturen

Zet een ondertekende `webhook.test`-gebeurtenis in de wachtrij voor het geregistreerde endpoint. De aflevering volgt de normale regels en nieuwe pogingen; `GET /webhook-endpoint` toont het resultaat.

- Aanvraaglimiet: 5/min en 50/u per API-sleutel.

**Parameters**

| Naam | Locatie | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- | --- |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Antwoorden**

- `202`: De testgebeurtenis staat in de wachtrij.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookTestQueued"
}
```

- `401`: Authenticatie mislukt. Niet opnieuw proberen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Niet opnieuw proberen: activeer een Enterprise-abonnement via `details.action_url` of neem contact op met support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 WEBHOOK_ENDPOINT_NOT_FOUND`. Voor het bedrijf van de API-sleutel is geen endpoint geregistreerd.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Tijdelijk niet beschikbaar. Probeer opnieuw met backoff: `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

## Schema’s

### `ConvertInvoiceRequest`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "CustomizationID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Customizationid"
    },
    "ProfileID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Profileid"
    },
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "IssueDate": {
      "title": "Issuedate",
      "type": "string"
    },
    "DueDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Duedate"
    },
    "TaxCurrencyCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxcurrencycode"
    },
    "TaxPointDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxpointdate"
    },
    "InvoicePeriod": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "InvoiceTypeCode": {
      "title": "Invoicetypecode",
      "type": "string"
    },
    "DocumentCurrencyCode": {
      "title": "Documentcurrencycode",
      "type": "string"
    },
    "OrderReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_OrderReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "SalesOrderReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_SalesOrderReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "ContractDocumentReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_ContractDocumentReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "ProjectReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_ProjectReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "TenderOrLotReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_TenderOrLotReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "DespatchDocumentReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Despatchdocumentreference"
    },
    "PrecedingInvoiceReference": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_PrecedingInvoiceReference"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Precedinginvoicereference"
    },
    "AdditionalDocumentReference": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_AdditionalDocumentReference"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Additionaldocumentreference"
    },
    "AdvancePaymentSettlement": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_AdvancePaymentSettlementRow"
          },
          "maxItems": 200,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Advancepaymentsettlement"
    },
    "UninvoicedPrepaidAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Reeds ontvangen brutobetaling zonder voorschotfactuur. Inbegrepen in BT-113 naast de genummerde AdvancePaymentSettlement-regels en afzonderlijk vermeld in de verrekeningsbijlage. Neem dit bedrag niet ook op in een genummerde voorschotregel.",
      "title": "Uninvoicedprepaidamount"
    },
    "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"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "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`

```json
{
  "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_accounts": {
      "type": "array",
      "maxItems": 5,
      "description": "Opgeslagen rekeningen van de begunstigde, in uitvoervolgorde. Elke IBAN moet geldig en uniek zijn. Als stamgegevens gelden, vervangt een niet-lege lijst alle geëxtraheerde overschrijvingsrekeningen (codes 30/42/58); andere betaalwijzen behouden hun selectieregels.",
      "items": {
        "type": "object",
        "required": [
          "iban"
        ],
        "additionalProperties": false,
        "properties": {
          "iban": {
            "type": "string",
            "maxLength": 34,
            "description": "Geldige IBAN van de begunstigde (BT-84), genormaliseerd zonder spaties."
          },
          "bic": {
            "type": "string",
            "maxLength": 11,
            "description": "BIC van de bank van de begunstigde (BT-86), indien opgegeven 8 of 11 tekens."
          },
          "account_name": {
            "type": "string",
            "maxLength": 240,
            "description": "Naam van de rekeninghouder (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_accounts": [
        {
          "iban": "DE02120300000000202051"
        }
      ]
    }
  ]
}
```

### `ConvertAcceptedResponse`

```json
{
  "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=<primary_result_format>`."
    },
    "client_reference": {
      "type": "string",
      "description": "Teruggave van `client_reference`."
    },
    "source_system": {
      "type": "string",
      "description": "Teruggave van `source_system`."
    }
  },
  "additionalProperties": false
}
```

### `TaskStatusResponse`

```json
{
  "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"
    },
    "review_url": {
      "type": "string",
      "format": "uri",
      "description": "Open de factuurcorrectie in de webapp. Vereist toegang tot het bedrijf."
    },
    "correction": {
      "type": [
        "object",
        "null"
      ],
      "description": "Gekoppelde correctie, indien gestart.",
      "required": [
        "status",
        "run_id",
        "item_id"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "review_required",
            "reviewing",
            "completed",
            "expired"
          ]
        },
        "run_id": {
          "type": "string",
          "format": "uuid"
        },
        "item_id": {
          "type": "string",
          "format": "uuid"
        },
        "result_url": {
          "type": "string",
          "description": "Relatieve download-URL, alleen aanwezig voor een voltooide en bewaarde correctie."
        }
      },
      "additionalProperties": false
    },
    "applied_values": {
      "type": "array",
      "description": "Aanwezig bij een voltooide taak waarvan het resultaat nog is opgeslagen. Waarden die de dienst heeft ingesteld in plaats van ze uit het document te lezen: waarden uit de stamgegevens van de verkoper en afgeleide waarden. Leeg wanneer niets is ingesteld. Zie *Toegepaste waarden*.",
      "items": {
        "$ref": "#/components/schemas/AppliedValue"
      }
    }
  },
  "additionalProperties": false
}
```

### `ResultArtifacts`

```json
{
  "type": "object",
  "description": "Downloadgereedheid per artefact.",
  "properties": {
    "xml": {
      "$ref": "#/components/schemas/ResultArtifactStatus"
    },
    "pdf": {
      "$ref": "#/components/schemas/ResultArtifactStatus"
    }
  },
  "additionalProperties": false
}
```

### `ResultArtifactStatus`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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",
        "IDEMPOTENCY_KEY_ALREADY_USED",
        "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",
        "DOCUMENT_NOT_CONVERTIBLE",
        "PROFILE_MISMATCH",
        "ZUGFERD_SOURCE_PDF_INCOMPATIBLE",
        "PROTECTED_BANK_DETAILS_MISMATCH",
        "ZUGFERD_CII_CONVERSION_FAILED",
        "ZUGFERD_PDF_GENERATION_FAILED",
        "XML_GENERATION_FAILED",
        "PDF_GENERATION_FAILED",
        "ARTIFACT_GENERATION_RERUN_REQUIRED",
        "EXTRACTION_INCOMPLETE_GROUP_FAILURE",
        "INTERNAL_ARTIFACT_INVARIANT_FAILED",
        "VALIDATION_REPORT_NOT_FOUND",
        "VALIDATION_REPORT_FAILED",
        "PROXY_ERROR",
        "INVALID_WEBHOOK_URL",
        "WEBHOOK_ENDPOINT_NOT_FOUND",
        "WEBHOOK_STORE_UNAVAILABLE",
        "CORRECTION_RESULT_UNAVAILABLE"
      ],
      "x-enumDescriptions": {
        "AUTHENTICATION_REQUIRED": "401 · nee · Stuur `Authorization: Bearer <api_key>`.",
        "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. Activeer een Enterprise-abonnement via `details.action_url` of 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 via `details.action_url` 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.",
        "IDEMPOTENCY_KEY_ALREADY_USED": "409 · nee · De sleutel is al gebruikt voor een voltooide conversie, en de replaygegevens daarvan zijn na 24 uur verlopen. Gebruik een nieuwe sleutel voor een nieuwe conversie.",
        "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`, de multipart-body of een webhook-body (8 KB) 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, GET op taakpaden en de methoden van de webhookpaden (zie `Allow`).",
        "NOT_FOUND": "404 · nee · Onbekend pad onder /api/v1.",
        "BAD_REQUEST": "400 · nee · `task_id` moet een UUID zijn, of een webhook-body is niet het JSON-object `{\"url\": \"...\"}`.",
        "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. Bij `/tasks/{task_id}` en `/result` ook een taak die niet via deze API is geaccepteerd.",
        "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.",
        "DOCUMENT_NOT_CONVERTIBLE": "422 · nee · Het brondocument kan zo niet worden geconverteerd (reden in `details.code`, volgende stap in `details.recovery_hint`). Corrigeer het document 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`.",
        "PROTECTED_BANK_DETAILS_MISMATCH": "422 · nee · Een IBAN van de begunstigde (BT-84) hoort niet bij de bankrekeningen die het controleadres van het account beschermt. Er is geen bestand uitgegeven en geen eenheid gebruikt. Corrigeer het IBAN in het brondocument of voeg de rekening toe in het profiel (het controleadres moet dit bevestigen) en start daarna een nieuwe conversie.",
        "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.",
        "ARTIFACT_GENERATION_RERUN_REQUIRED": "409 · nieuwe taak · Er is geen artefact uitgegeven: generatie of gezaghebbende validatie is mislukt na nieuwe pogingen door de server (reden in `details.code`, bijvoorbeeld `AUTHORITATIVE_VALIDATION_UNAVAILABLE`). Start een nieuwe conversie met een nieuwe Idempotency-Key.",
        "EXTRACTION_INCOMPLETE_GROUP_FAILURE": "409 · nieuwe taak · Extractiegroepen zijn mislukt (`details.failed_groups`). Start een nieuwe conversie met een nieuwe Idempotency-Key.",
        "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.",
        "CORRECTION_RESULT_UNAVAILABLE": "400/404/409/410/422/503 · voorwaardelijk · Correctie niet beschikbaar of niet voltooid. Controleer de gekoppelde correctiestatus. Probeer tijdelijke fouten opnieuw; verlopen of verwijderde invoer moet opnieuw worden ingediend.",
        "INVALID_WEBHOOK_URL": "422 · nee · De webhook-URL overtreedt een regel onder *Webhooks*, of de host verwijst naar een niet-openbaar adres. Zie `details.reason`.",
        "WEBHOOK_ENDPOINT_NOT_FOUND": "404 · nee · Voor het bedrijf van de sleutel is geen webhook-endpoint geregistreerd.",
        "WEBHOOK_STORE_UNAVAILABLE": "503 · ja · De webhookconfiguratie kon niet worden gelezen of opgeslagen. Probeer opnieuw met backoff."
      },
      "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`

```json
{
  "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`

```json
{
  "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`, `access`, `message`."
    },
    "code": {
      "type": "string",
      "description": "Onderliggende foutcode: de reden bij `500 TASK_FAILED`, `422 DOCUMENT_NOT_CONVERTIBLE` en `409 ARTIFACT_GENERATION_RERUN_REQUIRED`; zie `x-enumDescriptions`.",
      "examples": [
        "MULTIPLE_INVOICES_IN_DOCUMENT",
        "NO_INVOICE_DETECTED",
        "INSUFFICIENT_INVOICE_SIGNAL",
        "EMBEDDED_INVOICE_XML_INVALID",
        "EMBEDDED_INVOICE_XML_UNREPRESENTABLE",
        "SOURCE_TEXT_UNAVAILABLE",
        "SCHEMA_PARSE_FAILED",
        "ARTIFACT_PARITY_FAILED",
        "PROVIDER_ERROR",
        "task_interrupted",
        "AUTHORITATIVE_VALIDATION_UNAVAILABLE"
      ],
      "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.",
        "EMBEDDED_INVOICE_XML_INVALID": "Definitief. Alleen met `use_embedded_xml=true`: de in de PDF ingesloten XML kon niet worden gelezen. Corrigeer deze in het uitgevende systeem of stuur de PDF zonder `use_embedded_xml`.",
        "EMBEDDED_INVOICE_XML_UNREPRESENTABLE": "Definitief. Alleen met `use_embedded_xml=true`: de ingesloten XML bevat een waarde die niet ongewijzigd kan worden overgenomen, bijvoorbeeld een datum die niet in formaat 102 (`YYYYMMDD`) staat. Corrigeer deze in het uitgevende systeem of stuur de PDF zonder `use_embedded_xml`.",
        "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.",
        "task_interrupted": "Opnieuw te proberen. De server die de conversie uitvoerde, stopte voordat deze klaar was. Er is geen artefact uitgegeven en geen eenheid gebruikt. Start een nieuwe conversie met een nieuwe sleutel.",
        "AUTHORITATIVE_VALIDATION_UNAVAILABLE": "Bij `409 ARTIFACT_GENERATION_RERUN_REQUIRED`: de validator of een andere artefactafhankelijkheid bleef ook na nieuwe pogingen door de server onbeschikbaar. Er is geen artefact uitgegeven en geen eenheid gebruikt. Start een nieuwe conversie met een nieuwe Idempotency-Key."
      }
    },
    "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": "Machineleesbare volgende stap: `start_new_conversion`, `fix_source_document`, `buy_api_credits` of `activate_api_access`."
    },
    "action_url": {
      "type": "string",
      "format": "uri",
      "description": "Pagina waar de accounthouder `402 INSUFFICIENT_API_CREDITS` (tegoed kopen) of `403 API_NOT_ENABLED_FOR_TENANT` (API-toegang activeren) oplost."
    },
    "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`

```json
{
  "type": "object",
  "description": "Eén blokkerend validatieprobleem.",
  "properties": {
    "field": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pad van het factuurveld, bijvoorbeeld `BuyerReference`."
    },
    "business_term": {
      "type": [
        "string",
        "null"
      ],
      "description": "EN 16931-bedrijfsterm van het veld, indien bekend, bijvoorbeeld `BT-10`."
    },
    "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. Voor een regel die alleen een bedrag vermeldt, beschrijft het het voorstel in `proposal`."
    },
    "proposal": {
      "type": [
        "object",
        "null"
      ],
      "description": "Alleen aanwezig bij de bevindingen van een regel die alleen zijn nettobedrag (BT-131) vermeldt, zonder hoeveelheid en eenheidsprijs: hoeveelheid 1, eenheid `C62` en eenheidsprijs = nettobedrag, wat juist is voor een vast bedrag of één artikel. Een voorstel, geen conversie: als de factuur een hoeveelheid en prijs toont, stuur die; bevestig anders het voorstel door deze waarden in een nieuwe conversie te sturen. Ontbreekt bij een regel met een fysieke eenheid, een korting of toeslag, een prijskorting, een basishoeveelheid anders dan 1 of een negatief bedrag.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "amount_only_line"
          ]
        },
        "requires_confirmation": {
          "type": "boolean",
          "description": "Altijd `true`: er wordt niets toegepast voordat de aanroeper de waarden stuurt."
        },
        "line_index": {
          "type": "integer",
          "description": "Positie van de regel in `InvoiceLine` (of `CreditNoteLine`), vanaf nul."
        },
        "line_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "De regel-ID (BT-126)."
        },
        "values": {
          "type": "object",
          "description": "Voorgestelde waarden per regelpad: `InvoicedQuantity` (of `CreditedQuantity`) `1`, de `@unitCode` daarvan `C62` en `Price.PriceAmount` gelijk aan het nettobedrag van de regel.",
          "additionalProperties": {
            "type": "string"
          },
          "examples": [
            {
              "InvoicedQuantity": "1",
              "InvoicedQuantity.@unitCode": "C62",
              "Price.PriceAmount": "250"
            }
          ]
        }
      },
      "required": [
        "kind",
        "requires_confirmation",
        "line_index",
        "values"
      ]
    },
    "message": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": true
}
```

### `InsufficientApiCreditsPrepaidError`

```json
{
  "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",
        "recovery",
        "action_url"
      ],
      "properties": {
        "type": {
          "type": "string",
          "const": "context"
        },
        "remaining": {
          "type": "integer",
          "description": "Resterend prepaid tegoed."
        },
        "minimum_purchase": {
          "type": "integer",
          "description": "Kleinste tegoedpakket (100)."
        },
        "recovery": {
          "type": "string",
          "const": "buy_api_credits"
        },
        "action_url": {
          "type": "string",
          "format": "uri",
          "description": "Profielpagina waar API-tegoedpakketten worden verkocht."
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}
```

### `InsufficientApiCreditsAllowanceError`

```json
{
  "type": "object",
  "description": "402-vorm voor accounts met een afgedwongen inbegrepen 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",
        "included_remaining",
        "credit_remaining",
        "shortfall",
        "minimum_purchase",
        "recovery",
        "action_url"
      ],
      "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)."
        },
        "recovery": {
          "type": "string",
          "const": "buy_api_credits"
        },
        "action_url": {
          "type": "string",
          "format": "uri",
          "description": "Profielpagina waar API-tegoedpakketten worden verkocht."
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}
```

### `StructuredInvoice_AccountingCustomerParty`

```json
{
  "additionalProperties": false,
  "properties": {
    "Party": {
      "$ref": "#/components/schemas/StructuredInvoice_Party"
    }
  },
  "required": [
    "Party"
  ],
  "title": "AccountingCustomerParty",
  "type": "object"
}
```

### `StructuredInvoice_AccountingSupplierParty`

```json
{
  "additionalProperties": false,
  "properties": {
    "Party": {
      "$ref": "#/components/schemas/StructuredInvoice_Party"
    }
  },
  "required": [
    "Party"
  ],
  "title": "AccountingSupplierParty",
  "type": "object"
}
```

### `StructuredInvoice_AdditionalDocumentReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "DocumentTypeCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Documenttypecode"
    },
    "DocumentDescription": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Documentdescription"
    },
    "Attachment": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_Attachment"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "AdditionalDocumentReference",
  "type": "object"
}
```

### `StructuredInvoice_AdvancePaymentSettlementRow`

```json
{
  "additionalProperties": false,
  "description": "Een ontvangen voorschot dat een cumulatieve eindfactuur in BT-113 aftrekt.\n\nDe regels zijn geen EN 16931-groep: de e-factuur bevat ze als pdf-afrekeningstabel in de bijlage\n(BG-24, ID \"advance-settlement\"). Geef alleen waarden op die op het voorschot zijn vermeld;\nde btw wordt nooit afgeleid uit het brutobedrag. De brutobedragen moeten samen BT-113 vormen.",
  "properties": {
    "ID": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Id",
      "type": "string"
    },
    "IssueDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Issuedate"
    },
    "NetAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Netamount"
    },
    "TaxPercent": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxpercent"
    },
    "TaxAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxamount"
    },
    "GrossAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Grossamount"
    }
  },
  "required": [
    "ID",
    "GrossAmount"
  ],
  "title": "AdvancePaymentSettlementRow",
  "type": "object"
}
```

### `StructuredInvoice_AllowanceCharge`

```json
{
  "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": "string"
        },
        {
          "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": [
        {
          "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`

```json
{
  "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": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Percent"
    },
    "TaxScheme": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxScheme"
    }
  },
  "required": [
    "ID",
    "TaxScheme"
  ],
  "title": "AllowanceChargeTaxCategory",
  "type": "object"
}
```

### `StructuredInvoice_Attachment`

```json
{
  "additionalProperties": false,
  "properties": {
    "EmbeddedDocumentBinaryObject": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_EmbeddedDocumentBinaryObject"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "ExternalReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_ExternalReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "Attachment",
  "type": "object"
}
```

### `StructuredInvoice_BuyersItemIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "BuyersItemIdentification",
  "type": "object"
}
```

### `StructuredInvoice_CardAccount`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "Percent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ItemClassificationCode": {
      "$ref": "#/components/schemas/StructuredInvoice_ItemClassificationCode"
    }
  },
  "required": [
    "ItemClassificationCode"
  ],
  "title": "CommodityClassification",
  "type": "object"
}
```

### `StructuredInvoice_Contact`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "ContractDocumentReference",
  "type": "object"
}
```

### `StructuredInvoice_Country`

```json
{
  "additionalProperties": false,
  "properties": {
    "IdentificationCode": {
      "title": "Identificationcode",
      "type": "string"
    }
  },
  "required": [
    "IdentificationCode"
  ],
  "title": "Country",
  "type": "object"
}
```

### `StructuredInvoice_Delivery`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "DespatchDocumentReference",
  "type": "object"
}
```

### `StructuredInvoice_EmbeddedDocumentBinaryObject`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "#text": {
      "title": "#Text",
      "type": "string"
    },
    "@schemeID": {
      "title": "@Schemeid",
      "type": "string"
    }
  },
  "required": [
    "#text",
    "@schemeID"
  ],
  "title": "EndpointID",
  "type": "object"
}
```

### `StructuredInvoice_ExternalReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "URI": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Uri"
    }
  },
  "title": "ExternalReference",
  "type": "object"
}
```

### `StructuredInvoice_FinancialInstitutionBranch`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "FinancialInstitutionBranch",
  "type": "object"
}
```

### `StructuredInvoice_InvoiceLine`

```json
{
  "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": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Invoicedquantity"
    },
    "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "StartDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Startdate"
    },
    "EndDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Enddate"
    },
    "DescriptionCode": {
      "anyOf": [
        {
          "enum": [
            "3",
            "35",
            "432"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Descriptioncode"
    }
  },
  "title": "InvoicePeriod",
  "type": "object"
}
```

### `StructuredInvoice_Item`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "IdentificationCode": {
      "title": "Identificationcode",
      "type": "string"
    }
  },
  "required": [
    "IdentificationCode"
  ],
  "title": "OriginCountry",
  "type": "object"
}
```

### `StructuredInvoice_Party`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "CompanyID": {
      "title": "Companyid",
      "type": "string"
    },
    "TaxScheme": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxScheme"
    }
  },
  "required": [
    "CompanyID",
    "TaxScheme"
  ],
  "title": "PartyTaxScheme",
  "type": "object"
}
```

### `StructuredInvoice_PayeeFinancialAccount`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "Party": {
      "$ref": "#/components/schemas/StructuredInvoice_Party"
    }
  },
  "required": [
    "Party"
  ],
  "title": "PayeeParty",
  "type": "object"
}
```

### `StructuredInvoice_PaymentMandate`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "Note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    },
    "PenaltySurchargePercent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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"
    },
    "DiscountDayBasis": {
      "anyOf": [
        {
          "enum": [
            "calendar_days_from_invoice_date",
            "working_days",
            "goods_receipt_or_other_anchor",
            "unknown"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Discountdaybasis"
    },
    "DiscountPercent": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "PriceAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Priceamount"
    },
    "BaseQuantity": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "ProjectReference",
  "type": "object"
}
```

### `StructuredInvoice_SalesOrderReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "SalesOrderReference",
  "type": "object"
}
```

### `StructuredInvoice_SellersItemIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "SellersItemIdentification",
  "type": "object"
}
```

### `StructuredInvoice_StandardItemIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "schemeID": {
      "default": "0160",
      "title": "Schemeid",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "StandardItemIdentification",
  "type": "object"
}
```

### `StructuredInvoice_TaxCategory`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "Percent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "TaxScheme",
  "type": "object"
}
```

### `StructuredInvoice_TaxSubtotal`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "TenderOrLotReference",
  "type": "object"
}
```

### `WebhookEndpointRequest`

```json
{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "`https`-URL op poort 443 met een openbare DNS-host. Een querystring is toegestaan; die wordt nooit gelogd."
    }
  },
  "additionalProperties": false
}
```

### `WebhookEndpointCreated`

```json
{
  "type": "object",
  "required": [
    "url",
    "secret",
    "created_at",
    "updated_at",
    "event_types",
    "correlation_id"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "secret": {
      "type": "string",
      "pattern": "^whsec_[A-Za-z0-9_-]{43}$",
      "description": "Ondertekeningsgeheim: `whsec_` en 32 willekeurige bytes. Alleen in dit antwoord zichtbaar."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Wanneer het endpoint voor het eerst is geregistreerd (UTC)."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Wanneer URL en secret voor het laatst zijn ingesteld (UTC)."
    },
    "event_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "conversion.succeeded",
          "conversion.failed"
        ]
      },
      "description": "De gebeurtenistypen die het endpoint ontvangt."
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
```

### `WebhookLastDelivery`

```json
{
  "type": [
    "object",
    "null"
  ],
  "required": [
    "at",
    "outcome",
    "status_code",
    "error",
    "event_id"
  ],
  "description": "De laatste afleverpoging, of `null` vóór de eerste.",
  "properties": {
    "at": {
      "type": "string",
      "format": "date-time",
      "description": "Wanneer de poging is vastgelegd (UTC)."
    },
    "outcome": {
      "type": "string",
      "enum": [
        "delivered",
        "retrying",
        "failed"
      ],
      "description": "`delivered`: een `2xx`-antwoord. `retrying`: de poging is mislukt en een volgende is gepland. `failed`: de laatste poging is mislukt en de gebeurtenis is opgegeven."
    },
    "status_code": {
      "type": [
        "integer",
        "null"
      ],
      "description": "HTTP-status van uw antwoord, als er een is aangekomen."
    },
    "error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Waarom de poging mislukte: `http_status`, `timeout`, `connection_failed`, `request_failed`, `dns_failed`, `address_not_allowed` of een andere URL-regel uit `INVALID_WEBHOOK_URL`."
    },
    "event_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "`id` van de gebeurtenis van die poging."
    }
  },
  "additionalProperties": false
}
```

### `WebhookEndpoint`

```json
{
  "type": "object",
  "required": [
    "url",
    "created_at",
    "updated_at",
    "event_types",
    "last_delivery",
    "correlation_id"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "event_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "conversion.succeeded",
          "conversion.failed"
        ]
      },
      "description": "De gebeurtenistypen die het endpoint ontvangt."
    },
    "last_delivery": {
      "$ref": "#/components/schemas/WebhookLastDelivery"
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
```

### `WebhookTestQueued`

```json
{
  "type": "object",
  "required": [
    "event_id",
    "type",
    "correlation_id"
  ],
  "properties": {
    "event_id": {
      "type": "string",
      "description": "`id` van de gebeurtenis in de wachtrij; het verzoek bevat die in `X-Invoice-Converter-Event-Id`."
    },
    "type": {
      "type": "string",
      "enum": [
        "webhook.test"
      ]
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
```

### `WebhookConversionEventData`

```json
{
  "type": "object",
  "required": [
    "task_id",
    "status",
    "created_at",
    "completed_at",
    "client_reference",
    "source_system",
    "format",
    "profile",
    "error"
  ],
  "description": "Dezelfde waarden die `GET /tasks/{task_id}` voor de taak teruggeeft, plus het gevraagde `format` en `profile`.",
  "properties": {
    "task_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "completed",
        "failed"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "client_reference": {
      "type": [
        "string",
        "null"
      ],
      "description": "Echo van `client_reference`."
    },
    "source_system": {
      "type": [
        "string",
        "null"
      ],
      "description": "Echo van `source_system`."
    },
    "format": {
      "type": [
        "string",
        "null"
      ],
      "description": "Het gevraagde `format`, bijvoorbeeld `XRECHNUNG`."
    },
    "profile": {
      "type": [
        "string",
        "null"
      ],
      "description": "Het geldende profiel, bijvoorbeeld `XRECHNUNG`."
    },
    "error": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "code"
      ],
      "description": "`null` bij `conversion.succeeded`. Bij `conversion.failed` de `code` die `GET /tasks/{task_id}/result` teruggeeft; roep die aan voor de details.",
      "properties": {
        "code": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}
```

### `WebhookTestEventData`

```json
{
  "type": "object",
  "required": [
    "test"
  ],
  "properties": {
    "test": {
      "type": "boolean",
      "enum": [
        true
      ]
    }
  },
  "additionalProperties": false
}
```

### `WebhookEvent`

```json
{
  "type": "object",
  "required": [
    "id",
    "type",
    "api_version",
    "created_at",
    "data"
  ],
  "description": "Body van een webhookverzoek, ondertekend zoals verzonden. Haal resultaten op via de taakendpoints.",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^evt_[0-9a-f]{32}$",
      "description": "Gebeurtenis-ID, ook in `X-Invoice-Converter-Event-Id`. Nieuwe pogingen behouden die."
    },
    "type": {
      "type": "string",
      "enum": [
        "conversion.succeeded",
        "conversion.failed",
        "webhook.test"
      ]
    },
    "api_version": {
      "type": "string",
      "enum": [
        "v1"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Wanneer de gebeurtenis is aangemaakt (UTC)."
    },
    "data": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/WebhookConversionEventData"
        },
        {
          "$ref": "#/components/schemas/WebhookTestEventData"
        }
      ]
    }
  },
  "additionalProperties": false
}
```

### `AppliedValue`

```json
{
  "type": "object",
  "required": [
    "field",
    "source",
    "code"
  ],
  "properties": {
    "field": {
      "type": "string",
      "description": "Controleveld van de waarde, bijvoorbeeld `Seller.City` of `Payment.Accounts.0.IBAN`."
    },
    "business_term": {
      "type": "string",
      "description": "EN 16931-bedrijfsterm, bijvoorbeeld `BT-37`. Ontbreekt wanneer het veld er geen heeft."
    },
    "source": {
      "type": "string",
      "enum": [
        "seller_master_data",
        "derived"
      ],
      "description": "Waar de uitgegeven waarde vandaan komt."
    },
    "code": {
      "type": "string",
      "description": "Redencode, zie *Toegepaste waarden*. Er kunnen codes bijkomen."
    },
    "previous_value": {
      "type": "string",
      "description": "De documentwaarde die is vervangen. Ontbreekt wanneer het document er geen bevatte."
    },
    "value": {
      "type": "string",
      "description": "De uitgegeven waarde. Ontbreekt wanneer een waarde is verwijderd."
    }
  },
  "additionalProperties": false
}
```

## Foutcodes

| Code | Beschrijving |
| --- | --- |
| `AUTHENTICATION_REQUIRED` | 401 · nee · Stuur `Authorization: Bearer <api_key>`. |
| `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. Activeer een Enterprise-abonnement via `details.action_url` of 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 via `details.action_url` 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. |
| `IDEMPOTENCY_KEY_ALREADY_USED` | 409 · nee · De sleutel is al gebruikt voor een voltooide conversie, en de replaygegevens daarvan zijn na 24 uur verlopen. Gebruik een nieuwe sleutel voor een nieuwe conversie. |
| `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`, de multipart-body of een webhook-body (8 KB) 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, GET op taakpaden en de methoden van de webhookpaden (zie `Allow`). |
| `NOT_FOUND` | 404 · nee · Onbekend pad onder /api/v1. |
| `BAD_REQUEST` | 400 · nee · `task_id` moet een UUID zijn, of een webhook-body is niet het JSON-object `{"url": "..."}`. |
| `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. Bij `/tasks/{task_id}` en `/result` ook een taak die niet via deze API is geaccepteerd. |
| `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. |
| `DOCUMENT_NOT_CONVERTIBLE` | 422 · nee · Het brondocument kan zo niet worden geconverteerd (reden in `details.code`, volgende stap in `details.recovery_hint`). Corrigeer het document 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`. |
| `PROTECTED_BANK_DETAILS_MISMATCH` | 422 · nee · Een IBAN van de begunstigde (BT-84) hoort niet bij de bankrekeningen die het controleadres van het account beschermt. Er is geen bestand uitgegeven en geen eenheid gebruikt. Corrigeer het IBAN in het brondocument of voeg de rekening toe in het profiel (het controleadres moet dit bevestigen) en start daarna een nieuwe conversie. |
| `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. |
| `ARTIFACT_GENERATION_RERUN_REQUIRED` | 409 · nieuwe taak · Er is geen artefact uitgegeven: generatie of gezaghebbende validatie is mislukt na nieuwe pogingen door de server (reden in `details.code`, bijvoorbeeld `AUTHORITATIVE_VALIDATION_UNAVAILABLE`). Start een nieuwe conversie met een nieuwe Idempotency-Key. |
| `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 409 · nieuwe taak · Extractiegroepen zijn mislukt (`details.failed_groups`). Start een nieuwe conversie met een nieuwe Idempotency-Key. |
| `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. |
| `CORRECTION_RESULT_UNAVAILABLE` | 400/404/409/410/422/503 · voorwaardelijk · Correctie niet beschikbaar of niet voltooid. Controleer de gekoppelde correctiestatus. Probeer tijdelijke fouten opnieuw; verlopen of verwijderde invoer moet opnieuw worden ingediend. |
| `INVALID_WEBHOOK_URL` | 422 · nee · De webhook-URL overtreedt een regel onder *Webhooks*, of de host verwijst naar een niet-openbaar adres. Zie `details.reason`. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` | 404 · nee · Voor het bedrijf van de sleutel is geen webhook-endpoint geregistreerd. |
| `WEBHOOK_STORE_UNAVAILABLE` | 503 · ja · De webhookconfiguratie kon niet worden gelezen of opgeslagen. Probeer opnieuw met backoff. |
