Dubbele orders en facturen voorkomen bij herhaalde API-berichten

Onderscheid bezorging en zakelijke opdracht

Eén order kan meerdere gebeurtenissen opleveren: aangemaakt, goedgekeurd en gewijzigd. Eén gebeurtenis kan daarnaast meerdere keren worden bezorgd. Beschrijf daarom wat je precies eenmaal wilt laten gebeuren. Bijvoorbeeld: één concept voor versie drie van goedgekeurde order O-184. Dat is specifieker dan één bericht met een ordernummer verwerken, omdat een latere goedgekeurde wijziging mogelijk wel een andere behandeling vraagt.

Geef iedere poging een technische traceerreferentie, maar behoud daarnaast de stabiele zakelijke sleutel. Een nieuw uitvoeringsnummer bij elke herstart is bruikbaar voor onderzoek en ongeschikt als enige bescherming tegen dubbele verwerking. De koppeling moet kunnen vaststellen dat twee pogingen over dezelfde bedoelde handeling gaan. Leg ook vast wanneer een wijziging juist een nieuwe opdracht of een correctieverzoek is.

Controleer de mogelijkheden van het doel

Sommige API’s ondersteunen een idempotentiesleutel waarmee een herhaalde aanvraag als dezelfde bewerking wordt herkend. Stripe documenteert een dergelijke regeling, met eigen voorwaarden en verschillen tussen API-versies. Gebruik dat als concreet leveranciersvoorbeeld, niet als bewijs dat elke boekhoud- of CRM-API dezelfde bescherming biedt. Lees de actuele voorwaarden van het daadwerkelijke eindpunt dat je wilt gebruiken.

Controleer onder meer hoe lang herkenning geldig blijft, wat er gebeurt bij andere parameters en of het doelrecord later kan worden opgezocht met een externe referentie. Wanneer het doel geen geschikte voorziening heeft, moet de integratie meer eigen administratie en controle uitvoeren. Beschrijf de resterende onzekerheid. Een lokale tabel met verwerkt is niet automatisch voldoende als de koppeling na een doelbewerking kan uitvallen vóórdat die tabel is bijgewerkt.

Stripe: Idempotent requests ↗

Bewaar de verwerking als toestand

Een eenvoudige vlag gedaan kent geen verschil tussen nog niet gestart, bezig, bevestigd en onzeker. Maak voor een relevante handeling een beperkt, begrijpelijk toestandsmodel. Een ontvangst kan bijvoorbeeld eerst duurzaam worden vastgelegd, daarna voorbereid, vervolgens bij het doel aangeboden en ten slotte bevestigd met een doelreferentie. Een storing kan de toestand onzeker achterlaten.

Zo’n model helpt medewerkers gericht handelen. Bij een bevestigde verwerking hoort geen nieuwe creatiepoging; bij een ontbrekend veld moet de bron worden gecorrigeerd; bij onzeker moet eerst het doel worden onderzocht. Houd de toestanden klein en leg hun betekenis uit. Een lange lijst technische tussenstappen zonder zakelijke uitleg maakt herstel juist moeilijker en nodigt uit om alles alsnog met een algemene herstartknop te behandelen.

Bij een onzekere uitkomst moet je eerst vaststellen wat al is verwerkt. De herstelgids werkt die volgorde uit: Een API-koppeling werkt niet meer: onderzoek en herstel zonder dubbel werk.

Behandel gelijktijdige pogingen

Twee gelijke berichten kunnen bijna tegelijk worden verwerkt. Alleen vooraf kijken of een record bestaat is dan onvoldoende: beide uitvoeringen kunnen niets vinden en vervolgens allebei een doelrecord aanmaken. De beslissing om een zakelijke handeling te claimen moet daarom beschermd zijn tegen gelijktijdigheid, bijvoorbeeld met een geschikte unieke sleutel en consistente opslagregels.

Laat de ontwikkelaar aantonen wat de tweede uitvoering doet terwijl de eerste nog bezig is. Wacht die, leest die dezelfde uitkomst of eindigt die als herkenbare herhaling? Test ook een herstart na onderbreking. De bescherming moet de bedoelde handeling afdekken en niet per ongeluk elke toekomstige wijziging van dezelfde order blokkeren. Vraag om een voorbeeld waarin zowel een herhaling als een echte vervolgwijziging correct wordt onderscheiden.

