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. Ingesloten factuur-XML wordt standaard genegeerd; stel use_embedded_xml=true alleen in als uw integratie deze XML als primaire extractiebron accepteert. 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, hoofdletterongevoelig vergeleken. Elk formaat heeft een gesloten set toegestane waarden en één standaard: XRECHNUNG → [XRECHNUNG] (standaard XRECHNUNG); EN16931 → [EN16931] (standaard EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (standaard EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (standaard EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (standaard ZUGFERD_EN16931). ZUGFERD, FACTURX, FACTUR-X en FACTUR_X zijn aliassen voor ZUGFERD_EN16931; ZUGFERD-XRECHNUNG is een alias voor ZUGFERD_XRECHNUNG. Een waarde buiten de toegestane set geeft 422 OUTPUT_PROFILE_CONFLICT; een niet-herkende profielnaam geeft 422 INVALID_PROFILE met details.allowed_profiles; 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; email_input (vrije tekst, optioneel, alleen PDF-bronnen) — klantinstructies in elke taal, maximaal 10.000 tekens, aangeleverd zonder e-mailblokmarkeringen; alle AI-extractie- en correctiestappen ontvangen ze los van de brontekst van de factuur; niet te combineren met use_embedded_xml=true, onderdeel van de request-identiteit voor idempotentie en niet ondersteund door invoices:convert-structured; de standaard factuurvalidatie blijft gelden; 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; electronic_address en electronic_address_scheme moeten samen worden opgegeven of beide worden weggelaten; use_embedded_xml (boolean, optioneel, standaard false) — ingesloten Factur-X-, ZUGFeRD- of XRechnung-XML wordt genegeerd, tenzij de waarde expliciet true is; gebruik dit alleen als de integratie de ingesloten XML als primaire extractiebron accepteert. 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, hoofdletterongevoelig vergeleken. Elk formaat heeft een gesloten set toegestane waarden en één standaard: XRECHNUNG → [XRECHNUNG] (standaard XRECHNUNG); EN16931 → [EN16931] (standaard EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (standaard EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (standaard EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (standaard ZUGFERD_EN16931). Een waarde buiten de toegestane set geeft 422 OUTPUT_PROFILE_CONFLICT; een niet-herkende profielnaam geeft 422 INVALID_PROFILE met details.allowed_profiles; 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; electronic_address en electronic_address_scheme moeten samen worden opgegeven of beide worden weggelaten. Antwoord: 202 Accepted.

Poll de huidige status van een conversietaak. Retourneert pending (geaccepteerd en in de wachtrij, nog niet gestart), processing, completed of failed. Rate limit 10/min en 120/hour; dat is de bindende beperking voor polling: wacht na de geaccepteerde 202 ongeveer 20 seconden voor de eerste aanroep, bouw daarna af (20s, 30s, 45s, 60s en vanaf dan 60s) en stop bij 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; op een voltooide task is download=xml het verwacht beschikbare artefact, geen gegarandeerd artefact. Herhaalde downloads kunnen uit gecachte artefacten worden bediend wanneer het validatiebewijs nog actueel is. Tijdens verwerking retourneert het endpoint een 202 met de standaard foutenvelope ({"code":"TASK_NOT_READY","message":"Strict conversion is still processing. No validated artifact is available yet.","correlation_id":"<uuid>"}); blokkerende validatiefouten retourneren 422 VALIDATION_FAILED, retrybare ontbrekende afhankelijkheden 503, definitieve conversiefouten 500 TASK_FAILED met de reden in details.code, en artefact-invariantfouten 500 INTERNAL_ARTIFACT_INVARIANT_FAILED, telkens zonder bestand. Geslaagde downloads bevatten X-Correlation-ID, Content-Disposition, Cache-Control: no-store, X-Artifact-Sha256, X-Validation-Proof-Id, X-Artifact-Proof-Id, X-Artifact-State, X-Validation-State, X-Proof-Status en X-Validator-Bundle-Id; X-Task-Id wordt op dit endpoint niet gezet. Rate limit 10/min en ongeveer 134/hour. 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 het rapport voor het huidige gevalideerde resultaatartefact. Het rapport is pas beschikbaar nadat strikte conversie een artefact met actueel bewijs heeft opgeslagen; anders retourneert het endpoint 202 of 404. Responseheaders identificeren het artefact en rapportbewijs. X-Artifact-Sha256 verwijst naar het resultaatartefact, niet naar het rapportbestand. Rate limit: 10/min en 120/uur. Verzoek: geen (GET); task_id (pad, verplicht) — UUID die een conversie-endpoint retourneert; download (query, optioneel) — html of xml. Antwoord: 200 OK.

seller_master_data behandelt electronic_address en electronic_address_scheme nu als één optioneel paar. Geef beide velden op of laat beide weg; een onvolledig paar geeft 400 INVALID_SELLER_MASTER_DATA terug.

Correctie van de prijsdocumentatie: 1.000 prepaid credits kosten 400 EUR (0,40 EUR per credit). Pakketten van 100, 200 en 500 credits blijven 50, 100 en 250 EUR kosten. De toegepaste prijzen en bestaande aankopen blijven ongewijzigd.

Documentconversie negeert ingesloten factuur-XML nu standaard. Stel use_embedded_xml=true alleen in als de integratie de ingesloten XML expliciet als primaire extractiebron accepteert. E-mailimport negeert ingesloten factuur-XML altijd. Een wijziging van use_embedded_xml wijzigt de idempotency-hash van de request; gebruik een nieuwe Idempotency-Key wanneer u deze optie wijzigt.

Als verkoperstamgegevens een veld vullen, blijven resterende extractievlaggen zichtbaar maar blokkeren ze strikte e-mailimport of de External API niet meer. Koper, regels, btw, levering, vervaldatum, korting, omschrijving, niet-ingevulde profielvelden en ongeldige profielwaarden blijven blokkerend.

Enterprise werd direct te koop voor EUR 50/maand of EUR 420/jaar. Enterprise bevat 100 gedeelde E-mail/API-conversies per maand; extra conversies gebruiken prepaid credits van EUR 0,40–0,50. API-sleutels vereisen geen handmatige goedkeuring meer.

De actuele foutencatalogus en retries per code zijn gepubliceerd. Een status 500 is niet automatisch retrybaar; controleer code, details.code en details.retryable. Beide details-vormen voor 402 INSUFFICIENT_API_CREDITS en de verschillende herstelpaden voor 409-idempotency zijn gedocumenteerd. Bewijsheaders van het validatierapport, 24 uur bewaring, tasktimeouts en rate limits per endpoint zijn gepubliceerd. De gesloten format/profieltabel is gepubliceerd en de uitleg voor downloaden, METHOD_NOT_ALLOWED en PROFILE_MISMATCH is gecorrigeerd.

API-conversie wijst een bevestigde bron met meerdere facturen nu definitief af met MULTIPLE_INVOICES_IN_DOCUMENT. Splits bevestigde multi-factuurbestanden. Een onzeker signaal retourneert in plaats daarvan 422 VALIDATION_FAILED voor controle.

Ingeschakelde verkoperstamdata vervangt nu overeenkomende geëxtraheerde verkopers- of betaalwaarden. Ontbrekende profielvelden laten geëxtraheerde waarden ongewijzigd; verschillen blijven niet-blokkerende controlewaarschuwingen.

Vervangen door 2026-07-26: verkoperstamdata vervangt nu overeenkomende geëxtraheerde waarden in plaats van alleen ontbrekende waarden aan te vullen.

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.

Ingestuurde factuurdata is nu de databron voor hybride ZUGFeRD-uitvoer; deterministische opschoning en belastingnormalisatie blijven gelden. Tasks falen wanneer voortgang stopt of bij de limiet van 15 minuten, niet na een vaste timeout van vijf minuten.

Opslagfouten in gebruiksregistratie blokkeren geen gereed gevalideerd antwoord en kosten geen extra credit; mislukte events gaan naar reconciliatie.

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.

Strikte XML- en hybride PDF-artefacten kregen interne pariteitsdata; gebruik result_artifacts voor gereedheid en validatiestatus. De gedocumenteerde productie-base-URL werd https://www.invoice-converter.com/api/v1.

GET /api/v1/tasks/{task_id}/result haalt alleen op; de aanroep genereert, repareert of valideert geen bestanden. Strikte tasks eindigen pas nadat een gevalideerd artefact is opgeslagen; ontbrekend actueel bewijs faalt gesloten. External API-conversie staat vast op strikte uitgifte, zonder concept of waarschuwingsoverbrugging. Taskstatus kreeg result_artifacts-diagnostiek en gedocumenteerde delivery_channel-waarden.

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.

Taskstatus kreeg gereedheidsdiagnostiek voor XML/PDF-artefacten. Strikte resultaatdownloads leveren pas bestanden nadat servercontroles van het artefact slagen.

Geslaagde resultaatdownloads kregen server-side validatiebewijs voor het geretourneerde artefact. Ontbrekende validatie- of bewijsafhankelijkheden retourneren 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE. Downloads uit de cache worden alleen hergebruikt zolang hun opgeslagen validatiebewijs actueel blijft.

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.