Expedia Rapid Lodging Entegrasyon Rehberi

Expedia Rapid Lodging entegrasyonu “hotel ara, fiyat göster, booking yap” şeklinde tek API flow'u değildir. Sağlıklı implementation; durable catalog data ile short-lived shopping/booking state'ini ayırır, selected rate'i Price Check ile transaction'a yakın noktada tekrar doğrular ve booking attempt'lerini idempotent şekilde yönetir.

Expedia'nın resmi akışı content → geography → shopping → price check → booking → retrieve/manage şeklinde ilerler. Production sisteminizde de aynı lifecycle sınırlarını korumak, stale token, duplicate booking ve yanlış price breakdown gibi problemlerin büyük bölümünü daha oluşmadan engeller.

Ürün kapsamı ve işlem sınırları için Expedia Rapid profilini okuyun. Bu rehber uygulama ayrıntılarına odaklanır.

Provider companion özeti

Authentication contract

Rapid Lodging signature auth:

api_key + shared_secret + unix_timestamp
            |
            v
SHA-512
            |
            v
Authorization: EAN APIKey=...,Signature=...,timestamp=...

Timestamp signature üretiminde kullanılan değerle aynı olmalıdır. Sistem saatini NTP ile senkron tutun ve secret'ı browser'a taşımayın.

Rate limit ve performance-test sınırı

Rapid Shopping sabit tek bir "QPS" abstraction'ı değildir. Expedia load hesabında özellikle:

• property sayısı,
• room sayısı,
• stay length

gibi request boyutlarını önemli görür. Rate-limit response header'larını varsa ölçün ve account-specific limitleri partner configuration'dan okuyun.

Daha önemlisi: Rapid setup dokümantasyonu, planned performance test veya API call behavior değişikliği öncesinde planın Rapid API consultant ile review edilmesini ister. Bu yüzden load/benchmark testini standart functional traffic gibi çalıştırmayın.

Polling / pagination yaklaşımı

Core Lodging flow:

Shopping
   -> Price Check
   -> Booking
   -> Retrieve / Cancel

create/poll session modeli değildir. Tokenized links bir sonraki transaction adımını taşır. Resource list endpoint'i pagination sunuyorsa yalnız o endpoint contract'ını uygulayın.

Price Check / booking lifecycle

SHOPPED
   -> PRICE_CHECK
      -> MATCHED -> READY_TO_BOOK
      -> CHANGED -> USER_RECONFIRM_REQUIRED
      -> SOLD_OUT/UNAVAILABLE -> RE_SHOP_REQUIRED
   -> BOOKING
   -> CONFIRMED / UNKNOWN
   -> RETRIEVE / CANCEL / RECONCILE

Booking link kısa ömürlüdür. İlk booking denemesinde HTTP 503 link expiry anlamına gelebilir; eski linki kör retry etmek yerine yeni Price Check ile yeni booking link alın.

Test/stub contract

Rapid'in resmi test-header mekanizması Shopping ve Price Check için canned responses üretir. Bu fixture'lar:

• parser/serializer,
• error mapping,
• price-changed,
• sold-out,
• 5xx handling

gibi contract testleri için uygundur; gerçek availability veya latency kanıtı değildir.

Entegrasyonun sınırı nedir?

Rapid Lodging size property catalog, geography, live shopping, price confirmation ve booking lifecycle capability sağlar. Bu, yalnız affiliate deeplink üretmekten daha transaction-oriented bir modeldir.

Bununla birlikte kendi sisteminiz hâlâ şu sorumluluklara sahiptir:

• canonical property identity,
• supplier/property mapping,
• user search context,
• normalized offer modeli,
• persistence,
• payment/security boundary,
• idempotency,
• retry ve timeout policy,
• observability,
• booking reconciliation.

Provider API güçlü olsa bile internal domain modelinizi provider response shape'e bağlamak uzun vadede maliyet yaratır.

Production flow nasıl görünmeli?

Scheduled Content Sync
        |
        v
Local Property Catalog
        |
Traveler Search
        |
        +--> canonical destination/property resolution
        |
        v
Rapid Shopping
        |
        v
Normalized Offer Store / short cache
        |
Traveler selects rate
        |
        v
Rapid Price Check
        |
   +----+------+
   |           |
MATCHED      CHANGED / UNAVAILABLE
   |           |
   v           v
Booking Link  Update price / re-shop
   |
   v
Internal Booking Attempt
   |
   v
Rapid Booking
   |
   v
Itinerary / reservation identity
   |
   +--> retrieve
   +--> cancel/manage
   +--> reconciliation

Bu flow'da en kritik ayrım catalog state ile execution state arasındadır.

Hangi data durable, hangisi short-lived?

Durable saklanabilecek data

• Expedia property ID,
• canonical property mapping,
• region/geography mapping,
• content snapshot metadata,
• room/rate normalized attributes,
• booking/itinerary ID,
• internal booking attempt ID,
• price observations,
• booking lifecycle events.

Short-lived olarak ele alınması gereken data

• shopping response içindeki operational token'lar,
• Price Check'ten gelen booking link,
• bazı transaction execution link'leri,
• ephemeral request/session context.

