Draaiboek18 min leestijd

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 wetElke 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ënPeppol 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).
OrdoGridDuurzame 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 aanbevelingHet 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

BeveiligingBereik en duurVoorkomtVoorkomt niet
Header Idempotency-KeyDe aanroepende API-sleutel; 24 uurEen tweede uitvoering van dezelfde POST: een identieke herhaling geeft het opgeslagen geslaagde antwoord terug met Idempotent-Replay: trueAndere 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 documentBedrijf, Integratie-ID en documentsoort; verloopt niet, overleeft rotatieEen tweede factuur of creditnota voor dezelfde brontransactieEen nieuwe ID; een andere Integratie-ID; elke wijziging aan de aanmaakinhoud (409 EXTERNAL_ID_REUSED)
external_id van een bewegingBedrijf en Integratie-ID, over alle facturen en bewegingssoorten heen; verloopt nietHetzelfde geld twee keer tellen: een herhaling geeft de oorspronkelijke beweging terug met replayed: trueEen ander bedrag, andere munt, betaalwijze, tijdstip of referentie, of dezelfde ID op een andere factuur (EXTERNAL_ID_REUSED)
Peppol-verzendbeveiligingEén verzending per factuur of creditnotaEen tweede verzending: een aanvaarde verzending komt terug met replayed: true, een onzekere wordt geweigerdEen 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_id in de API, Integratie-ID op de pagina API-sleutels). Elke external_id wordt opgezocht binnen de naamruimte van de aanroepende sleutel. Tot 80 letters, cijfers, _, . of -; vast bij aanmaak; het veld staat standaard op default.

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.

  1. Leid de ID af van de bedrijfsgebeurtenis (1 tot 200 tekens). Een UUID per verzoek schakelt alle beveiligingen hierboven uit.
  2. 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.
  3. Laat number weg, zodat de reeks van het bedrijf het toekent. Eigen nummers plus een herhaling zonder external_id geven 409 DOCUMENT_NUMBER_TAKEN.
  4. Zet een leesbare bronreferentie in het veld reference van elke beweging; de boekhouding ziet ze in de Mutatiegeschiedenis van het paneel Afrekening bij de factuur. Houd ze bij elke herhaling identiek.
  5. 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):

  1. 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.
  2. Een vervangende sleutel via Sleutel aanmaken moet exact de oude Integratie-ID krijgen. Blijft die op default, dan geven opzoekingen 404 en maken herhalingen nieuwe facturen of betalingen aan.
  3. De sleutellijst toont de Integratie-ID niet: roep GET /api/v1/me aan en vergelijk api_key.integration_id met uw register voor u de connector herstart.
  4. 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

