Publieke API-integratie: bedrijfsscope, financiële mapping en acceptatie
Bouw een bedrijfsgebonden factuurintegratie met het actuele API-contract, stabiele bronidentiteiten, afrekening en gestructureerde Peppol-uitwisseling.
- Bijgewerkt
- Inhoudsverantwoordelijke
- Integratieteam
- Voor
- Integratie-engineers · Solution architects · Technische finance-eigenaars
In één oogopslag
Verifieer bedrijf en mogelijkheden van de sleutel, map financiële gegevens expliciet en bewijs aanmaak, herstel, aflevering en afstemming.
Voordat u begint
- Een bevoegde eigenaar van de bedrijfs-API-sleutel
- Gestructureerde documenten met stabiele bronidentiteiten
- Afgesproken veldmapping en financiële voorbeelden
Wat u bereikt
- Een geteste integratie per bedrijf
- Duurzame koppeling tussen bron- en productidentiteiten
- Acceptatiebewijs voor herstel, afrekening en uitwisseling
Op deze pagina
De publieke API is een financiële integratiegrens. Gebruik het actuele contract en behoud bronidentiteiten vanaf het prototype. Een succesvol HTTP-verzoek is bewijs, maar een enterprise-integratie moet ook verklaren wat zij maakte, voor welk bedrijf en hoe herstel doublures voorkomt.
Ontdek contract en bedrijf
Haal GET /api/v1/openapi.json op voor de werkelijk beschikbare routes. Begin geauthenticeerd met GET /api/v1/me en verifieer bedrijf, namespace, ondersteunde bewerkingen, betaalmethoden, valuta en fiscale mogelijkheden. Bewaar contractversie en ophaaldatum bij de mapping.
Een bevoegde eigenaar/admin maakt de sleutel via Bedrijf → API-sleutels. Het geheim verschijnt één keer; gebruik uw goedgekeurde secret manager. De sleutel hoort bij één bedrijf. Er is geen header waarmee een caller een ander bedrijf kan kiezen. Appsessiecookies authentiseren deze API niet.
| Verantwoordelijkheid | Eigenaar | Bewijs |
|---|---|---|
| Bedrijf en scopes | Sleuteleigenaar | Opgeschoonde /me en rechtenlijst |
| Gegevens en IDs | Integratie-engineer | Versiebeheerde veldmapping |
| Financiële verwachting | Controller | Bedragen en fiscale gevallen |
| Herstel en bewaking | Integratieoperations | Replay- en uitzonderingsbewijs |
| Release | Service-eigenaar | Acceptatiebesluit en overdracht |
Kies beperkte rechten
Gebruik Authorization: Bearer … of X-Api-Key. Ontdek scopes via GET /api/v1/scopes. Documentschrijven vraagt bijbehorende write-scope. Geldbewegingen en voorschotten bij aanmaak vragen payments:write.
POST /api/v1/peppol/send maakt een factuur en kan verzenden, dus vereist invoices:write en peppol:send. Lezen vraagt afzonderlijk peppol:read. Registratiegoedkeuring en maandquota staan los van sleutelrechten.
Leg de financiële mapping vast
Noteer per veld bron, API-veld, type, transformatie, autoriteit en weigeringsafhandeling. Adressen vereisen straat, plaats, postcode en land. Onbekende velden worden geweigerd; stuur niet uw volledige bronobject. Laat number weg als de bedrijfsreeks moet nummeren.
Gebruik decimale strings voor geld met ondersteunde precisie. Lever valuta en occurrence time met tijdzone aan. Rond niet ongemerkt af, converteer geen valuta en leid geen betaalbeweging af uit een betaald-label zonder geldbevestiging.
ERP-order order-4711 kan factuur external_id: order-4711 worden in namespace erp. Het bevestigde voorschot krijgt eigen ID tender-4711-1. Behoud beide bij retries en sleutelvervanging.
Scheid aanmaak en uitwisseling
POST /api/v1/invoices maakt het document. Een bestaande factuur gaat via /peppol/invoices/{invoice_id}/send; creditnota's gebruiken hun aparte route. Offertes en ontvangstbewijzen hebben geen Peppol-verzendroute.
De gecombineerde /peppol/send accepteert gestructureerde velden en optioneel een eigen PDF. send: false maakt zonder netwerkverzending. Dit maakt nog steeds een echte factuur en is geen sandbox.
Peppol vervoert UBL. Een PDF is begeleidend bewijs, geen bron voor extractie. BIS Billing publiceert factuur- en creditnotastructuren. Deze publieke API biedt geen OCR-van-PDF-factuurroute.
Maak herstel duurzaam
Gebruik stabiele document-/bewegings-external_id en daarnaast Idempotency-Key voor HTTP-herhaling. HTTP-idempotentie duurt 24 uur en is sleutelgebonden. Financiële identiteiten blijven daarna en na rotatie bestaan.
Zoek na verloren antwoord op externe ID of herhaal identieke inhoud. EXTERNAL_ID_REUSED betekent gewijzigde aanmaakinhoud of bewegingsdetails onder dezelfde identiteit; onderzoek oorspronkelijke mapping en passende correctie zonder een willekeurige nieuwe ID. Een onzekere Peppol-transmissie vraagt providerreconciliatie vóór herverzending.
Lees iedere lijstpagina. Baseer foutlogica op code, niet op de prozatekst. Respecteer rate-limitheaders en Retry-After bij 429.
Bewijs acceptatie met bedragen
Test gewone factuur, creditnota, voorschot, gedeeltelijke betaling, echte refund, dubbele aanmaakretry, bewegingsretry en verloren antwoord. Vergelijk bedragen, bron-ID, nummer, afrekening, aflevering en XML/PDF apart.
Een €121-factuur met €40 voorschot heeft payments €40 en outstanding €81. Na €81 betaling is zij afgerekend. Het voorschot opnieuw synchroniseren moet dezelfde beweging teruggeven en payments op €121 laten.
Kies PDF-views bewust: current is een gedateerde afrekeningsstaat; issued/original bewaart oorspronkelijke weergave. Peppol-document-ID haalt uitgewisselde XML/PDF op en verschilt van factuur- en provider-ID.
Draag mapping, sleuteleigenaar, identiteitenregister, bewaking en opgeschoonde foutvoorbeelden over. Release pas zonder onverklaarde financiële afwijkingen. Vervolg met integratiebetrouwbaarheid en maandafsluiting.
Stel een overdraagbaar foutdossier samen
Bewaar voor elk belangrijk refusal-geval een opgeschoond verzoek, code, verwacht herstel en eigenaar. Neem een ontbrekend adresveld, een onvoldoende scope, een te precies geldbedrag en een hergebruikte identiteit op. Toon daarbij hoe het systeem beslist tussen mappingcorrectie, lookup, herhaling en commerciële correctie.
Gebruik geen echte bearer secret in voorbeeldcode of tickets. Het dossier moet ook voor een vervanger aantonen dat de sleutel het bedoelde bedrijf bereikt. Noteer hoe rotatie doorwerkt naar de connector en hoe de namespace behouden blijft. Test na een mappingwijziging niet alleen de nieuwe happy path, maar ook de bestaande herstelgevallen. Een extra optioneel bronveld kan de aanmaakpayload veranderen en daardoor een bestaande identiteit niet meer identiek replayen. Behandel dat als een versiebeheerbeslissing, geen reden om nieuwe IDs te genereren.