reserve
Бронирование.
Ресурс
https://selena-online.ru/rest/v1/reserve [PUT]
Структура данных
Входные данные передаются в теле http-запроса и представлены в формате JSON. Передаваемый сервису http-запрос должен содержать заголовок Content-Type, соответствующий формату входных данных: application/json.
Шаблон структуры входных данных в формате JSON:
{
"commit": boolean,
"pre_order": boolean,
"order": {
"baseid": int ,
"begindate": date,
"enddate": date,
"duration": int,
"tourid": int,
"agentid": int,
"customerid": int,
"note": string,
"promo": string,
"silence": boolean,
"agree_number": string,
"agree_date": date,
"agree_cost": int,
"seller_taxcode": string,
"seller_phone": string,
"seller_email": string
},
"buyer": {
"firstname": string,
"middlename": string,
"lastname": string,
"citizenship": string,
"birthdate": date,
"identity": int,
"identity_sn": string,
"address": string,
"phone": string,
"email": string
},
"tourists": [
{
"is_buyer": boolean,
"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 можно выбирать, от чьего имени должен быть выполнен заказ.
Также существует возможность указать покупателя-физлицо с помощью параметров раздела buyer, или с помощью параметра туриста is_buyer. Это работает как при установленном agentid, так и без него. Указанный покупатель добавляется в системный справочник покупателей-физлиц. При этом, если установлен agentid, то физлицо становится клиентом агента и доступно только турагенту в его собственном справочнике покупателей-физлиц, в его ЛК. Рекомендуется использовать buyer когда конечный покупатель путёвки (физлицо) не является одним из туристов. Для того, чтобы по возможности исключить добавление одного и того же покупателя-физлица в справочник много раз, выполняется сопоставление по параметрам firstname, lastname и phone. Идентификатор созданного покупателя возвращается в ответе на запрос в параметре customer_id.
Турагент-посредник
Следующие параметры заполняются, если между агентом agentid и конечным покупателем стоят один или более посредников-турагентов. В соответствии с требованиями ГИС ЭП эти данные обязательно должны указываться турагентом agentid.
string:agree_number - номер договора конечного покупателя (туриста, юр.лица) с продавцом путёвки. Опциональный. Если не будет указан, номер договора назначится автоматически как номер заявки у оператора.
string:agree_date - дата договора конечного покупателя (туриста, юр.лица) с продавцом путёвки. Опциональный. Если не будет указана, дата договора назначится автоматически как дата создания заявки у оператора.
string:agree_cost - цена договора конечного покупателя (туриста, юр.лица) с продавцом путёвки. Опциональный. Если не будет указана, цена договора назначится автоматически как полная стоимость заявки у оператора (включая агентскую комиссию).
string:seller_taxcode - ИНН конечного агента-продавца, с которым заключает договор конечный покупатель. Опциональный. Если не будет указан, продавцом путёвки будет считаться агент agentid.
string:seller_phone - Контактный телефон конечного агента-продавца, с которым заключает договор конечный покупатель. Опциональный. Обязательно должен быть указан, если указан seller_taxcode.
string:seller_email - Email конечного агента-продавца, с которым заключает договор конечный покупатель. Опциональный. Обязательно должен быть указан, если указан seller_taxcode.
Заказчик - не турист
Раздел buyer является необязательным и описывает данные заказчика, если это не один из туристов:
string:firstname - имя заказчика. Обязательный.
string:middlename - отчество заказчика. Обязательный.
string:lastname - фамилия заказчика. Обязательный.
date(yyyy-mm-dd):birthdate - дата рождения заказчика. Опциональный.
string:citizenship - код (в контексте официального справочника - числовой, здесь должен быть представлен строковым типом) гражданства заказчика по ОКСМ (Общероссийский классификатор стран мира). Обязательный.
int:identity - документ, удостоверяющий личность заказчика: 1 - паспорт РФ, 2 - загранпаспорт, 3 - свидетельство о рождении, 100 - другой документ. По умолчанию - паспорт РФ.
string:identity_sn - серия и номер документа, удостоверяющего личность заказчика. Обязательный.
string:address - адрес заказчика. Обязательный.
string:phone - контактный телефон заказчика. Обязательный.
string:email - email заказчика. Опциональный.
Данные туристов и их размещение
Раздел tourists содержит список туристов, их личные данные, а также информацию о категории размещения и типе места.
boolean:is_buyer - Турист является покупателем. Опциональный. Игнорируется, если есть раздел buyer.
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, а также в соответствии с требованиями ГИС ЭП.
string:citizenship - код (в контексте официального справочника - числовой, здесь должен быть представлен строковым типом) гражданства туриста по ОКСМ (Общероссийский классификатор стран мира). Обязательный в соответствии с требованиями ГИС ЭП.
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 - контактный телефон туриста. Обязательный в соответствии с требованиями ГИС ЭП, если установлен параметр is_buyer.
string:email - email туриста. Опциональный.
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: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. Если не установлен, выполняется только формальный логический контроль входных данных и расчёт стоимости заказа.
boolean:pre_order - флаг "Предварительный заказ". По умолчанию false. Если true, заказ принудительно устанавливается в статус "Ожидание подтверждения", при этом в момент бронирования не выполняются проверки заполнения некоторых полей персональных данных, которые, в частности, требуются для передачи информации в ГИС ЭП. Следует иметь в виду, что установка в true будет иметь эффект только в случаях, если это разрешено внутренней политикой оператора, и это нужно уточнять.
Бронирование
При обработке запроса на бронирование система выполняет такие же операции и такую же проверку входных данных, которые выполняются при бронировании в личном кабинете (ЛК) через веб-интерфейс. Поэтому заказ, выполненный через 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 | INVALID_MONEY_FORMAT | Неверно указана сумма |
| 422 | INVALID_TAXCODE | Неверно указан ИНН |
| 422 | INVALID_PHONE | Неверно указан номер телефона |
| 422 | INVALID_EMAIL | Неверно указан email |
| 422 | RESERVATION_ERROR | Ошибка бронирования. Обычно эта ошибка содержит текстовое описание, поясняющее её суть. |
| 422 | INVALID_BUYER_DATA | Ошибка в личных данных заказчика или не указаны обязательные данные. |
| 422 | INVALID_BUYER_CONTACT_DATA | Ошибка в контактных данных заказчика или не указаны обязательные данные. |
Флаг commit определяет, нужно ли сразу после проверки данных и расчёта заказа выполнять его бронирование. Если флаг commit не установлен, то система не выполняет реальное бронирование, и возвращается структура с данными, описывающими результат расчёта заказа, включая итоговые суммы. Эту информацию можно использовать для того, чтобы перед реальным бронированием показать туристу форму с итоговым заказом и кнопкой "Подтвердить". Нажатие на кнопку "Подтвердить" должно инициировать повторный запуск этого же метода с теми же входными данными, но с установленным флагом commit. Если флаг commit установлен, система выполняет его бронирование и возвращает информацию о реальном заказе.
Если бронирование подразумевает размещение в конкретный номер, например, в каюту речных круизах, то запрос без указания номера каюты выполнит бронирование, но туристы не будут размещены в каюты. Так как на круизах обычно контроль за наличием мест выполняется на основе информации о занятости кают, такой заказ не будет гарантировать размещение до тех пор, пока менеджер оператора не разместит туристов в каюты.
Автозаполнение
Если туристов в заказе более одного, некоторые незаполненные данные второго и последующих туристов автоматически заполняются аналогичными данными первого туриста. К таким относятся:
- город проживания
- адрес
- телефон
- гражданство
Заказчиком - конечным покупателем тура - при бронировании через API по умолчанию является первый турист в заказе.
Ответ
Возвращает структуры данных, состав которых зависит от установки флага 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,
"bill_enabled": bool,
"customer_id": int
}
string:order_id - номер заказа.
int:id - id заказа.
int:status - статус заказа: 0 или 1 - заказ на брони, 5 - заказ ожидает подтверждения.
string:currency - валюта заказа.
string:url - прямая беспарольная ссылка на html-страницу, содержащую информацию о заказе. Эту ссылку можно отправлять туристу.
bool:bill_enabled - флаг, указывающий на доступность счёта на оплату. В зависимости от действующих условий бронирования, счёт может быть либо доступен сразу после бронирования, либо станет доступным после подтверждения заявки менеджером.
int:customer_id - id заказчика (частное лицо), который создаётся в справочнике покупателей, если в запросе передан параметр buyer. Если заказчик уже был в справочнике, возвращается его id.
Статус заказа 0 или 1 означает, что заказ принят к исполнению и ожидает оплаты. Такой заказ может быть автоматически аннулирован системой через определённое количество дней, если он не оплачивается заказчиком.
Статус заказа 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"}
}
]
}