reserve

Бронирование.

Ресурс

https://selena-online.ru/rest/v1/reserve [PUT]

Структура данных

Входные данные передаются в теле http-запроса и представлены в формате JSON. Передаваемый сервису http-запрос должен содержать заголовок Content-Type, соответствующий формату входных данных: application/json.

Шаблон структуры входных данных в формате JSON:

{
    "commit": boolean,
    "order": {
        "baseid": int ,
        "begindate": date,
        "enddate": date,
        "duration": int,
        "tourid": int,
        "agentid": int,
        "customerid": int,
        "note": string,
        "promo": string,
        "silence": boolean},
    "tourists": [
        {
            "apartmentid": int,
            "place_type": int,
            "main_place_type": int,
            "place_is_locked": boolean
            "firstname": string,
            "middlename": string,
            "lastname": string,
            "birthdate": date,
            "identity": int,
            "identity_sn": string,
            "identity_issued": date,
            "identity_issuer": string,
            "identity_expired": date,
            "address": string,
            "phone": string,
            "email": string,
            "sex": int,
            "roomid": int,
            "services": [int,int, ...],
            "socials": {"id": int, "doc": string},
            "tourpackid": int,
            "city": string,
            "cityid": int,
            "citizenship": string,
            "forward_tripid": string,
            "forward_trip_seat": string,
            "forward_load_point": int,
            "forward_unload_point": int,
            "backward_tripid": string,
            "backward_trip_seat": string,
            "backward_load_point": int,
            "backward_unload_point": int
        },
        {
            "apartmentid": int,
            "place_type": int,
            ...
        }
    ]
}

Пакет данных, содержащий запрос на бронирование заказа, условно разделяется на 3 части: основные параметры заказа, данные туристов и их размещения, и управляющая информация.

Основные параметры заказа

Раздел order описывает следующие характеристики заказа:

int:baseid - ID объекта размещения (тура - для экскурсионных туров). Обязательный.

int:tourid - ID тура. Обязательный.

date(yyyy-mm-dd):begindate - дата начала тура. Необязательный, если тур является фиксированным (свойство тура type="fixed").

int:duration - Продолжительность тура, дней. Необязательный, тур является фиксированным.

int:customerid - ID заказчика-туриста. Опциональный.

int:agentid - ID заказчика-агента. Опциональный.

string:note - примечание к заказу в свободной форме. Опциональный.

string:promo - промокод. Опциональный.

boolean:silence - Флаг "Режим тишины". Если true, то система не отправляет покупателю никаких уведомлений о происходящих с заказом событиях: о факте бронирования, об изменении статуса заказа и т.д. Опциональный.

customerid и agentid - взаимоисключающие параметры. Если указаны оба параметра, приоритет имеет agentid, а customerid игнорируется.

customerid устанавливается в случае, если заказчик - турист. Если не указан или указан 0 (ноль), в качестве заказчика используется первый турист в заказе, но только при условии, что соответствующее разрешение установлено в конфигурации базы данных (определяется оператором БД). Если такого разрешения нет, ID заказчика должен быть целым положительным числом, отличным от нуля, а это означает, что заказчик либо должен присутствовать в справочнике, либо его нужно предварительно создать.

agentid устанавливается в случае, если заказчик - турагент. При этом выполняется автоматический расчёт комиссий, если это предусмотрено в конфигурации БД оператора. Для сторонних компаний и агрегаторов, использующих API бронирования для создания соответствующего интерфейса на своих онлайн-ресурсах, agentid необязателен, т.к. он принудительно устанавливается в ID этой компании в БД оператора системы бронирования. В случае, если компания имеет несколько юр. лиц, то с помощью agentid можно выбирать, от чьего имени должен быть выполнен заказ.

Данные туристов и их размещения

Раздел tourists содержит список туристов, их личные данные, а также информацию о категории размещения и типе места.

int:apartmentid - ID категории размещения. Обязательный.

int:place_type - тип места: 1 - основное, 2 - дополнительное, 3 - детское (без места). Обязательный.

boolean:main_place_type - тип основного места: 0 - не имеет значения, 1 - нижнее место, 2 - верхнее место. Опциональный, по умолчанию 0. Имеет смысл:
- только для основных мест (place_type=1);
- только для номеров, в которых есть основные верхние места;
- только если указан параметр roomid.

Если параметр = 0, система сама размещает туриста на первое свободное место в номере, начиная поиск с нижних мест. Если параметр отличается от 0, то система пытается найти свободное место указанного типа, и если его нет - возвращает отказ.

boolean:place_is_locked - флаг "место зарезервировано". Если требуется (N-1)-местное размещение в N-местном номере, то флаг указывает место (только одно на номер), которое резервируется без размещения туриста. Опциональный, по умолчанию false.

string:firstname - имя туриста. Обязательный, если не установлен флаг place_is_locked.

string:middlename - отчество туриста. Обязательный, если не установлен флаг place_is_locked.

string:lastname - фамилия туриста. Обязательный, если не установлен флаг place_is_locked.

