Travelport Air API Entegrasyon Rehberi

Travelport JSON Air v11 entegrasyonu “search yap, fare göster, booking gönder” akışı değildir. Search sonucu, AirPrice doğrulaması, workbench içindeki mutable booking state, commit sonrası reservation ve ticket/servicing lifecycle birbirinden farklı kimlik ve dayanıklılık sınırlarına sahiptir.

Travelport aynı API ailesinde GDS ve NDC content sunar; fakat aynı itinerary görünümü aynı capability anlamına gelmez. Sağlam tasarım karşılaştırılabilir alanları normalize ederken source, carrier, offer lineage ve servicing capability'lerini korur.

Production senaryosu

Gerçek bir production senaryosunda kullanıcı NDC offer'ı seçer, ödeme formunda beklerken reference veya workbench expire olur ve commit cevabı network timeout nedeniyle kaybolur. Sistem bunu basit failure sayıp yeniden booking yaparsa duplicate reservation; hiç işlem yapmazsa kullanıcıdan para alınıp confirmation gösterilemeyen unknown state oluşabilir.

Entegrasyonun sınırı nedir?

Flights API erişim ve content kapsamınıza göre şunları sağlayabilir:

• flight search ve availability,
• selected offer pricing,
• fare rules, seats ve ancillaries,
• workbench tabanlı booking,
• payment ve ticketing,
• reservation retrieve,
• GDS/NDC'ye göre değişen cancel, void, refund ve exchange akışları.

Bu, her carrier ve source için bütün fonksiyonların eşit olduğu anlamına gelmez. Capability matrix, provision edilmiş PCC/credential, carrier ve GDS/NDC source'a göre oluşturulmalıdır.

Sisteminiz hâlâ şunların sahibidir:

• canonical airport, carrier ve traveler identity,
• normalized itinerary/offer modeli,
• search deadline ve supplier fan-out,
• internal booking attempt ve idempotency,
• user reconfirmation policy,
• payment/security boundary,
• reservation/ticket reconciliation,
• source-specific servicing UX'i.

Erişim ve OAuth nasıl yönetilmeli?

Travelport TripServices credential'ları provisioning sırasında sağlanır. API OAuth 2.0 token kullanır; resmî getting-started dokümanı yeni token'ın 24 saatte bir alınması gerektiğini belirtir.

Token management shared backend component olmalıdır:

Provisioned credentials
        |
        v
OAuth token manager ---> encrypted shared cache
        |
        v
Travelport adapter pool

• credential'ları browser veya mobile app'e koymayın,
• token'ı expiry margin ile reuse edin,
• concurrent refresh'i single-flight yapın,
• pre-production ve production base URL/credential'larını ayırın,
• auth failure'ı shopping veya booking failure'dan ayrı ölçün.

PCC, agency, market ve content entitlement gibi request context'i config version ile kaydedin. Aynı normalized request farklı credential scope'unda farklı content döndürebilir.

End-to-end flow nasıl görünmeli?

Traveler Search
      |
      v
Normalized Air Request
      |
      v
Travelport Search (GDS / NDC)
      |
      v
Normalized Offer + Source References
      |
      v
AirPrice / selected-offer validation
      |
  +---+----------------+
  |                    |
valid             changed/unavailable
  |                    |
  v                    v
Create Workbench    user reconfirm / re-search
  |
  +--> add offer
  +--> add traveler/contact
  +--> add seat/ancillary/payment where applicable
  |
  v
Commit Workbench
  |
  v
Reservation Locator(s)
  |
  +--> retrieve
  +--> ticket/fulfill
  +--> cancel/modify/exchange where supported
  +--> reconciliation

AirPrice çoğu carrier için optional/recommended olabilir; resmî dokümana göre low-cost ve bazı NDC carrier'lar için gereklidir. Product policy daha güçlü olabilir: selected offer'ı commit öncesi her zaman price etmek, değişiklik davranışını tek yerde yönetir.

Normalized request modeli neyi korumalı?

interface AirSearchRequest {
  origin: string;
  destination: string;
  departureDate: string;
  returnDate?: string;
  travelers: Array<{
    type: "ADT" | "CHD" | "INF";
    count: number;
  }>;
  cabin?: string;
  directOnly?: boolean;
  currency: string;
  market: string;
  agencyContextRef: string;
}

Airport/city code, passenger type ve age semantics, point of sale, currency ve agency context cache key ve source request ile birlikte korunmalıdır. Fare sonucu yalnız origin/destination/date üzerinden tekrar üretilemez.

