Веб сервис для взаимодействия с ресторанной системой
Способы вызова функций из внешней системы
Через WEB-службу. Конфигурация «1С:Отель» включает WEB-службу "RestaurantInterfaces" определенную в пространстве имен http://www.1hotel.ru/ws/interfaces/restaurant/.
Сценарии обмена.
По карте клиента.
Используется, когда у всех клиентов отеля есть карты гостя. На карте записан только идентификатор карты, обычно строка от 6 до 36 символов.
Карта выдается гостю при поселении. Роль карты может выполнять ключ от номера, если система электронных замков поддерживает запись на вторую дорожку или, при использовании бесконтактной системы, идентификатор карты возвращается и прикрепляется к гостю.
Карта выполняет роль идентификатора клиента. По карте можно получить текущий баланс клиента и его глубину кредита. В отеле к одному лицевому счету может быть прикреплено несколько карт (например, для семьи).
Порядок закрытия:
-
Проверка карты – по идентификатору нужно проверить есть ли такая карта в системе гостиницы, и если есть, получить по ней ФИО гостя и текущий баланс.
Для этого вызывается функция GetClientCardBalance -
Закрытие заказа на карту. Передается номер карты и сумма заказа.
Вызывается функция ChargeServiceByClientCard.
В случае если возвращается пустое сообщение об ошибке, то операция считается успешной и заказ можно закрыть. - Balance – число без кавычек, текущий баланс гостя по лицевому счету карты;
- Client – фамилия имя отчество гостя полностью;
- Hotel – содержит название гостиницы;
- Room – номер комнаты в котором живет гость. В COM интерфейсе строка в кавычках;
- CheckInDate – Дата и время заезда гостя
- CheckOutDate – дата и время выезда гостя
- IsCheckedOut – false – если гость еще проживает, true – если гость уже выселен. (так бывает, гостя выселили, а он пошел в ресторан, в этом случае нельзя записывать в кредит на карту, можно закрывать заказ только в пределах предоплаты)
- IsBlocked – true – если карта заблокирована. Флаг блокировки в гостинице ставят например при утере карты. Также равен true если карта не найдена.
- BlockReason – строка с описанием причины блокировки карты, если, конечно ее ввели при включении флажка. Если карта не найдена передается строка «Unknown card!»
- CreditLimit – лимит кредита по карте, т.е. сумма на которую разрешено уходить в минус. Обычно, если средств предоплаты на карте не хватает, то можно позвонить на ресепшн и они могут увеличить этот лимит и тем самым разрешить закрыть заказ.
- GuestGroup – номер группы гостя.
- Customer – контрагент, наименование. Заполняется, если плательщиком по счету карты является контрагент, а не физическое лицо.
- PaymentMethod – наименование планируемого способа оплаты по счету карты.
- FolioCurrency – код валюты лицевого счета карты. Именно в этой валюте указывается баланс и глубина кредита.
- RoomRate – наименование тарифа, по которому поселен гость.
- Discount – величина скидки гостя в процентах
- DiscountType – наименование типа скидки.
- DiscountCard – код дисконтной карты, если она привязана к этой карте гостя. Если у гостя есть персональная дисконтная карта, и эта карта привязана к гостю, то код этой карты будет заполнен. Например картой гостя выступает ключ от номера и по этому ключу идет обмен, а у гостя есть еще постоянная дисконтная карта.
- ClientCode – код клиента в справочнике гостиницы.
- Card – обязательный параметр, то, что записано на второй дорожке без символов префикса и суффикса.
- Service – Код места продажи (Строка до 5 символов). Когда в отеле несколько точек продаж, то для статистики в базе отеля заказ из разных точек будет начислен по разным кодам услуг. Соответствия кодов задаются в базе отеля. Если соответствие не задано, или в параметре передана пустая строка, то будет использована стандартная услуга «по-умолчанию» («Заказ ресторана»).
- Sum – обязательный параметр, число, сумма заказа в валюте лицевого счета карты;
- Quantity – не обязательный параметр, число, количество, которое будет начислено по услуге; Если не указано, то принимается равным 1
- Remarks –строка, которая будет отражена в описании начисления на счет. Может быть: номер заказа, время заказа, название ресторана или зала ресторана, номер столика…
- Details – строка, которая содержит список позиций заказа. По сути является текстовым представлением ресторанного счета.
- Currency – код валюты лицевого счета. Для рублей 643. Если код валюты другой, то в базе отеля нужно настроить таблицу переконвертации. И тогда сюда надо указывать код валюты или наименование так, как он задан в ресторанной системе. Если не указывать, то будет использована валюта счета гостя.
- ExternalSystemCode – строка. Наименование системы с которой выполняется обмен. Например «iiko» или «traktirfo3». Используется как идентификатор для настройки таблицы переконвертации.
- Guest – имя гостя. Если указано, то будут возвращены все гости с указанным именем. Поиск выполняется по первым буквам имени гостя. Т.е. если передать «А», то будут найдены все гости у котрых фамилия начинается на «А».
- Room – номер комнаты. Указывается номер комнаты. Поле гостя при этом оставляется пустое – получим всех гостей, которые проживают в комнате.
- Hotel – код отеля. В одной базе может быть учет по нескольким отелям.
- Guest – имя клиента (Фамилия Имя Отчество)
- GuestCode – код клиента в справочнике гостиницы.
- Hotel – содержит название гостиницы;
- Room – номер комнаты в котором живет гость. В COM интерфейсе строка в кавычках;
- CheckInDate – Дата и время заезда гостя
- CheckOutDate – дата и время выезда гостя
- GuestGroup – номер группы гостя.
- Customer – контрагент, наименование. Заполняется, если плательщиком по счету карты является контрагент, а не физическое лицо.
- PaymentMethod – наименование планируемого способа оплаты по счету гостя.
- ClientBalance – число без кавычек, текущий баланс гостя по лицевому счету карты;
- FolioCurrency – код валюты лицевого счета карты. Именно в этой валюте указывается баланс и глубина кредита.
- CreditLimit – лимит кредита по карте, т.е. сумма на которую разрешено уходить в минус. Обычно, если средств предоплаты на карте не хватает, то можно позвонить на ресепшн и они могут увеличить этот лимит и тем самым разрешить закрыть заказ.
- Discount – величина скидки гостя в процентах
- DiscountType – наименование типа скидки.
- DiscountCard – код дисконтной карты, если она привязана к этой карте гостя. Если у гостя есть персональная дисконтная карта, и эта карта привязана к гостю, то код этой карты будет заполнен. Например картой гостя выступает ключ от номера и по этому ключу идет обмен, а у гостя есть еще постоянная дисконтная карта.
- AccommodationCode – номер документа Размещение в базе гостиницы.
- IsRoomShare – флаг совместного поселения с другими гостями. Если гость занимает весь номер то = false
- Guest – код гостя в справочнике гостиницы. Получается из функции GetHotelsList по номеру комнаты или ФИО.
- GuestLastName – фамилия клиента
- GuestFirstName – имя клиента
- GuestSecondName – отчество клиента
- GuestDateOfBirth – дата рождения
- GuestPhoto – фото в формате Base64
- Room – номер комнаты
- DateTime – дата и время закрытия заказа. Это время используется при проверке проживал ли гость в номере в указанное время
- Sum – сумма заказа
- Client – код клиента. Нужен, если в номере живет несколько человек. Если не указан то будет на числено на того гостя, который заехал первым.
- Currency – валюта заказа
- Service – код услуги для начисления. Код услуги обычно = коду точки продажи. В базе отеля для каждой точки продаж заводится услуга.
- Quantity = количество. Обычно =1.
- ChargeType = тип начисления. Строка. Дополнительный строковый идентификатор. Может быть например, название точки продажи. Необязательный параметр.
- Remarks – примечания – краткое описание заказа. Обычно содержит номер заказа и название точик продажи.
- Details – текстовая копия счета. Используется для того чтобы дать возможность ресепшн поднять копию чека ресторана, например, для того чтобы распечатать гостю. Или включения в итоговый счет деталей.
- Hotel – код отеля.
- ExternalSystemCode внешний код системы. Используется в таблице перекодировки значений справочников. Например “iiko”
- FolioNumber – номер лицевого счета
- Hotel – код отеля
- ExternalSystemCode – код внешней системы
- FolioNumber – номер лицевго счета отеля
- Service – код услуги
- Sum – сумма заказа
- Quantity = количество
- Remarks – примечания с описанием заказа. Номер заказ и название точки продаж.
- Details – текстовая копия счета. Используется для того чтобы дать возможност ьресепшн поднять копию чека ресторана, напрмер для того чтобы распечатать гостю. Или включения в итоговый счет деталей.
- Hotel – код отеля.
- ExternalSystemCode внешний код системы. Используется в таблице перекодировки занчений справочников. Например “iiko”
- Currency – код валюты
Функция получения баланса клиента по идентификатору карты клиента
GetClientCardBalance Используется для получения баланса по карте клиента. На вход принимается номер карты, на выход передаются данные клиента и его текущий баланс.
Параметры:
<m:Card> - передается код карты клиента.
Пример запроса. (ChargeServiceByClientCard.xml)
Пример ответа в случае успеха (без скидки) (GetClientCardBalanceResponse.xml)
Пример карты со скидкой. (GetClientCardBalanceResponse_discount.xml)
Пример ответа в случае если карта не найдена (GetClientCardBalance_UnknownCard_Response.xml)
Возвращаемые значения:
В случае, если карта с запрашиваемым кодом не найдена, то будет возвращен тот же xml, но все поля будут пустые кроме IsBlocked и BlockReason. Значения этих тегов будет: IsBlocked = true, BlockReason = Unknown card!
Пример в файле GetClientCardBalance_UnknownCard_Response.xml
Функция записи заказа на счет гостю по идентификатору карты клиента
ChargeServiceByClientCard
Пример SOAP запроса:
В ответ возвращается xml с тегом return. Если ошибок нет, то он пустой
Если же произошла ошибка, то в теге return будет описание этой ошибки. Что означает что заказ не был записан на счет гостю.
Примеры строк ошибок:
1) «Не найдена карта клиента!» - передан неправильный номер карты
2) «После начисления услуги долг на лицевом счете 151,50р превысит установленную глубину кредита ! Операция прервана» - не достаточно средств на карте – нужно добавить кредитный лимит
3) «Не удалось определить услугу!» - надо настроить 1С:Отель. Указать константу для использования услуг по-умолчанию и задать таблицу переконвертации значений
Примеры:
1) Запись заказа на карту (ChargeServiceByClientCard.xml)
2) Ответ (ChargeServiceByClientCardResponse.xml)
3) Ответ с ошибкой (ChargeServiceByClientCardResponse_error.xml)
По номеру комнаты.
Используется, когда в гостинице клиентам не выдают персональные карты или при закрытии заказа рум-сервисом, когда гостя нет рядом и нет карты гостя на руках. В этом случае заказ закрывается на номер комнаты. В конце смены все такие чеки сдаются на ресепшн, где и хранятся до выезда гостя. В случае возражений клиенту предъявляется чек с его подписью.
В номере может проживать несколько человек, поэтому сначала запрашивается кто проживает в номере. Если живет несколько, то нужно дать возможность выбрать одного из гостей.
1) Запрос кто живет. Вызов функции GetHotelGuests
2) (Опционально) По выбранному гостю запрос фото и дополнительных деталей– вызов GetGuestDetails
3) Запись заказа на номер комнаты. Вызов ChargeServiceByRoom – передать номер комнаты и код гостя, полученный в п.1.
GetHotelGuests Функция запроса клиентов по номеру комнаты
Используется для сценария закрытия заказы на номер комнаты, без предъявления карты гостя. На вход передается номер комнаты. На выходе список гостей с информацией по каждому гостю.
Параметры:
Пример запроса. (GetHotelGuests.xml)
Пример ответа в случае успеха 1 гость в номере (GetHotelGuestsResponse_1guest.xml)
Пример ответа – 2 гостя в номере (GetHotelGuestsResponse_2guests.xml)
Пример ответа в случае если в номере никто не проживает (GetHotelGuestsResponse_no_guests.xml)
Возвращемые занчения:
Список GuestItems. Для каждого гостя в номере структура:
GetGuestDetails Функция запроса клиентов по номеру комнаты
Используется для получения дополнительной информации по гостю. На вход передается код гостя На выходе данные гостя – ФИО, телефон, адрес, фото
Параметры запроса:
Пример запроса (GetGuestDetails.xml)
Пример ответа (GetGuestDetailsResponse_photo.xml) (GetGuestDetailsResponse.xml)
Пример ошибки, если гость не найден. (GetGuestDetailsResponse_not_found.xml)
Возвращаемые значения:
ChargeServiceByRoom Функция записи заказа на номер комнаты
Используется для передачи заказа на номер комнаты. Отель сам определить правильный счет для начисления по номеру комнаты и фамилии гостя. Фамилия гостя нужна для случаев, когда в одном номере живут 2 человека с раздельными счетами, например, командировочные. На выход – сообщение об ошибке.
Примеры:
Начисление на 1 гостя в номере (ChargeServiceByRoom_1guest.xml)
Начисление на номер, когда в номере 2 челоека – указывается код гостя плательщика (ChargeServiceByRoom_2guest.xml)
Ответ в случае успешного начисления (ChargeServiceByRoomResponse_OK.xml)
Ответ с ошибкой (неверный номер комнаты» (ChargeServiceByRoomResponse_no_room.xml)
По номеру фолио.
Этот вариант используется
1) для постоянных гостей, которым открыт мастер-счет где внесена предоплата или открыт существенный лимит. Такие счета обычно закрываются раз в сезон.
2) для проведения мероприятий. В базе отеля мероприятие оформляется через «Бронь ресурса» (например конференц-зала). На данное бронирование открывается лицевой счет куда и начисляются все услуги по мере проведения мероприятия.
Порядок использования.
1) Запрос лицевого счета. Вызов GetFolioDescription.
Проверяется открыт ли счет. Если открыт проверяется баланс и лимит счета.
2) Закрытие заказ на номер счета. Вызов ChargeServiceByFolio.
GetFolioDescription Функция запроса клиентов по номеру комнаты
Используется для получения информации по лицевому счету. В случае, когда происходит закрытие заказ на фолио. Используется в сценарии закрытия заказа на счет гостя, который не прожимает в отеле. Это может быть постоянный мастер-счет ВИП-клиента, или специальный счет мероприятия, банкета, или специальный счет организации. В общем любые сценарии, при которых нужно вести взаиморасчеты, но при этом клиент не проживает в отеле. На вход передается номер лицевого счета. На выходе данные по фолио – контрагент, клиент, лимит и баланс.
Параметры запроса:
ChargeServiceByFolio Функция записи заказа на номер фолио
Используется для сценариев закрытия заказов на фолио, клиента, которые не проживают в отеле. На вход номер фолио.
Параметры запроса: