Структура ответа#
Детальное описание структуры ответа от /api/hotels/view_booking.
Основная структура#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
bookingId | guid | Да | Идентификатор бронирования TAPI (формат UUID) |
supplierOrderId | string | Нет | Идентификатор заказа у поставщика |
partner | ViewBookingPartnerInfo | Нет | Информация о заказе партнера |
hotel | ViewBookingHotelInfo | Нет | Информация об отеле и номере |
guests | ViewBookingGuestsInfo | Нет | Информация о гостях |
prices | ViewBookingPriceInfo | Нет | Ценовая информация |
bookingInfo | ViewBookingInfo | Нет | Статус и даты бронирования |
checkin | date | Да | Дата заезда (YYYY-MM-DD) |
checkout | date | Да | Дата выезда (YYYY-MM-DD) |
checkinTime | time | Нет | Время заезда (HH:mm) |
checkoutTime | time | Нет | Время выезда (HH:mm) |
upsells | ViewBookingUpsellInfo[] | Нет | Дополнительные услуги |
customer | ViewBookingCustomerInfo | Нет | Контактное лицо |
hostContacts | ViewBookingHostInfo | Нет | Контактная информация владельца квартиры (только при details.includeResidenceDetails = true, по умолчанию — да) |
extraInfo | ViewBookingExtraInfo | Нет | Дополнительная информация по проживанию (только при details.includeResidenceDetails = true, по умолчанию — да) |
supplier | ViewBookingSupplierInfo | Нет | Информация о поставщике/субпровайдере |
Структура ViewBookingPartnerInfo#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
partnerOrderId | string | Нет | Идентификатор заказа партнера |
comment | string | Нет | Комментарий |
amountSellB2b2c | Money | Нет | Сумма продажи B2B2C |
Структура ViewBookingHotelInfo#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
hotelId | string | Да | Идентификатор отеля |
room | ViewBookingRoomInfo | Да | Информация о номере |
Структура ViewBookingRoomInfo#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | Нет | Название номера |
rateName | string | Нет | Название тарифа |
roomId | string | Нет | Идентификатор категории номера |
mealName | string | Нет | Тип питания |
beddingNames | string[], enum | Нет | Типы кроватей. Возможные значения: unspecified, single, double, smallDouble, twin, triple, bunkBed, king, queen, sofa, sofaSingle, sofaDouble, childBed, extraBed, armchair, rollaway |
Структура ViewBookingGuestsInfo#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
count | integer | Да | Общее количество гостей |
adultCount | integer | Нет | Количество взрослых |
childrenCount | integer | Нет | Количество детей |
guests | ViewBookingGuestDetails[] | Нет | Детали гостей |
Структура ViewBookingGuestDetails#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
firstName | string | Нет | Имя |
lastName | string | Нет | Фамилия |
isChild | boolean | Нет | Ребенок |
age | integer | Нет | Возраст (для детей) |
citizenship | string | Нет | Гражданство (ISO 3166-1 alpha-2) |
gender | string | Нет | Пол |
Структура ViewBookingPriceInfo#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
supplier | string | Да | Поставщик, через которого совершено бронирование. Поставщики отельного домена: ostrovok, acase, avito, ariadna, hotelbook — полный список значений см. в Supplier |
contractId | string | Нет | Идентификатор контракта, по которому было совершено бронирование |
searchPresetId | string | Нет | Идентификатор пресета поиска, который использовался на момент поиска предложения |
searchPresetName | string | Нет | Название пресета поиска. null, если searchPresetId не заполнен |
pricingPresetId | string | Нет | Идентификатор пресета ценообразования, который использовался на момент поиска предложения |
pricingPresetName | string | Нет | Название ценового пресета. null, если pricingPresetId не заполнен |
payable | Money | Нет | Оплаченная сумма |
amountSell | Money | Нет | Сумма продажи |
paymentType | string | Нет | Тип оплаты |
cancellationRules | CancellationRules | Нет | Правила отмены |
Детализация цен (только при details.includePriceDetails = true)#
Поля этой секции — необязательные, присутствуют только при details.includePriceDetails = true. Для бронирований, созданных до внедрения этой детализации (у которых нужные данные не сохранены в БД), поля возвращаются как null, без ошибки.
| Поле | Тип | Описание |
|---|---|---|
total | Money | Итоговая цена для клиента |
discount | Money | Сумма скидки |
markup | Money | Сумма наценки |
serviceFee | Money | Сервисный сбор |
commission.margin | string | Маржа (%) |
commission.marginCurrency | string | Валюта маржи |
commission.supplier | Money | Комиссия поставщика |
commission.subagent | Money | Субагентское вознаграждение |
supplierBreakdown.netto | Money | Нетто-стоимость у поставщика |
supplierBreakdown.gross | Money | Валовая стоимость у поставщика |
supplierBreakdown.rack | Money | Стоимость Rack Rate |
supplierBreakdown.bar | Money | Стоимость Best Available Rate |
supplierBreakdown.minRetailPrice | Money | Минимальная розничная цена, установленная поставщиком (порог price parity). Отсутствует или ноль — у предложения такого порога нет |
vat.percent | number | Ставка НДС (%) |
vat.value | Money | Сумма НДС |
vat.isVatFree | boolean | true — НДС не применяется |
vat.included | boolean | true — НДС включён в цену |
deposit.value | Money | Сумма депозита |
deposit.isRefundable | boolean | true — депозит возвратный |
Аналогичная детализация (
value,discount,markup,serviceFee,supplier,commission.*,vat.*) добавляется в каждый элементupsells[]приdetails.includePriceDetails = true. Вupsells[]полеsupplier— это Money (цена поставщика за услугу), а не объект детализации: разбивкиnetto/gross/rack/barдля допуслуг нет.
Структура ViewBookingInfo#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
status | string, enum | Да | Статус бронирования. Возможные значения: unknown, inWork, completed, rejected, cancelled, failed |
isCancellable | boolean | Да | Признак доступности отмены в текущий момент. false означает, что бронирование недоступно для отмены — например, если отмена уже запрошена или бронирование уже отменено |
createdAt | datetime | Нет | Дата создания (ISO 8601) |
updatedAt | datetime | Нет | Дата обновления (ISO 8601) |
cancelledAt | datetime | Нет | Дата отмены (ISO 8601) |
Изменение значений
status. Было:Unknown,Inwork,Booked,Rejected,Cancelled,Error(произвольная строка, не документирована как перечисление). Станет:unknown,inWork,completed,rejected,cancelled,failed(фиксированный enum) — тот же набор значений, что в/api/hotels/create_bookingи/api/hotels/search_bookings.
Структура ViewBookingUpsellInfo#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
type | string | Нет | Тип услуги (earlyCheckin, lateCheckout) |
name | string | Нет | Название услуги |
value | Money | Нет | Стоимость |
Структура ViewBookingCustomerInfo#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
firstName | string | Нет | Имя |
lastName | string | Нет | Фамилия |
email | string | Нет | |
phone | string | Нет | Телефон |
comment | string | Нет | Комментарий |
Структура ViewBookingHostInfo#
Наличие данных зависит от поставщика:
- Авито — возвращает информацию (при наличии) за день до заезда или если бронь подтверждена и отмена возможна только со штрафом.
- Островок, Roomlink — ограничений нет, но данные зависят от заполненности у поставщика.
- Acase, HBPro — данные не возвращаются.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | Нет | Имя |
email | string | Нет | |
phone | string | Нет | Телефон |
comment | string | Нет | Комментарий |
Структура ViewBookingExtraInfo#
Наличие данных зависит от поставщика:
- Авито — возвращает информацию (при наличии) за день до заезда или если бронь подтверждена и отмена возможна только со штрафом.
- Островок, Roomlink — ограничений нет, но данные зависят от заполненности у поставщика.
- Acase, HBPro — данные не возвращаются.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
entrance | string | Нет | Номер подъезда |
apartmentNumber | string | Нет | Номер квартиры |
entranceCode | string | Нет | Код от домофона |
howToFind | string | Нет | Как найти дом |
howToGetIn | string | Нет | Как попасть в квартиру |
lockCode | string | Нет | Код от сейфа или двери |
checkInRules | string | Нет | Правила заселения |
checkOutRules | string | Нет | Правила выселения |
accommodationRules | string | Нет | Правила проживания |
wifiName | string | Нет | Название сети Wi-Fi |
wifiPassword | string | Нет | Пароль от Wi-Fi |
Структура ViewBookingSupplierInfo#
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
subProviderName | string | Нет | Наименование субпровайдера (не путать с юрлицом-агентом) |
invoiceNumber | string | Нет | Номер счёта |
comment | string | Нет | Комментарий от поставщика |
Примеры ответов#
Успешный ответ#
Пример ниже — для запроса с
details.includePriceDetails = true(полная детализация цен). Без этого флага блок цен ограничивается полямиsupplier/contractId/searchPresetId/searchPresetName/pricingPresetId/pricingPresetName/payable/amountSell/paymentType/cancellationRules.
Развернуть пример
1{
2 "bookingId": "019a0c82-5d2b-7a5e-84fe-56357a57df66",
3 "supplierOrderId": "SUP-12345",
4 "partner": {
5 "partnerOrderId": "ORDER-12345",
6 "comment": "VIP клиент"
7 },
8 "hotel": {
9 "hotelId": "hotel-001",
10 "room": {
11 "name": "Стандартный двухместный",
12 "rateName": "Невозвратный тариф",
13 "roomId": "room-7",
14 "mealName": "Завтрак",
15 "beddingNames": ["Двуспальная кровать"]
16 }
17 },
18 "guests": {
19 "count": 2,
20 "adultCount": 2,
21 "childrenCount": 0,
22 "guests": [
23 {
24 "firstName": "IVAN",
25 "lastName": "IVANOV",
26 "isChild": false,
27 "citizenship": "RU",
28 "gender": "male"
29 },
30 {
31 "firstName": "MARIA",
32 "lastName": "IVANOVA",
33 "isChild": false,
34 "citizenship": "RU",
35 "gender": "female"
36 }
37 ]
38 },
39 "prices": {
40 "supplier": "ostrovok",
41 "contractId": "uy123u8213y2j",
42 "searchPresetId": "87123eh22323",
43 "searchPresetName": "Стандартный поиск",
44 "pricingPresetId": "ed23uhds223f",
45 "pricingPresetName": "Базовое ценообразование",
46 "payable": {
47 "amount": 15000.00,
48 "currency": "RUB"
49 },
50 "amountSell": {
51 "amount": 15000.00,
52 "currency": "RUB"
53 },
54 "paymentType": "online",
55 "cancellationRules": {
56 "freeCancellationBefore": "2025-12-13T12:00:00+00:00"
57 },
58 "total": {
59 "amount": 13500.00,
60 "currency": "RUB"
61 },
62 "discount": null,
63 "markup": {
64 "amount": 1000.00,
65 "currency": "RUB"
66 },
67 "serviceFee": {
68 "amount": 200.00,
69 "currency": "RUB"
70 },
71 "commission": {
72 "margin": "10.00",
73 "marginCurrency": "RUB",
74 "supplier": {
75 "amount": 1500.00,
76 "currency": "RUB"
77 },
78 "subagent": {
79 "amount": 300.00,
80 "currency": "RUB"
81 }
82 },
83 "supplierBreakdown": {
84 "netto": {
85 "amount": 13500.00,
86 "currency": "RUB"
87 },
88 "gross": {
89 "amount": 15000.00,
90 "currency": "RUB"
91 },
92 "rack": null,
93 "bar": null,
94 "minRetailPrice": null
95 },
96 "vat": {
97 "percent": 20,
98 "value": {
99 "amount": 2500.00,
100 "currency": "RUB"
101 },
102 "isVatFree": false,
103 "included": true
104 },
105 "deposit": null
106 },
107 "bookingInfo": {
108 "status": "completed",
109 "isCancellable": true,
110 "createdAt": "2025-11-20T10:30:00+00:00",
111 "updatedAt": "2025-11-20T10:30:05+00:00"
112 },
113 "checkin": "2025-12-15",
114 "checkout": "2025-12-18",
115 "checkinTime": "14:00",
116 "checkoutTime": "12:00",
117 "supplier": {
118 "subProviderName": "ООО Академсервис",
119 "invoiceNumber": "INV-20251120-001",
120 "comment": "Номер подтверждён поставщиком"
121 },
122 "customer": {
123 "firstName": "Ivan",
124 "lastName": "Ivanov",
125 "email": "ivan@example.com",
126 "phone": "+79991234567"
127 },
128 "hostContacts": {
129 "name": "Petr",
130 "email": "petr@example.com",
131 "phone": "+12345678",
132 "comment": "comment"
133 },
134 "extraInfo": {
135 "entrance": "1",
136 "apartmentNumber": "1",
137 "entranceCode": "111",
138 "howToFind": "red roof",
139 "howToGetIn": "apartment number 1",
140 "lockCode": "789123",
141 "checkInRules": "after 16:00",
142 "checkOutRules": "before 12:00",
143 "accommodationRules": "string",
144 "wifiName": "wifi name",
145 "wifiPassword": "123qwerty"
146 }
147}Ответ с ошибкой#
1{
2 "error": {
3 "code": "BOOKING_NOT_FOUND",
4 "message": "Бронирование не найдено",
5 "description": "Бронирование с указанным идентификатором не найдено",
6 "errorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
7 }
8}Типичные ошибки TAPI#
| Код ошибки | Причина | Решение |
|---|---|---|
BOOKING_NOT_FOUND | Бронирование не найдено, не принадлежит клиенту или не является отельным | Проверьте корректность bookingId |
VALIDATION_ERROR | Ошибка валидации запроса | Проверьте обязательные поля и форматы значений |
Помимо перечисленных TAPI-кодов, при ошибке на стороне поставщика в ответе может быть возвращён код ошибки поставщика без изменений (проброс) — набор таких кодов зависит от поставщика и не фиксирован.