Hotelbeds API Suite Entegrasyon Rehberi

Hotelbeds entegrasyonu static property content, cached discovery data ve live booking state ayrı veri sınıfları olarak ele alındığında daha güvenlidir. Hotelbeds API Suite profili ekosistem rolünü açıklar; bu rehber production implementation'a odaklanır.

Production akışı

Content API -> canonical hotel/content store
Cache API?  -> discovery acceleration
Booking API availability -> live normalized offers
Selected rate -> CheckRates
Validated rate -> Bookings
Booking reference -> retrieve / cancel / amend / reconcile

Authentication boundary

Hotelbeds API key ve API key + secret + current timestamp'ten üretilen X-Signature modelini dokümante eder. Secret server-side kalmalı; signature generation merkezi olmalıdır. Clock skew ve credential rotation monitor edilmelidir.

Content synchronization

Content API static hotel bilgisini dynamic price/availability'den ayrı sunar. Provider hotel ID ve content freshness korunarak canonical property modeline map edilmelidir.

Availability ve rate identity

Booking API dynamic offer üretir. Booking/validation için gereken upstream rate key ve commercial field'ları kaybetmeyin. Offer'ı hotel ID + total price'a indirgemeyin.

Occupancy, room/rate identity, board basis, cancellation, taxes/fees, payment characteristics ve original currency normalize edilmelidir.

CheckRates ve booking

Seçili rate validation gerektiriyorsa CheckRates transaction boundary'dir. Price veya condition değişikliği sessiz kabul edilmemeli, caller'a gösterilmelidir.

Booking create non-idempotent kabul edilmelidir; timeout UNKNOWN state üretir ve ikinci create öncesi lookup/reconciliation gerekir.

Cache boundary

Cache API discovery için değerlidir fakat live transaction state değildir. Cached observation age görünür olmalı; booking öncesi current provider offer ile doğrulanmalıdır.

Failure mode'lar

Stale rate key, Content/Booking property mapping mismatch, clock/signature error, cancellation-policy kaybı, cached data'nın live inventory sanılması ve timeout sonrası duplicate create temel risklerdir.

Observability

Content sync age, auth/signature failure, availability latency, CheckRates delta, booking UNKNOWN age, cancellation success ve mapping error izlenmelidir.

Production checklist

• secure key/secret,
• clock skew monitoring,
• content/dynamic store ayrımı,
• rate key preservation,
• explicit CheckRates handling,
• UNKNOWN booking state,
• transaction öncesi live validation,
• provider ID lineage,
• cancel/amend reconciliation.

Ana kural: cached discovery product'u bulabilir; booking current provider offer'a dayanmalıdır.

Provider companion özeti

Capability boundary

Content API → canonical static content → Availability → rateKey + BOOKABLE/RECHECK → gerekirse CheckRates → Booking → retrieve/modify/cancel.

Static content freshness ile live availability freshness aynı SLA değildir.

Authentication ve transport

X-Signature, apiKey + secret + UNIX timestamp değerinin SHA-256 hash'idir. Api-key ve X-Signature server-side üretilmelidir. Güncel Hotels knowledge-base ayrıca availability, CheckRate ve booking/post-booking operasyonlarında mutual TLS gereksinimini açıklar.

Rate limit / quota

Public onboarding evaluation key için 50 request/gün kota verir. Certification/production kotası account seviyesinde farklı olabilir. Evaluation kotasını global production limiti gibi sunmayın; quota response'larını auth/schema hatalarından ayırın.

Idempotency, polling ve booking recovery

Core booking flow poll-session modeli değildir. Booking create timeout'u UNKNOWN state üretir; provider reference/retrieve-reconciliation yapılmadan ikinci create gönderilmemelidir. Content list pagination'ı varsa yalnız ilgili endpoint contract'ına göre uygulanmalıdır.