# Externe API V1-documentatie Technisch documentatiepakket voor selfservice API-implementatie en review. Deze pagina vat het externe API-contract, het toegangsmodel en de integratiegrenzen samen. ## Overzicht Technisch documentatiepakket voor selfservice API-implementatie en review. Deze pagina vat het externe API-contract, het toegangsmodel en de integratiegrenzen samen. De API accepteert multipart-uploads, retourneert JSON-responses en gebruikt standaard HTTP-statuscodes en Bearer-authenticatie. Dien een PDF-factuur in, wacht op de asynchrone verwerking en haal daarna het gegenereerde resultaat op. Stuur een PDF-factuur naar één endpoint en Invoice-Converter verzorgt extractie, validatie en outputgeneratie. Het resultaat-endpoint geeft het gegenereerde bestand pas terug nadat de validatiepoorten slagen; anders retourneert het 422 VALIDATION_FAILED. > **Status: selfservice**: Basispad: /api/v1. Laatst gesynchroniseerd 2026-05-23. ## Belangrijkste mogelijkheden - Eén endpoint voor PDF-naar-XML-conversie - AI-ondersteunde extractie van factuurgegevens - Geautomatiseerde EN 16931- en KoSIT-validatie - Uitvoerformaten voor XRechnung, ZUGFeRD, UBL en CII - Asynchrone verwerking met polling, kleine facturen rond 30 seconden en grotere facturen tot 1-2 minuten - Idempotente writes voor veilige retries ## Leveringsartefacten Download machineleesbare integratieartefacten voor de Developer API. - [OpenAPI JSON](/developer-api/v1/openapi.json) - [Postman-collectie](/developer-api/v1/postman.json) - [API Playground](/developer-api/playground) ## Snelstart Drie API-aanroepen voltooien een conversie. Het convert-endpoint wordt aangeboden op /api/v1 en vereist authenticatie. ### POST /api/v1/invoices:convert (In ontwikkeling) PDF naar gestructureerde e-factuur converteren ### GET /api/v1/tasks/{task_id} (In ontwikkeling) Taskstatus pollen ### GET /api/v1/tasks/{task_id}/result (In ontwikkeling) Conversieresultaat downloaden ## Gesloten-beta-toegang aanvragen - Maak een account aan en open je profiel. - Koop vooraf betaalde API-credits of gebruik een Enterprise-plan met inbegrepen API-toegang. - Maak een API-sleutel in de sectie API-toegang. - Voer de eerste request uit met server-side credentials en beheer daarna gebruik en sleutelrotatie vanuit je profiel. ## Base-URL en API-sleutels - Productie-base-URL: `https://invoice-converter.com/api/v1`. - Gebruik dezelfde productie-API-host voor al het pilotverkeer: `https://invoice-converter.com/api/v1`. - Gebruik tijdens onboarding kleine fixture-aanvragen; geaccepteerde conversieaanvragen verbruiken API-credits. - Behandel sleutels als server-side secrets. Plaats ze niet in browser- of mobiele clients. ## Eerste succesvolle request Gebruik deze volgorde als minimale happy path nadat je een API-sleutel hebt aangemaakt. - Uploaden: `POST /api/v1/invoices:convert` met `Authorization`, `Idempotency-Key`, `file=@invoice.pdf` en `format=XRECHNUNG`. - Controleer elke `2-5 seconden`: `GET /api/v1/tasks/{task_id}` tot status `completed` of `failed` is. - Downloaden: `GET /api/v1/tasks/{task_id}/result` en sla `X-Correlation-ID` plus `X-Validation-Proof-Id` op wanneer aanwezig. - Voor ZUGFeRD PDF-output stuurt u `format=ZUGFERD`; het result endpoint levert standaard de hybride PDF. ## Veelgebruikte payloadvoorbeelden - `XRECHNUNG`: stuur `format=XRECHNUNG`; dit is de standaard als format ontbreekt. - `ZUGFERD`: stuur `format=ZUGFERD` voor een EN16931 ZUGFeRD/Factur-X hybride PDF. - `UBL`: stuur `format=UBL` voor EN16931 UBL XML. - `CII`: stuur `format=CII` voor EN16931 CII XML. ## Vereiste headers - Authorization: Bearer ## Auth-regels API-toegang is selfservice. Maak API-sleutels in je profiel, gebruik ze als Bearer-token en koop vooraf betaalde API-credits voor conversie-automatisering. - Sleutels zijn tenantgebonden en gebruiken het `icp_`-prefix. - Maak, roteer en trek API-sleutels in vanuit je profiel zodra External API-toegang is ingeschakeld. Kopieer nieuwe sleutels meteen, want plaintext sleutels worden maar één keer getoond. - Een ontbrekende of ongeldige sleutel retourneert `401`. - Aanroepen naar `/api/v1` krijgen automatisch een `X-Correlation-ID` wanneer die ontbreekt. - Schrijfaanroepen vereisen `Idempotency-Key`; houd deze waarde stabiel over retries. - Gebruik server-to-server-integratie vanuit uw backend. Browser-origin-toegang is in productie beperkt. ## Idempotency-contract - Stuur bij elke schrijfaanroep een `Idempotency-Key`. - Idempotency keys moeten overeenkomen met `[A-Za-z0-9._:-]+` en maximaal 200 tekens lang zijn. - Als u uw eigen key opgeeft, retourneert dezelfde key + identieke payload de gecachte response. - Dezelfde key + andere payload retourneert `409 IDEMPOTENCY_CONFLICT`. - Idempotency keys verlopen na `24 hours`. ## Endpoint-referentie Alle endpoints zijn beschikbaar onder /api/v1. Timeouts verschijnen als 504 en andere tijdelijke verbindingsfouten als 502; correlatie-ID’s helpen support om requests end-to-end te volgen. ### POST /api/v1/invoices:convert (In ontwikkeling) Upload een PDF-factuur en start asynchrone conversie. Retourneert een task_id voor polling. Verzoek: multipart/form-data. Antwoord: 202 Accepted. ### GET /api/v1/tasks/{task_id} (In ontwikkeling) Poll de huidige status van een conversietaak. Retourneert pending, processing, completed of failed. Bij failed bevat de response een error-veld met de reden. Verzoek: geen (GET). Antwoord: 200 OK. ### GET /api/v1/tasks/{task_id}/result (In ontwikkeling) Download het gegenereerde bestand. ZUGFERD-taken leveren standaard een EN16931 ZUGFeRD/Factur-X hybride PDF; andere formaten leveren standaard XML. Herhaalde downloads kunnen uit gecachte gegenereerde artefacten worden bediend. Als blokkerende validatieproblemen blijven bestaan, retourneert dit endpoint 422 VALIDATION_FAILED zonder bestandsbody. Verzoek: geen (GET). Antwoord: 200 OK. ## Uitvoerformatenmatrix | Formaat | Syntaxis | Versie / Profiel | Content-Type | Extensie | | --- | --- | --- | --- | --- | | XRECHNUNG | UBL 2.1 XML | XRechnung 3.0.2 | application/xml | .xml | | ZUGFERD | Standaard EN16931 hybride PDF/A-3; CII XML met download=xml | ZUGFeRD 2.4 / Factur-X 1.08 | application/pdf of application/xml | .pdf / .xml | | EN16931 | UBL 2.1 XML | EN 16931 | application/xml | .xml | | UBL | UBL 2.1 XML | OASIS UBL 2.1 | application/xml | .xml | | CII | UN/CEFACT CII XML | D16B | application/xml | .xml | ## Wijzigingslogboek Meest recente extern zichtbare API-wijzigingen. ### 2026-05-08 Prepaid External API-credits toegevoegd voor niet-Enterprise-tenants. 402 INSUFFICIENT_API_CREDITS gedocumenteerd voor tenants zonder Enterprise-facturering of prepaid credits. Bevestigd dat idempotente replays geen extra API-credits verbruiken. Conversieverzoeken vereenvoudigd tot bestand plus formaat; extractie-instellingen worden server-side beheerd. ### 2026-03-06 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. ### 2026-02-23 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. ### 2026-02-20 Statusresponses vereenvoudigd naar statusgerichte output. IndexNow-inzendvalidatie en authenticatiecontroles versterkt. API-toegangscontroles en request-limitinggedrag in productie verstevigd. ## Foutcontract | Code | HTTP | Opnieuw te proberen | Notities | | --- | --- | --- | --- | | AUTHENTICATION_REQUIRED | 401 | Nee | Bearer-token ontbreekt/is leeg | | INVALID_API_KEY | 401 | Nee | API-sleutel niet gevonden, ingetrokken of verlopen | | INSUFFICIENT_API_CREDITS | 402 | Nee | Koop minimaal 10 prepaid API-credits of gebruik Enterprise-facturering | | IDEMPOTENCY_KEY_REQUIRED | 400 | Nee | Schrijfendpoint aangeroepen zonder Idempotency-Key | | INVALID_IDEMPOTENCY_KEY | 400 | Nee | Idempotency key heeft een ongeldig formaat | | IDEMPOTENCY_CONFLICT | 409 | Nee | Zelfde key gebruikt met andere request-hash | | IDEMPOTENCY_IN_PROGRESS | 409 | Ja | Veilig later opnieuw proberen met dezelfde key/payload | | AUTH_SERVICE_UNAVAILABLE | 503 | Ja | Auth-backend niet beschikbaar | | RATE_LIMIT_SERVICE_UNAVAILABLE | 503 | Ja | Rate-limit-backend niet beschikbaar | | RATE_LIMITED | 429 | Ja | Respecteer Retry-After en quotaheaders | | BAD_REQUEST | 400 | Nee | Ongeldige JSON of ongeldig UUID-padparameter | | PAYLOAD_TOO_LARGE | 413 | Nee | Uploadgrootte overschrijdt limiet | | INVALID_UPLOAD | 400 | Nee | Upload lezen/parsen mislukt | | UPLOAD_FAILED | 4xx/5xx | Voorwaardelijk | Corrigeer ongeldige requestopties; probeer alleen opnieuw bij tijdelijke 5xx-gevallen | | TASK_NOT_READY | 202 | Ja | Poll opnieuw voor asynchrone voltooiing | | TASK_STATUS_FAILED | 4xx/5xx | Voorwaardelijk | Opnieuw proberen bij tijdelijke serviceconditie | | TASK_RESULT_FAILED | 4xx/5xx | Voorwaardelijk | Opnieuw proberen bij tijdelijke serviceconditie | | XML_GENERATION_FAILED | 500 | Ja | Tijdelijke XML-generatiefout of timeout | | PDF_GENERATION_FAILED | 500 | Ja | Tijdelijke PDF-generatiefout of timeout | | PROFILE_MISMATCH | 422 | Nee | Invoice CustomizationID conflicts with the selected public format | | PROXY_ERROR | 502/504 | Ja | Tijdelijke verbindingsfout (504 bij timeout) | ## Veelvoorkomende fouten en wat te doen - Opnieuw proberen met backoff: `429`, `500`, `502`, `503`, `504`. - Request of brondata corrigeren: `400`, `409`, `413`, `422`. - Toegang of credentials corrigeren: `401`, `403`. - Later blijven pollen: `202 TASK_NOT_READY`. - Bij `422 VALIDATION_FAILED` toont u het teruggegeven veld, de regel-ID en de voorgestelde oplossing aan een menselijke controleur voordat u opnieuw probeert met gecorrigeerde factuurdata. ## Rate- en payloadlimieten Rate limits per sleutel en payloadgroottebeperkingen gelden voor alle API-aanroepen. Geweigerde requests verbruiken geen quotum. - Endpointbewuste quota zijn kosten-gewogen. Convert gebruikt het basisplanquotum (standaard `30/min` en `500/hour`), terwijl polling-endpoints lager gewogen quota gebruiken. - Lees effectieve limieten uit `X-RateLimit-Limit-Minute` en `X-RateLimit-Limit-Hour` op responses. - Maximale PDF-uploadgrootte: `20 MB` - Maximale JSON-payloadgrootte: `1 MB` - Rate-limit-responses bevatten `Retry-After`, `X-RateLimit-Limit-Minute` en `X-RateLimit-Limit-Hour`. ## Retry-richtlijn - Gebruik exponentiële backoff met jitter. - Probeer alleen tijdelijke klassen (`429`, `500`, `502`, `503`, `504`) opnieuw, waar mogelijk met dezelfde payload en idempotency key. - Probeer validatie- of contractfouten (`400`, `401`, `403`, `409`, `413`) niet blind opnieuw. ## Taaklevenscyclus en bewaartermijn - Completed en failed tasks blijven `10 minutes` beschikbaar nadat ze een terminale status bereiken. - Verwerking krijgt een timeout na `5 minutes`; vastgelopen tasks worden automatisch als `failed` gemarkeerd. - Idempotency keys verlopen na `24 hours`. - Rate-limit-tellers resetten op een rollend venster. ## Supportmodel - Support tijdens kantooruren. - Doel voor eerste reactie: 1 werkdag. ## Stuur technische feedback Deel implementatievragen, risico’s en benodigde contractwijzigingen met ons team. - [Technische feedback e-mailen](mailto:contact@invoice-converter.com?subject=Technische%20reviewfeedback%20Externe%20API%20V1&body=Hallo%20Invoice-Converter-team%2C%0D%0A%0D%0AWij%20hebben%20de%20Externe%20API%20V1-documentatie%20beoordeeld%20en%20hebben%20de%20volgende%20feedback%3A%0D%0A%0D%0A1)%2520%0D%0A2)%2520%0D%0A3)%2520%0D%0A%0D%0AMet%20vriendelijke%20groet%2C) ## Postman en OpenAPI gebruiken - Importeer de Postman-collectie en stel `baseUrl`, `apiKey` en een nieuwe variabele `idempotencyKey` in. - Voer de collectie op volgorde uit: convert, status pollen, daarna result ophalen. - Gebruik de OpenAPI JSON om typed clients te genereren, maar dek file upload, polling en binaire result handling af met integratietests. - Leg `X-Correlation-ID` vast in logs zodat support requests end-to-end kan traceren.