Hotelbeds API Integration Guide for Hotel Booking Systems
Hotelbeds API Integration Guide for Hotel Booking Systems
A clean Hotelbeds API integration rarely means calling one endpoint and being done. Hotelbeds APItude exposes a family of HTTPS APIs — hotels, activities, transfers — each with its own base path, but a shared authentication model and a familiar booking funnel: search → detail → hold → confirm.
This guide walks through the architecture behind a multi-supplier CRS (Central Reservation System) booking engine that wraps Hotelbeds and other suppliers behind a single token-based B2B/B2C API, blends live Hotelbeds inventory with offline partner inventory, and supports the two-step confirmation flow required when payment happens outside Hotelbeds.
Why a wrapper layer, not a direct call
Hotelbeds delivers inventory over HTTPS with JSON. Each product line has its own hostname path:
| Product | Test base URL (example) |
|---|---|
| Activities | https://api.test.hotelbeds.com/activity-api/3.0 |
| Transfers | https://api.test.hotelbeds.com/transfer-api/1.0 |
| Hotels | https://api.test.hotelbeds.com/hotel-api/1.0 |
The booking funnel stays consistent across all three:
- Availability / Search — real-time listing with filters
- Details / CheckRate — drill into one product and a set of operational dates
- Booking / Post-booking — confirm, cancel, modify, list
For B2C sites collecting payment through an external gateway like Stripe, Hotelbeds recommends a two-step flow: Preconfirm (locks the allotment) → payment → Reconfirm (finalizes the booking). A single confirm call books immediately — acceptable for B2B where payment is handled offline, but risky for B2C where a card charge can still fail.
Authentication: the X-Signature pattern
Every APItude request carries two headers:
Api-key— the API keyX-Signature—SHA256(apiKey + secret + unixTimestampSeconds)
This logic belongs in a single shared utility reused across every product adapter rather than duplicated per service:
A few production lessons worth building in from day one:
- Signatures are time-based, so clock skew between servers can cause intermittent 401s — keep NTP synced.
- Log every request and response body in a dedicated supplier request log; it's invaluable for admin debugging and certification.
- Treat a JSON
errors[]array in the response body as a failure even when the HTTP status is 200.
The standard APItude booking funnel
Hotelbeds documents several funnel variants. The one that maps cleanly to a token-based CRS API looks like this:
| APItude step | Booking engine endpoint (Activities example) | What the client holds |
|---|---|---|
| Availability | POST /activities/search |
Search token per activity |
| Details | GET /activities/details |
Same search token |
| Modality & rates | POST /activities/modality-rates |
Rate token per bookable row |
| Rate hold (optional) | POST /activities/hold |
Hold token |
| Prebook | POST /activities/bookings/prebook |
booking_id + prebook token |
| Preconfirm | PUT /activities/bookings/preconfirm |
Locks allotment (~30 min) |
| Reconfirm / Confirm | PUT /activities/bookings/reconfirm or POST .../confirm |
Confirmed order + vouchers |
Hotelbeds returns a rateKey on availability and detail responses. That key should never reach API clients directly — store it server-side against an internal rate token record and issue an opaque token (something like arate_…) to the frontend instead.
Architecture: supplier factory + blender
The core design problem is multi-supplier orchestration — live Hotelbeds inventory, offline partner inventory, and (for hotels) a separate live supplier — without duplicating booking logic in every controller.
Supplier factory
A thin router selects the adapter based on the search channel or rate token metadata — picking the Hotelbeds adapter when a channel is explicitly Hotelbeds, or the offline CRS service otherwise, and doing the same lookup by inspecting whether a rate token carries an external rate key. The same pattern applies identically for transfers and hotels: hotel suppliers register against an api_slug map, with a slot reserved for a Hotelbeds entry alongside whichever live hotel supplier is active today.
Every supplier implements a common interface so the blender and booking controllers stay supplier-agnostic — no branching on supplier name anywhere in controller code.
Blender: parallel search + dedupe
On search, the activity blender (and the equivalent hotel blender) calls all configured suppliers in parallel, normalizes offers to a common shape, deduplicates by a stable key, and picks a winner — typically lowest price with a preference for refundable rates.
A few Hotelbeds Activities quirks are worth encoding directly in the adapter:
- The GPS filter must be shaped as
{ "type": "gps", "latitude": …, "longitude": … }— the older comma-separated string format returnsE_REQUEST_MISSINGFILTERVALUEin test and live. - Content enrichment: unmapped service codes should trigger a call to the Activity Content API to upsert canonical, prefixed activities, so browsing doesn't depend on a full static import.
- Rate key TTL is roughly 30 minutes — expiring internal tokens a couple of minutes early avoids edge-case confirm failures near the boundary.
Token system: hiding supplier internals from clients
A recurring mistake in supplier integrations is leaking hotel_id, rateKey, or supplier booking references to the frontend. A well-designed CRS API stays token-only after search — the same pattern documented for hotels and reused for activities and transfers.
| Token | Typical TTL | Backend stores |
|---|---|---|
| Search | ~60 min | Filters, dates, paxes, channel, resolved product id |
| Rate | ~28–60 min | External rate key (Hotelbeds) or rate plan id (offline) |
| Hold / Block | ~15 min | Allotment lock context |
| Prebook | ~45 min | Guest details, supplier preconfirm reference |
This matters for three reasons: clients can't scrape the full catalogue by iterating supplier IDs, suppliers can be swapped or remapped without breaking client integrations, and expired tokens return a stable error code that's trivial to handle in the UI as "search again."
B2C: preconfirm before payment, reconfirm after
Hotelbeds doesn't provide a payment gateway for activities. With a hosted checkout flow like Stripe, preconfirming first is mandatory — otherwise a failed card charge can leave a confirmed booking in place, or a successful charge can lose its allotment.
| Channel | Preconfirm | Reconfirm / Confirm |
|---|---|---|
| B2B | Optional; often bundled into confirm |
Client pays offline; single confirm step |
| B2C (hosted checkout) | At prebook — before checkout | After payment succeeds, via sync-payment |
Offline CRS suppliers can simply treat the preconfirm step as a no-op, so the same B2C flow works regardless of whether a given offer resolved to Hotelbeds or to offline inventory.
Data model: canonical product + supplier maps
Whether inventory is live API or offline, it's worth keeping one canonical product row and mapping supplier codes to it, rather than letting supplier-specific identifiers leak into application logic:
For Hotelbeds, codes are often prefixed after content import. Manual seed maps can bridge certification test codes to canonical activities during development, ahead of full automated mapping.
Hotel booking: same pattern, supplier-agnostic by design
The hotel CRS can follow an identical token funnel:
Search → Details → Room List → Block → Prebook → Confirm → Order Info / Cancel
Live hotel availability can come from any supplier today, as long as the API contract and database schema are designed to match Hotelbeds-style semantics — cancellation policy windows, meal plans, opaque tokens. Adding a Hotelbeds Hotel adapter later then becomes a matter of implementing the common hotel service interface, registering it under its supplier slug, seeding the supplier table, and mapping a search channel to that slug — the blender already merges offline and live offers the same way it does for activities.
Observability, certification, and operations
A handful of practices consistently save time during Hotelbeds certification and staging:
| Practice | Implementation |
|---|---|
| Request/response logging | A dedicated supplier API request log, scoped per module and per supplier slug |
| Postman collections | Reusable collections per product for end-to-end replay |
| Environment separation | Distinct test and live base URLs driven entirely by environment variables |
| Scripted end-to-end tests | Booking flow scripts that exercise the full funnel automatically |
| Error normalization | Mapping Hotelbeds errors[] into stable internal codes like soldout, rate_not_found, token_invalid |
Checklist for a Hotelbeds integration
- Shared auth module — one signature helper reused across every APItude product.
- Adapter per product — implement a common interface; never branch on supplier name in controllers.
- Token facade — never expose
rateKeyor supplier references to clients. - Blender for multi-source search — parallel search, normalize, dedupe, mint tokens.
- Two-step confirm for B2C — preconfirm before payment, reconfirm after.
- Canonical catalogue + maps — one product row, many supplier codes.
- Content API for browse — optional runtime import instead of full static dumps.
- Logging from day one — certification and production debugging both depend on it.
- Factory registration — new suppliers plug in without rewriting the booking engine.
Summary
Hotelbeds APItude isn't a single "hotel booking API" — it's a consistent integration style across hotels, activities, and transfers: signed requests, filter-driven availability, rate keys, and optional two-step confirmation for external payments.
The most durable approach is not wrapping Hotelbeds' raw endpoints directly in a public API, but building a CRS booking engine that's token-based, multi-supplier, and blender-mediated, with Hotelbeds adapters for whichever products are live today and a hotel layer ready for the same pattern tomorrow. That separation makes it possible to pass certification, add offline partners, and swap or add suppliers later without rewriting the frontend or partner integrations.
For teams starting a similar project, investing early in tokens, supplier factories, and request logging pays off across every product line APItude offers.
Planning a Hotelbeds integration or a multi-supplier CRS booking engine? Get in touch with Teenva AI & Digital Ventures at sales@teenvaai.com or +91 9572020107.