AntwoordOpgeslagen?Actie
201; of Idempotent-Replay: true of replayed: true (200 bij bewegingen)JaNoteer id en number. Een replay geeft het eerste resultaat terug, geen nieuwe verkoop of betaling
Time-out, verbroken verbinding, 5xx zonder code uit deze tabelOnbekendZoek 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_TYPENeeHerstel 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_SCOPENeeStop 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_LIMITEDNeeWacht Retry-After seconden; vertraag
409 IDEMPOTENT_REQUEST_IN_PROGRESSEerste aanroep loopt nogWacht enkele seconden; herhaal met dezelfde sleutel en inhoud
409 EXTERNAL_OPERATION_IN_PROGRESSEen andere aanroep houdt de identiteit vastWacht meer dan twee minuten (de uitvoeringsvergrendeling) en zoek dan op
409 IDEMPOTENCY_KEY_REUSED of EXTERNAL_ID_REUSEDEerste versie bestaat of is gereserveerdHoud vast; vergelijk de bewaarde en de nieuwe inhoud; omzeil nooit met een nieuwe sleutel of ID
409 SETTLEMENT_CONFLICTNeeGelijktijdige wijziging aan de factuur; herhaal met dezelfde external_id na een wachttijd
409 OVERPAYMENT, OVER_REFUNDNeeNiet herhalen; ga na of het geld al onder een andere ID geregistreerd is
409 DOCUMENT_FINANCIAL_CONTENTS_LOCKED bij een wijzigingNeeEr 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_CREATEDJa, pdf of bijlagen niet afgewerktVerstuur 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_stateBetekenisActie
403 PEPPOL_APPROVAL_REQUIRED, PEPPOL_LIMIT_REACHEDNiets aangemaakt of verzondenOnderteken de Autorisation Peppol of wijzig uw abonnement in Facturatie & Abonnement; verstuur hetzelfde verzoek opnieuw
PEPPOL_CLIENT_NOT_FOUNDNiets verzonden; met POST /api/v1/peppol/send bestaat de factuur alControleer 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_PROGRESSXML wordt opgebouwd en gearchiveerdWacht minstens vijf minuten en lees dan de status
prepared, preparation_failedNog niet overgedragenHerstel de eventuele oorzaak (bijvoorbeeld een ontbrekende pdf) en verstuur dezelfde factuur opnieuw
acceptedHet toegangspunt heeft het bericht aangenomen; dat is niet de aanvaarding door de koperVolg status tot processed
rejected, PEPPOL_TRANSMISSION_REJECTEDUitdrukkelijk geweigerdZoek de oorzaak; een nieuwe poging verstuurt dezelfde gearchiveerde bytes. Foute inhoud: Mislukte Peppol-verzending of afgewezen Peppol-factuur herstellen
sending, uncertain, PEPPOL_TRANSMISSION_UNCERTAINHet bericht staat misschien al op het netwerkVasthouden: geen nieuwe factuur, geen kopie per e-mail; laat de uitkomst afstemmen door OrdoGrid-support
409 PEPPOL_HISTORY_RECONCILIATION_REQUIREDEr bestaan oudere dubbele verzendingenNeem contact op met OrdoGrid-support
PEPPOL_ARCHIVE_HASH_MISMATCH, XML_NOT_AVAILABLE, PDF_NOT_AVAILABLEHet gearchiveerde bestand kan niet worden geleverd zoals bewaardEscaleer; 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.

  1. Classificeren. Onbekende uitkomst: niet opnieuw versturen.
  2. Opzoeken. GET /api/v1/invoices/lookup?external_id=SO-58213 geeft 200: factuur F-2026-0418 bestaat (deze route maakt de factuur aan vóór de verzending).
  3. Verzending lezen. De status toont transmission_state uncertain, transmitted: false. De registerrij wordt vastgehouden; eigenaar Anke Peeters; volgende controle om 15.00 uur UTC.
  4. Afronden. Om 15.00 uur staat transmission_state op accepted; om 15.20 uur staat status op processed (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

SituatieJuiste reactie
Opzoeken geeft 404 na een time-outControleer 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 wijzigdeDe 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 minutenZoek 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 facturenBewegings-ID's zijn uniek over alle facturen heen: bank-20261020-0144-a en -b
Fout bedrag geregistreerdEen 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 terugAfgeleverd bij zijn Peppol-provider: de klant kijkt daar na. Niet opnieuw verzenden en niet mailen

Bewaak zakelijke uitkomsten, niet alleen beschikbaarheid

IndicatorVoorgesteld alarmEigenaar
Oudste nog niet ingediende gebeurtenisOuder dan 30 minuten tijdens de kantoorurenExploitatie
Oudste vastgehouden itemOuder dan één werkdagWachtrijeigenaar
Verzendingen in sending of uncertainElke verzending ouder dan 4 uurIntegratiebeheer
Niet-gefactureerde gebeurtenissen waarvan de termijn (15de van de volgende maand) binnen 5 werkdagen valtElk gevalBoekhouding
4xx-weigeringen per dag, per codeEen nieuwe code, of een verdubbeling van dag tot dagIntegratieontwikkelaar
Replay-antwoorden / verzoekenMeer dan 5% gedurende een uurIntegratieontwikkelaar
Dagtotalen van de bron tegenover document_total en paymentsElk verschil dat niet € 0,00 isController

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.

ScenarioVerwacht resultaat
Aanmaken, dan identieke herhaling met dezelfde sleutel, dan met een nieuwe sleutel201, daarna twee keer 201 met Idempotent-Replay: true; één factuur
Zelfde sleutel, andere inhoud409 IDEMPOTENCY_KEY_REUSED; item vastgehouden
Zelfde external_id, andere inhoud409 EXTERNAL_ID_REUSED; item vastgehouden, boekhouding verwittigd
Twee verwerkingen, zelfde gebeurtenisEén 201; de andere een 409 "bezig" of een replay
Betaling, dan identieke herhaling met een nieuwe sleutel201, daarna 200 met replayed: true; saldo één keer verminderd
Betaling boven outstanding409 OVERPAYMENT; geen herhaling
Piek boven de limiet429 met Retry-After; niets verloren
Roteren, dan eerdere gebeurtenissen opnieuw indienenAlleen 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 en code.
  • Per Peppol-verzending: peppol_document_id, het verloop van transmission_state en de uitgewisselde XML via GET /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 in transmission_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