Integrare API rezervări zboruri: ce nu spune documentația

Pe tichetul din board scrie doar „adaugă zboruri”. Când ajungi la o integrare API rezervări zboruri după ce ai livrat deja o integrare de plăți, una de tarife de transport, poate și una de hărți, vii cu modelul mental evident: căutare, rezultate, încasezi cardul, gata. Apoi prima rezervare reală se întoarce la alt preț decât cel din pagina de rezultate, a doua dă timeout și nimeni nu-ți poate spune dacă clientul are loc, iar cineva din operațiuni întreabă de ce există o rezervare, dar niciun bilet. Privită din afară, seamănă cu checkout-ul unui magazin online. Dedesubt, este o tranzacție distribuită cu sisteme proiectate cu mult înainte de REST, iar cele mai multe surprize vin exact din această diferență.
Textul e scris pentru dezvoltatorul care n-a văzut niciodată un PNR. Nu e despre endpoint-urile unui anumit furnizor: numele se schimbă de la un furnizor la altul, forma rămâne aceeași.
Secvența de apeluri dintr-o integrare API rezervări zboruri
Aproape orice API de zboruri, oricum și-ar numi metodele, parcurge aceiași patru pași. Să trasezi corect granițele dintre ei reprezintă cea mai mare parte a muncii.
| Pas | Ce primești | Ce trebuie să salvezi | Ce merge prost |
|---|---|---|---|
| Căutare | Itinerarii cu un preț și o cheie opacă de ofertă sau de tarif | Nimic durabil — rezultatele se învechesc repede | Tratezi prețul ca final; cheia expiră înainte de checkout |
| Preț / verificare | Prețul confirmat, regulile tarifului, bagajul, uneori câmpuri obligatorii pentru pasageri | Oferta verificată și termenul ei de expirare | Prețul s-a schimbat; clasa s-a epuizat; regulile diferă de ce ai afișat |
| Rezervare | O rezervare — PNR-ul — cu un record locator și un termen-limită de emitere | Referința ta proprie, locatorul, termenul-limită, datele exacte ale pasagerilor trimise | Timeout fără răspuns; PNR-uri duplicate; nume respinse |
| Emitere bilet | Numerele de e-ticket emise; aici se angajează efectiv banii | Fiecare număr de bilet, legat de pasagerul și segmentul cărora le aparține | Emitere parțială; rezervare anulată de companie pentru că a trecut termenul |
Rândul cu care se ceartă lumea e al treilea, pentru că multe API-uri îți permit să rezervi și să emiți biletul într-un singur apel. Folosește-l, dacă vrei. În lumea companiei aeriene, cele două rămân totuși separate: un PNR poate exista fără bilet, iar un bilet poate eșua după ce PNR-ul a fost creat. Un endpoint combinat doar ascunde momentul în care una a reușit și cealaltă nu, așa că modelul tău de date tot trebuie să aibă loc pentru acea stare.
Observă și ce nu întoarce căutarea: o promisiune. E o reclamă. Pasul de preț este oferta fermă, iar vânzarea e doar biletul.
De ce prețul găsit la căutare nu e prețul la care rezervi
Dezvoltatorii web se așteaptă la un catalog. Inventarul aerian nu este unul. Un zbor se vinde pe clase de rezervare, fiecare fiind un lot de locuri la un anumit tarif, iar compania deschide și închide aceste loturi continuu, pe măsură ce zborul se umple. Rezultatele căutării sunt asamblate rapid din disponibilități care pot fi deja puțin în urmă; până când utilizatorul a tastat datele din două pașapoarte, cel mai ieftin lot de pe acel zbor se poate să se fi închis. Când rulează pasul de preț, întreabă din nou, iar răspunsul onest e uneori mai mare.
Taxele aduc propria lor deviere. Sunt recalculate la pricing pentru pasagerii și ruta exacte, iar un copil sau un infant are alt preț decât adultul pe care l-a presupus căutarea. Conversia valutară, dacă vitrina ta afișează altă monedă decât cea în care cotează furnizorul, e încă un loc în care cifra se mișcă.
Consecința de design e simplă și des sărită: nu încasa niciodată pe prețul din căutare. Rulează pasul de preț înainte de plată, compară, iar dacă suma s-a schimbat, arată noua cifră și cere acordul. Orice adaos aplici trebuie recalculat pe tariful nou, nu preluat din pagina de rezultate — e aceeași logică prin care trece o agenție când își stabilește strategia de adaos online, și se strică la fel atunci când baza se mișcă sub ea.
Idempotența și ce înseamnă un timeout la rezervare
Aceasta e secțiunea de citit de două ori.
Când un apel de rezervare dă timeout, nu știi ce s-a întâmplat. Cererea poate să nu fi ajuns deloc. Poate a ajuns și a eșuat. Sau — cazul care doare — a ajuns, furnizorul a creat PNR-ul la compania aeriană, iar răspunsul s-a pierdut pe drumul înapoi spre tine. Pentru codul tău, toate trei arată identic. Pentru compania aeriană, al treilea e o rezervare activă care ține locuri pe numele clientului tău.
Reflexul adus din alte integrări e să reîncerci. Aici, o reîncercare oarbă poate produce un al doilea PNR pentru aceiași pasageri pe același zbor. Companiile aeriene tratează rezervările duplicate ca pe o încălcare a politicii lor; în funcție de transportator și de acordurile agenției, consecința merge de la anularea automată a uneia sau a ambelor rezervări până la o notă de debit — un ADM — trimisă celui care le-a emis. Agenția care o primește va vrea să știe de ce sistemul tău a rezervat de două ori.
Ce funcționează, cam în această ordine:
- Creează-ți propria referință de rezervare înainte de apel, salveaz-o și trimite-o odată cu cererea oriunde API-ul acceptă o referință de client. Dacă API-ul suportă o cheie de idempotență (idempotency key), folosește-o; dacă nu, referința ta rămâne ceea ce îți permite să cauți rezervarea ulterior.
- Modelează explicit starea necunoscută. În așteptare, confirmată, eșuată — și necunoscută. Un timeout mută rezervarea în necunoscut, nu în eșuat.
- Rezolvă necunoscutul întrebând, nu repetând. Recuperează rezervarea după referința ta sau listează rezervările recente pentru acei pasageri înainte să decizi dacă mai încerci o dată.
- Rulează un job de reconciliere care trece prin tot ce e încă necunoscut și compară cu ce raportează furnizorul, iar ce nu poate lămuri trimite într-o coadă pentru un om, în loc să ghicească.
Timeout-urile la emitere sunt aceeași problemă, doar că implică bani. Dacă încasezi cardul înainte de emitere și emiterea se blochează, ai un client care a plătit și, posibil, niciun bilet. Dacă emiți înainte de încasare și încasarea eșuează, ai emis un document pe care cineva trebuie să-l plătească companiei aeriene. Forma obișnuită e autorizarea cardului mai întâi, apoi emiterea, apoi încasarea la succes — ideea e să decizi asta în mod deliberat, nu să o descoperi în producție.
Conceptele din turism care îi surprind pe dezvoltatorii web
Niciunul nu e greu. Fiecare l-a costat pe cineva o săptămână pentru că nu știa că există.
Un PNR nu e un bilet
PNR-ul este înregistrarea rezervării: pasageri, segmente, contacte, un termen-limită. Biletul e documentul plătit care îi dă pasagerului dreptul să zboare. Un PNR fără bilet expiră la termenul de emitere, iar locurile revin la vânzare, uneori fără ca tu să afli.
Numele sunt aproape imuabile
După emitere, majoritatea tarifelor nu permit schimbarea numelui dincolo de o corectură minoră, iar regulile despre ce înseamnă „minor” diferă de la o companie la alta. Numele trebuie să corespundă documentului de călătorie. Colectează separat numele de familie și prenumele, nu lăsa un titlu introdus liber să ajungă în câmpul de nume și validează înainte de apelul de rezervare, nu după.
Tipurile de pasager au preț, nu sunt decor
Adult, copil și infant sunt tipuri de tarif, iar vârsta care decide ce se aplică e de obicei vârsta la data călătoriei, nu la data rezervării. Un infant ținut în brațe de regulă nu ocupă loc și poate călători doar cu un adult. Greșești tipul, iar pasul de preț fie eșuează, fie cotează tariful greșit.
Orele sunt locale, iar segmentele nu sunt tronsoane
Orele de plecare și de sosire sunt date în ora locală a fiecărui aeroport. Nu le converti în fusul orar al utilizatorului la afișare și nu calcula durate scăzându-le fără decalaje. O călătorie conține segmente; un segment cu o escală tehnică conține mai mult de un tronson. Interfața și datele tale trebuie să cadă de acord care dintre ele se numește „escală”.
Lucrurile se întâmplă și după vânzare
Companiile aeriene schimbă orarele după emiterea biletelor. O rezervare corectă la emitere poate arăta, săptămâni mai târziu, o oră nouă, un număr de zbor nou sau o conexiune ruptă, iar în funcție de furnizor afli prin notificare, printr-o coadă sau recuperând din nou rezervarea. Pornește de la ideea că rezervarea se poate schimba după ce ai încetat să te uiți la ea.
Void nu înseamnă rambursare
La scurt timp după emitere există de obicei o fereastră în care biletul poate fi anulat prin void, ca și cum n-ar fi existat. După această fereastră, e posibilă doar o rambursare conform regulilor tarifului, care poate costa o penalizare sau poate să nu returneze nimic. Fereastra și regulile ei țin de furnizor și de acordul de emitere; citește-le înainte să construiești un buton „anulează”.
Cât costă greșelile
Eșecurile dintr-o integrare de zboruri sunt scumpe într-un fel anume: cad pe oameni, nu în loguri. O rezervare duplicată devine un telefon la compania aeriană și, posibil, o notă de debit pe contul agenției. Un client taxat fără bilet devine o rambursare, o reclamație și un risc de chargeback. Un bilet emis fără o plată reușită devine o datorie față de compania aeriană pe care cineva trebuie s-o achite. O schimbare de orar pe care n-a procesat-o nimeni devine un călător în aeroport pentru un zbor care a plecat mai devreme.
Nimic din toate acestea nu apare într-un test pe drumul fericit. Scrie mai întâi drumurile nefericite: timeout-ul la rezervare, prețul care a crescut, biletul care a eșuat după PNR, void-ul după o plată reușită. Dacă pe acestea le-ai rezolvat, drumul fericit e partea ușoară.
Testarea pe un API de zboruri
Mediile de test ale furnizorilor sunt utile și incomplete. Tind să fie mai liniștite decât producția, așa că clasele epuizate și schimbările de preț apar mai rar, iar unele nu simulează deloc timeout-uri. Folosește-le pentru forma apelurilor și pentru erorile de validare, apoi planifică o rulare controlată în producție, cu rezervări reale pe care le anulezi prin void în interiorul ferestrei — cu operațiunile la curent că faci asta.
Dacă merită să integrezi deloc e o altă întrebare. Dacă de fapt ai nevoie de o vitrină, nu de inventar brut în propriul sistem, compromisul e explicat în white label sau propriul motor de rezervări, iar același raționament se aplică unui portal B2B pentru subagenți. Dacă vrei inventarul chiar în codul tău, platforma oferă API-uri pentru zboruri și hoteluri, iar accesul începe cu o discuție despre cazul tău de utilizare, nu cu o cheie obținută în self-service — exact momentul potrivit să pui fiecare dintre întrebările de mai sus.