Offer response nasıl normalize edilmeli?

interface AirOffer {
  provider: "travelport";
  contentSource: "GDS" | "NDC";
  source?: string;
  sourceOfferRef: string;
  itinerary: Array<{
    origin: string;
    destination: string;
    departureAt: string;
    arrivalAt: string;
    marketingCarrier: string;
    operatingCarrier?: string;
    flightNumber: string;
    bookingClass?: string;
  }>;
  passengerPrices: unknown[];
  fareBrand?: string;
  baggage?: unknown;
  ancillariesSupported: boolean;
  baseAmount: number;
  taxAmount: number;
  totalAmount: number;
  currency: string;
  observedAt: string;
  sourcePayloadRef: string;
}

Görsel olarak aynı flight number ve saatlere sahip iki offer farklı content source, validating carrier, fare product veya servicing capability taşıyabilir. Offer fingerprint deduplication için kullanılabilir; provider source reference'ın yerine geçmez.

Reference payload ile full payload arasındaki sınır nedir?

Travelport follow-on request'lerde önceki Search/AirPrice cevabındaki reference'ları veya gerekli itinerary detaylarını taşıyan full payload'ı destekler. Reference daha küçük olabilir fakat provider cache lifetime'a bağlıdır.

Güncel v11 Booking Guide'a göre Travelport search cache'i GDS content için 12 dakika, NDC content için 34 dakika tutulur. Reference ile price veya workbench'e add-offer çağrısı bu pencere içinde tamamlanmalıdır. Bu süreleri kendi offer validity garantiniz olarak yorumlamayın; price veya availability daha erken değişebilir.

Reference expired olduğunda:

1. aynı reference'ı retry loop'a sokmayın,
2. yeniden search veya desteklenen full-payload path'ini değerlendirin,
3. yeni offer ile eski selection'ın equivalence kontrolünü yapın,
4. amount/rule değiştiyse user reconfirmation isteyin.

AirPrice hangi boundary'yi oluşturur?

AirPrice seçili search sonucunun pricing'ini doğrular. En azından şunları ayrı saklayın:

• displayed amount,
• priced amount,
• base/tax/fee breakdown,
• pricing timestamp,
• source ve offer reference,
• fare brand/class,
• baggage ve rule snapshot,
• price-updated status.

SELECTED
   |
AIR_PRICE
   |
   +--> MATCHED -----> READY_FOR_WORKBENCH
   +--> CHANGED -----> USER_RECONFIRM_REQUIRED
   +--> FAILED ------> RE_SEARCH_REQUIRED

Fiyat aynı kalsa bile baggage veya fare rule değişikliği material olabilir. Reconfirmation policy yalnız numeric total delta'ya bakmamalıdır.

Workbench neden ephemeral transaction state'tir?

Workbench offer, traveler, contact, payment, seat ve ancillary'yi commit öncesinde bir araya getiren mutable container'dır. Resmî v11 dokümanına göre workbench 30 dakika geçerlidir; commit edilmezse expire olur.

Workbench ID:

• durable reservation ID değildir,
• anonymous search cache'inde tutulmamalıdır,
• başka user's session'ı ile paylaşılmamalıdır,
• expiry-aware state taşımalıdır,
• failed attempt sonrası otomatik olarak yeniden kullanılmamalıdır.

booking_attempt
- internal_attempt_id
- source_offer_ref
- priced_amount
- workbench_id
- workbench_expires_at
- status
- reservation_locator
- carrier_locator
- created_at

Commit workbench'teki state'i reservation'a dönüştürür ve workbench lifecycle'ını bitirir. GDS two-step commit seçeneği belirli price/schedule-change warning senaryolarında booking yaratmadan kullanıcıya karar alanı açabilir; bu capability NDC için aynı değildir.

Durable ve ephemeral data nasıl ayrılmalı?

Durable saklayın

• canonical airport/carrier mapping'leri,
• normalized search context,
• offer observation ve price breakdown,
• original payload'a güvenli reference,
• internal booking attempt,
• reservation ve carrier locator'ları,
• ticket/document identifier'ları,
• lifecycle/status event'leri,
• servicing capability snapshot,
• reconciliation sonucu.

Ephemeral saklayın

• OAuth token,
• search/catalog reference'ları,
• workbench ID ve workbench content,
• seat/ancillary quote reference'ları,
• temporary payment/session context.

