Документация по SOAP запросам к веб-сервису 1CHotelReservationInterfaces от 1С:Отель
Работа модуля бронирования осуществляется через WEB-службу. Конфигурация «1С:Отель» включает WEB-службу «ReservationInterfaces» определенную в пространстве имен http://www.1chotel.ru/ws/interfaces/reservation/.
WSDL с описанием веб-службы доступен по адресу: http://demo.1chotel.ru/dev/ws/1CHotelReservationInterfaces.1cws?wsdl
Тестовая среда работает по адресу: http://demo.1chotel.ru/dev
Типовые параметры:
RoomRate – настройка модуля «Код тарифа» (Строка не более 32 символов).
ClientType – настройка модуля «Тип клиента».
ExternalSystemCode – настройка модуля «Код внешней системы».
RoomQuota – настройка модуля «RoomQuota».
ReservationStatus – настройка модуля «Код статуса брони».
Hotel – Код отеля.
Customer – параметр используется когда доступ к модулю предоставляется для агентов отеля. Агент заходит на сайт со своим логином и паролем. Тогда из свойств пользователя берется код контрагента. Если вход не выполнен, или у пользователя код контрагента не указан, то берется код контрагента из настроек модуля.
Contract – берется из настроек пользователя, если выполнен вход и этот параметр у пользователя заполнен. Если нет, то берется из настроек модуля.
LanguageCode – язык интерфейса, выбирается пользователем в интерфейсе.
Входные данные
Пример запроса: http://www.1chotel.ru/interfaces/reservation/GetHotelsList.xml
ExternalSystemCode – код внешней системы из параметров модуля.
LanguageCode – код языка, для которого будут возвращены параметры. Для русского «RU», для английского «EN»
Возвращаемые значения
Пример возвращаемого значения: http://www.1chotel.ru/interfaces/reservation/GetHotelsListResponse.xml
Список элементов с параметрами:
Каждый элемент HotelParameters содержит информацию об отеле на том языке что был запрошен:
HotelPrintName – название гостиницы.
ReservationConditions – текст условий бронирования.
HotelPostAddress – адрес гостиницы.
HowToDriveToTheHotel – как добраться.
ReservationDivisionContacts – строка с контактами отдела бронирования.
HotelPhones – телефон гостиницы.
HotelFax – факс гостиницы.
HotelEMail – e-mail гостиницы.
HotelLogoLink – ссылка на логотип гостиницы.
ServerTimeZone – сдвиг в секундах по времени сервера. -14400 означает зону времени +4 часа.
MaxAdults (число) – максимальное количество взрослых возможных к поселению в один номер.
MaxKids (число) – максимальное количество детей в одном номере.
Входные данные:
Hotel – код отеля.
ExternalSystemCode – «1CBITRIX».
LanguageCode (Язык) – «RU» для русского языка, «EN»- для английского.
RoomRate – пустой.
Возвращаемые значения
HotelPrintName – название гостиницы.
ReservationConditions – условия бронирования.
HotelPostAddress – адрес гостиницы.
HowToDriveToTheHotel – как добраться.
ReservationDivisionContacts
HotelPhones – телефон гостиницы.
HotelFax – факс гостиницы.
HotelEMail – E-mail гостиницы.
HotelLogoLink – ссылка на логотип гостиницы.
MaxAdults – число, максимальное количество взрослых возможных к поселению в один номер.
MaxKids – число, максимальное количество детей в одном номере.
Входные данные:
Hotel – код отеля.
RoomRate – из настроек модуля.
ClientType – пустой
RoomType (Код типа номера) – пустой.
RoomQuota (Код квоты номеров) – из настроек модуля.
PeriodFrom (Начало периода) – данные пользователя.
PeriodTo (Конец периода) – данные пользователя.
ExternalSystemCode – из настроек модуля,
LanguageCode. RU – для русского, EN- для английского.
Email – адрес электронной почты заказчика, если указан.
Phone – телефон заказчика, если указан.
Login – логин агента на сайте.
PromoCode – введенное значение промо кода на странице бронирования.
GuestsQuantity
Adults – количество взрослых
Kids – количество детей
Age – возврат ребенка
Примеры xml файла вызова функции:
Пример А) Запрос 1 взрослый + 2 ребенка 3 и 6 лет:
Вызов: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypes-1_2.xml
Ответ: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypesResponse-1_2.xml
Пример Б) Запрос на 1 взрослый.
Вызов: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypes-1.xml
Ответ: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypesResponse-1.xml
Пример В) Запрос на 2х взрослых + 2 ребенка:
Запрос: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypes-2_2.xml
Ответ: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypesResponse-2_2.xml
Пример Г) Запрос на 3х взрослых + 3 ребенка. В гостинице только 1 категория номеров, куда помещается 6 человек.
Запрос: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypes-3_3.xml
Ответ: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypesResponse-3_3.xml
Пример Д) Запрос на 3х взрослых + 4 ребенка. В гостинице нет номеров, куда помещается 7 человек.
Запрос: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypes-3_4.xml
Ответ: http://www.1chotel.ru/interfaces/reservation/GetAvailableRoomTypesResponse-3_4.xml
Возвращаемые значения
XML ответ состоит из 3-х частей:
ReservationConditions – строка с описанием ограничений тарифа и условий отмены бронирования. Просто текст.
AvailableRoomTypesRows – перечень типов номеров со стоимостью проживания. Используется для отрисовки таблицы поиска номеров. Для каждой категории в таблице будет тег AvailableRoomTypesRow.
Значения:
Hotel – код отеля.
RoomType – наименование типа номера.
RoomsAvailable – количество номеров доступных для бронирования данной категории. Нигде не отображается. Используется для того чтобы вывести отметку «Осталось только Х номеров» когда номеров меньше 5ти.
BedsAvailable – количество свободных мест. Нигде не отображается. Используется гостиницами, торгующими местами (хостелы, общежития).
Amount – сумма = стоимость проживания на весь срок проживания в валюте, указаной в теге Currency.
Currency – представление валюты.
RoomTypeCode – код типа номера.
RoomTypeDescription – наименование типа номера.
CurrencyCode – код валюты, в которой отображается Amount – стоимость.
CurrencyDescription – наименование валюты, в которой возвращается стоимость брони.
RoomTypePictureLink – ссылка на картинку типа номера. Строка, использовалась в старом модуле бронирования. Сейчас, картинка должна подставляться из галереи. Связь между строкой и галереей лучше всего делать по коду типа номера.
RoomTypeInfoLink – ссылка на страницу типа номера. Строка. Предполагается, что не используется, т. к. связь между типом номера и страницей описания задается кодом типа номера.
AmountPresentation – представление стоимости проживания. Обычно отформатированная сумма, с разделителями тысяч и копеек с наименованием валюты. Например («12 000 р.»)
AccommodationTypes – структура со списком видов размещений для каждого гостя. Содержит перечень видов размещений для каждого гостя. Тегов будет столько, сколько всего было заказано гостей = взрослые+дети. Данная структура используется на следующем шаге для заданий ФИО гостей. Для каждого типа номера перечисляется какой вид размещения для какого возраста используется. Виды размещения используются на странице ввода гостей. Каждая строка заказа начинается с вида размещения. Для разных категорий номеров может быть разный набор видов размещений. Например, при поселении 1 взрослого и 2х детей, для типа номера «Люкс» набор видов размещений будет «Номер+Совместно+Доп. место+Доп. место», а для категории «Стандарт» набор будет «Номер+Доп. место+Доп. место детское+Доп. место детское».
Для каждого RoomType в свойствах тега выводятся свойства:
Code – код типа номера. Такой же, как код в теге RoomTypeCode.
Description – наименование категории. Такое де как в теге RoomTypeDescription.
AccommodationTypesList – выводится для каждого типа номера и содержит список видов размещения. Для каждого вида размещения тег AccommodationType со свойствами:
Пример:
<AccommodationType Code="40" Description="Доп. место" Age="12"/>
Code – код вида размещения.
Description – наименование вида размещения
Age – возраст гостя для которого нужно использовать этот вид размещения
Пример вызова для 2х взрослых + 2 ребенка (соответствует примеру В из предыдущей функции):
Запрос: http://www.1chotel.ru/interfaces/reservation/WriteExternalGroupReservation-2_2.xml
Ответ: http://www.1chotel.ru/interfaces/reservation/WriteExternalGroupReservationResponse-2_2.xml
Входные данные
WriteExternalGroupReservationRows – для каждого гостя содержит элемент WriteExternalGroupReservationRow.
Атрибут Login – содержит логин текущего пользователя на сайте.
Элементы WriteExternalGroupReservationRow:
ReservationCode – остается пустой.
GroupCode (номер заказа) - остается пустой.
GroupDescription – остается пустой.
GroupCustomer – остается пустой. Из настроек модуля.
GroupClient – ФИО заказчика.
ReservationStatus (Код статуса брони) - из настроек модуля. По умолчанию пустой.
PeriodFrom (Начало периода) – данные пользователя.
PeriodTo (Начало периода) – данные пользователя.
Hotel (Код Гостиницы).
RoomType (Код Типа Номера) - какой номер будет забронирован. Берется из таблицы возвращаемой функцией AvailableRoomTypes.
AccommodationType (Код типа размещения) - возможные значения берутся из таблицы возвращаемой функцией из AvailableRoomTypes.
ClientType – пустой.
RoomQuota – из настроек модуля.
RoomRate – из настроек модуля.
Customer – из настроек модуля.
Contract – из настроек модуля.
Agent - пустой.
ContactPerson – пустой.
NumberOfRooms = 1.
NumberOfPersons = 1
Элемент Client:
ClientCode – пустой.ClientLastName (фамилия) – данные введенные в заказе по гостю.ClientFirstName (имя) – данные введенные в заказе по гостю.ClientSecondName (отчество) – данные введенные в заказе по гостю.ClientSex (пол) – данные введенные в заказе по гостю.ClientCitizenship (гражданство) – данные введенные в заказе по гостю.ClientBirthDate (дата рождения) – данные введенные в заказе по гостю.ClientPhone (телефон) – данные пользователя.ClientFax (факс) – пустой.ClientEMail (e-mail) – данные пользователя.ClientRemarks – пустойClientSendSMS – true – если уведомление об отправке СМС включено. False – если флажок об отправке СМС выключенReservationRemarks (Пожелания к брони) – заполняется клиентом на сайте.
Car (Номер автомобиля) – некоторые отели, обычно загородные, просят отдельно указать номер автомобиля, чтобы передать списки на въезд.
PlannedPaymentMethod - остается пустой.
ExternalSystemCode (Код Внешней Системы) – из настройки модуля.
DoPosting = TRUE.
PromoCode (Промо-код) – заполняется пользователем.
Возвращаемые значения
В случае успеха, возвращается xml с данными брони и стоимостью.
Возможные возвращаемые ошибки:
Нет мест.
Ошибка в программе. Пример: http://www.1chotel.ru/interfaces/reservation/WriteExternalGroupReservationResponse-error.xml
При любой ошибке бронь считается не проведенной и клиенту сообщается о том, что операция неуспешна.
Функция GetGroupReservationDetails. Для поиска и идентификации брони используется e-mail + номер брони, либо телефон + номер брони.
Входные данные
Пример: http://www.1chotel.ru/interfaces/reservation/GetGroupReservationDetails.xml
EMail – e-mail гостя.
Phone – телефон гостя, вводится пользователем
Login – текущий логин пользователя
GuestGroupCode – номер брони, вводится пользователем
ExternalSystemCode – из настроек модуля
LanguageCode – код языка, на котором нужно получить ответ – RU=Русский, EN=Английский.
Возвращаемые значения
Пример: http://www.1chotel.ru/interfaces/reservation/GetGroupReservationDetailsResponse.xml
ErrorDescription – строка с описанием ошибки. Если строка пуста, значит ошибок нет.
GuestGroup – Номер брони
Customer - наименование контрагента, если он указан в качестве заказчика.
Contract – наименование договора, если он указан в брони.
Agent – наименование агента, если он указан в брони
GuestFullName – ФИО гостя-заказчика, полностью, одной строкой.
GuestBirthDate – дата рождения главного гостя-заказчика
GuestPassport – номер паспорта гостя-заказчика
GuestPhone – номер телефона гостя
GuestFax – номер факса гостя
GuestEMail – e-mail гостя
Currency – описание валюты, в которой произведено бронирование
CurrencyCode – код валюты, в которой произведено бронирование
CurrencyDescription – наименование валюты
BaseCurrency – базовая валюта отеля, т.е. та валюта у которой курс = 1 и относительно которой отель рассчитывает курсы остальных валют
CurrencyRate – курс валюты
TotalSum – итоговая сумма брони
TotalSumPresentation – строковое представление итоговой суммы, включая символ или наименование валюты
BalanceAmount – сумма баланса по данной брони. Если эта сумма = 0, это значит, что бронь оплачена. Если сумма > 0 то значит что бронь оплачена не полностью.
BalanceAmountPresentation – строковое представление баланса включает символ или наименование валюты
FirstDaySum – сумма за первые сутки проживания. Используется обычно при расчете штрафа за аннуляцию, или минимальной суммы оплаты по брони.
FirstDaySumPresentation – строковое представление стоимости первых суток проживания, включая символ валюты.
HotelName – наименование отеля на том языке, на котором был запрос.
ExternalReservationStatusRow - строка с данными гостя, для каждого гостя отдельная строка.
IsPosted – true – если бронь проведена. False если бронь не проведена, что означает что такая бронь не учитывается отелем.
ReservationStatus – наименование текущего статуса брони.
ReservationStatusCode – код текущего статуса брони
ReservationStatusDescription – наименование текущего статуса брони.
ConfirmationReply – текст с подтверждением бронирования. Если отель гостю хочет отправить какой-то текс, то он указывается здесь. Например, причина аннуляции или комментарий к заказанным доп. услугам.
GuestGroup – номер брони. Повторяется в каждой строке.
GuestFullName – ФИО гостя полностью включая имя отчество без сокращений.
GuestBirthDate – дата рождения гостя
GuestPassport – номер паспорта гостя.
GuestPhone – номер телефона
GuestFax – номер факса
GuestEMail – e-mail гостя
RoomQuantity – количество забронированных номеров. Обычно = 1.
NumberOfPersons – количество человек. Обычно = 1.
RoomType – тип номера
RoomTypeCode – код типа номера
RoomTypeDescription – наименование типа номера
AccommodationType – вид размещения
AccommodationTypeCode – код вида размещения
AccommodationTypeDescription – наименование вида размещения
CheckInDate – дата и время заезда
Duration – продолжительность в днях или часах в зависимости от выбранного тарифа
CheckOutDate – дата и время выезда
Currency - валюта
CurrencyCode – код валюты
CurrencyDescription – наименование валюты
BaseCurrency – базовая валюта, та относительно которой считается курс
CurrencyRate – курс валюты
Sum – сумма услуг по этому гостю
SumPresentation – строковое представление суммы услуг гостя, включая символ валюты
FirstDaySum – стоимость первого дня проживания данного гостя
FirstDaySumPresentation – строковое представление первого дня проживания, включая символ валюты
Функция CancelReservation вызывается для аннулирования брони.
http://www.1chotel.ru/interfaces/reservation/CancelGroupReservation.xml
Входные данные
Элементы WriteExternalGroupReservationRow:
GuestGroupCode (Номер брони) – номер группы, который был возвращен функцией «WriteExternalGroupReservation».
Hotel – код гостиницы
ExternalSystemCode – из настроек модуля.
LanguageCode – код языка. На этом языке будет возвращен результат функции
Reason – причина аннуляции.
В случае отказа при проведении платежа указывается «CanceledPayment».
В случае если пользователь в списке бронирования нажал «Аннулировать» то указывается «CanceledByUser».
Возвращаемые значения
Возвращает строку с ошибкой. Если строка пуста, то значит что вызов прошел успешно, ошибок нет.
http://www.1chotel.ru/interfaces/reservation/CancelGroupReservationResponse.xml
Функция получает список действующей брони:
http://www.1chotel.ru/interfaces/reservation/GetActiveGroupsList.xml
Входные данные
Login – логин агента на сайте.
Hotel – код гостиницы
ExternalSystemCode – из настроек модуля.
LanguageCode – код языка. RU= русский, EN = английский
Возвращаемое значение:
Возвращает описание ошибки.
Если описание ошибки пусто – то вызов прошел успешно.
Входные данные
Пример: http://www.1chotel.ru/interfaces/reservation/WriteGuestGroupPayment.xml
ReservationCode – код брони во внешней системе. Может быть пустой.
GroupCode – номер брони = номер заказа
ClientCode – код клиента, если известен. Может быть пустой
PayerName – наименование плательщика, если известно.
PaymentMethod – код способа оплаты. Если платежная система возвращает выбранный способ оплаты, то передавать его. Если нет, то указывать «СС»
Sum – сумма платежа
Currency – валюта платежа
PaymentSection – секция платежа, по умолчанию = 0
Hotel – код отеля
ExternalSystemCode – из настроек модуля.
ReferenceNumber – номер платежа в платежной системе, если он возвращается. Если неизвестен то указывается «0»
AuthorizationCode – код авторизации платежа из платежной системы. Если неизвестен, то указвается «0»
Remarks – комментарии к платежу. Если платежная система что-то вернула, то заполняем.
Возвращаемые значения
Пример: http://www.1chotel.ru/interfaces/reservation/WriteGuestGroupPaymentResponse.xml
PaymentNumber – номер документа в базе отеля.
ErrorDescription – текстовое описание ошибки в случае, если платеж не смог быть проведен в базе отеля. В этом случае гостя лучше предупредить, что у нас что-то сломалось и лучше позвонить в отель, чтобы уточнить детали.
Пример с ошибкой:
http://www.1chotel.ru/interfaces/reservation/WriteGuestGroupPaymentResponse-error-pm.xml
Источник: http://www.1chotel.ru/interfaces/reservation/