Externe API V1-documentatie

Factuurdocument converteren

Gestructureerde data converteren

Taskstatus pollen

Upload een PDF-, DOCX- of TXT-factuurdocument en start asynchrone conversie. Retourneert een task_id voor polling. ZUGFeRD/Factur-X hybride PDF-downloads vereisen een PDF-bronupload; DOCX/TXT-bronnen moeten XML-resultaten aanvragen. Verzoek: multipart/form-data; file (binary, verplicht) — PDF-, DOCX- of TXT-factuurbrondocument; oude DOC/RTF-, afbeeldings- en andere bestanden worden geweigerd; format (string, verplicht) — doeluitvoerformaat; zie de formaatmatrix hieronder; profile (string, optioneel, aanbevolen voor deterministische integraties) — expliciet complianceprofiel. Standaardwaarden volgen het formaat; toegestane waarden zijn onder meer XRECHNUNG, PEPPOL, EN16931 en ondersteunde ZUGFeRD/Factur-X-profielen; jurisdiction (string, optioneel) — expliciete ISO 3166-1 alpha-2-jurisdictiecontext voor validatie-/adviescontroles; overschrijft het profiel niet; transaction_scope (string, optioneel) — expliciete transactiecontext, zoals B2G; toegepast op de queued task; delivery_channel (string, optioneel) — een van PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN; toegepast op de queued task; client_reference of external_invoice_id (string, optioneel) — factuur-/jobreferentie van de klant, teruggegeven in geaccepteerde uploads en taskstatusresponses; source_system (string, optioneel) — upstream ERP- of facturatiesysteemlabel, teruggegeven in geaccepteerde uploads en taskstatusresponses; use_seller_master_data (boolean, optioneel) — zonder waarde geldt de standaard uit het tenantprofiel; false negeert opgeslagen verkopersstamgegevens voor deze request, true levert/gebruikt verkopersstamgegevens; seller_master_data (JSON-objectstring, optioneel) — verkopersstamgegevens die alleen worden gebruikt wanneer use_seller_master_data=true; ondersteunt bedrijfs-, adres-, belasting-, contact- en betaalvelden (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); elke profielwaarde vervangt de overeenkomstige geëxtraheerde waarde, ontbrekende profielvelden blijven ongewijzigd en verschillen geven niet-blokkerende waarschuwingen. Antwoord: 202 Accepted.

Upload een drager-PDF met CSV-, JSON-, XML-, XLSX- of TXT-factuurdata en start asynchrone conversie vanuit gestructureerde data. De data_file-parts zijn de enige semantische bron; de PDF vult geen ontbrekende factuurvelden aan. Voor ZUGFeRD/Factur-X wordt de PDF gebruikt als drager-PDF, en bij XML-georiënteerde output wordt hij bewaard als ingediend PDF-artefact. Gebruik één conversierequest per factuur; herhaal data_file alleen voor gesplitste ERP-exports die dezelfde factuur beschrijven. Verzoek: multipart/form-data; pdf_file (binary, verplicht) — drager-PDF voor ZUGFeRD/Factur-X-insluiting en bewaring bij XML-georiënteerde output; data_file (binary, verplicht, herhaalbaar) — CSV-, JSON-, XML-, XLSX- of TXT-factuurdata als enige semantische bron; .xls, PDF’s en afbeeldingsbestanden worden als data_file geweigerd; herhaal voor gesplitste header-/regel-exports van dezelfde factuur; de aliassen data_files en data_files[] worden geaccepteerd; totale grootte gestructureerde data — maximaal 2 MB over alle data_file-parts; format (string, verplicht) — doeloutputformaat; ondersteunt XRECHNUNG, ZUGFERD, EN16931, UBL en CII; profile (string, optioneel, aanbevolen voor deterministische integraties) — expliciet complianceprofiel. Standaard op basis van format; jurisdiction (string, optioneel) — expliciete ISO 3166-1 alpha-2-jurisdictiecontext voor validatie-/adviescontroles; overschrijft het profiel niet; transaction_scope (string, optioneel) — expliciete transactiecontext, zoals B2G; toegepast op de queued task; delivery_channel (string, optioneel) — een van PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN; toegepast op de queued task; client_reference of external_invoice_id (string, optioneel) — factuur-/jobreferentie van de klant, teruggegeven in geaccepteerde uploads en taskstatusresponses; source_system (string, optioneel) — upstream ERP- of facturatiesysteemlabel, teruggegeven in geaccepteerde uploads en taskstatusresponses; use_seller_master_data (boolean, optioneel) — zonder waarde geldt de standaard uit het tenantprofiel; false negeert opgeslagen verkopersstamgegevens voor deze request, true levert/gebruikt verkopersstamgegevens; seller_master_data (JSON-objectstring, optioneel) — verkopersstamgegevens die alleen worden gebruikt wanneer use_seller_master_data=true; ondersteunt bedrijfs-, adres-, belasting-, contact- en betaalvelden (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); elke profielwaarde vervangt de overeenkomstige geëxtraheerde waarde, ontbrekende profielvelden blijven ongewijzigd en verschillen geven niet-blokkerende waarschuwingen. Antwoord: 202 Accepted.

