Hotelbeds API Suite Integration Guide

Hotelbeds integration works best when static property content, cached discovery data and live booking state are treated as different data classes. The Hotelbeds API Suite profile covers the ecosystem role; this guide focuses on production implementation.

Production flow

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

Authentication boundary

Hotelbeds documents API key plus an X-Signature generated from the API key, secret and current timestamp. Keep the secret server-side and centralize signature generation so clock skew and credential rotation are observable.

Content synchronization

Content API returns static hotel information independently from dynamic price/availability. Load and map content into a canonical property model. Track provider hotel IDs and content freshness rather than overwriting canonical identity.

Availability and rate identity

The Booking API returns dynamic offers. Preserve the upstream rate key and all commercial fields required for validation or booking. Do not reduce the offer to hotel ID + total price.

Rate normalization should retain occupancy, room/rate identity, board basis, cancellation policy, taxes/fees, payment characteristics and original currency.

CheckRates and booking

When the selected rate requires validation, CheckRates is a transaction boundary. A price or condition change must be surfaced to the caller rather than silently accepted.

Booking create should be treated as non-idempotent unless the provider contract explicitly proves otherwise. A timeout produces UNKNOWN state and should trigger lookup/reconciliation before another create attempt.

Cache boundary

Cache API data is useful for discovery but should not be presented as guaranteed live transaction state. Mark cached observations with age and revalidate before booking.

Failure modes

• expired/stale rate key,
• property mapping mismatch between Content and Booking data,
• clock/signature errors,
• cancellation-policy loss during normalization,
• cache data used as live inventory,
• duplicate create after timeout.

Observability

Track content sync age, signature/auth failures, availability latency, CheckRates price delta, booking unknown-state age, cancellation success and source-to-canonical mapping errors.

Production checklist

• secure API key/secret storage,
• clock-skew monitoring,
• separate content and dynamic offer stores,
• preserve rate keys,
• explicit CheckRates handling,
• UNKNOWN booking state,
• live validation before transaction,
• provider-ID lineage,
• cancellation/amendment reconciliation.

The important architectural rule is simple: cached discovery data can help find products, but booking must be anchored in a current provider offer.

Provider companion snapshot

Capability boundary

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

Static-content freshness and live-availability freshness need separate SLAs.

Authentication and transport

X-Signature is SHA-256 over apiKey + secret + UNIX timestamp. Generate Api-key and X-Signature server-side. Current Hotels knowledge-base documentation also requires mutual TLS for availability, CheckRate and booking/post-booking operations.

Rate limits and quotas

Public onboarding gives evaluation credentials a 50 requests/day quota. Certification/production quota can differ by account. Do not present evaluation quota as a universal production limit; classify quota responses separately from authentication/schema failures.

Idempotency, polling and booking recovery

The core booking flow is not a poll-session model. A booking-create timeout creates UNKNOWN state; retrieve/reconcile before another create. Paginate content/list resources only according to the relevant endpoint contract.