date(yyyy-mm-dd):birthdate - дата рождения туриста. Обязательный, если не установлен флаг place_is_locked.

int:identity - документ, удостоверяющий личность туриста: 1 - паспорт РФ, 2 - загранпаспорт, 3 - свидетельство о рождении, 100 - другой документ. Опциональный, по умолчанию - паспорт РФ.

string:identity_sn - серия и номер документа, удостоверяющего личность туриста. Опциональный.

date(yyyy-mm-dd):identity_issued - дата выдачи документа, удостоверяющего личность туриста. Опциональный.

string:identity_issuer - орган власти, выдавший документа, удостоверяющий личность туриста. Опциональный.

date(yyyy-mm-dd):identity_expired - срок действия документа, удостоверяющего личность туриста. Опциональный.

string:address - адрес туриста. Опциональный.

string:phone - контактный телефон туриста. Опциональный.

int:sex - пол туриста: 1 - мужской, 2 - женский. Опциональный, по умолчанию - мужской.

int:roomid - ID номера (каюты и пр.) для размещения, если необходимо разместить туриста. Опциональный.

[int]:services - список ID-ов услуг, выбранных туристом. Опциональный.

array:socials - документ, представленный туристом в подтверждение права на скидку. Опциональный. Документ передаётся в виде ассоциативного массива: {"id": social_discount_id, "doc": document_number}

social_discount_id: id социальной скидки. Список скидок возвращается ресурсом discountlist.
document_number: номер предоставленного документа.

int:tourpackid - ID вида путёвки (тарифа). Опциональный.

string:city - название города проживания туриста. Опциональный.

int:cityid - идентификатор города проживания туриста (справочник citylist). Опциональный.

string:citizenship - код гражданства туриста (ОКСМ — Общероссийский классификатор стран мира). Опциональный.

string:forward_tripid - идентификатор рейса "туда" (автобус, поезд, авиа и т.д.), который перевозит туриста в рамках тура. Этот же рейс может быть рейсом "обратно", если в туре не предусмотрено отдельного обратного рейса, и турист возвращается из тура домой на том же транспортном средстве и на том же месте.

string:backward_tripid - идентификатор рейса "обратно" (автобус, поезд, авиа и т.д.), который перевозит туриста в рамках тура. Если в туре нет обратного рейса, параметр не указывается.

string:forward_trip_seat - место в рейсе "туда"

string:backward_trip_seat - место в рейсе "обратно"

string:forward_load_point - пунк посадки туриста на рейс "туда"

string:forward_unload_point - пунк высадки туриста с рейса "туда"

string:backward_load_point - пунк посадки туриста на рейс "обратно"

string:backward_unload_point - пунк высадки туриста с рейса "обратно"

Флаг place_is_locked устанавливается, если нужно занять основное место без подселения в многоместном номере (более одного основного места). Например, если необходимо 1-местное размещение в 2-местном номере, одно из мест нужно отметить флагом place_is_locked. При этом не нужно указывать данные туристов и тип места, т.к. резервировать можно только основные места, и place_type=1 устанавливается по умолчанию:

        ...
        {
            "apartmentid": 19,
            "roomid": 209,
            "place_is_locked": true
        },
        ...

Для (N-1)-местного размещения в N-местном номере, в котором есть верхние места, и требуется размещение в номер (указан параметр roomid), действует специальное условие: резервировать (выкупать без размещения туриста) можно только верхнее место. Это означает, что place_is_locked=true может быть только в случае, если main_place_type=2.

При резервировании места важно учитывать тот факт, что неполное заселение допускается не во все категории размещения. Информацию о параметрах категории размещения можно найти в соответствующем разделе FrontAPI.

Управляющая информация

boolean:commit - флаг "выполнить проверку данных и бронирование". Опциональный, по умолчанию false.

Бронирование

При обработке запроса на бронирование система выполняет такие же операции и такую же проверку входных данных, которые выполняются при бронировании в личном кабинете (ЛК) через веб-интерфейс. Поэтому заказ, выполненный через API, ничем не отличается от заказа, сделанного в ЛК. При возникновении ошибок при проверке входных данных, а также при отсутствии возможности подтвердить наличие мест (квот) система возвращает соответствующие сообщения. Некоторые сообщения, кроме http-кодов, могут содержать коды ошибок, поясняющие причину неуспеха операции. В следующей таблице перечислены дополнительные коды возможных ошибок.

