Foutafhandeling in de API van je boekingsmotor: drie fouten die geld kosten

Het supportticket komt binnen op een donderdagavond. Een klant heeft betaald, de pagina bleef draaien en toonde daarna een generieke fout. De kaart is belast. Je logs tonen een POST naar de leverancier die nooit antwoord kreeg. Heeft de airline een stoel vastgehouden? Niemand kan het zeggen, en de klant wacht. Goede foutafhandeling in de API van een boekingsmotor is vooral het werk om nooit in die positie te komen, of om in elk geval precies te weten wat je moet doen als het toch gebeurt.
De meeste integratiegidsen behandelen fouten als een catalogus van statuscodes. Bij boekingen zijn de codes het makkelijke deel. Wat geld kost is een kleine groep situaties waarin het verzoek mislukt lijkt maar de wereld toch veranderd is, of geslaagd lijkt terwijl de wereld niet veranderd is. Drie ervan wegen zwaarder dan de rest.
Fout één: de prijs verschoof tussen zoeken en boeken
Zoekresultaten zijn een offerte, geen contract. Tarieven worden gecachet, voorraad wordt gedeeld over elk kanaal waarlangs de leverancier verkoopt, en het bedrag dat je om 14:02 toonde kan enkele minuten later verouderd zijn. De leverancier meldt het bij de stap waarin je de boeking aanmaakt, soms met een nette «tarief gewijzigd»-respons, soms door stilletjes een ander totaal terug te geven binnen een verder geslaagde respons.
De tweede variant is de gevaarlijke. Als je code de bevestiging leest, de boeking opslaat en de klant het bedrag in rekening brengt dat hij zag, gaat het verschil van je marge af, of later van een ADM. De regel is simpel: vergelijk het door de leverancier bevestigde totaal met het totaal dat de klant accepteerde, elke keer, in code, voordat je de betaling int.
Wat je doet bij een verschil hangt af van de grootte van het gat en van wie het draagt. Een paar cent afronding tussen valuta's is een tolerantie die je één keer instelt. Alles daarboven gaat terug naar de klant als nieuwe prijs met een expliciete accepteerknop. Absorbeer het nooit automatisch en belast het nooit automatisch.
Fout twee: geboekt, maar niet getickett
Een bestaand PNR is niet hetzelfde als een bestaand ticket. Veel flows maken eerst de reservering en geven het e-ticket uit in een aparte stap, met een tijdslimiet ertussen. Slaagt de betaling en mislukt de uitgifte, dan heb je het geld van een klant en een reservering die op haar eigen klok verloopt.
De fout is zelden luid. De uitgifteaanroep geeft een fout of timeout, en de boeking blijft in een status die jouw database «betaald» noemt terwijl de leverancier nog «vastgehouden» zegt. Ondertussen loopt de ticketingdeadline, en anders dan je supportwachtrij wacht de airline niet.
Behandel het als een eigen status, niet als variant van succes of mislukking. Een boeking heeft minstens deze toestanden nodig: aangemaakt, vastgehouden, betaling geïnd, wordt uitgegeven, uitgegeven, mislukt-en-terugbetaalbaar. «Betaling geïnd, wordt uitgegeven» is de status die een timer nodig heeft: zit een boeking daar te lang, dan moet een job de reservering bij de leverancier opnieuw lezen en beslissen, zonder te wachten tot een mens het merkt. De beslissing is goedkoop als je de limiet van de leverancier kent, want die vertelt hoe lang je veilig kunt herproberen voordat je moet terugbetalen.
Fout drie: de timeout met onbekende uitkomst
Dit is het ticket van donderdagavond. Je verzoek is weg; er kwam geen antwoord; de verbinding viel weg of de gateway gaf het op. De leverancier kan het volledig, gedeeltelijk of helemaal niet verwerkt hebben.
De verleiding is opnieuw proberen. Probeer een aanmaakaanroep niet blind opnieuw, want de tweede poging kan een tweede reservering opleveren, en een dubbele boeking kost echt geld: twee stoelen vastgehouden, misschien twee tickets uitgegeven, een terugbetalingsruzie over een van beide.
De veilige volgorde is: stoppen, lezen, dan beslissen. Stop de klantflow met een eerlijke status, «we bevestigen je boeking». Lees de kant van de leverancier door de boeking op te zoeken met de referentie die je vóór de aanroep zelf genereerde (daarom maak je eerst een eigen klantreferentie en stuur je die mee als de leverancier dat toestaat). Pas dan beslis je: gevonden betekent doorgaan vanuit de echte status; niet gevonden na het eigen verwerkingsvenster van de leverancier betekent dat je één keer veilig opnieuw kunt proberen.
Biedt de leverancier geen opzoeking op jouw referentie, zoek dan op naam van de passagier, route en datum binnen een smal venster en beschouw een treffer als gevonden. Lelijk, maar veel goedkoper dan een dubbele boeking.
Een beslistabel waar je het mee oneens mag zijn
| Wat je ziet | Wat je weet | Wat je doet | Wat je niet doet |
|---|---|---|---|
| Leverancier geeft «tarief gewijzigd» | Er is niets geboekt | Toon het nieuwe totaal, vraag akkoord, voer de aanmaak opnieuw uit | Opnieuw uitvoeren met de oude prijs in de hoop dat het slaagt |
| Succes, maar het totaal wijkt af van wat de klant accepteerde | Er bestaat een boeking tegen de nieuwe prijs | Houd de betaling vast, vraag de klant, annuleer de boeking bij weigering | Het oude bedrag innen en het verschil slikken |
| Betaling geïnd, uitgifteaanroep geeft fout | Er is een PNR, ticketstatus onbekend | Lees de reservering opnieuw, herprobeer uitgifte binnen de limiet, betaal daarna terug | De boeking als mislukt markeren en het PNR vergeten |
| Timeout bij aanmaken | Uitkomst onbekend | Zoek op je eigen referentie, ga dan door of probeer één keer opnieuw | Direct blind opnieuw proberen |
| Timeout bij annuleren | Je kunt nog aansprakelijk zijn voor het segment | Lees de status opnieuw voordat je de klant iets vertelt | «Geannuleerd» tonen omdat er geklikt is |
Eén regel waar je over kunt twisten: sommige teams betalen terug bij de eerste uitgiftefout om de klant rustig te houden. Verdedigbaar bij kleine tickets, een slechte gewoonte bij dure, want je kunt een tarief verliezen dat je een minuut later nog had kunnen redden.
Wat het kost om dit fout te doen
Elke fout heeft een andere rekening. Een gemiste prijswijziging is marge die je verliest op elke geraakte boeking, vaak pas bij de afstemming ontdekt. Een geboekt-maar-niet-getickett geval is een klant die op het vliegveld staat met een verlopen reservering en een afschrijving op de kaart: een chargeback en een reputatieprobleem tegelijk. Een blinde herpoging na een timeout is een dubbele reservering, en airlines controleren dubbele boekingen; een patroon daarvan belandt al snel in een ADM.
Niets hiervan is exotisch. Het is het onglamoureuze leidingwerk dat een demo scheidt van iets wat je een weekend kunt laten draaien.
Bouw de afstemmingsjob voordat je hem nodig hebt
Alle drie de fouten eindigen hetzelfde: jouw database en die van de leverancier zijn het oneens. Schrijf dus de job die ze vergelijkt vóór het eerste incident, niet erna. Een nachtelijke run is het minimum; om de paar minuten voor alles in een tussenstatus is beter. Hij somt boekingen op die vastzitten in vastgehouden, uitgifte of onbekend, vraagt de leverancier wat die denkt, en herstelt het record of maakt een ticket aan met het bewijs erbij.
Bewaar elk verzoek en elke respons van boekingsaanroepen, ook timeouts, met de referentie die je meestuurde. Als een klant een afschrijving betwist, is dat log je argument. Het houdt ook het gesprek over latentie eerlijk: lees wat je wel en niet kunt oplossen aan API-latentie om te zien waarom timeouts een gegeven zijn en geen bug die je uitroeit.
Ben je nog aan het bepalen hoe je de leveranciersverbinding zelf aansluit, dan behandelt de uitleg in integratie van een vluchtboekings-API de volgorde van aanroepen die dit artikel veronderstelt. En wil je bespreken hoe deze statussen zich verhouden tot onze vlucht- en hotel-API's, dan begint toegang met een gesprek: bekijk de pagina over reis-API's.