Betrouwbare integraties: herhalingen, onzekere verzending, afstemming
Een OrdoGrid-API-aanroep herhalen zonder dubbele factuur of betaling: stabiele external_id, Integratie-ID, Idempotency-Key, foutcodes, onzekere Peppol-verzending.
- Bijgewerkt
- Inhoudsverantwoordelijke
- Integratieoperations
- Voor
- Integratieontwikkelaars · Integratiebeheer · Financiële controllers
In één oogopslag
Geef elke bedrijfsgebeurtenis één stabiele external_id onder een vaste Integratie-ID, classificeer elk antwoord op zijn code vóór u herhaalt, en zoek de gebeurtenis op na elke time-out. Gebruik na een verloren antwoord nooit een nieuwe ID, en houd een onzekere Peppol-verzending vast tot OrdoGrid de uitkomst heeft bevestigd.
Voordat u begint
- Een Business-abonnement met toegang tot de publieke API
- Een OrdoGrid-API-sleutel met alleen de nodige permissies en een gekende Integratie-ID
- Een bronsysteem dat per factuur, creditnota en betaling één stabiele ID kan afleiden
- Opgeschoonde logs van verzoeken en antwoorden, en een aangewezen eigenaar van de herhaalwachtrij
Wat u bereikt
- Een herhaalbeleid dat op foutcodes steunt, met geteste limieten en wachttijden
- Geen dubbele factuur, creditnota of betaling na een time-out, een crash of een sleutelrotatie
- Een bewaakte wachtrij waarin elk vastgehouden item een eigenaar en een beslissing heeft
Op deze pagina
Een integratie is betrouwbaar als ze een zakelijke transactie kan herstellen na een verloren HTTP-antwoord, een afgebroken verwerking of een onduidelijke overdracht naar Peppol, zonder een tweede factuur, betaling of verzending te maken. "Drie keer opnieuw proberen" volstaat niet: sommige verzoeken worden geweigerd voor er iets is opgeslagen, andere mislukken nadat OrdoGrid de factuur al genummerd of de betaling al geregistreerd heeft. Dit playbook legt vast welke identiteiten u bewaart, hoe u elk antwoord classificeert, wanneer u herhaalt, wanneer u vasthoudt en wat u bewaakt.
Het is bedoeld voor ontwikkelaars en beheerders van connectoren op de publieke OrdoGrid-API (/api/v1). Sleutels, permissies en mapping staan in Publieke API-integratie; de coördinatie van een lopend incident in Facturatie-incident; de betekenis van de badges in Peppol-afleverstatus. Het volledige contract is de API-referentie.
Waarom een dubbel duur uitvalt
| Wat geldt | |
|---|---|
| De wet | Elke factuur krijgt een uniek doorlopend nummer en wordt ingeschreven in het boek van uitgaande facturen (koninklijk besluit nr. 1, art. 5, §1, 1°); ze moet uiterlijk de 15de van de maand na het belastbare feit uitgereikt zijn (art. 4, §1). Een document dat een gestructureerde factuur verbetert, wordt in hetzelfde formaat uitgereikt (art. 53, §2bis Btw-Wetboek): een via Peppol verstuurd dubbel corrigeert u dus met een creditnota via Peppol (FAQ, V5), niet door te schrappen. |
| FOD Financiën | Peppol herkent geen dubbels; ze opsporen is de taak van de gebruiker en zijn software (FAQ specifieke vragen, V4). Aflevering duurt meestal enkele minuten tot een paar uur; meld vertraging van meer dan één werkdag aan uw softwareleverancier (Peppol-FAQ, V9). |
| OrdoGrid | Duurzame external_id-identiteiten, 24 uur replay (teruggave van het opgeslagen antwoord) via Idempotency-Key, één uitgaande verzending per factuur en een blokkering van elke herverzending zolang de uitkomst onduidelijk is. Die beveiligingen werken alleen als uw connector dezelfde identiteiten behoudt. |
| Onze aanbeveling | Het register, de herhaallimieten, het vasthouden en de alarmen hieronder: suggesties om aan uw volumes aan te passen, geen dienstverleningsverbintenissen van OrdoGrid. |
Vier beveiligingen en hun grenzen
| Beveiliging | Bereik en duur | Voorkomt | Voorkomt niet |
|---|---|---|---|
Header Idempotency-Key | De aanroepende API-sleutel; 24 uur | Een tweede uitvoering van dezelfde POST: een identieke herhaling geeft het opgeslagen geslaagde antwoord terug met Idempotent-Replay: true | Andere inhoud onder dezelfde sleutel (409 IDEMPOTENCY_KEY_REUSED); een nieuwe uitvoering na een mislukte aanroep (de sleutel wordt vrijgegeven); PATCH, PUT, DELETE; een herhaling onder een geroteerde sleutel |
external_id van een document | Bedrijf, Integratie-ID en documentsoort; verloopt niet, overleeft rotatie | Een tweede factuur of creditnota voor dezelfde brontransactie | Een nieuwe ID; een andere Integratie-ID; elke wijziging aan de aanmaakinhoud (409 EXTERNAL_ID_REUSED) |
external_id van een beweging | Bedrijf en Integratie-ID, over alle facturen en bewegingssoorten heen; verloopt niet | Hetzelfde geld twee keer tellen: een herhaling geeft de oorspronkelijke beweging terug met replayed: true | Een ander bedrag, andere munt, betaalwijze, tijdstip of referentie, of dezelfde ID op een andere factuur (EXTERNAL_ID_REUSED) |
| Peppol-verzendbeveiliging | Eén verzending per factuur of creditnota | Een tweede verzending: een aanvaarde verzending komt terug met replayed: true, een onzekere wordt geweigerd | Een nieuwe factuur voor dezelfde verkoop; een pdf per e-mail |
Gebruik beide: Idempotency-Key maakt een onmiddellijke herhaling goedkoop, external_id maakt herstel mogelijk na 24 uur of na een sleutelwissel. De API aanvaardt documenten zonder external_id, maar behandel het als verplicht; voor bewegingen is het verplicht.
- Integratie-ID
- De naamruimte van een API-sleutel (
integration_idin de API, Integratie-ID op de pagina API-sleutels). Elkeexternal_idwordt opgezocht binnen de naamruimte van de aanroepende sleutel. Tot 80 letters, cijfers,_,.of-; vast bij aanmaak; het veld staat standaard opdefault.
Houd een identiteitenregister bij
Houd één rij per bedrijfsgebeurtenis bij, niet per HTTP-verzoek: brongebeurtenis en external_id (SO-58213), Integratie-ID (erp-prod), documentsoort, de exact verzonden inhoud of de SHA-256 ervan, de Idempotency-Key, OrdoGrid-id, number en peppol_document_id, elke beweging met al haar velden, de laatste uitkomst met UTC-tijd en code, en de status in de wachtrij met de eigenaar.
- Leid de ID af van de bedrijfsgebeurtenis (1 tot 200 tekens). Een UUID per verzoek schakelt alle beveiligingen hierboven uit.
- Bevries de inhoud bij de eerste indiening en verstuur ze ongewijzigd opnieuw. OrdoGrid berekent een vingerafdruk van de volledige aanmaakinhoud: een ERP dat het verzoek opnieuw opbouwt met een verbeterd e-mailadres of een andere vervaldag, krijgt
EXTERNAL_ID_REUSED. - Laat
numberweg, zodat de reeks van het bedrijf het toekent. Eigen nummers plus een herhaling zonderexternal_idgeven409 DOCUMENT_NUMBER_TAKEN. - Zet een leesbare bronreferentie in het veld
referencevan elke beweging; de boekhouding ziet ze in de Mutatiegeschiedenis van het paneel Afrekening bij de factuur. Houd ze bij elke herhaling identiek. - Bescherm het register. Een correctie is een nieuwe rij die naar de oude verwijst, nooit een gewijzigde ID.
Behoud de naamruimte bij een sleutelwissel
Op de pagina API-sleutels (eigenaars en beheerders):
- Roteren maakt een nieuwe sleutel met dezelfde naam, Permissies, vervaldatum en Integratie-ID; de oude sleutel stopt onmiddellijk. Kopieer het nieuwe geheim onder Kopieer deze sleutel nu: het wordt maar één keer getoond.
- Een vervangende sleutel via Sleutel aanmaken moet exact de oude Integratie-ID krijgen. Blijft die op
default, dan geven opzoekingen404en maken herhalingen nieuwe facturen of betalingen aan. - De sleutellijst toont de Integratie-ID niet: roep
GET /api/v1/meaan en vergelijkapi_key.integration_idmet uw register voor u de connector herstart. - De HTTP-replaygegevens horen bij de oude sleutel; herstel na een rotatie via opzoeken op
external_id.
Classificeer elke uitkomst voor u herhaalt
Ga uit van de fout-code, nooit van de tekst van de melding. Alles wat hier niet staat: beschouw de uitkomst als onbekend en zoek de gebeurtenis op.
Documenten en geldbewegingen
| Antwoord | Opgeslagen? | Actie |
|---|---|---|
201; of Idempotent-Replay: true of replayed: true (200 bij bewegingen) | Ja | Noteer id en number. Een replay geeft het eerste resultaat terug, geen nieuwe verkoop of betaling |
Time-out, verbroken verbinding, 5xx zonder code uit deze tabel | Onbekend | Zoek eerst op via external_id: GET /api/v1/invoices/lookup of /api/v1/credit-notes/lookup voor documenten, GET /api/v1/invoices/payments/lookup voor bewegingen |
400 VALIDATION_ERROR, UNKNOWN_FIELD, INVALID_AMOUNT_PRECISION, CURRENCY_MISMATCH, INVALID_OCCURRENCE_TIME, UNKNOWN_VAT_TYPE | Nee | Herstel de mapping; verstuur de verbeterde inhoud onder dezelfde external_id (komt er EXTERNAL_ID_REUSED, zie bijzondere gevallen). Geen automatische herhaling |
401 API_KEY_EXPIRED, API_KEY_REVOKED, INVALID_API_KEY; 403 INSUFFICIENT_SCOPE | Nee | Stop de wachtrij. INVALID_API_KEY: controleer het ingestelde geheim. Sleutel ingetrokken door Roteren: installeer het nieuwe geheim. Verlopen of om een andere reden ingetrokken sleutel, of ontbrekende Permissies: Roteren helpt niet (dat behoudt de permissies en de vervaldatum en wordt niet aangeboden voor een verlopen of ingetrokken sleutel); maak dus een nieuwe sleutel via Sleutel aanmaken, typ exact de oude Integratie-ID, controleer die met GET /api/v1/me en hervat dan met dezelfde identiteiten |
429 RATE_LIMITED | Nee | Wacht Retry-After seconden; vertraag |
409 IDEMPOTENT_REQUEST_IN_PROGRESS | Eerste aanroep loopt nog | Wacht enkele seconden; herhaal met dezelfde sleutel en inhoud |
409 EXTERNAL_OPERATION_IN_PROGRESS | Een andere aanroep houdt de identiteit vast | Wacht meer dan twee minuten (de uitvoeringsvergrendeling) en zoek dan op |
409 IDEMPOTENCY_KEY_REUSED of EXTERNAL_ID_REUSED | Eerste versie bestaat of is gereserveerd | Houd vast; vergelijk de bewaarde en de nieuwe inhoud; omzeil nooit met een nieuwe sleutel of ID |
409 SETTLEMENT_CONFLICT | Nee | Gelijktijdige wijziging aan de factuur; herhaal met dezelfde external_id na een wachttijd |
409 OVERPAYMENT, OVER_REFUND | Nee | Niet herhalen; ga na of het geld al onder een andere ID geregistreerd is |
409 DOCUMENT_FINANCIAL_CONTENTS_LOCKED bij een wijziging | Nee | Er is een betaling geregistreerd, de factuur is voorbereid voor of verzonden via Peppol, of het document is een opgeslagen creditnota: niet wijzigen; corrigeer met een nieuwe creditnota of factuur |
502 DOCUMENT_CREATED | Ja, pdf of bijlagen niet afgewerkt | Verstuur de identieke inhoud onder dezelfde external_id om af te werken; zonder external_id: gebruik details.document_id en maak nooit opnieuw aan |
Limieten gelden per sleutel en per minuut (standaard 120); lees X-RateLimit-Remaining en X-RateLimit-Reset (in seconden) in plaats van het getal hard te coderen.
Peppol-verzendingen
Lees GET /api/v1/peppol/invoices/{id}/status (of de tegenhanger voor creditnota's) met de permissie peppol:read. transmission_state beschrijft de overdracht door OrdoGrid aan zijn toegangspunt; status volgt de aflevering en komt overeen met de badges in Peppol → Outbox (processed is Traité).
Code of transmission_state | Betekenis | Actie |
|---|---|---|
403 PEPPOL_APPROVAL_REQUIRED, PEPPOL_LIMIT_REACHED | Niets aangemaakt of verzonden | Onderteken de Autorisation Peppol of wijzig uw abonnement in Facturatie & Abonnement; verstuur hetzelfde verzoek opnieuw |
PEPPOL_CLIENT_NOT_FOUND | Niets verzonden; met POST /api/v1/peppol/send bestaat de factuur al | Controleer het btw-nummer met GET /api/v1/peppol/participants/{vat_number} en verstuur dan de bestaande factuur; kan de klant niet via Peppol ontvangen, bezorg dan diezelfde factuur op een andere manier |
preparing, 409 PEPPOL_TRANSMISSION_IN_PROGRESS | XML wordt opgebouwd en gearchiveerd | Wacht minstens vijf minuten en lees dan de status |
prepared, preparation_failed | Nog niet overgedragen | Herstel de eventuele oorzaak (bijvoorbeeld een ontbrekende pdf) en verstuur dezelfde factuur opnieuw |
accepted | Het toegangspunt heeft het bericht aangenomen; dat is niet de aanvaarding door de koper | Volg status tot processed |
rejected, PEPPOL_TRANSMISSION_REJECTED | Uitdrukkelijk geweigerd | Zoek de oorzaak; een nieuwe poging verstuurt dezelfde gearchiveerde bytes. Foute inhoud: Mislukte Peppol-verzending of afgewezen Peppol-factuur herstellen |
sending, uncertain, PEPPOL_TRANSMISSION_UNCERTAIN | Het bericht staat misschien al op het netwerk | Vasthouden: geen nieuwe factuur, geen kopie per e-mail; laat de uitkomst afstemmen door OrdoGrid-support |
409 PEPPOL_HISTORY_RECONCILIATION_REQUIRED | Er bestaan oudere dubbele verzendingen | Neem contact op met OrdoGrid-support |
PEPPOL_ARCHIVE_HASH_MISMATCH, XML_NOT_AVAILABLE, PDF_NOT_AVAILABLE | Het gearchiveerde bestand kan niet worden geleverd zoals bewaard | Escaleer; stel een opnieuw gegenereerd bestand nooit voor als het origineel |
De Invoice Response-specificatie van OpenPeppol houdt transportbevestigingen gescheiden van de zakelijke beslissing van de koper, en kopers hoeven niet te antwoorden. Bewaar verzendstatus, klantantwoord en afrekening in afzonderlijke velden: afgeleverd is niet aanvaard en niet betaald.
De herhaallus
Onze voorgestelde startwaarden, geen productlimieten: wachttijden van 1, 2, 4, 8, 16 en 32 seconden, begrensd op 60, met ±20% willekeurige spreiding; zes pogingen per gebeurtenis, daarna vasthouden met een reden. Wachttijden door een 429 tellen niet mee. Gebruik één Idempotency-Key per bedrijfsoperatie (SO-58213-create) voor alle pogingen; wijzig de inhoud alleen na een 4xx, wanneer OrdoGrid de sleutel heeft vrijgegeven.
zolang pogingen < 6:
r = POST /api/v1/invoices (bevroren inhoud, zelfde Idempotency-Key)
2xx -> klaar(r.id, r.number)
429 -> wacht Retry-After; ga verder
definitieve 4xx of *_REUSED -> vasthouden(code); stop
502 DOCUMENT_CREATED -> pogingen += 1; ga verder (identiek opnieuw versturen werkt het af)
EXTERNAL_OPERATION_IN_PROGRESS -> wacht 150 s
l = GET /api/v1/invoices/lookup?external_id=...
200 -> klaar(l.id, l.number) 409 -> wacht 150 s 404 -> herhaal
pogingen += 1; wacht wachttijd(pogingen)
vasthouden("herhaalbudget op")
Na 24 uur vervalt de Idempotency-Key; een identieke herhaling blijft beschermd door external_id. PATCH, PUT en DELETE hebben geen replay: lees na een verloren antwoord het document met GET en vergelijk voor u de wijziging opnieuw toepast.
Rekenvoorbeeld: time-out, sleutelrotatie, overschrijving
Verhaeghe Technics BV (Kortrijk) factureert vanuit zijn ERP met een sleutel "ERP productie", Integratie-ID erp-prod. Verkooporder SO-58213 is voor Brasserie Lambert SRL (Namen), die via Peppol ontvangt: 8 u machineonderhoud × € 95,00 = € 760,00 en een verplaatsbare pomp van € 1.240,00 (geen werk in onroerende staat, dus geen btw-verlegging), samen € 2.000,00 excl. btw + € 420,00 btw aan 21% = € 2.420,00.
12 oktober 2026, 14.02 uur UTC (16.02 uur in Brussel). POST /api/v1/peppol/send met external_id SO-58213 en Idempotency-Key SO-58213-send loopt na 30 seconden in een time-out.
- Classificeren. Onbekende uitkomst: niet opnieuw versturen.
- Opzoeken.
GET /api/v1/invoices/lookup?external_id=SO-58213geeft200: factuur F-2026-0418 bestaat (deze route maakt de factuur aan vóór de verzending). - Verzending lezen. De status toont
transmission_stateuncertain,transmitted: false. De registerrij wordt vastgehouden; eigenaar Anke Peeters; volgende controle om 15.00 uur UTC. - Afronden. Om 15.00 uur staat
transmission_stateopaccepted; om 15.20 uur staatstatusopprocessed(Traité in Peppol → Outbox). Eén factuur, één verzending, € 2.420,00 te ontvangen.
Een naïeve connector die drie keer opnieuw probeert met telkens een nieuwe UUID, had F-2026-0419 tot F-2026-0421 aangemaakt en verzonden: 3 × € 2.420,00 = € 7.260,00 aan onterechte vorderingen, waarvan € 1.260,00 btw, die Peppol niet als dubbel markeert. Elke factuur vraagt dan een eigen creditnota via Peppol (NC-2026-0031 tot NC-2026-0033) en een telefoon naar de klant.
20 oktober. De beheerder klikt op Roteren; GET /api/v1/me toont nog steeds erp-prod. Om 9.15 uur UTC registreert de bankkoppeling de eerste overschrijving:
{"external_id":"bank-20261020-0144","amount":"1000.00","currency":"EUR","method":"bank_transfer","occurred_at":"2026-10-20T09:12:00Z","reference":"Uittreksel 203 lijn 14"}
Het antwoord gaat verloren. De bewaarde inhoud wordt opnieuw verstuurd met dezelfde Idempotency-Key: de oorspronkelijke 201 komt terug, gemarkeerd met Idempotent-Replay: true (zonder de header, of na 24 uur, antwoordt de duurzame identiteit: 200 met replayed: true). In beide gevallen is outstanding "1420.00". Een opnieuw opgebouwde referentie zoals "Uittr. 203/14" had 409 EXTERNAL_ID_REUSED opgeleverd.
Was de connector tussen het verloren antwoord en de herhaling overgeschakeld op een sleutel gemaakt via Sleutel aanmaken en op default gelaten, dan had die herhaling een tweede betaling van € 1.000,00 geregistreerd: outstanding € 420,00 terwijl de klant nog € 1.420,00 schuldig is, wat pas op 3 november zou opvallen, wanneer de echte betaling van € 1.420,00 met OVERPAYMENT wordt geweigerd. Nu brengt betaling bank-20261103-0029 outstanding op "0.00" en settlement.status op settled.
Bijzondere gevallen en veelgemaakte fouten
| Situatie | Juiste reactie |
|---|---|
Opzoeken geeft 404 na een time-out | Controleer eerst de naamruimte met GET /api/v1/me en verstuur dan de identieke inhoud onder dezelfde external_id; nooit een nieuwe ID "omdat ze niet bestaat" |
EXTERNAL_ID_REUSED nadat iemand de order in het ERP wijzigde | De boekhouding beslist welke versie klopt; een bestaande foute factuur krijgt een creditnota en een nieuwe factuur. Voeg geen -v2 toe |
Verbeterde inhoud geeft EXTERNAL_ID_REUSED na een weigering tijdens de aanmaak (zoals OVERPAYMENT op voorschotten bij aanmaak of DOCUMENT_NUMBER_TAKEN) | De identiteit blijft gekoppeld aan de geweigerde inhoud. Geeft opzoeken ruim na twee minuten nog 409 EXTERNAL_OPERATION_IN_PROGRESS, dan is er niets opgeslagen: laat OrdoGrid-support dat bevestigen, gebruik dan een nieuwe ID en koppel beide in het register |
IDEMPOTENT_REQUEST_IN_PROGRESS langer dan enkele minuten | Zoek op; ontbreekt de gebeurtenis, verstuur dan de identieke inhoud met een nieuwe Idempotency-Key; de external_id blokkeert een dubbel nog altijd |
| Eén overschrijving voor twee facturen | Bewegings-ID's zijn uniek over alle facturen heen: bank-20261020-0144-a en -b |
| Fout bedrag geregistreerd | Een tegenboeking annuleert altijd de volledige beweging: boek ze tegen en registreer dan het juiste bedrag onder een nieuwe ID |
| De klant vindt een factuur met Traité niet terug | Afgeleverd bij zijn Peppol-provider: de klant kijkt daar na. Niet opnieuw verzenden en niet mailen |
Bewaak zakelijke uitkomsten, niet alleen beschikbaarheid
| Indicator | Voorgesteld alarm | Eigenaar |
|---|---|---|
| Oudste nog niet ingediende gebeurtenis | Ouder dan 30 minuten tijdens de kantooruren | Exploitatie |
| Oudste vastgehouden item | Ouder dan één werkdag | Wachtrijeigenaar |
Verzendingen in sending of uncertain | Elke verzending ouder dan 4 uur | Integratiebeheer |
| Niet-gefactureerde gebeurtenissen waarvan de termijn (15de van de volgende maand) binnen 5 werkdagen valt | Elk geval | Boekhouding |
4xx-weigeringen per dag, per code | Een nieuwe code, of een verdubbeling van dag tot dag | Integratieontwikkelaar |
| Replay-antwoorden / verzoeken | Meer dan 5% gedurende een uur | Integratieontwikkelaar |
Dagtotalen van de bron tegenover document_total en payments | Elk verschil dat niet € 0,00 is | Controller |
Tel verzoeken los van bedrijfsgebeurtenissen: een replay is geen nieuwe omzet. Log codes, ID's en UTC-tijden, nooit het geheim (ik_live_…) of de header Authorization. Lees alle pagina's van een lijst (limit tot 100, offset) met vaste filters en noteer het extractievenster; zie Maandafsluiting.
Bewijs het herstel voor de ingebruikname
OrdoGrid heeft geen testomgeving en geen Peppol-testmodus: elke aanroep werkt op echte gegevens, en "send": false maakt toch een genummerde factuur aan. Test waar mogelijk in een apart bedrijf voor acceptatie (Créer une nouvelle entreprise, nieuw bedrijf aanmaken) met een eigen sleutel; anders plant u een creditnota per testfactuur. Simuleer onzekere of geweigerde verzendingen met opgenomen antwoorden in uw eigen HTTP-client.
| Scenario | Verwacht resultaat |
|---|---|
| Aanmaken, dan identieke herhaling met dezelfde sleutel, dan met een nieuwe sleutel | 201, daarna twee keer 201 met Idempotent-Replay: true; één factuur |
| Zelfde sleutel, andere inhoud | 409 IDEMPOTENCY_KEY_REUSED; item vastgehouden |
Zelfde external_id, andere inhoud | 409 EXTERNAL_ID_REUSED; item vastgehouden, boekhouding verwittigd |
| Twee verwerkingen, zelfde gebeurtenis | Eén 201; de andere een 409 "bezig" of een replay |
| Betaling, dan identieke herhaling met een nieuwe sleutel | 201, daarna 200 met replayed: true; saldo één keer verminderd |
Betaling boven outstanding | 409 OVERPAYMENT; geen herhaling |
| Piek boven de limiet | 429 met Retry-After; niets verloren |
| Roteren, dan eerdere gebeurtenissen opnieuw indienen | Alleen replays; /me toont dezelfde Integratie-ID |
Aanvaard wanneer elke gebeurtenis precies één OrdoGrid-identiteit heeft, de afrekening met de bron klopt, geen onzekere verzending herhaald is en een vervanger de vastgehouden items alleen met het register kan afwerken. Geef de beslissingstabellen, de sleuteleigenaar, de Integratie-ID, de plaats van het register, de drempels en het supportcontact door. Stem na een incident de volledige getroffen populatie af voor u het herstel meldt (Facturatie-incident).
Te bewaren bewijs
- Het register: bevroren inhoud of de vingerafdruk ervan,
Idempotency-Key-waarden, elke uitkomst met UTC-tijd encode. - Per Peppol-verzending:
peppol_document_id, het verloop vantransmission_stateen de uitgewisselde XML viaGET /api/v1/peppol/documents/{id}/xml(ID van het Peppol-document, niet van de factuur;peppol:read), plus/pdf. OrdoGrid toetst beide aan de SHA-256-vingerafdrukken intransmission_snapshot. - Sleutelwijzigingen (wie, wanneer, Integratie-ID voor en na) en, per vastgehouden item, de reden, de controles, wie heeft vrijgegeven en de uitwisseling met support.
- Facturen worden zeven jaar bewaard vanaf 1 januari van het jaar na uitreiking; OrdoGrid biedt geen garantie voor wettelijke archivering, dus bewaar een eigen kopie (Facturen bewaren in België).
Veelgestelde vragen
Hoe lang wachten we na een time-out voor we opnieuw proberen?
Zoek eerst op in plaats van te wachten. Bestaat het document, noteer het dan; houdt een andere aanroep de identiteit vast, wacht dan meer dan twee minuten; geeft opzoeken 404, verstuur dan de identieke inhoud met oplopende wachttijden.
Mogen we dezelfde Idempotency-Key na een fout opnieuw gebruiken?
Ja. OrdoGrid bewaart alleen geslaagde antwoorden en geeft de sleutel vrij na een mislukking, zodat hij na een 4xx verbeterde inhoud kan dragen. Binnen 24 uur na een succes wordt andere inhoud onder die sleutel geweigerd.
Waarom krijgen we EXTERNAL_ID_REUSED terwijl alleen de omschrijving veranderde?
Bij documenten telt de volledige aanmaakinhoud, ook omschrijvingen, e-mailadressen en vervaldagen. Bij bewegingen tellen bedrag, munt, betaalwijze, tijdstip en referentie. Verstuur de bewaarde inhoud opnieuw of laat de boekhouding beslissen.
Is het veilig om de Peppol-verzending voor dezelfde factuur opnieuw aan te roepen?
Ja, als de aanroep dezelfde factuur betreft: de verzendroute van die factuur, of POST /api/v1/peppol/send herhaald met dezelfde external_id (zonder external_id maakt die route een nieuwe factuur aan). Een aanvaarde verzending komt terug met replayed op true, een geweigerde verstuurt de gearchiveerde bytes opnieuw, een onzekere wordt geweigerd. Een nieuwe factuur voor dezelfde verkoop of een kopie per e-mail is niet veilig.
Breekt het roteren van een API-sleutel de bescherming tegen dubbels?
Niet met Roteren, dat de Integratie-ID behoudt. Alleen de replay via Idempotency-Key (24 uur) blijft aan de oude sleutel gekoppeld. Een sleutel via Sleutel aanmaken moet met de hand dezelfde Integratie-ID krijgen.
Kunnen we herhalingen testen in een testomgeving?
Nee. Er is geen testomgeving en geen Peppol-testmodus. Gebruik waar mogelijk een apart acceptatiebedrijf en simuleer Peppol-uitkomsten met opgenomen antwoorden.
Bronnen en referenties
- Referentie van de publieke OrdoGrid-API: idempotentie, extern opzoeken en foutcodes
- Peppol BIS Invoice Response 3.2: transportbevestigingen versus zakelijke antwoorden
- FOD Financiën, FAQ e-facturatie: specifieke vragen (V4 dubbels, V5 creditnota's)
- FOD Financiën, Peppol-FAQ: vertraging bij aflevering (V9)
- Wet van 6 februari 2024, art. 53, §2bis Btw-Wetboek: verbeterende documenten in hetzelfde gestructureerde formaat (Belgisch Staatsblad, 20.02.2024)
- Koninklijk besluit nr. 1, art. 4 en 5: uitreikingstermijn en doorlopende nummering (Justel, gecoördineerd)