NDC booking'lerde Travelport locator ile carrier locator birlikte dönebilir. İkisini de typed identity olarak saklayın; string locator'ları source bilgisi olmadan birleştirmeyin.

GDS ve NDC capability farkı nasıl modellenmeli?

Hard-coded isNdc branch'leri yerine booking anındaki capability snapshot'ı saklayın:

interface AirServicingCapabilities {
  source: "GDS" | "NDC";
  seatMap: boolean;
  paidAncillaries: boolean;
  hold: boolean;
  instantPay: boolean;
  void: boolean;
  cancel: boolean;
  refund: boolean;
  exchange: boolean;
}

NDC ve GDS; fare rules, seat/ancillary, locator, held booking, ticketing, modification, exchange ve refund akışlarında farklı olabilir. Current carrier/source support table go-live sırasında ve periyodik review'da yeniden doğrulanmalıdır.

Commit idempotency ve unknown state nasıl yönetilmeli?

Kritik senaryo:

1. service commit gönderir,
2. carrier/Travelport reservation oluşturur,
3. response network'te kaybolur,
4. client işlemi failed sanır.

Commit'i kör tekrar göndermek ikinci reservation veya belirsiz workbench davranışı doğurabilir. Internal attempt'i commit öncesi SUBMITTING durumuna alın ve correlation data'yı yazın. Timeout sonrası BOOKING_STATE_UNKNOWN üretin.

Recovery sırası:

1. elinizde dönen locator varsa Reservation Retrieve yapın,
2. provider correlation/support verisiyle original outcome'u araştırın,
3. workbench ve attempt state'ini reconcile edin,
4. duplicate riski çözülmeden yeni booking başlatmayın,
5. otomatik recovery mümkün değilse manual review'a taşıyın.

HTTP success ile business success'i ayırın. Commit response'ta warning, price update, eksik carrier locator veya ticketing pending state bulunabilir.

Reservation ve ticketing source of truth nedir?

Commit sonrası durable operasyon identity'si reservation locator'dır. Reservation Retrieve; itinerary, offers, traveler, receipt/document ve schedule-change state'ini doğrulamak ve local lifecycle ile provider state arasındaki drift'i bulmak için kullanılmalıdır.

Booking confirmation ticket issuance değildir. Held booking'in ticketing time limit'i commit response'taki ilgili expiry/payment alanlarından okunmalı; “genellikle 24 saat” gibi default assumption'a güvenilmemelidir. Ticket number ve document state ayrı lifecycle'dır.

RESERVATION_CONFIRMED
       |
       +--> TICKETING_PENDING
       +--> TICKETED
       +--> TICKETING_FAILED
       +--> EXPIRED / CANCELLED

Error taxonomy ve retry policy

AUTH_FAILED
ENTITLEMENT_OR_SCOPE_DENIED
INVALID_SEARCH_CONTEXT
NO_AVAILABILITY
REFERENCE_EXPIRED
PRICE_CHANGED
OFFER_UNAVAILABLE
WORKBENCH_EXPIRED
WORKBENCH_REJECTED
PAYMENT_REJECTED
COMMIT_WARNING
COMMIT_REJECTED
BOOKING_STATE_UNKNOWN
CARRIER_LOCATOR_PENDING
TICKETING_FAILED
RETRIEVE_FAILED
SERVICING_UNSUPPORTED
RATE_LIMITED
PROVIDER_TIMEOUT
PROVIDER_5XX

Search ve read operation'larında transient network/selected 5xx bounded retry alabilir. Reference expired, validation, unsupported servicing, payment rejection ve price change kör retry edilmemelidir. Rate limit'te server guidance, jitter ve shared concurrency budget kullanın.

Stage bazlı timeout budget ayırın:

Search             -> interactive deadline'ın bir bölümü
AirPrice           -> sıkı selection-time budget
Workbench steps    -> bounded transaction budget
Commit             -> daha uzun, unknown-state recovery ile
Retrieve/ticketing -> async retry ve reconciliation'a uygun

Failure mode'lar

Expired reference

Search cache ömrü geçmiştir; tekrar price/add-offer yapmak permanent failure üretir. Re-search gerekir.

Workbench expiry

Traveler payment formunda beklerken 30 dakikalık state biter. UI countdown yerine backend expiry ve restart strategy kullanmalıdır.

Price veya fare-rule drift

Total değişmese bile baggage/refund koşulu değişebilir. Material-change evaluator gerekir.

GDS/NDC capability leakage

