Salt la conținut
Blog

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

Redacția Tekravel
Scris cu ajutorul IA

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 veziCe știiCe faciCe nu faci
Furnizorul returnează «tarif modificat»Nu s-a rezervat nimicArăți noul total, ceri acceptul, rulezi din nou creareaRulezi din nou cu prețul vechi sperând că trece
Succes, dar totalul diferă de cel acceptat de clientExistă o rezervare la prețul nouReții plata, întrebi clientul, anulezi rezervarea dacă refuzăÎncasezi suma veche și înghiți diferența
Plată încasată, apelul de emitere dă eroareExistă un PNR, starea biletului e necunoscutăRecitești rezervarea, reîncerci emiterea în limită, rambursezi după eaMarchezi rezervarea ca eșuată și uiți PNR-ul
Timeout la creareRezultat necunoscutCauți după referința ta, apoi continui sau reîncerci o datăReîncercare imediată, oarbă
Timeout la anularePoți răspunde încă pentru segmentRecitești starea înainte de a spune ceva clientuluiAfiș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.

Redacția Tekravel

Departamentul de tehnologii de turism

Departamentul de tehnologii de turism al Tekravel scrie pentru industrie: proprietari de agenții, consolidatori și dezvoltatorii care îi integrează. Fiecare articol este verificat pe platforma pe care o descrie înainte de publicare.