Expedia Booking API dokümantasyonu, Price Check'ten gelen booking link'in kısa süre sonra expire olabildiğini açıkça belirtir. Bu nedenle bu link'i “booking endpoint identifier” gibi kalıcılaştırmak yanlış abstraction'dır.

Property content nasıl ingest edilmeli?

Rapid property catalog; property ID, name, address, contact ve star rating gibi static/semi-static content sağlar. Expedia bu content'in düzenli, hatta daily refresh edilmesini önerir.

Local catalog için tipik tablolar:

properties
provider_properties
property_content_snapshots
property_amenities
property_images
provider_regions
provider_property_regions

Önemli pattern:

internal_property_id != expedia_property_id

Expedia ID external identity'dir; internal canonical ID değildir.

Geography neden ayrı bir boundary olmalı?

Destination search'i Expedia taxonomy'sine doğrudan bağlarsanız başka supplier eklediğinizde search modeliniz supplier-specific hale gelir.

Daha sağlıklı yaklaşım:

User destination
      |
Canonical destination
      |
Provider mappings
   +--+--------+
   |           |
Expedia     Provider B
Region ID   Region ID

Bu, multi-supplier metasearch'te geography normalization'ın önemini artırır.

Shopping request context'inde ne korunmalı?

Rapid Shopping API stay date, occupancy ve property ID gibi bilgilerle live room/rate döndürür. Expedia'nın resmi dokümanında tek request'te belirli sayıda property ve room constraint'leri bulunur; implementation güncel limitleri resmi dokümandan okumalıdır.

Internal normalized request örneği:

{
  "checkIn": "2026-10-10",
  "checkOut": "2026-10-13",
  "rooms": [
    {
      "adults": 2,
      "children": []
    }
  ],
  "currency": "TRY",
  "travelerCountry": "TR",
  "language": "tr-TR",
  "propertyIds": ["..."]
}

Provider adapter bu normalized contract'ı Expedia request formatına çevirir.

Shopping response nasıl normalize edilmeli?

Shopping response yalnız price içermez; room, refundable state, cancellation penalty, fees, promotions ve price breakdown gibi commercial semantics taşır.

Internal offer modeli en azından şunları korumalı:

interface HotelOffer {
  provider: "expedia-rapid";
  providerPropertyId: string;
  providerRoomId?: string;
  providerRateId?: string;

  checkIn: string;
  checkOut: string;
  occupancy: Occupancy[];

  roomName: string;
  refundable: boolean;
  cancellation?: CancellationPolicy;

  baseAmount: number;
  taxAmount: number;
  mandatoryFeeAmount: number;
  totalAmount: number;
  currency: string;

  observedAt: string;
  sourcePayloadRef: string;
  priceCheckLink: string;
}

Normalize ederken original payload veya replay edilebilir source reference'ı da korumak debugging açısından değerlidir.

Price Check neden ayrı bir transaction boundary'dir?

Shopping ile booking arasında price veya availability değişebilir. Rapid Price Check seçilmiş offer'ın hâlâ geçerli olup olmadığını doğrular.

Temel durumlar:

MATCHED

Price hâlâ geçerlidir ve booking için yeni link alınır.

CHANGED

Amount değişmiştir. UI yeni total price'ı kullanıcıya göstermelidir.

UNAVAILABLE / re-shop

Selected rate artık bookable değildir ve yeni Shopping gerekir.

Bu nedenle booking service'in input'u raw shopping token değil, başarılı Price Check sonucu olmalıdır.

Fiyat değişirse ne yapılmalı?

Sessizce changed price ile booking yapmak risklidir.

Önerilen state machine:

SELECTED
   |
PRICE_CHECK
   |
   +--> MATCHED --------> READY_TO_BOOK
   |
   +--> CHANGED --------> USER_RECONFIRM_REQUIRED
   |
   +--> UNAVAILABLE ----> RE_SHOP_REQUIRED

Displayed amount ve confirmed amount ayrı kaydedilmelidir.

Booking idempotency nasıl tasarlanmalı?

En kritik edge-case:

1. internal service Expedia Booking'i çağırır,
2. Expedia booking'i oluşturur,
3. response network timeout nedeniyle size ulaşmaz,
4. sistem request başarısız sanıp tekrar booking çağırır.

Kör retry duplicate reservation üretebilir.

Booking öncesi internal attempt oluşturun:

booking_attempt
- id
- user/session
- provider
- offer_fingerprint
- displayed_amount
- confirmed_amount
- status
- created_at
- provider_itinerary_id

Timeout sonrasında yeni create çağrısı yapmadan önce mümkünse booking outcome'u retrieve/reconcile edin.

Error taxonomy nasıl olmalı?

Tüm upstream error'ları “Expedia error” altında toplamayın.

Örnek taxonomy:

• AUTH_ERROR
• INVALID_SEARCH_CONTEXT
• NO_AVAILABILITY
• PRICE_CHANGED
• PRICE_CHECK_EXPIRED
• BOOKING_LINK_EXPIRED
• PAYMENT_REJECTED
• PROVIDER_4XX
• PROVIDER_5XX
• PROVIDER_TIMEOUT
• RATE_LIMIT
• BOOKING_STATE_UNKNOWN
• RETRIEVE_FAILED
• CANCEL_FAILED