http код	Код ошибки	Описание
422	INVALID_PLACEMENT_TYPE	Неверно указан тип размещения (place_type).
422	INVALID_APARTMENT_CATEGORY	Неверно указана категория размещения.
422	MAIN_PLACES_NOT_SPECIFIED	Не указаны основные места. Обычно ошибка возникает, если была попытка выполнить заказ только на дополнительные или детские места, а конфигурация БД оператора этого не позволяет.
422	PLACES_LIMIT_EXCEEDED	Превышено допустимое количество дополнительных или детских мест. Информацию о количестве таких мест для каждой категории размещения можно найти в соответствующем разделе FrontAPI.
422	APARTMENT_MUST_BE_RESERVED_WHOLLY	Номер должен быть забронирован целиком.
422	EMPTY_PLACE_PROHIBITED	Запрещено резервирование (выкуп) основного места без заселения на него туриста. Т.е. нельзя, например, бронировать 2-местный номер в одноместном размещении. Эта ошибка указывает на то, что параметр place_is_locked применяется некорректно.
422	EMPTY_PLACE_LIMIT_EXCEEDED	Превышено количество зарезервированных (выкупленных) мест. При бронировании через API и ЛК не позволяется резервировать (выкупать) более одного места на номер.
422	ADD_PLACE_WITHOUT_FULL_BOOKING_PROHIBITED	Нельзя бронировать дополнительное место, если номер не бронируется целиком.
422	ADD_OR_CHILD_PLACE_WITHOUT_MAIN_PLACE_PROHIBITED	Нельзя бронировать дополнительное или детское место, если для него не бронируется основное место. Т.е. ребёнок без места размещается на основном месте, вместе со взрослым.
422	INVALID_DATE_FORMAT	Неверный формат даты.
422	INVALID_IDENTITY	Неверно указан тип документа, удостоверяющего личность (identity).
422	RESERVATION_ERROR	Ошибка бронирования. Обычно эта ошибка содержит текстовое описание, поясняющее её суть.

Флаг commit определяет, нужно ли сразу после проверки данных и расчёта заказа выполнять его бронирование. Если флаг commit не установлен, то система не выполняет реальное бронирование, и возвращается структура с данными, описывающими результат расчёта заказа, включая итоговые суммы. Эту информацию можно использовать для того, чтобы перед реальным бронированием показать туристу форму с итоговым заказом и кнопкой "Подтвердить". Нажатие на кнопку "Подтвердить" должно инициировать повторный запуск этого же метода с теми же входными данными, но с установленным флагом commit. Если флаг commit установлен, система выполняет его бронирование и возвращает информацию о реальном заказе.

Если бронирование подразумевает размещение в конкретный номер, например, в каюту речных круизах, то запрос без указания номера каюты выполнит бронирование, но туристы не будут размещены в каюты. Так как на круизах обычно контроль за наличием мест выполняется на основе информации о занятости кают, такой заказ не будет гарантировать размещение до тех пор, пока менеджер оператора не разместит туристов в каюты.

Ответ

Возвращает структуры данных, состав которых зависит от установки флага commit.

Если флаг commit не установлен, возвращается информация об итоговых суммах заказа:

{
"bonus_sum": float,
"discount_desc": string,
"discount_sum": float,
"full_sum": float,
"order_sum": float
}

float:full_sum - полная сумма заказа, без учёта скидок и комиссий.

float:order_sum - сумма заказа к оплате.

float:discount_sum - сумма скидки.

string:discount_desc - текстовое описание скидки.

float:bonus_sum - сумма комиссии, если заказ от агента.

Если флаг commit установлен, возвращается информация о заказе:

{
"id": int,
"order_id": string,
"status": int,
"currency": string,
"url": string
}

string:order_id - номер заказа.

int:id - ID заказа.

int:status - статус заказа: 0 - заказ на брони, 5 - заказ ожидает подтверждения.

string:currency - валюта заказа.

string:url - прямая беспарольная ссылка на html-страницу, содержащую информацию о заказе. Эту ссылку можно отправлять туристу.

Статус заказа 0 означает, что заказ принят к исполнению и ожидает оплаты. Такой заказ может быть автоматически аннулирован системой через определённое количество дней, если он не оплачивается заказчиком.

Статус заказа 5 означает, что заказ требует подтверждения оператора, и в общем случае может быть изменён без согласования с покупателем.

Следует заметить однако, что решение об изменении заказа оператор может принять в любом случае, независимо от статуса, и обычно это регламентируется договором оферты или субагентским договором. Но в любом случае и при любом из указанных статусов действует правило: если бронирование подразумевает снятие квот или заселение в номер (каюту), то происходит реальное снятие/заселение, и купленные в заказе места могут быть реализованы другому покупателю только в том случае, если заказ будет аннулирован.

Пример запроса

{   "order": {
        "baseid": 2 ,
        "tourid": 9,
        "agentid": 1,
        "note": "Тестовый заказ",
        "promo": "495663524-443" },
    "commit": true,
    "tourists": [
        {
            "apartmentid": 19,
            "place_type": 1,
            "firstname": "Иван",
            "middlename": "Иванович",
            "lastname": "Иванов",
            "birthdate": "1980-01-01",
            "identity": 1,
            "identity_sn": "1232 123312",
            "identity_issued": "2000-01-01",
            "identity_issuer": "Кировский РОВД",
            "address": "Пермь, ул.Ленина, д. 20, кв. 17",
            "phone": "213123123",
            "sex": 1,
            "place_is_locked": false,
            "services": [2,7],
            "socials": {"id": 3, "doc": "CA-675342"}
        }
    ]
}

Index BookingAPI