Начало работы
Это обычный REST API поверх HTTPS, который возвращает JSON. Аутентификация — по единственному API-ключу, который вы создаёте сами после одобрения доступа. В примерах ниже {BASE_URL} используется как условный адрес — ваш базовый URL указан рядом с ключом в кабинете разработчика.
- 1
Подайте заявку
Расскажите о своей платформе. Мы вручную рассматриваем каждую заявку — обычно в течение 1–2 рабочих дней.
- 2
Создайте ключ
После одобрения создайте API-ключ в кабинете разработчика и зарегистрируйте IP-адреса серверов, с которых будете обращаться к API. Ключ показывается только один раз.
- 3
Вызывайте API
Передавайте ключ в заголовке X-API-Key в каждом запросе. Больше для подключения ничего не нужно.
Аутентификация
Передавайте ключ в заголовке X-API-Key в каждом запросе. Никакого OAuth, обмена токенами и срока действия — ключ действует, пока вы его не перевыпустите или не отзовёте.
curl -X GET '{BASE_URL}/b2b/api/apiv2/b2c/tours/search?term=cappadocia&page_size=5' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Accept: application/json'const res = await fetch(
'{BASE_URL}/b2b/api/apiv2/b2c/tours/search',
{
method: 'POST',
headers: {
'X-API-Key': process.env.TSB_API_KEY,
'Content-Type': 'application/json',
Accept: 'application/json',
},
body: JSON.stringify({ term: 'cappadocia', page_size: 5 }),
},
)
const data = await res.json()Список разрешённых IP
Партнёрские эндпоинты принимают запросы только с зарегистрированных вами IP-адресов серверов. После одобрения доступа добавьте в кабинете разработчика публичные IP-адреса, с которых ваши серверы отправляют исходящие запросы. Максимальное число адресов по умолчанию — 3.
- Регистрируйте отдельные адреса IPv4 или IPv6. Диапазоны, частные и зарезервированные адреса, а также адреса Cloudflare не принимаются.
- Указывайте адрес, с которого ваш сервер отправляет запросы, а не IP сайта. Если сайт работает через Cloudflare, этот адрес принадлежит Cloudflare и не может быть зарегистрирован.
- Если на сервере есть IPv6, запросы могут уходить по IPv6. Зарегистрируйте и этот адрес или настройте HTTP-клиент на использование IPv4. Чтобы увидеть оба адреса, выполните команды ниже на самом сервере.
- Изменения вступают в силу примерно через минуту.
curl -4 https://api.ipify.org
curl -6 https://api64.ipify.orgЕсли запрос заблокирован
Запросы с незарегистрированного IP останавливаются ещё до API: вместо JSON-ошибки вы получите HTTP 403 и HTML-страницу проверки с заголовком «Just a moment...». Пока вы не зарегистрировали ни одного IP, сам ключ не привязан к IP-адресам, но запросы с ваших серверов будут получать эту страницу. Если вы её видите, проверьте, какой IP на самом деле использует ваш сервер, и зарегистрируйте этот адрес.
Как только зарегистрирован хотя бы один IP, ключ принимается только с этих адресов. Запрос с вашим ключом, пришедший в API с любого другого IP, отклоняется с кодом 403 и ошибкой ip_not_allowed; в теле ответа указан IP, который мы увидели. Утёкший ключ бесполезен за пределами ваших серверов.
{
"message": "This API key is not allowed from your IP address. Register it under Allowed server IPs in your developer dashboard.",
"code": "ip_not_allowed",
"ip": "203.0.113.10"
}Лимиты запросов и квоты
Действуют два независимых лимита. Оба считаются отдельно для каждого партнёра и ни с кем не делятся.
Запросов в минуту: 240
Лимит на пиковую нагрузку. Каждый ответ содержит заголовки X-RateLimit-Limit и X-RateLimit-Remaining, чтобы вы могли регулировать частоту запросов.
Запросов в сутки: 20000
Суточная квота по умолчанию после одобрения. Она сбрасывается в полночь по UTC, а по запросу мы её увеличим — сообщите ожидаемый объём, и мы подберём лимит.
При превышении любого из лимитов возвращается код 429. Текущее использование с разбивкой по эндпоинтам доступно в кабинете разработчика.
Правила для контента
Период ожидания для новых туров — 30 дн. Тур, добавленный в наш каталог, не отображается в партнёрских результатах поиска, в деталях тура и в ответах о ценах и наличии мест, пока с момента добавления не пройдёт 30 дн. На запросы по отдельному туру возвращается 404 с кодом tour_embargoed и датой, когда тур станет доступен. Так тур успевает сначала проиндексироваться на нашем сайте, и поисковые системы видят первоисточник. Всё, что старше, доступно вам полностью. Если вы также являетесь нашим поставщиком и ваш аккаунт привязан к вашей компании-поставщику, на ваши собственные туры это правило не распространяется: они доступны через API сразу, без периода ожидания.
Цены, даты и контент проверяются ежедневно. Ответы можно кешировать, но обновляйте цены и наличие мест не реже раза в сутки — и всегда перепроверяйте наличие мест непосредственно перед созданием бронирования.
Tour search & content
Search the catalogue and pull full tour content. These are the endpoints most integrations start with.
/b2b/api/apiv2/b2c/tours/searchSearch tours
Full catalogue search with faceted filters. Send filters as query parameters (GET) or as a JSON body (POST) — POST is recommended once you use array filters.
| Параметр | Тип | Описание |
|---|---|---|
term | string | Free-text search across tour titles and content. |
destination | string | Destination slug to scope the search to. |
category | string | Single category slug. |
categories | string[] | Several category slugs at once. |
activities | string[] | Activity slugs (see the activities endpoint). |
languages | string[] | Guiding language codes. |
price | [min, max] | Price range as a two-item array, in EUR. |
duration | [min, max] | Duration range in days (defaults 1–28). |
rating | number | Minimum review rating. |
start_location | integer | Pickup location id. |
end_location | integer | Drop-off location id. |
transports | string[] | Transport type slugs. |
accommodations | string[] | Accommodation type ids. |
physical_ratings | integer[] | Physical difficulty rating ids. |
ids | integer[] | Restrict the result to specific tour ids. |
supplier_ids | integer[] | Only tours run by these suppliers. To list your own tours as a supplier, use the Your supplier tours endpoint instead. |
order | string | Sort field. Defaults to created_at. |
page | integer | Page number, 1-based. |
page_size | integer | Results per page. Defaults to 10. |
Results respect the content embargo — see Content rules below.
/b2b/api/apiv2/b2c/tours/detail/{slug}Tour detail
The complete tour record: itinerary, inclusions, images, departure rules and review summary. {slug} is the tour slug returned by search.
An unavailable, deleted, or embargoed tour returns 404. A partner cannot infer its state from that response.
/b2b/api/apiv1/b2c/quicksearch/toursQuick tour search
Type-ahead search for search boxes. Same engine as the full search but tuned for short, fast queries.
| Параметр | Тип | Описание |
|---|---|---|
term | string | What the user has typed so far. |
/b2b/api/supplier/toursYour supplier tours
If you are also one of our suppliers, this returns your own tours. No supplier ID is needed: your API key identifies your company. Accepts the same parameters and returns the same format as Search tours. Your own tours are available as soon as they are published, with no waiting period.
| Параметр | Тип | Описание |
|---|---|---|
term | string | Optional free-text search within your tours. |
page | integer | Page number, 1-based. |
page_size | integer | Results per page, up to 250. Defaults to 10. |
Returns 403 if your API key is not linked to a supplier account. Contact us to have it linked.
Catalogue synchronization
Import complete public tour content and current retail departure schedules through two paginated change feeds.
With pricing=default, use pricing.reference.amount for your reference price. It follows the supplier detail page’s initial traveller count and first available month, with regular retail pricing preferred when offered, otherwise private. The amount is already discounted in EUR. Minimum 0 or 1 selects three travellers capped by the maximum; another minimum selects that minimum. A null reference means no displayable initial price. Do not substitute a minimum over raw rates.
The schedule feed additionally returns pricing.options: equal EUR prices grouped by explicit dates for the default traveller count. Promotions are already applied. In this mode, crossing an hour since modified-since refreshes authorized schedules even without rate edits. A cursor is bound to its pricing mode. On upgrade, restart product pagination from the last saved modified-since to preserve removal markers, and restart schedules with a full scan.
For the first scan, omit modified-since. Follow nextCursor until it is null, sending each cursor without modified-since. Save syncStartedAt from the first page; send it as modified-since on the next run. Each cursor belongs to one partner account and one feed. Apply records by tourId and allow duplicate updates at time boundaries.
Initial scans contain only active, non-deleted, non-custom tours. Incremental product scans return a minimal INACTIVE record when a previously public tour is disabled, made custom or soft-deleted; remove or hide that tour and its saved schedule locally. No disabled tour content or prices are returned. The schedule feed stays active-only. The content embargo applies, except to your own supplier tours when your account is linked. Use syncStartedAt, not an item’s modifiedAt, as the next checkpoint.
Departure dates can pass without a database modification. Remove past dates locally; each incremental schedule update replaces the complete saved schedule for that tour.
/b2b/api/products/modified-sinceNew and modified products
An ACTIVE item contains tourId, slug, modifiedAt, status and product with full public tour content. An INACTIVE item contains only tourId, slug, modifiedAt and status; remove or hide the saved tour. If republished, it arrives again as ACTIVE. Net prices and private company fields are excluded.
| Параметр | Тип | Описание |
|---|---|---|
modified-since | ISO 8601 | Timestamp with a timezone offset, for example 2026-10-20T09:00:00Z. Omit for an initial full scan. |
count | integer | Page size from 1 to 500; defaults to 100. |
cursor | string | Opaque nextCursor from the previous page. Send it without modified-since. |
pricing | default | Opt in to the public detail page’s default B2C reference quote. Send pricing=default on every cursor page too. Adds pricingPolicy and per-tour pricing. |
activeCurrency | EUR | With pricing=default, EUR is the only accepted currency and is the default. The legacy raw rates keep their native currencies. |
curl -G '{BASE_URL}/b2b/api/products/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'pricing=default' --data-urlencode 'activeCurrency=EUR' --data-urlencode 'count=100'curl -G '{BASE_URL}/b2b/api/products/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'count=100'curl -G '{BASE_URL}/b2b/api/products/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'cursor=NEXT_CURSOR'{
"products": [
{
"tourId": 123,
"slug": "example-tour",
"modifiedAt": "2026-10-20T08:00:00+00:00",
"status": "ACTIVE",
"product": {
"id": 123,
"slug": "example-tour",
"name": "Example tour",
"itineraries": []
}
}
],
"nextCursor": null,
"syncStartedAt": "2026-10-20T09:00:00+00:00"
}{
"products": [
{
"tourId": 123,
"slug": "example-tour",
"modifiedAt": "2026-10-20T08:15:00+00:00",
"status": "INACTIVE"
}
],
"nextCursor": null,
"syncStartedAt": "2026-10-20T09:00:00+00:00"
}INACTIVE records contain no product details or prices. Only active tours appear in an initial scan. A complete incremental scan and saved checkpoint replace periodic full-catalogue comparison for later soft deletions. If active content is temporarily unavailable, retry the 503 page without advancing its cursor.
/b2b/api/availability/schedules/modified-sinceModified availability schedules
Each availabilitySchedules[] item contains tourId, slug, modifiedAt and rates: the complete current set of retail rates for that tour, not just the changed rate. Each rate includes its dates from today onward.
| Параметр | Тип | Описание |
|---|---|---|
modified-since | ISO 8601 | Timestamp with a timezone offset. Omit for an initial full scan. |
count | integer | Page size from 1 to 500; defaults to 100. |
cursor | string | Opaque nextCursor from the previous page. Send it without modified-since. |
pricing | default | Opt in to the public detail page’s default B2C reference quote. Send pricing=default on every cursor page too. Adds pricingPolicy and per-tour pricing. |
activeCurrency | EUR | With pricing=default, EUR is the only accepted currency and is the default. The legacy raw rates keep their native currencies. |
curl -G '{BASE_URL}/b2b/api/availability/schedules/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'pricing=default' --data-urlencode 'activeCurrency=EUR' --data-urlencode 'count=100'curl -G '{BASE_URL}/b2b/api/availability/schedules/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'modified-since=2026-10-20T09:00:00Z'{
"availabilitySchedules": [
{
"tourId": 123,
"slug": "example-tour",
"modifiedAt": "2026-10-20T08:00:00+00:00",
"rates": [
{
"rateId": 456,
"startsAt": "2026-11-01",
"endsAt": "2026-11-30",
"minPax": 1,
"maxPax": 20,
"currency": "EUR",
"departureTypeId": "scheduled",
"description": {
"en": "Standard departure"
},
"prices": {
"regular": {
"dbl": 200
}
},
"dates": [
"2026-11-05"
]
}
]
}
],
"nextCursor": null,
"syncStartedAt": "2026-10-20T09:00:00+00:00"
}When the last rate is deleted, the tour is returned with rates: [] so you can clear its saved schedule. A rate can have a valid period but dates: []. Prices are retail only; supplier net prices and markup are never returned. Successful pages use Cache-Control: private, no-store.
Pricing & availability
Live departure availability and B2C retail prices. Partner API keys do not provide access to supplier net prices.
/b2b/api/apiv2/b2c/availability/{slug}Availability & price for a tour
Departure availability and retail pricing for one tour.
| Параметр | Тип | Описание |
|---|---|---|
roomType | string | sng, dbl or trp. Defaults to dbl. |
date | YYYY-MM-DD | A single departure date. |
startDate | YYYY-MM-DD | Start of a date range. |
endDate | YYYY-MM-DD | End of a date range. |
pax | integer | Number of travellers. |
service_type | string | Service level. Defaults to regular. |
rooms | array | Room breakdown, as [{ id, pax, count }]. |
include_prices | yes | no | Include the price breakdown. |
include_rooms | yes | no | Include room options. |
An unavailable, deleted, or embargoed tour returns 404.
/b2b/api/apiv2/b2c/prices/{type}Batch prices
One retail price per tour for a list of ids — what listing and category pages need.
| Параметр | Тип | Описание |
|---|---|---|
idsобязательный | integer[] | Tour ids to price. |
roomType | string | sng, dbl or trp. Defaults to dbl. |
startDate | YYYY-MM-DD | Defaults to today. |
endDate | YYYY-MM-DD | Optional range end. |
Unavailable, deleted, and embargoed tours are left out of the response.
/b2b/api/apiv2/b2c/pricemonths/{type}/{id}Available months
Available month dates for a tour, for building a departure calendar. This endpoint does not return prices.
An unavailable, deleted, or embargoed tour returns 404.
Destinations & taxonomy
The reference data behind filters, menus and search boxes.
/b2b/api/apiv1/b2c/countries/listCountries
All countries with their id, name, slug and phone code.
/b2b/api/apiv1/b2c/quicksearch/locationsLocation search
Search destinations by name — cities, regions and countries.
| Параметр | Тип | Описание |
|---|---|---|
q | string | Search term. |
ids | string | Comma-separated ids, to resolve known locations instead of searching. |
limit | integer | Max results, 1–50. Defaults to 20. |
/b2b/api/apiv1/location-parents/{id}Location ancestors
The parent chain of a location (city → region → country), for breadcrumbs.
/b2b/api/apiv1/b2c/quicksearch/tour-categoriesTour categories
Category pages matching a term, with their titles and URLs.
| Параметр | Тип | Описание |
|---|---|---|
term | string | Search term. |
/b2b/api/apiv1/b2c/quicksearch/activitiesActivities
Activity list (hiking, diving, …) with id, name and slug — the values the activities filter accepts.
| Параметр | Тип | Описание |
|---|---|---|
term | string | Search term. |
/b2b/api/apiv1/b2c/tours/available-destinationsAvailable destinations
Destinations that currently have bookable tours.
/b2b/api/apiv1/b2c/tours/trending-destinationsTrending destinations
Destinations with the strongest recent demand.
Enquiries & bookings
Create demand on our side from your platform. Everything you create here is attributed to your partner account and appears in your dashboard.
/b2b/api/apiv1/bookings/new-enquiryCreate an enquiry
A traveller question about a tour. Creates an enquiry record and notifies the operator.
| Параметр | Тип | Описание |
|---|---|---|
tour_idобязательный | integer | The tour being asked about. |
contact_nameобязательный | string | The traveller's name. |
contact_emailобязательный | string | The traveller's email. |
messageобязательный | string | The question, up to 5000 characters. |
phone_code | integer | Location id of the phone country code. |
contact_phone | string | Phone number without the country code. |
buyer_currency | USD | EUR | Currency to quote in. Defaults to EUR. |
No captcha is required on API-key requests — your key, quota and rate limit are the gate.
/b2b/api/apiv1/bookings/new-bookingCreate a booking
A booking checkout with travellers and rooms, priced from B2C retail availability. Returns the reference_id and token used for payment.
| Параметр | Тип | Описание |
|---|---|---|
tour_idобязательный | integer | The tour being booked. |
paxобязательный | integer | Number of travellers. |
dateобязательный | YYYY-MM-DD | Departure date, today or later. |
service_typeобязательный | string | Service level, as returned by availability. |
buyer_currencyобязательный | string | Currency the traveller pays in. The seller currency is taken from the tour’s own price record. |
rooms | array | Required for tours with accommodation: [{ id: "dbl", pax, count }]. |
customersобязательный | array | Travellers. The first is the lead and needs title, first_name, last_name, email, phone_code and phone. |
/b2b/api/apiv1/bookings/{referenceId}Booking detail
Read one booking. Pass the booking token as ?token= — the token scopes access to that single booking.
| Параметр | Тип | Описание |
|---|---|---|
tokenобязательный | string | The token returned when the booking was created. |
/b2b/api/apiv1/bookings/{referenceId}/payment-requestOpen a payment request
Start a collection against a booking, for a payment page hosted on your own front end. Call it from your server; the amount is calculated from the booking — the client cannot set it. The response carries the payment request’s id, reference_id and token, which your payment page needs for the next step (Take the card payment).
| Параметр | Тип | Описание |
|---|---|---|
tokenобязательный | string | The booking token. |
payment_model | total | deposit | Collect the full remaining amount or just the deposit. |
Do not send card details here. Card data goes from the traveller’s browser straight to us in the next step, so it never passes through your servers.
/payments/payTake the card payment
Submit this from the traveller’s browser as a plain HTML form post (not from your server). We pass the card to the bank and the traveller continues on the bank’s 3D Secure page. When the bank is done, the traveller lands on your return_url; read the outcome with Payment request status.
| Параметр | Тип | Описание |
|---|---|---|
referenceобязательный | string | reference_id of the payment request. |
tokenобязательный | string | token of the payment request (not the booking token). |
return_urlобязательный | string | Where the traveller lands after the bank. Must be on the website registered for your partner account, or one of its subdomains. |
card_nameобязательный | string | Name on the card. |
card_numberобязательный | string | Card number, digits only. |
exp_monthобязательный | integer | Expiry month, 1–12. |
exp_yearобязательный | integer | Expiry year, two digits. |
cvcобязательный | string | Security code. |
No X-API-Key on this call — it comes from the traveller’s browser; the payment request’s token is what authorises it. A wrong token, a return_url outside your website, or a closed or cancelled booking is refused.
/b2b/api/apiv1/bookings/{referenceId}/payment-request/{id}Payment request status
Poll the state of a payment request. Requires the same token.
| Параметр | Тип | Описание |
|---|---|---|
tokenобязательный | string | The booking token. |
/b2b/api/apiv1/bookings/abandoned-cartReport an abandoned cart
Tell us a traveller started but did not finish a booking, so our team can follow up. Creates no booking record.
| Параметр | Тип | Описание |
|---|---|---|
sourceобязательный | tsb | tst | Which storefront the cart came from. |
tourобязательный | string | Tour slug. |
name | string | The traveller's name. |
email | string | The traveller's email. |
phone_code | integer | Location id of the phone country code. |
phone | string | Phone number. |
date | YYYY-MM-DD | Intended departure date. |
pax | integer | Number of travellers. |
Deprecated response fields
Since 3 November 2026, tour search, tour detail and the product feed return the fields below as null. The keys stay in the response until 1 May 2027 so existing integrations keep parsing; after that date they are removed. Do not build on them.
Tour fields: guides, transfers, additional_service_location, is_bokun_completed, free_cancelation, all_inclusive, type, vat, deleted_at, b2c, bokun_id, sales, meta_title, meta_description, content_score and defaults.content_score.
Reviews: reviews is null. The rating and review_count summary is still returned.
name_en keeps its value until 1 May 2027 and is removed after that. Use name instead.
Price fields: the trp_, chd_ and inf_ minimum prices (min_reg_price, min_prv_price and their _pax variants), sng_/dbl_/unit_/adl_min_reg_price_pax and min_prv_price_pax. Keep using price and the sng_/dbl_/unit_/adl_ min_reg_price, min_prv_price and min_prv_price_pax fields; for exact prices and availability, call the pricing endpoints.
In rates[].dates[], id, rate_id and tour_id are null; date is unchanged.
Ошибки
Для ошибок используются стандартные коды состояния HTTP, а в JSON-теле передаётся message и — при ошибках валидации — объект errors с ключами по именам полей.
| Код | Значение | Что делать |
|---|---|---|
| 200 | OK | The request succeeded. |
| 401 | Unauthorized | The X-API-Key header is missing, or the key is not recognised. Check that you are sending the key you generated, not the one it replaced. |
| 403 | Forbidden | Your API access is suspended or not yet approved. Contact us if you believe this is a mistake. |
| 403 | IP not allowed | The body carries code ip_not_allowed and the ip we saw. Your key is bound to the server IPs you registered and this request came from another address. Register that address in your developer dashboard, or send the request from a registered server. |
| 403 | Challenge page | An HTML page titled "Just a moment..." instead of JSON. The request came from an IP that is not on your allowlist and was stopped before it reached the API. Register your server’s outgoing IP in your developer dashboard; changes take effect within about a minute. |
| 404 | Not found | The tour, booking or location is unavailable, deleted, embargoed or unknown; for token-scoped endpoints, the token may not match. |
| 422 | Unprocessable | Validation failed. The body contains a message; field validation may also include an errors object. For change feeds, check the timestamp, count and cursor, and never send cursor with modified-since. |
| 429 | Too many requests | You exceeded either the per-minute rate limit or your daily quota. Check the X-RateLimit-Remaining header and back off. |
| 503 | Temporarily unavailable | The product change feed could not read complete tour content. Wait for Retry-After, then retry the same page without saving or advancing its cursor. |
| 500 | Server error | Something failed on our side. Retry with backoff; if it persists, contact us with the time of the request. |
{
"message": "The given data was invalid.",
"errors": {
"tour_id": ["The selected tour id is invalid."],
"customers.0.email": ["The customers.0.email must be a valid email address."]
}
}Версионирование
Некоторые эндпоинты сохраняют исторический путь /b2b/api/apiv1/… или /b2b/api/apiv2/…. Собственные партнёрские эндпоинты, включая ленты изменений каталога, находятся непосредственно в /b2b/api/…. Все они работают и поддерживаются.
В рамках версии мы вносим только дополняющие изменения — новые поля и новые эндпоинты. Мы не переименовываем и не удаляем поля, на которые вы уже опираетесь. Всё, что может сломать интеграцию, выходит под новым путём версии, а перед выводом версии из эксплуатации мы уведомляем по e-mail всех активных партнёров.
Готовы начать?
Подайте заявку на доступ и создайте ключ. Не знаете, какая интеграция вам подходит? Наша команда с радостью поможет.