Bir source'ta çalışan refund veya exchange diğerinde varmış gibi sunulur. Reservation-time capability snapshot gerekir.

Missing carrier locator

Commit başarılıdır fakat carrier locator gecikmiştir. Booking'i failed saymak yerine retrieve/reconciliation kuyruğuna alın.

Commit response loss

Reservation oluşur fakat client timeout alır. Blind retry yerine unknown-state recovery gerekir.

Ticketing time-limit breach

Reservation vardır fakat ticketing tamamlanmadan expiry olur. Order-to-ticket SLO ve alarm gerekir.

Monitoring ve KPI'lar

Authentication ve access

• token generation success/failure,
• token age ve refresh margin,
• entitlement rejection by PCC/source,
• auth-related blocked traffic.

Search ve price

• search success/no-availability rate,
• GDS/NDC offer share,
• p50/p95 latency,
• reference-expired rate,
• offer-to-AirPrice conversion,
• price/rule change rate,
• source coverage by route/carrier.

Booking

• workbench create/add-offer/commit success,
• workbench expiry rate,
• user reconfirmation rate,
• booking unknown-state rate,
• missing-carrier-locator age,
• duplicate-prevented count.

Fulfillment ve servicing

• reservation retrieve success,
• held-to-ticketed conversion,
• ticketing pending age,
• time-limit breach,
• cancel/void/refund/exchange success by source,
• reconciliation gap count and age.

Provider health dashboard'u yalnız HTTP uptime göstermemeli; GDS/NDC source bazında semantic success ve lifecycle completion göstermelidir.

Security boundary

• credential ve OAuth token backend secret store'da olmalı,
• PII/payment data loglarda maskelenmeli,
• raw source payload encrypted ve retention-limited tutulmalı,
• workbench ownership internal user/session'a bağlanmalı,
• payment operation authorization ve audit trail taşımalı,
• support dump'larında traveler/document data redacted olmalı.

Go-live checklist

• Provisioning, PCC, credential ve content entitlement doğrulandı mı?
• Pre-production ve production tamamen ayrıldı mı?
• OAuth token reuse ve refresh single-flight mı?
• Canonical airport/carrier ID'leri provider identity'den ayrıldı mı?
• Full search context ve original offer lineage korunuyor mu?
• GDS/NDC source ve capability snapshot saklanıyor mu?
• Reference cache expiry handle ediliyor mu?
• Selected offer commit öncesi price ediliyor mu?
• Price/rule değişikliği user reconfirmation'a gidiyor mu?
• Workbench ID ephemeral ve expiry-aware mı?
• Internal booking attempt commit öncesi durable mı?
• Commit timeout unknown-state recovery başlatıyor mu?
• Reservation ve carrier locator typed identity olarak saklanıyor mu?
• Booking ile ticketing lifecycle ayrıldı mı?
• Ticketing time limit response'tan okunuyor mu?
• Retry operation ve error class'a göre mi?
• Retrieve/ticket/servicing reconciliation test edildi mi?
• GDS/NDC capability matrix current docs ve carrier kapsamıyla doğrulandı mı?
• PII/payment log masking ve access control tamam mı?

Meta Search yorumu

Travelport entegrasyonunda en değerli asset yalnız normalize edilmiş fiyat değildir; o fiyatın source'u, offer lineage'ı ve hangi transaction/servicing yetenekleriyle geldiğidir. Search reference'ını durable reservation sanmamak, AirPrice ile selection'ı doğrulamak, workbench'i ephemeral tutmak ve commit sonrası locator/ticket lifecycle'ını reconcile etmek provider-specific ayrıntıları adapter içinde tutarken ürünün güvenilirliğini korur.

Provider companion özeti

Capability boundary

Search → offer/reference → AirPrice → workbench → commit → reservation → ticket/service/cancel/exchange.

GDS ve NDC aynı UI modeline normalize edilebilir ancak fulfillment/servicing capability'leri eşit kabul edilmemelidir.

Freshness, idempotency ve ordering

Search reference expiry, AirPrice sonucu ve workbench lifetime ayrı freshness clock'lardır. Commit timeout'u FAILED değil UNKNOWN state üretir; ikinci create/commit öncesi reservation retrieve/reconciliation gerekir.

Polling / pagination / rate-limit sınırı

Core booking lifecycle paginated veya poll-session tabanlı değildir. Collection endpoint'leri varsa yalnız kendi contract'ına göre paginate edilir. Tek universal public quota doğrulanmadığından provisioned agreement/endpoint limitleri source of truth'tur.