Gestionarea erorilor API-ului unui motor de rezervări: trei defecțiuni care costă bani

Tichetul de suport sosește într-o joi seara. Un client a plătit, pagina s-a învârtit, apoi a afișat o eroare generică. Cardul a fost debitat. Jurnalele tale arată un POST către furnizor care nu a primit niciodată răspuns. A blocat compania aeriană un loc? Nimeni nu poate spune, iar clientul așteaptă. O bună gestionare a erorilor API-ului unui motor de rezervări înseamnă în mare parte munca de a nu ajunge niciodată în acea poziție, sau cel puțin de a ști exact ce faci când ajungi.
Majoritatea ghidurilor de integrare tratează erorile ca pe un catalog de coduri de stare. La rezervări, codurile sunt partea ușoară. Ce costă bani este un set mic de situații în care cererea pare eșuată, dar lumea s-a schimbat oricum, sau pare reușită, iar lumea nu s-a schimbat. Trei dintre ele contează mai mult decât restul.
Defecțiunea unu: prețul s-a mișcat între căutare și rezervare
Rezultatele căutării sunt o ofertă, nu un contract. Tarifele sunt păstrate în cache, disponibilul este partajat între toate canalele prin care vinde furnizorul, iar suma pe care ai afișat-o la 14:02 poate fi depășită după câteva minute. Furnizorul îți spune la pasul de creare a rezervării, uneori printr-un răspuns clar «tarif modificat», alteori returnând pe tăcute un alt total într-un răspuns altfel reușit.
A doua variantă este cea periculoasă. Dacă tot codul tău citește confirmarea, salvează rezervarea și debitează clientul cu suma pe care a văzut-o, diferența iese din marja ta sau, mai târziu, dintr-un ADM. Regula e simplă: compară totalul confirmat de furnizor cu totalul acceptat de client, de fiecare dată, în cod, înainte de a încasa plata.
Ce faci când diferă depinde de mărimea diferenței și de cine o suportă. Câțiva bani de rotunjire între monede sunt o toleranță pe care o fixezi o dată. Orice mai mare se întoarce la client ca preț nou, cu un buton explicit de acceptare. Nu absorbi niciodată automat și nu încasa niciodată automat.
Defecțiunea doi: rezervat, dar neemis
Existența unui PNR nu e același lucru cu existența unui bilet. Multe fluxuri creează mai întâi rezervarea și emit e-ticketul într-un pas separat, cu o limită de timp între ele. Dacă plata reușește și emiterea eșuează, ții banii unui client și o rezervare care va expira după ceasul ei.
Defecțiunea e rareori zgomotoasă. Apelul de emitere returnează o eroare sau un timeout, iar rezervarea rămâne într-o stare pe care baza ta o numește «plătit», în timp ce furnizorul spune încă «reținut». Între timp, limita de emitere curge și, spre deosebire de coada ta de suport, compania aeriană nu așteaptă.
Tratează-o ca pe o stare aparte, nu ca pe o variantă de succes sau de eșec. O rezervare are nevoie de cel puțin aceste stări: creată, reținută, plată încasată, în emitere, emisă, eșuată-și-rambursabilă. «Plată încasată, în emitere» este starea care are nevoie de un temporizator: când o rezervare stă prea mult acolo, un job trebuie să recitească rezervarea de la furnizor și să decidă, fără să aștepte ca un om să observe. Decizia e ieftină dacă știi limita de timp a furnizorului, pentru că ea îți spune cât timp poți reîncerca în siguranță înainte să rambursezi.
Defecțiunea trei: timeout cu rezultat necunoscut
Acesta e tichetul de joi seara. Cererea ta a plecat; niciun răspuns nu s-a întors; conexiunea a căzut sau gateway-ul a renunțat. Furnizorul poate să fi procesat-o complet, parțial sau deloc.
Tentația e să reîncerci. Nu reîncerca orbește un apel de creare, pentru că a doua încercare poate produce o a doua rezervare, iar un duplicat e un cost real: două locuri reținute, poate două bilete emise, o dispută de rambursare pe unul dintre ele.
Ordinea sigură este: oprește, apoi citește, apoi decide. Oprește fluxul vizibil clientului cu o stare sinceră, «ne confirmăm rezervarea». Citește partea furnizorului căutând rezervarea după referința pe care ai generat-o înainte de apel (de aceea îți creezi mai întâi propria referință de client și o trimiți, dacă furnizorul o acceptă). Abia apoi decizi: găsită înseamnă să continui din starea reală; negăsită după fereastra proprie de procesare a furnizorului înseamnă că poți reîncerca o dată în siguranță.
Dacă furnizorul nu oferă căutare după referința ta, caută după numele pasagerului, rută și dată într-o fereastră îngustă și consideră o potrivire drept găsită. Urât, dar mult mai ieftin decât un duplicat.
Un tabel de decizie cu care poți să nu fii de acord
| Ce vezi | Ce știi | Ce faci | Ce nu faci |
|---|---|---|---|
| Furnizorul returnează «tarif modificat» | Nu s-a rezervat nimic | Arăți noul total, ceri acceptul, rulezi din nou crearea | Rulezi din nou cu prețul vechi sperând că trece |
| Succes, dar totalul diferă de cel acceptat de client | Există o rezervare la prețul nou | Reții plata, întrebi clientul, anulezi rezervarea dacă refuză | Încasezi suma veche și înghiți diferența |
| Plată încasată, apelul de emitere dă eroare | Există un PNR, starea biletului e necunoscută | Recitești rezervarea, reîncerci emiterea în limită, rambursezi după ea | Marchezi rezervarea ca eșuată și uiți PNR-ul |
| Timeout la creare | Rezultat necunoscut | Cauți după referința ta, apoi continui sau reîncerci o dată | Reîncercare imediată, oarbă |
| Timeout la anulare | Poți răspunde încă pentru segment | Recitești starea înainte de a spune ceva clientului | Afișezi «anulat» pentru că s-a dat clic |
Un rând cu care poți polemiza: unele echipe rambursează la prima eroare de emitere ca să-și liniștească clientul. E de apărat la bilete mici și un obicei prost la cele scumpe, pentru că poți pierde un tarif pe care l-ai fi putut salva un minut mai târziu.
Cât te costă să greșești
Fiecare defecțiune are altă factură. O schimbare de preț ratată înseamnă marjă pierdută pe fiecare rezervare atinsă, adesea observată abia la reconciliere. Un caz rezervat-neemis este un client care ajunge pe aeroport cu o rezervare expirată și o taxare pe card: un chargeback și o problemă de reputație în același timp. O reîncercare oarbă după timeout este o rezervare dublă, iar companiile aeriene auditează duplicatele; un tipar de ele ajunge ușor într-un ADM.
Nimic din toate astea nu e exotic. Este instalația fără glamour care desparte o demonstrație de ceva ce poți lăsa să ruleze peste weekend.
Construiește jobul de reconciliere înainte să ai nevoie de el
Toate cele trei defecțiuni se termină la fel: baza ta și cea a furnizorului nu se potrivesc. Scrie deci jobul care le compară înainte de primul incident, nu după. O rulare nocturnă e minimul; la câteva minute pentru orice se află într-o stare de tranziție e mai bine. Listează rezervările blocate în reținut, emitere sau necunoscut, întreabă furnizorul ce crede și fie repară înregistrarea, fie deschide un tichet cu dovezile atașate.
Păstrează fiecare cerere și răspuns ale apelurilor de rezervare, inclusiv timeouturile, cu referința trimisă. Când un client contestă o taxare, acel jurnal e argumentul tău. Ține și discuția despre latență cinstită: vezi ce poți și ce nu poți repara la latența API-urilor pentru a înțelege de ce timeouturile sunt un fapt al vieții, nu un bug de eliminat.
Dacă încă decizi cum legi conexiunea cu furnizorul, ghidul din integrarea API-ului de rezervare zboruri acoperă ordinea apelurilor presupusă de acest articol. Iar dacă vrei să discuți cum se mapează aceste stări pe API-urile noastre de zboruri și hoteluri, accesul începe cu o conversație: vezi pagina API-urilor de călătorie.