Externe API V1-documentatie

Belangrijkste mogelijkheden#

Gebruik deze punten als praktische controles voor deze sectie.

• Upload-endpoints voor PDF-facturen en gestructureerde factuurdata
• AI-ondersteunde extractie van factuurgegevens
• Geautomatiseerde EN 16931- en KoSIT-validatie
• Uitvoerformaten voor XRechnung, ZUGFeRD, EN16931, 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.

Snelstart#

Drie API-aanroepen voltooien een conversie. Het convert-endpoint wordt aangeboden op /api/v1 en vereist authenticatie.

API-toegang krijgen#

Gebruik deze punten als praktische controles voor deze sectie.

• Maak een account aan en vraag API-toegang aan.
• Gebruik prepaid API-credits voor goedgekeurde tests of Enterprise-facturering per order form voor productiegebruik.
• Maak na goedkeuring een live API-sleutel aan voor je tenant.
• Verstuur de eerste request met Bearer-token en een stabiele Idempotency-Key.

Base-URL en API-sleutels#

Gebruik deze punten als praktische controles voor deze sectie.

• Productie-base-URL: https://www.invoice-converter.com/api/v1.
• Live-sleutels gebruiken de productiehost en het prefix icp_....
• Gebruik goedgekeurde live sleutels voor onboarding en validatieruns voordat u productievolume verstuurt.
• 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 10-15 seconden: GET /api/v1/tasks/{task_id} tot status completed of failed is.
• Downloaden: GET /api/v1/tasks/{task_id}/result?download=xml en sla X-Correlation-ID op voor support-tracing.
• Voor ZUGFeRD PDF-output vraagt u format=ZUGFERD bij convert en download=pdf bij result.
• Voor gestructureerde invoer roept u POST /api/v1/invoices:convert-structured aan met pdf_file=@invoice.pdf, data_file=@invoice-data.json en het doel-format.
• Stuur optioneel client_reference of external_invoice_id en source_system mee voor ERP-reconciliatie.
• Voor gesplitste ERP-exports van één factuur herhaalt u data_file; voor meerdere facturen start u één task per factuur met een eigen idempotency key.
• Sla result_artifacts uit de statusresponse op om te zien of XML/PDF-artefacten gevalideerd, gecachet of door afhankelijkheden nog niet beschikbaar zijn.

Veelgebruikte payloadvoorbeelden#

Gebruik deze punten als praktische controles voor deze sectie.

• XRECHNUNG: stuur format=XRECHNUNG.
• ZUGFERD: stuur format=ZUGFERD; gebruik download=pdf bij result voor de hybride PDF/A-3-output.
• Gestructureerde invoer: stuur pdf_file plus een of meer data_file-parts; geaccepteerde dataformaten zijn CSV, JSON, XML, XLSX en TXT, met elk ondersteund doelformaat. De data_file-parts moeten alle verplichte data bevatten; de PDF vult geen ontbrekende velden aan.
• Meerdere facturen: verstuur afzonderlijke convert-requests en volg elke geretourneerde task_id; herhaalde data_file-parts zijn alleen voor gesplitste exports van dezelfde factuur.
• UBL: stuur format=UBL; stel voor deterministische integraties ook een expliciet profile in, zoals PEPPOL, XRECHNUNG of EN16931.
• CII: stuur format=CII; stel voor deterministische integraties ook een expliciet profile in, zoals EN16931.

Vereiste headers#

Gebruik deze punten als praktische controles voor deze sectie.

• Authorization: Bearer <api_key>

Auth-regels#

API-toegang is goedkeuringsplichtig. Goedgekeurde accounts kunnen API-sleutels in het profiel maken, ze als Bearer-token gebruiken en prepaid credits voor goedgekeurde tests of Enterprise-facturering per order form voor productie gebruiken.

• API-sleutels zijn tenant-gebonden live-credentials voor goedgekeurde accounts. Het huidige productieprefix is icp_....
• Maak, roteer en trek API-sleutels in vanuit je profiel nadat 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#

Gebruik deze punten als praktische controles voor deze sectie.

• 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 uur.

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.

Uitvoerformatenmatrix#

Wijzigingslogboek#

Meest recente extern zichtbare API-wijzigingen.

Foutcontract#

Veelvoorkomende fouten en wat te doen#

Gebruik deze punten als praktische controles voor deze sectie.

• Opnieuw proberen met backoff: 429, 500, 502, 503, 504.
• Request of brondata corrigeren: 400, 409, 413, 422.
• Toegang of credentials corrigeren: 401, 403.
• Bevestig goedkeuring, prepaid testcredits of Enterprise-facturering per order form: 402 INSUFFICIENT_API_CREDITS.
• 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.
• Bij 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE haalt u dezelfde task later opnieuw op; er is geen ongecontroleerd artefact geleverd.

Rate- en payloadlimieten#

Rate limits per API-sleutel en payloadgroottebeperkingen gelden voor alle API-aanroepen. Geweigerde conversies verbruiken geen prepaid API-credits; rate limits worden apart per endpoint bepaald.

• Endpointgebonden limieten zijn kostengewogen. De twee upload-endpoints gebruiken het basisquotum (standaard 30/min en 500/hour); taskpolling is momenteel standaard minimaal 10/min en 120/hour, en resultdownloads zijn momenteel standaard minimaal 10/min en ongeveer 134/hour.
• Lees effectieve limieten uit X-RateLimit-Limit-Minute en X-RateLimit-Limit-Hour op responses.
• Maximale PDF-uploadgrootte: 20 MB
• Maximale uploadgrootte gestructureerde data: 2 MB totaal over alle data_file-parts.
• Maximale JSON-payloadgrootte: 1 MB
• Rate-limit-responses bevatten Retry-After, X-RateLimit-Limit-Minute en X-RateLimit-Limit-Hour.

Retry-richtlijn#

Gebruik deze punten als praktische controles voor deze sectie.

• 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, 402, 403, 409, 413, 422) niet blind opnieuw.

Taaklevenscyclus en bewaartermijn#

Gebruik deze punten als praktische controles voor deze sectie.

• Voltooide en mislukte taken blijven 10 minuten beschikbaar nadat ze een terminale status bereiken.
• Verwerking krijgt een timeout na 5 minuten; vastgelopen tasks worden automatisch als failed gemarkeerd.
• Idempotency keys verlopen na 24 uur.
• Rate-limit-tellers resetten op een rollend venster.

Supportmodel#

Gebruik deze punten als praktische controles voor deze sectie.

• Support tijdens kantooruren op basis van commercieel redelijke inspanningen.
• Geen formele SLA, servicecredit of reactietijdverplichting tenzij afgesproken in een order form.

Stuur technische feedback#

Deel implementatievragen, risico’s en benodigde contractwijzigingen met ons team.

Postman en OpenAPI gebruiken#

Gebruik deze punten als praktische controles voor deze sectie.

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