Bu sınıflar retry policy'yi de belirler.

Hangi error retry edilmeli?

Retry edilebilir

• network timeout,
• selected 5xx,
• transient connection failure,
• bazı rate-limit senaryoları.

Kör retry edilmemeli

• invalid occupancy,
• validation error,
• price changed,
• unavailable rate,
• payment/business rejection,
• booking state unknown.

Booking state unknown özellikle ayrı ele alınmalıdır; “unknown” ile “failed” aynı şey değildir.

Timeout budget nasıl ayrılmalı?

Interactive flow için provider call'ları sınırsız beklememelidir.

Örnek:

Shopping       -> 1500-2500 ms budget
Price Check    -> stricter user-facing budget
Booking        -> longer but bounded transaction budget
Retrieve       -> async/recovery capable
Content Sync   -> background timeout/retry policy

Rakamlar kendi latency distribution'ınıza göre belirlenmelidir.

Price breakdown neden olduğu gibi korunmalı?

Base price, taxes, fees ve property-payable component'leri flatten edip yalnız total saklamak reconciliation'ı zorlaştırır.

En azından:

• displayed base,
• taxes,
• mandatory fees,
• property fees,
• total,
• currency,
• billable/display currency farkı,

korunmalıdır.

Expedia dokümantasyonu bazı market ve currency senaryolarında display/fee davranışlarının değişebileceğini belirtir. Bu nedenle normalization source semantics'i silmemelidir.

Monitoring hangi seviyede kurulmalı?

Shopping

• requests/search,
• success rate,
• empty availability rate,
• p50/p95 latency,
• property coverage.

Price Check

• match rate,
• changed-price rate,
• unavailable rate,
• price delta distribution.

Booking

• booking success rate,
• state-unknown rate,
• duplicate-prevented count,
• payment rejection,
• booking latency.

Post-booking

• retrieve success,
• cancellation success,
• reconciliation gap,
• unmatched itinerary.

Provider dashboard yalnız API uptime göstermemelidir.

Security boundary nasıl kurulmalı?

Payment ve PII içeren booking flow browser'dan doğrudan provider'a secret credential ile çağrılmamalıdır.

Backend service:

• credential yönetir,
• sensitive field logging'i engeller,
• request masking uygular,
• audit trail tutar,
• idempotency ve authorization uygular.

Loglarda full payment payload tutmak debugging kolaylığı değil security problemidir.

Go-live checklist

• Canonical property mapping hazır mı?
• Daily/semi-static content refresh planı var mı?
• Geography provider taxonomy'sinden ayrılmış mı?
• Shopping request context eksiksiz mi?
• Original offer semantics korunuyor mu?
• Price Check zorunlu boundary olarak uygulanıyor mu?
• CHANGED price kullanıcı confirmation istiyor mu?
• Booking link expiry handle ediliyor mu?
• Booking attempt idempotent mi?
• Timeout sonrası unknown-state recovery var mı?
• Full price breakdown persist ediliyor mu?
• PII/payment logging maskeleniyor mu?
• Retry error class bazlı mı?
• Shopping/PriceCheck/Booking KPI'ları ayrı mı?
• Retrieve/cancel reconciliation test edildi mi?

2026 API audit notları

Güncel Rapid dokümantasyonu entegrasyon açısından üç kritik detayı ayrıca güçlendiriyor:

• Shopping response içindeki tokenized price_check linkleri kısa ömürlüdür; uzun süre saklanmamalıdır.
• Price Check sonucunda rate değişmişse yeni fiyat ve yeni booking link'i dönülebilir; user reconfirmation boundary korunmalıdır.
• Başarılı Booking response'u Retrieve/Cancel gibi follow-up linkleri üretir; bu linkler booking lifecycle'ın provider reference'larıdır ve itinerary ile birlikte güvenli biçimde saklanmalıdır.

Ayrıca yeni price-display alanlarında property_inclusive gibi toplamı daha açık taşıyan alanlar bulunur. Internal normalization bu alanları tek bir total değerine kör biçimde flatten etmemeli; base, taxes, Expedia/property collected fees ve display/billable currency ayrımını korumalıdır.

Rapid'in güncel Postman collection ve OpenAPI materyalleri request/response contract regression testleri için doğrudan kullanılabilir. CI'da provider'a canlı call atmak yerine örnek payload/schema fixture'ları üzerinden serializer/parser contract testleri çalıştırmak daha güvenlidir.

Meta Search yorumu

Expedia Rapid'i doğru entegre etmek endpoint sırasını ezberlemek değildir. Asıl mesele durable catalog ile ephemeral transaction state'i ayırmak, selected offer'ı Price Check ile yeniden doğrulamak ve booking lifecycle'ını idempotent yönetmektir. Bu sınırlar doğru kurulursa provider-specific API, sisteminizin geri kalanını kirletmeden adapter içinde kalabilir.