Integration patterns

The method pages describe one call at a time. A real integration combines several calls in a fixed order. The six patterns below follow the order in which an integration is usually built, and each one ends with a list of what can go wrong.

Every example uses fictional values (hotel "Example Guest House", ids such as 1001 and 2001, dates in 2027). The base URL is https://api.effectivetours.com/v1, and every call except /health carries your key as Authorization: Bearer $ET_API_KEY.

Principles that apply to every pattern

Keep the key on your server

The API key is a key-exposure rule, not a technical block: CORS is open, so a browser could call the API, but the key must never be in a URL, a log, browser code or a mobile app. Call the API from your server only.

There is no sandbox

A reservation or a price you write is real and reaches the connected channels. Read calls are safe at any time. For write tests use dates far in the future, create only a few bookings, cancel each one right after, and connect OTAs only after the integration works.

Use the reservation reference as the idempotency key

When you create a reservation, send your own booking id in reference. A retry with the same reference returns the existing live reservation instead of creating a duplicate. Cancelling by ?reference= is a success no-op when everything is already cancelled.

Use date windows instead of pagination

No list endpoint has pagination, and no endpoint returns only what changed. Always send both start and end when you list reservations, and keep the window small.

Re-read after every write

A write answer tells you the request was accepted. Read the object again (or the list that contains it) and compare, so your copy matches what Effective Tours holds.

Back off on errors

There is no published rate limit. Be gentle (poll a property no more often than every 2-5 minutes, keep date windows small) and back off on 429 and 503. Retry reads after a pause; retry a create only with the same reference.

The patterns

1. Pattern: first connection - check the service, your key and the hotels your company can see.
2. Pattern: map rooms and rates - store Effective Tours room and rate ids next to your own room types.
3. Pattern: read and update prices - read daily prices, write new ones (distributors only) and ask for a channel update.
4. Pattern: reservation sync - poll reservations in date windows and read cancelled channel bookings.
5. Pattern: create a booking safely - write a reservation with a reference so a retry never double-books.
6. Pattern: modify and cancel - change dates or guests, and cancel by id or by reference.

Method pages

• Hotels, rooms and rates
• Daily prices
• Channel update
• Reservations

The full operation reference is at api.effectivetours.com/docs. Before you start, fetch https://api.effectivetours.com/v1/openapi.json and treat its list of operations (method and path) as the truth: the info.version label is fixed and does not change when operations are added.