Externe API V1-documentatie

Belangrijkste mogelijkheden#

Gebruik deze punten als praktische controles voor deze sectie.

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

Snelstart#

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

Gesloten-beta-toegang aanvragen#

Gebruik deze punten als praktische controles voor deze sectie.

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

Gebruik deze punten als praktische controles voor deze sectie.

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

Gebruik deze punten als praktische controles voor deze sectie.

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

Gebruik deze punten als praktische controles voor deze sectie.

• Authorization: Bearer <api_key>

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#

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

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

Taaklevenscyclus en bewaartermijn#

Gebruik deze punten als praktische controles voor deze sectie.

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

Gebruik deze punten als praktische controles voor deze sectie.

• Support tijdens kantooruren.
• Doel voor eerste reactie: 1 werkdag.

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.