Poll de huidige status van een conversietaak. Retourneert pending, processing, completed of failed. Voltooide taken bevatten result_artifacts-diagnostiek, zodat clients kunnen zien welke XML/PDF-artefacten beschikbaar, gecachet en met validatiebewijs onderbouwd zijn. Payloads van voltooide taken kunnen aanvullende _processing_warnings- en _validation_warnings-items met SOURCE_CONTEXT_*-regel-ID’s bevatten wanneer bronbewijs ontbrak, twijfelachtig of afgekapt was; behandel deze als beoordelingssignalen, niet als fouten. Bij failed bevat de response een error-veld met de reden. Verzoek: geen (GET); task_id (path, verplicht) — UUID die door het convert-endpoint is geretourneerd; include_validation_report_html (query, optioneel) — true of false (standaard false); bij true bevat de statusresponse het opgeschoonde HTML-validatierapport van het huidige strikte artefact wanneer dit beschikbaar is. Antwoord: 200 OK.

Download het gegenereerde bestand (XML of PDF). De resultaantsyntaxis komt overeen met het oorspronkelijke taskformaat: XRECHNUNG/EN16931/UBL retourneren UBL XML, CII/ZUGFERD retourneren CII XML, en ZUGFERD + download=pdf retourneert een hybride PDF/A-3. Bij andere formaten kan download=pdf een gerenderde PDF leveren. Herhaalde downloads kunnen uit gecachte artefacten worden bediend wanneer het validatiebewijs nog actueel is. Tijdens verwerking retourneert het endpoint 202 TASK_NOT_READY; blokkerende validatiefouten retourneren 422 VALIDATION_FAILED, retrybare ontbrekende afhankelijkheden 503 en artefact-invariantfouten 500, telkens zonder bestand. Verzoek: geen (GET); task_id (path, verplicht) — UUID die door het convert-endpoint is geretourneerd; download (query, verplicht) — xml of pdf. Antwoord: 200 OK.

Download the validation report tied to the current validated result artifact. The report is available only after strict conversion has produced a cached artifact with current validation proof, and returns 404 when no report is bound to the delivered artifact. Verzoek: none (GET); task_id (path, required) — UUID returned by the convert endpoint; download (query, optional) — html or xml. Antwoord: 200 OK.

When seller master data is enabled, every supplied profile value replaces the corresponding extracted seller or payment value. Fields absent from the profile remain unchanged. Source differences are non-blocking review warnings.

Documentatie-inhaalslag; geen wijziging in runtimegedrag. De foutcatalogus documenteert nu eerder ongedocumenteerde runtime-foutcodes, waaronder API_CREDIT_SERVICE_UNAVAILABLE, TASK_NOT_FOUND, INVALID_CLIENT_METADATA, INVALID_SELLER_MASTER_DATA, PROFILE_MISMATCH, ZUGFERD_SOURCE_PDF_REQUIRED, VALIDATION_REPORT_NOT_FOUND, VALIDATION_REPORT_FAILED, INVALID_QUERY_PARAMETER en METHOD_NOT_ALLOWED. Clients die foutresponses via het machineleesbare code-veld verwerken, hoeven niets te wijzigen; clients die op een vaste lijst codes schakelen, moeten de nieuw gedocumenteerde waarden toevoegen. Changelogdatums gecorrigeerd: ondersteuning voor DOCX/TXT-bronnen verscheen op 2026-06-30, niet op 2026-07-06.

Payloads van voltooide taken kunnen aanvullende _processing_warnings- en _validation_warnings-items met SOURCE_CONTEXT_*-regel-ID’s bevatten wanneer bronbewijs vóór extractie ontbrak, twijfelachtig of afgekapt was. Behandel SOURCE_CONTEXT_*-items als beoordelingssignalen voor klantzijdige uitzonderingsafhandeling; strikte artefactdownloads blijven onderworpen aan validatiebewijs en artefactcontroles.

