Hotelbeds

Nexa integrates with Hotelbeds APITUDE as the second of two primary hotel inventory sources (alongside Amadeus). Hotelbeds is a bedbank with deep coverage of leisure-focused properties; it complements Amadeus's GDS-centric catalog.

What we use it for

Capability	Hotelbeds API	Nexa adapter
Hotel availability + content	APITUDE Booking API	HotelbedsHotelProviderAdapter (IHotelProvider)
Hotel booking	APITUDE Booking API	HotelbedsBookingProviderAdapter (IBookingProvider)
Booking cancellation	APITUDE Booking API (DELETE)	HotelbedsBookingProviderAdapter.cancel

Authentication

Hotelbeds uses HMAC-SHA256 request signing, not OAuth2:

• Each request carries an X-Signature header computed as SHA256(api_key + secret + timestamp_seconds).
• Timestamp must be within 60 seconds of Hotelbeds' clock.
• The signature is per-request; there is no token cache.

Nexa's adapter computes the signature on every call (no caching beyond 60 seconds) and re-signs on retry to keep within the timestamp window.

Credentials are tenant-managed under nexa/<tenant>/vendor/hotelbeds/.

Rate limiting

Hotelbeds publishes plan-tier-specific TPS:

• hotelbeds.search — typically 10 TPS
• hotelbeds.booking — typically 5 TPS

Enforced cluster-wide via the vendor-egress token bucket. Burst beyond the configured TPS blocks at the worker level.

Scatter-gather behavior

Hotelbeds runs as one leg of the parallel inventory search alongside Amadeus and direct contracts. The booking aggregator's 2-second time-box applies — slow Hotelbeds responses don't appear in the result set for that search but don't slow the operator UI.

The Hotelbeds adapter normalizes the response into NexaInventoryObject, deduplicating against Amadeus and direct-contract results. The CDM mapper handles Hotelbeds-specific concerns: rate code translation, board-basis normalization (BB / HB / FB / AI), cancellation-policy normalization, amenity mapping.

Deduplication

Hotelbeds and Amadeus often surface the same physical hotel under different vendor IDs. The booking aggregator deduplicates on a tuple of (name, lat, lng, address) with fuzzy matching, preferring the cheapest of the two for ranking. Both vendor URNs are retained on the result so the operator can pick which vendor the booking goes through.

Booking behavior

The booking worker dispatches to Hotelbeds when Urn.vendor(offerUrn) === 'hotelbeds'. Sequence:

1. Acquire token from hotelbeds.booking bucket.
2. Mint Nexa-side reservation URN.
3. Sign and call Hotelbeds APITUDE booking endpoint.
4. On success, wrap the Hotelbeds confirmation as urn:reservation:<hotelbeds-id>:vendor:hotelbeds:status:confirmed.
5. On failure, classify and route.

Idempotency

Hotelbeds accepts a clientReference field. Nexa supplies the Nexa-side reservation URN. Replays return the same confirmation.

Cancellation deadlines

Hotelbeds bookings often carry strict cancellation deadlines (sometimes < 24 h before check-in). The Nexa booking record persists the deadline parsed from the response; the saga rollback path checks the deadline before attempting cancel. Past-deadline cancels fall directly into COMPENSATION_FAILED without retry.

Permanent-failure classification

Hotelbeds error	Nexa classification	Action
BOOKING_PAST_CANCELLATION_DEADLINE	Permanent	compensation_dead_letters row; sub-case → COMPENSATION_FAILED.
ROOM_NOT_AVAILABLE (book attempt)	Permanent (this offer specifically)	Mark the offer stale; operator picks a different one.
RATE_CHANGED	Permanent (this offer specifically)	Same as above.
INVALID_HOTEL_CODE	Permanent	Surface to operator; offer is malformed.
5xx, timeouts, network	Transient	Retry with backoff.
429	Transient	Retry with longer backoff.

Mock mode

hotelbeds.mock.data.ts provides deterministic test fixtures. Same flag and pattern as Amadeus.

Onboarding checklist

• Tenant procures APITUDE production credentials.
• Credentials in nexa/<tenant>/vendor/hotelbeds/.
• TPS configured per Hotelbeds-published plan tier.
• Adapter health check passes against Hotelbeds production.
• Mock-mode flipped to live.
• End-to-end booking validated.

Compliance & data handling

Hotelbeds is a data sub-processor under Nexa's tenant DPAs. Same minimum-necessary data principle as Amadeus: lead-passenger name, contact, group size, room requirements only.