Onderzoek een time-out zorgvuldig

In een fictieve proef maakt het doelsysteem een conceptfactuur aan, maar gaat de response onderweg verloren. De bron ziet een time-out. Nogmaals aanmaken kan een tweede concept opleveren. De eerste vraag is daarom niet hoe snel we opnieuw proberen, maar welke gegevens bewijzen of de eerste opdracht al is uitgevoerd.

Zoek met de overeengekomen externe referentie of vraag de toestand van een bekende bewerking op wanneer het pakket dat ondersteunt. Kan de koppeling geen betrouwbare conclusie trekken, stuur het item naar een gecontroleerde beoordeling. Maak zichtbaar welke systemen zijn geraadpleegd en welke beslissing nog openstaat. Onzekerheid eerlijk tonen is operationeel beter dan een valse foutmelding die een medewerker aanspoort zonder onderzoek opnieuw te beginnen.

Verwar herhaling niet met een correctie

Een order kan na de eerste verwerking inhoudelijk wijzigen. Dezelfde zakelijke relatie blijft bestaan, maar een nieuw bedrag, adres of orderregel vraagt een aparte afweging. Maak onderscheid tussen dezelfde payload opnieuw aanbieden en een nieuwe versie behandelen. Een beschermingsregel die beide zomaar negeert kan duplicaten voorkomen en tegelijk terechte wijzigingen laten verdwijnen.

Leg per type wijziging vast wat is toegestaan. Een nog niet beoordeeld concept kan mogelijk worden bijgewerkt; een verder verwerkt document kan menselijke beoordeling vragen. Welke behandeling financieel passend is beslist de verantwoordelijke eigenaar. Bewaar de verwijzing naar eerdere versies zodat de correctie begrijpelijk blijft. Gebruik geen nieuw willekeurig kenmerk om de bescherming te omzeilen wanneer iemand eigenlijk een bestaande handeling wil herhalen.

Geef medewerkers een veilige herstelroute

Een hersteloverzicht moet onderscheid maken tussen opnieuw aanbieden, bron corrigeren, doel controleren en afhandelen zonder nieuwe actie. Toon de bronreferentie, laatste poging, eventuele doelreferentie en de reden waarom een volgende stap wordt voorgesteld. Vraag bij een ingrijpende handeling voldoende context, zodat iemand niet alleen een rood vakje probeert weg te werken.

Maak ook de grenzen van toegang duidelijk. Een medewerker die een fout onderzoekt hoeft niet automatisch alle records te kunnen verwijderen of definitieve documenten te wijzigen. Bewaar welke beslissing is genomen en welk resultaat is bevestigd. Controleer dat de herstelactie dezelfde zakelijke sleutel gebruikt waar dat hoort. Een aparte herstelknop die alle bescherming omzeilt maakt het zorgvuldig ontworpen automatische pad onbetrouwbaar.

Test de situaties die duplicaten veroorzaken

Voer dezelfde gebeurtenis tweemaal na elkaar en vervolgens gelijktijdig uit. Onderbreek daarna de proef tussen doelopslag en lokale bevestiging. Test een response die verloren gaat, een doel dat tijdelijk niet bereikbaar is en een echte nieuwe orderversie. De verwachte uitkomst moet gaan over aantallen én identiteit: één bedoeld doelrecord dat met de bron verbonden is.

Controleer daarnaast het meldingsgedrag. Herhaalde bezorging mag niet telkens een nieuw supportticket of klantbericht veroorzaken als dat dezelfde zakelijke actie vertegenwoordigt. Bewaar de proefuitkomsten als regressiescenario’s voor latere wijzigingen. Een systeem is niet bewezen veilig omdat één normale order één concept opleverde; juist de ongunstige volgorde en het herstel laten zien of de gekozen bescherming zijn doel dient.

Stripe: Receive webhook events ↗

Van uitleg naar een concrete projectkeuze

Leg je aannames, open vragen en oplevercriteria vast in de bijbehorende tool. Gebruik de dienstengidsen om uitvoering en afbakening te bespreken.

• API-koppeling laten maken ↗
• CRM Integratie ↗

Vragen over dit onderwerp

Verder met een aansluitende vraag