Strikte ZUGFeRD-voorwaardefouten (ontbrekende verplichte velden voor hybride generatie) falen nu als 422 VALIDATION_FAILED met de blokkerende regel-ID’s in plaats van een herhaalbare 503; leid deze naar een datacorrectieflow, niet naar een retry-lus. Voor XML-only formaten (XRECHNUNG, EN16931, UBL, CII) is de PDF-weergave nu een best-effort gemaksartefact: download=xml blijft leidend en beschikbaar op voltooide taken, terwijl download=pdf onbeschikbaar kan zijn als de weergave na de XML-uitgifte mislukte. Conversies met onopgeloste blokkerende bronconflicten falen nu als 422 VALIDATION_FAILED met blocking_source_conflict-items in plaats van een artefact uit te geven.

POST /api/v1/invoices:convert accepteert nu PDF-, DOCX- en TXT-factuurbrondocumenten in het file-veld. Oude DOC-, RTF-, afbeeldings- en andere niet-ondersteunde bronbestanden worden geweigerd voordat de conversie start. ZUGFeRD/Factur-X hybride PDF-downloads vereisen nog steeds een PDF-bronupload; gebruik XML-downloads voor DOCX/TXT-bronconversies. Optionele include_validation_report_html=true toegevoegd op GET /api/v1/tasks/{task_id} om het opgeschoonde HTML-validatierapport inline te leveren wanneer beschikbaar. Conversie-uploads accepteren nu op beide endpoints optionele use_seller_master_data- en seller_master_data-velden, zodat goedgekeurde tenants opgeslagen of request-gebonden verkopersstamgegevens kunnen inschakelen.

GET /api/v1/tasks/{task_id}/validation-report?download=html|xml toegevoegd om het validatierapport op te halen dat aan het huidige strikte resultaatartefactbewijs is gekoppeld. Validatierapportresponses tonen task-ID, artefact-SHA-256, validatiebewijs-ID, rapportbewijs-ID, rapportcontenttype en correlatie-ID-headers.

External API-toegang is nu gedocumenteerd als goedgekeurde toegang in plaats van onbeperkte sleutelaanmaak. Verduidelijkt dat er geen formele SLA, servicecredit of contractuele boete geldt tenzij afgesproken in een order form. format is nu verplicht op beide conversie-endpoints; ontbrekende waarden retourneren 400 FORMAT_REQUIRED en niet-ondersteunde waarden 422 INVALID_FORMAT. download is nu verplicht op task-resultrequests; ontbrekende waarden retourneren 400 DOWNLOAD_FORMAT_REQUIRED en niet-ondersteunde waarden 400 INVALID_DOWNLOAD_FORMAT. Conversie-uploads accepteren nu client_reference/external_invoice_id en source_system voor klantzijdige reconciliatie. Geaccepteerde conversie- en taskstatusresponses bevatten nu status_url, primary_result_format, primary_result_url en meegestuurde reconciliatievelden.

Gestructureerde conversie accepteert nu alle publieke outputformaten: XRECHNUNG, ZUGFeRD, EN16931, UBL en CII. Gestructureerde conversie accepteert nu herhaalbare data_file-onderdelen plus de aliassen data_files en data_files[] voor gesplitste ERP-exports. Gestructureerde multi-file bundles moeten precies één factuur beschrijven en falen vroeg bij conflicterende of ontbrekende bundle-factuur-ID’s. Verduidelijkt dat meerdere factuurdocumenten als afzonderlijke conversietasks moeten worden ingestuurd, elk met een eigen idempotency key.

POST /api/v1/invoices:convert-structured toegevoegd voor conversie vanuit gestructureerde data met drager-PDF en CSV/JSON/XML/XLSX/TXT over ondersteunde outputformaten. Gedocumenteerd dat gestructureerde data op dit endpoint de enige semantische bron is; de PDF wordt gebruikt voor hybride insluiting. OpenAPI- en Postman-artefacten bijgewerkt voor gestructureerde conversie.

Prepaid External API-credits toegevoegd voor niet-Enterprise-tenants. 402 INSUFFICIENT_API_CREDITS gedocumenteerd voor goedgekeurde tenants zonder Enterprise-facturering per order form of prepaid credits. Bevestigd dat idempotente replays geen extra API-credits verbruiken. Verduidelijkt dat External API V1 modelrouting server-side beheert, terwijl profiel- en leveringscontext door de aanroeper worden bepaald.

Task-result-downloads formaatgetrouw gemaakt voor CII- en ZUGFERD-uitvoer. Hergebruik van gecachte resultaatartefacten toegevoegd voor herhaalde XML/PDF-downloads van dezelfde task. Pollingquota afgestemd op endpoint-gescopeerde gewogen rate-limit-buckets.

Duidelijkere, consistente API-foutresponses toegevoegd voor alle endpoints. Convert-opties uitgebreid en XML/PDF-downloadgedrag voor taskresultaten gedocumenteerd. Retryveiligheid verbeterd met strengere idempotency-vereisten en validatie. OpenAPI/Postman-artefacten bijgewerkt naar huidig API-gedrag.