---
title: "Hotelbeds API Suite Entegrasyon Rehberi"
description: "API-key signature, Content API sync, live availability, CheckRates, booking state ve reconciliation içeren production Hotelbeds entegrasyonu."
slug: "hotelbeds-api-suite-integration"
translationKey: "integration-hotelbeds-api-suite"
locale: "tr"
type: "guide"
category: "integration"
tags: ["hotelbeds","hbx","bedbank","hotel-api","checkrates","booking"]
vertical: ["hotel"]
platform: "Hotelbeds API Suite"
domain: "developer.hotelbeds.com"
publishedAt: "2026-09-26"
updatedAt: "2026-09-26"
reviewedAt: "2026-09-26"
technicalVerifiedAt: "2026-09-26"
sourceVersion: "HBX/Hotelbeds Hotels API Suite public docs reviewed 2026-09-26"
testedAgainst: "Official public documentation and evaluation-environment contract; not a certified production account"
codeExampleStatus: "illustrative"
changelog:
  - "2026-09-26 — Provider companion standard applied; access, lifecycle, quota/polling and evidence boundaries clarified."
sources:
  - title: "Getting Started with API Suite"
    url: "https://developer.hotelbeds.com/documentation/getting-started/"
  - title: "Hotel Booking API"
    url: "https://developer.hotelbeds.com/documentation/hotels/booking-api/"
  - title: "Hotel Content API"
    url: "https://developer.hotelbeds.com/documentation/hotels/content-api/"
---
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](/tr/metasearch/ecosystem/hotelbeds-api-suite) ekosistem rolünü açıklar; bu rehber production implementation'a odaklanır.

## Production akışı

```text
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

| Alan | Durum |
|---|---|
| Erişim | Evaluation → certification → production progression |
| Auth | Api-key + SHA-256 X-Signature; Booking API operasyonlarında güncel mTLS gereksinimi |
| Evaluation quota | Kayıt sonrası evaluation key için 50 request/gün; aşım 403 |
| Primary contracts | Content API, Booking API availability, CheckRates, Bookings; Cache API ayrı discovery surface |
| Pagination | Content/list endpoint'lerinde endpoint-specific |
| Polling | Core hotel booking lifecycle polling tabanlı değildir |
| Reprice | rateType=RECHECK ise CheckRates; BOOKABLE rate doğrudan booking'e gidebilir |
| Booking ownership | Booking API confirm/retrieve/modify/cancel lifecycle |
| Evidence | Official docs reviewed; certified production account testi iddia edilmiyor |
| Code | Illustrative |

### 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.