Интеграция ShelterCloud и 1С:Бухгалтерия

Продукт: Shelter Cloud | Уровень: Пользовательский

Описание механизма обмена данными между системой управления гостиницами ShelterCloud (FrontDesk24 PMS) и 1С:Бухгалтерия.

Оглавление

  1. Общая информация
  2. Установка и запуск
  3. Принципы работы
  4. Подробное описание API-эндпоинтов
  5. Маппинг полей API → документы 1С
  6. Настраиваемые параметры
  7. Интерфейс пользователя
  8. Технические особенности
  9. Серверная часть (hmsExport)
  10. Импорт платежей из 1С в ShelterCloud
  11. Настройка комиссии в договорах
  12. Полный цикл данных: Яндекс Путешествия → БД → 1С
  13. Postman-коллекция для тестирования API
  14. Версия и поддержка

Общая информация

Назначение: Документ описывает полный механизм обмена данными между системой управления гостиницами ShelterCloud (FrontDesk24 PMS) и 1С:Бухгалтерия.

Компоненты интеграции:

  • ShelterCloud_Фреш (версия 2.33) — внешняя обработка для 1С:Бухгалтерия
  • hmsExport — серверный API для выгрузки данных
  • hmsYandexTravel — интеграция с каналом Яндекс Путешествия (для примера работы с агентами)
  • SQL-процедуры — хранимые процедуры для формирования данных экспорта

Конфигурация 1С: 1С:Бухгалтерия предприятия (Фреш/облачная версия)


Принципы работы

1. Архитектура интеграции

Обработка работает по принципу pull-интеграции:

  • Пользователь в 1С инициирует загрузку данных из ShelterCloud
  • Данные загружаются через HTTP API с сервера cloud.shelter.ru (или pms.frontdesk24.ru)
  • На основе загруженных данных создаются документы в 1С

2. API взаимодействие

Обработка использует API-эндпоинты ShelterCloud для загрузки различных типов данных: бронирования, платежи, дополнительные услуги. Полный список эндпоинтов и соответствующих SQL-процедур приведён в разделе Серверная часть (hmsExport).

Выбор API-эндпоинта в обработке

Реализация проживания

Используется: SellingByDateUntil.aspx (всегда)

Выборка бронирований происходит по дате выезда:

  • В период попадают брони, где D_Until (дата выезда) находится между dateFrom и dateTo
  • Дополнительное условие на сервере: статус брони N_InUseStatusId = 5 ("Гости выехали")

Почему именно по дате выезда:

  • Документ реализации создаётся по факту оказания услуги проживания
  • Услуга считается оказанной в момент выезда гостя
  • Это соответствует требованиям бухгалтерского учёта

Счета на оплату

Используется: SellingByDate.aspx

Выборка бронирований происходит по дате создания брони:

  • В период попадают брони, где D_Date (дата создания) находится между dateFrom и dateTo
  • Статус выезда не проверяется — счёт можно выставить до заезда

Почему по дате создания:

  • Счёт выставляется заранее, до фактического проживания
  • Дата создания брони — это момент, когда известны условия для выставления счёта

Дополнительные услуги

Выбор зависит от флажка "Выгружать на дату выезда" в интерфейсе обработки:

Режим Эндпоинт Фильтр на сервере
Флажок выключен ExtraServices.aspx По дате оказания услуги (D_Execute)
Флажок включен ExtraServicesByDateUntil.aspx По дате выезда брони (D_Until)

Особенности:

  • Если заполнена настройка "Группа дополнительных услуг" — флажок автоматически включается и становится недоступным для изменения
  • Подсказка в интерфейсе: "В период попадают брони на дату выезда брони, при условии статус брони «Гости выехали», если не выбрано — в период попадают брони по дате предоставления доп.услуг. Если нет даты предоставления — по дате начисления"

Когда использовать какой режим:

  • По дате оказания — когда нужно выгрузить услуги за конкретный день (например, питание за сегодня)
  • По дате выезда — когда нужно выгрузить все услуги по завершённым бронированиям (для сверки с реализацией)

Метод передачи данных: HTTP POST с параметрами:

  • token - токен авторизации отеля
  • dateFrom - дата начала периода
  • dateTo - дата окончания периода

Формат ответа: XML (ArrayOfElement)

Защита соединения: SSL (ЗащищенноеСоединениеOpenSSL)


Подробное описание API-эндпоинтов

SellingByDateUntil.aspx — Реализация по дате выезда

SQL-процедура: dbo.ExportReservationsByDateUntil

Логика выборки:

Выбираются бронирования указанного отеля, которые не аннулированы, имеют статус «Гости выехали» и дата выезда попадает в запрошенный период.

Возвращаемые поля:

Поле Тип Описание
N_ID int ID бронирования
N_OrderID int ID заявки (группы бронирований)
D_FROM string Дата/время заезда (YYYYMMDDHHMMSS)
D_UNTIL string Дата/время выезда (YYYYMMDDHHMMSS)
N_Price decimal Стоимость проживания
N_PriceWithoutDiscount decimal Стоимость без скидки (до комиссии)
N_Commission decimal Сумма комиссии агента
N_Discount int Процент скидки
N_GuestsCount int Количество гостей
N_MainPlaces int Основных мест
N_Number int Номер бронирования
N_RoomTypeId int ID типа номера
V_RoomTypeName string Название типа номера (с корпусом)
N_ContragentId int ID контрагента (агента)
V_ContragentName string Краткое наименование контрагента
V_FullContragentName string Полное наименование контрагента
V_ContragentINN string ИНН контрагента
V_ContragentKPP string КПП контрагента
N_OurFirmId int ID нашей организации
V_OurFirmName string Наименование нашей организации
V_OurFirmINN string ИНН нашей организации
V_OurFirmKpp string КПП нашей организации
N_ContractId int ID договора
V_ContractName string Наименование договора
V_ContractNumber string Номер договора
D_ContractDate string Дата подписания договора
D_ContractUntil string Дата окончания договора
V_Guest string ФИО главного гостя
N_BreakfastCount int Количество завтраков
N_DinnerCount int Количество обедов
N_SupperCount int Количество ужинов
B_Beznal bit Признак безналичной оплаты (0/1)
N_DocumentNumber int Номер акта выполненных работ (если есть)

Особенности:

  • Поля питания (N_BreakfastCount, N_DinnerCount, N_SupperCount) рассчитываются на основе пансиона и периода проживания
  • Исключаются брони с оплатой через ОТА (Booking, Expedia, Airbnb) для некоторых отелей

Соотношение N_Price, N_PriceWithoutDiscount и N_Commission:

Полная стоимость до скидки (N_PriceWithoutDiscount) — это сумма, которую платит гость. Она делится на две части: доход отеля и комиссия агента. Комиссия рассчитывается как процент (N_Discount) от полной стоимости.

Логика поля N_Price:

Если комиссия равна нулю, берётся цена из бронирования. Если комиссия есть — берётся полная стоимость до скидки.

Вывод: При наличии комиссии N_Price = N_PriceWithoutDiscount (полная стоимость). N_Price уже ВКЛЮЧАЕТ комиссию, т.е. N_Commission — это часть N_Price, которую получит агент.

Формулы:

  • Гость платит: N_Price (= N_PriceWithoutDiscount при комиссии)
  • Агент получает: N_Commission
  • Отель получает: N_Price - N_Commission

SellingByDate.aspx — Бронирования по дате создания

SQL-процедура: dbo.ExportReservationsByDate

Логика выборки:

Выбираются не аннулированные бронирования указанного отеля, дата создания которых попадает в запрошенный период.

Возвращаемые поля: Аналогично SellingByDateUntil, но без полей питания и с дополнительными:

Поле Тип Описание
D_Date date Дата создания бронирования
V_RoomNumber string Номер комнаты
N_PansionId int ID пансиона (типа питания)
V_PansionName string Название пансиона
V_Status string Статус бронирования
D_UpdateDate string Дата последнего обновления
N_DocumentNumber int Номер счёта (для отеля 6259)

Отличия от SellingByDateUntil:

  • Фильтр по D_Date (дата создания) вместо D_Until (дата выезда)
  • Не проверяется статус выезда — выгружаются все активные брони
  • Используется для выставления счетов до заезда гостя

CashByDate.aspx — Кассовые операции

SQL-процедура: dbo.ExportCashByDate

Логика выборки:

Выбираются не удалённые платежи (не начисления) указанного отеля за наличные или по карте, дата которых попадает в запрошенный период. Исключаются депозиты и нулевые суммы.

Возвращаемые поля:

Поле Тип Описание
N_ID int ID платежа
D_Date string Дата/время платежа (YYYYMMDDHHMMSS)
N_Sum decimal Сумма платежа (отрицательная = возврат)
V_Comment string Комментарий к платежу
V_InvoiceNumber string Номер счёта-фактуры
V_CheckNo string Номер чека ККМ
V_PrintedFrom string ID кассы, с которой пробит чек
N_ReservationId int ID связанного бронирования
N_PaymentTypeId int ID типа платежа
V_PaymentTypeName string Название типа платежа
N_PaymentTypeKind int Вид платежа: 1=наличные, 2=карта, 0=безнал
V_PaymentTypeDescription string Описание типа платежа
B_ForReservation bit Признак оплаты за проживание (0/1)
B_Beznal bit Признак безналичной оплаты (0/1)
N_NDS int Ставка НДС (NULL, 0, 10, 20)
V_ServiceName string Наименование услуги
N_OrderId int ID заявки (минимальный ID брони в группе)
N_UserID int ID пользователя, создавшего платёж
V_UserFullname string ФИО пользователя
V_UserINN string ИНН пользователя (для самозанятых)
+ поля контрагента, организации, договора, типа номера, гостя

Логика определения НДС (приоритет):

  1. НДС из услуги начисления (ExtraServices.N_NDS) через PaymentEntries
  2. НДС из настроек кассы (KKMChannels.N_NDS)
  3. НДС по умолчанию из настроек отеля (Default_NDS)

Логика определения наименования услуги:

  1. Из услуги связанного начисления (ExtraServices.V_Name)
  2. Из комментария начисления (Cash.V_Comment через N_AccrualCashId)
  3. Из комментария платежа (Cash.V_Comment)

Особенности:

  • Платежи с несколькими начислениями с разным НДС выводятся несколькими строками
  • Исключаются специальные платежи (V_Name LIKE 'Спец%')
  • Исключаются безналичные платежи физ.лиц (Безнал. Физ. лица)

ExtraServices.aspx — Доп. услуги по дате оказания

SQL-процедура: dbo.ExportExtraServicesByDateExecute

Логика выборки:

Выбираются не удалённые начисления (не оплата за проживание) указанного отеля, дата оказания услуги которых (или дата начисления, если дата оказания не указана) попадает в запрошенный период.

Возвращаемые поля:

Поле Тип Описание
N_ID int ID начисления
N_ReservationId int ID бронирования
D_Execute string Дата оказания услуги (YYYYMMDDHHMMSS)
D_Date date Дата начисления
N_Sum decimal Сумма услуги
N_Count decimal Количество
N_ExtraServiceId int ID услуги из справочника
V_ServiceName string Наименование услуги (Группа/Услуга)
V_ServiceGroupName string Название группы услуг
V_Comment string Комментарий к начислению
B_IsGood bit Признак товара (1) или услуги (0)
N_NDS int Ставка НДС из справочника услуг
V_Unit string Единица измерения (из справочника товаров)
V_ExCode string Код для экспорта (для отеля Лада Холидей)
D_FROM / D_UNTIL string Даты бронирования
V_RoomTypeName string Тип номера
N_Number int Номер бронирования
V_Guest string ФИО гостя (приоритет — связанный с начислением)
+ поля контрагента, организации, договора (если B_ContragentIsPayer = 1)

Особенности:

  • Дата оказания D_Execute может быть пустой — тогда используется дата начисления D_Date
  • Наименование услуги формируется как "Группа/Услуга" (если есть группа)
  • Исключаются начисления, оплаченные спец. платежами
  • Для отеля "Касимовские зори" исключается группа "Питание"

ExtraServicesByDateUntil.aspx — Доп. услуги по дате выезда

SQL-процедура: dbo.ExportExtraServicesByDateUntil

Логика выборки:

Выбираются не удалённые начисления (не оплата за проживание) указанного отеля, где дата выезда связанного бронирования попадает в запрошенный период.

Возвращаемые поля: Идентичны ExtraServices.aspx.

Отличия от ExtraServices.aspx:

  • Фильтр по дате выезда бронирования (Reservations.D_Until) вместо даты оказания услуги
  • Используется для синхронизации с реализацией проживания (обе выгрузки по дате выезда)
  • Позволяет выгрузить ВСЕ допуслуги завершённого бронирования одним запросом

Сравнительная таблица эндпоинтов

Эндпоинт Фильтр по дате Статус брони Основное применение
SellingByDateUntil.aspx Дата выезда (D_Until) Гости выехали Реализация проживания
SellingByDate.aspx Дата создания (D_Date) Любой активный Выставление счетов
CashByDate.aspx Дата платежа (D_Date) — Кассовые документы
ExtraServices.aspx Дата оказания (D_Execute) — Ежедневные допуслуги
ExtraServicesByDateUntil.aspx Дата выезда (D_Until) — Допуслуги к реализации

Маппинг полей API → документы 1С

Реализация проживания (SellingByDateUntil.aspx → Реализация товаров и услуг)

Поле API → Реквизит документа 1С Формула/примечание
N_Price → Товары.Сумма Полная стоимость проживания
D_FROM, D_UNTIL → Количество (ночей) Количество = (D_UNTIL - D_FROM) в днях
— → Товары.Цена Цена = N_Price / Количество ночей
V_OurFirmINN → Организация Поиск по ИНН
V_ContragentINN → Контрагент Поиск по ИНН или создание нового
V_ContractName → ДоговорКонтрагента Поиск по наименованию
V_RoomTypeName → Товары.Номенклатура Сопоставление с номенклатурой 1С
N_NDS (из настроек) → Товары.СтавкаНДС Из настроек обработки
— → Товары.СуммаНДС РассчитатьСуммуНДС(Сумма, СтавкаНДС)

Если включена загрузка питания:

Поле API → Реквизит документа 1С Формула/примечание
N_BreakfastCount → Строка "Завтрак".Количество Количество завтраков
N_DinnerCount → Строка "Обед".Количество Количество обедов
N_SupperCount → Строка "Ужин".Количество Количество ужинов
Цена из настроек → Товары.Цена (питание) Из настроек обработки
— → Товары.Сумма (питание) Цена × Количество
— → Товары.Сумма (проживание) N_Price - Σ(Стоимость питания)

Если есть комиссия агента (→ Отчёт комиссионера о продажах):

При наличии комиссии (N_Commission > 0) вместо документа "Реализация товаров и услуг" создаётся документ "Отчёт комиссионера о продажах".

Поле API → Реквизит документа 1С Формула/примечание
N_Price → Услуги.Сумма Полная стоимость для покупателя
D_FROM, D_UNTIL → Услуги.Количество Количество ночей
— → Услуги.Цена N_Price / Количество ночей
N_Commission → Услуги.СуммаВознаграждения Сумма комиссии агента
— → Услуги.СуммаНДСВознаграждения НДС от комиссии (по ставке из настроек)
V_ContragentINN → Контрагент Агент (комиссионер)
V_Guest → Покупатель (физлицо) Конечный покупатель
V_OurFirmINN → Организация Комитент (отель)

Пример для брони: 10 000 ₽, комиссия 10%, 2 ночи:

В документе «Отчёт комиссионера о продажах» создаётся одна строка: Номенклатура = «Проживание», Количество = 2 ночи, Цена = 5 000 ₽, Сумма = 10 000 ₽, Сумма вознаграждения = 1 000 ₽ (10%).

Показатель Сумма
Сумма реализации (что заплатил гость) 10 000 ₽
Вознаграждение агента (комиссия) 1 000 ₽
Задолженность агента перед отелем 9 000 ₽

Проводки (упрощённо):

  • Дт 76.09 (Агент) Кт 90.01 (Выручка) — 10 000 ₽ (реализация через агента)
  • Дт 44 (Расходы) Кт 76.09 (Агент) — 1 000 ₽ (комиссия агента)
  • Итого к получению от агента: 9 000 ₽

Скидка от канала (N_ChannelFee, N_ChannelDiscount)

При работе с каналами продаж (ОТА, агенты) возможна ситуация, когда агент предоставляет скидку гостю из своей комиссии.

Новые поля в таблице Reservations:

  • N_ChannelFee — базовая комиссия канала (до скидки)
  • N_ChannelDiscount — скидка, которую канал предоставил гостю из своей комиссии

Пример: базовая цена 10 000 ₽, комиссия 10%, скидка от агента 300 ₽:

Распределение средств:

  • Базовая цена (N_PriceWithoutDiscount): 10 000 ₽
  • Базовая комиссия канала (N_ChannelFee): 1 000 ₽ (10%)
  • Скидка от канала гостю (N_ChannelDiscount): 300 ₽

Расчёт сумм:

  • Гость платит (N_Price): 9 700 ₽ = 10 000 − 300
  • Агент получает (N_Commission): 700 ₽ = 1 000 − 300
  • Отель получает: 9 000 ₽ = 9 700 − 700

Проверка: отель + агент = 9 000 + 700 = 9 700 ₽ (то, что заплатил гость).

Рекомендуемые значения полей API:

Поле Значение Формула / Описание
N_PriceWithoutDiscount 10 000 ₽ Базовая цена (до скидки канала)
N_ChannelFee 1 000 ₽ Базовая комиссия канала
N_ChannelDiscount 300 ₽ Скидка от канала гостю
N_Price 9 700 ₽ N_PriceWithoutDiscount - N_ChannelDiscount
N_Commission 700 ₽ N_ChannelFee - N_ChannelDiscount

Документ "Отчёт комиссионера о продажах" в 1С:

Реквизит Значение Описание
Услуги.Сумма 9 700 ₽ То, что заплатил гость (N_Price)
Услуги.СуммаВознаграждения 700 ₽ Фактическая комиссия агента (N_Commission)
Задолженность агента 9 000 ₽ Сумма - СуммаВознаграждения

Важно: При такой схеме:

  • Отель получает ту же сумму (9 000 ₽), что и без скидки
  • Скидка финансируется агентом из его комиссии
  • В документе 1С отражается фактическая сумма реализации и фактическая комиссия

Кассовые документы (CashByDate.aspx → ПКО / Оплата картой / РКО)

Определение типа документа:

Для наличных платежей (N_PaymentTypeKind = 1): положительная сумма → ПКО (приходный кассовый ордер), отрицательная → РКО (расходный кассовый ордер). Для оплаты картой (N_PaymentTypeKind = 2) создаётся документ «Оплата платёжной картой».

Поле API → Реквизит документа 1С Формула/примечание
N_Sum → СуммаДокумента Сумма платежа (по модулю для РКО)
N_Sum → РасшифровкаПлатежа.СуммаПлатежа Сумма в табличной части
N_Sum → РасшифровкаПлатежа.СуммаВзаиморасчетов = СуммаПлатежа
D_Date → Дата Дата документа
V_OurFirmINN → Организация Поиск по ИНН
V_ContragentINN → Контрагент Поиск по ИНН (если B_ContragentIsPayer=1)
V_Guest → Контрагент Физлицо (если нет контрагента)
N_NDS → РасшифровкаПлатежа.СтавкаНДС Ставка НДС из API
— → РасшифровкаПлатежа.СуммаНДС РассчитатьСуммуНДС(СуммаПлатежа, СтавкаНДС)
V_CheckNo → Комментарий/доп.реквизит Номер чека ККМ

Дополнительные услуги (ExtraServices.aspx → Реализация товаров и услуг)

Поле API → Реквизит документа 1С Формула/примечание
N_Sum → Товары.Сумма Сумма услуги
N_Count → Товары.Количество Количество
— → Товары.Цена Цена = N_Sum / N_Count
D_Execute → Дата Дата документа (дата оказания услуги)
V_ServiceName → Товары.Номенклатура Сопоставление с номенклатурой 1С
B_IsGood → Товары.Номенклатура.ВидНоменклатуры 1=Товар, 0=Услуга
N_NDS → Товары.СтавкаНДС Ставка НДС из справочника услуг
— → Товары.СуммаНДС РассчитатьСуммуНДС(Сумма, СтавкаНДС)
V_Unit → Товары.ЕдиницаИзмерения Сопоставление единицы измерения
V_OurFirmINN → Организация Поиск по ИНН
V_ContragentINN → Контрагент Поиск по ИНН (если B_ContragentIsPayer=1)
V_Guest → Контрагент Физлицо (если нет контрагента)

Счета (SellingByDate.aspx → Счёт на оплату покупателю)

Поле API → Реквизит документа 1С Формула/примечание
N_Price → Товары.Сумма Стоимость = Цена (количество = 1)
N_Price → Товары.Цена = N_Price
1 → Товары.Количество Всегда = 1
D_Date → Дата Дата счёта = дата создания брони
V_OurFirmINN → Организация Поиск по ИНН
V_ContragentINN → Контрагент Поиск по ИНН
V_ContractName → ДоговорКонтрагента Поиск по наименованию
V_RoomTypeName → Товары.Номенклатура Услуга проживания
N_DocumentNumber → Номер Номер счёта (для отеля 6259)

Сводная таблица: поля с суммами

Тип данных Поле API суммы Поле API кол-ва Расчёт цены в 1С
Реализация проживания N_Price Ночи (D_UNTIL-D_FROM) Цена = N_Price / Ночей
Реализация + питание N_Price Ночи Цена = (N_Price - СтоимостьПитания) / Ночей
Отчёт комиссионера N_Commission — Сумма комиссии напрямую
Кассовые документы N_Sum — Сумма напрямую
Допуслуги N_Sum N_Count Цена = N_Sum / N_Count
Счета N_Price 1 Цена = N_Price

Настраиваемые параметры

Основные настройки

  • Токен отеля - ключ авторизации в ShelterCloud
  • Организация по умолчанию - основная организация для документов
  • Контрагент "Частное лицо" - для гостей без реквизитов
  • Ответственный - пользователь-автор документов

Настройки реализации

  • Услуга проживания по умолчанию - номенклатура для услуг проживания
  • Основной договор - договор по умолчанию
  • Склад - склад для товарных операций
  • Тип цен продажи - для ценообразования

Настройки кассы

  • Эквайер - контрагент-эквайер для оплат картой
  • Договор эквайринга - договор с эквайером
  • Счет кассы ПКО - касса для приходных ордеров

Настройки питания

  • Загружать питание - включить/выключить загрузку питания
  • Загружать питание в агентские услуги - для агентской схемы
  • Номенклатура завтрак/обед/ужин - отдельная номенклатура для каждого приёма пищи
  • Агент по питанию - контрагент-поставщик питания
  • Договор по питанию - агентский договор на питание

Настройки НДС

  • Ставка НДС - ставка по умолчанию (по умолчанию "Без НДС")
  • НДС комиссии - ставка НДС для комиссионных услуг

Специальные настройки

  • Группа дополнительных услуг - группа допуслуг ShelterCloud, стоимость которых включается в стоимость проживания и не выгружается отдельно

Интерфейс пользователя

Вкладки формы

  1. Реализация проживания - таблица загруженных бронирований с возможностью выбора для создания документов
  2. Касса - платежи для создания кассовых документов
  3. Дополнительные услуги - услуги для создания реализаций
  4. Счета - счета для создания в 1С

Основные действия

  • Скачать из Shelter Cloud - загрузка данных за выбранный период
  • Выбрать все / Снять все - массовый выбор строк
  • Создать/обновить документы - создание документов по выбранным строкам
  • Сохранить сопоставления - сохранение ручных сопоставлений

Технические особенности

Хранение настроек

Настройки сохраняются в ХранилищеНастроекДанныхФорм с ключами:

  • FDТокен - токен авторизации
  • ОрганизацияПоУмолчанию, УслугаПроживаниеПоУмолчанию, КонтрагентЧастноеЛицо и др.

Сопоставления

Сопоставления (маппинг) данных ShelterCloud с объектами 1С сохраняются в таблице Объект.ТаблицаДокументов и используются для автоматического заполнения при повторных загрузках.

Обработка ошибок

  • Проверка заполненности токена перед загрузкой
  • Сообщения пользователю о результатах операций
  • Возможность повторной загрузки и обновления документов

Установка и запуск

Требования

  • 1С:Бухгалтерия предприятия (Фреш/облачная версия)
  • Токен экспорта — получается в ShelterCloud (см. ниже)
  • Доступ к интернету для подключения к API ShelterCloud

Получение токена экспорта в ShelterCloud

  1. Войдите в ShelterCloud (https://pms.frontdesk24.ru/shelter-cloud/)
  2. Перейдите в раздел Токены: https://pms.frontdesk24.ru/shelter-cloud/#/tokens
  3. Нажмите кнопку "Добавить токен"
  4. В поле "Тип" выберите или введите: ExportToken
  5. Поле "Токен" можно оставить пустым — система сгенерирует автоматически
  6. Нажмите "Сохранить"
  7. Скопируйте созданный токен (нажмите на него в таблице)

Примечание: Токен привязан к конкретному отелю. Для каждого отеля нужен свой токен типа ExportToken.

Установка обработки в 1С

  1. Скачайте файл обработки ShelterCloud_Фреш_2.33.epf
  2. Откройте 1С:Бухгалтерия
  3. Перейдите в раздел Администрирование → Печатные формы, отчёты и обработки
  4. Откройте "Дополнительные отчёты и обработки"
  5. Нажмите "Создать" и выберите файл ShelterCloud_Фреш_2.33.epf
  6. В карточке обработки:
    • Укажите наименование (например, "Загрузка из ShelterCloud")
    • Установите флажок "Использовать"
    • При необходимости настройте доступ для пользователей
  7. Нажмите "Записать и закрыть"

После добавления обработка будет доступна через меню Администрирование → Дополнительные отчёты и обработки.

Первоначальная настройка

При первом запуске обработки необходимо заполнить:

  1. Токен отеля — вставьте токен, полученный в ShelterCloud
  2. Организация по умолчанию — выберите вашу организацию
  3. Контрагент "Частное лицо" — укажите контрагента для физических лиц
  4. Услуга проживания — выберите номенклатуру для услуг проживания

Запуск обмена

  1. Откройте обработку в 1С
  2. Выберите период для загрузки данных
  3. Нажмите "Скачать из Shelter Cloud"
  4. После загрузки данных отметьте нужные строки
  5. Нажмите "Создать/обновить документы"

Серверная часть

Серверная часть интеграции (hmsExport) постоянно развёрнута на сервере ShelterCloud и не требует установки со стороны пользователя.


Серверная часть (hmsExport)

Архитектура сервиса

Серверная часть представляет собой ASP.NET Web Application (hmsExport), который:

  • Принимает HTTP-запросы от обработки 1С
  • Авторизует запросы по токену из таблицы ApplicationTokens
  • Вызывает хранимые SQL-процедуры
  • Возвращает результат в формате XML

Технологии: ASP.NET, C#, MS SQL Server, NLog (логирование)

Соответствие API-эндпоинтов и SQL-процедур

API-эндпоинт Хранимая процедура Назначение
SellingByDate.aspx dbo.ExportReservationsByDate Реализация по дате создания брони
SellingByDateUntil.aspx dbo.ExportReservationsByDateUntil Реализация по дате выезда
CashByDate.aspx dbo.ExportCashByDate Кассовые операции (платежи)
ExtraServices.aspx dbo.ExportExtraServicesByDateExecute Доп. услуги по дате оказания
ExtraServicesByDateUntil.aspx dbo.ExportExtraServicesByDateUntil Доп. услуги по дате выезда
SellingServicesByDate.aspx dbo.ExportReservationServicesByDateZv Услуги проживания по дате
SellingServicesByDateUntil.aspx dbo.ExportReservationServicesByDateUntilZv Услуги проживания по дате выезда
SellingGuestsByDate.aspx dbo.ExportReservationGuestsByDate Данные гостей по бронированиям
SellingTasksByDate.aspx dbo.ExportReservationsTasksByDate Задачи по бронированиям
Agents.aspx dbo.ExportAgents Справочник агентов

Авторизация запросов

Токен авторизации проверяется в таблице ApplicationTokens. Система ищет запись с именем «ExportToken» и переданным значением токена. Если найдено — возвращается ID отеля, если токен не найден — возвращается ErrorCode = 1.


Структура данных в SQL-процедурах

Подробное описание возвращаемых полей приведено в разделе Подробное описание API-эндпоинтов. Здесь описаны таблицы БД и логика расчётов.

Используемые таблицы БД

Процедура Основные таблицы
ExportReservationsByDate[Until] Reservations, RoomTypes, Contragents, Contracts, Clients
ExportCashByDate Cash, PaymentEntries, SimpleReferences, ExtraServices, KKMChannels
ExportExtraServicesByDateExecute Cash, ExtraServices, ExtraServicesGroups, InventoryGoods

Расчёт комиссии

Комиссия рассчитывается как произведение цены без скидки (N_PriceWithoutDiscount) на процент комиссии, делённое на 100.

Приоритет определения процента комиссии:

  1. Из поля брони N_Discount, если больше нуля
  2. Из договора Contracts.N_Discount, если есть договор
  3. Иначе равен нулю

Цена без скидки вычисляется функцией dbo.GetPriceWithoutDiscount().

Расчёт количества питания

Подсчёт выполняется из таблицы BoardingMessings на основе пансиона гостя, периода проживания и времени приёма пищи.


Особые условия для отелей

В SQL-процедурах есть специфичные условия для отдельных отелей:

Hotel ID Название Особенности
1118 Крымтур Отдельная логика по корпусам
1713 Касимовские зори Особый расчёт даты услуги, исключение питания
5256 Арт-Гранд Виктория Отдельная процедура для кассы
5504 — Исключение 3-го этажа
5872 Лада Холидей Экспорт по дням, особый код услуг
6259 — Автонумерация документов (Счёт, Акт)
6478 Гостиница Звёздная Только безналичные платежи

Формат дат в API

Все даты возвращаются в формате YYYYMMDDHHMMSS (без разделителей). Например, дата 2026-02-02T14:30:00 преобразуется в строку 20260202143000.


Импорт платежей из 1С в ShelterCloud

Назначение и принцип работы

Помимо экспорта данных из ShelterCloud в 1С существует обратный механизм — импорт платежей из 1С в ShelterCloud. Это позволяет автоматически создавать платежи в системе управления отелем на основе банковских выписок, обработанных в 1С.

Направление данных: 1С:Бухгалтерия → ShelterCloud (обратное направление)

SQL-процедура: dbo.Import1CPayment

Таблица логов: Import1CPayment_Log — все входящие запросы логируются для аудита

Авторизация: используется тот же токен типа ExportToken

Параметры запроса

Параметр Тип Описание
id VARCHAR(200) Идентификатор платежа из 1С
transactionDate DATE Дата платежа
payerInn VARCHAR(20) ИНН плательщика (контрагента)
payerName VARCHAR(800) Наименование плательщика
sum DECIMAL(18,2) Сумма платежа
paymentComment VARCHAR(MAX) Комментарий / назначение платежа
reservationNumber VARCHAR(100) Номер бронирования (если известен)
authToken VARCHAR(400) Токен авторизации (ExportToken)
paymentType INT Тип платежа (ID из справочника)

Дополнительные параметры (банковские реквизиты):

  • recepientInn, recepientName, recepientAccount, recepientBank — реквизиты получателя
  • payerAccount, payerBank, payerBankBik — реквизиты плательщика

Алгоритм сопоставления

Процедура использует интеллектуальное сопоставление платежа с бронированием:

1. Если указан номер бронирования (reservationNumber):

  • Платёж создаётся напрямую для указанного бронирования
  • Проверяется только существование брони с таким номером

2. Для юридических лиц (указан ИНН плательщика):

  • Поиск контрагента по ИНН (payerInn)
  • Поиск неоплаченных бронирований этого контрагента
  • Сопоставление по сумме платежа и сумме брони (N_Price)

3. Для физических лиц (ИНН не указан):

  • Поиск по точному совпадению ФИО плательщика с гостем брони
  • Сумма не проверяется — достаточно совпадения ФИО

Результаты сопоставления:

Ситуация Действие
Найдена ровно 1 подходящая бронь Платёж создаётся автоматически
Найдено несколько бронирований Возвращается список для ручного выбора
Бронирования не найдены Возвращается запрос на указание номера брони
Найдена бронь с другой суммой Возвращается запрос на подтверждение или указание номера

Коды возврата

Успешный импорт (ok = 1):

Поле Описание
ok 1 = успех
ReservationNumber Номер бронирования
ReservationDescription Описание (гость, даты)
ReservationPrice Сумма бронирования

Требуется уточнение (ok = 0):

Возвращается список бронирований для ручного выбора с полями: ReservationNumber, ReservationDescription, ReservationPrice.

Ошибки:

  • Неверный токен — токен не найден или неактивен
  • Не найден контрагент по данному recepient_inn — контрагент с указанным ИНН отсутствует
  • Не удалось найти reservation по данному reservation_number — указанный номер брони не существует

Создание платежа

При успешном сопоставлении создаётся запись в таблице Cash:

Поле Значение
N_Type 2 (платёж)
N_Sum Сумма из параметра sum
D_Date Дата из transactionDate или текущая дата
V_Comment Комментарий из paymentComment
N_PaymentTypeId Тип платежа (безналичный по умолчанию)

После создания платежа автоматически вызываются:

  • dbo.SetReservationPayed — обновление статуса оплаты брони
  • dbo.CorrectPaymentEntries — распределение платежа по начислениям

Настройка комиссии в договорах (B_ApplyCommission)

Галочка "Оплата за вычетом комиссии" в Dogovors.aspx

В интерфейсе договоров (hmsStar/Dogovors.aspx) есть флажок "Оплата за вычетом комиссии" (поле B_ApplyCommission в таблице Contracts).

Назначение флага: указывает, что при работе с контрагентом по этому договору цена бронирования должна быть уменьшена на сумму комиссии.

Хранение данных

Таблица Поле Описание
Contracts B_ApplyCommission Флаг "Оплата за вычетом комиссии" (0/1)
Contracts N_Discount Процент комиссии по договору
YandexTravelChannels N_ContragentId Контрагент канала (агент)
YandexTravelChannels N_ContractId Договор канала

Влияние на Яндекс Путешествия

При сохранении бронирования из канала Яндекс Путешествия используется хранимая процедура dbo.UpdateReservationYandexTravel.

⚠️ Важно: В текущей реализации флаг B_ApplyCommission НЕ проверяется при сохранении бронирований из Яндекс Путешествий.

Логика процедуры UpdateReservationYandexTravel:

  1. Получение ID договора из канала по ID канала
  2. Если процент скидки не задан и есть контрагент — берётся процент комиссии (N_Discount) из договора. Важно: проверка флага B_ApplyCommission при этом НЕ выполняется
  3. Если процент скидки задан — рассчитывается сумма скидки как произведение цены на процент, и цена уменьшается на эту сумму

Сравнение с другими интеграциями

В общей процедуре dbo.InsertOrUpdateReservationFromChannel (используется для Expedia, Otello, customChannels) флаг B_ApplyCommission проверяется: процент комиссии берётся из договора только если флаг B_ApplyCommission равен 1.

Результат:

Интеграция Проверка B_ApplyCommission Корректировка цены
Яндекс Путешествия ❌ Не проверяется Всегда применяется при наличии N_Discount
Expedia ✅ Проверяется Не корректируется (цена из канала)
Otello ✅ Проверяется Корректируется если B_ApplyCommission=1
customChannels ✅ Проверяется Зависит от типа канала

Практический вывод

Для бронирований из Яндекс Путешествий:

  1. Если в канале указан контрагент (N_ContragentId) и договор (N_ContractId)
  2. И в договоре указан процент комиссии (N_Discount > 0)
  3. То комиссия всегда применяется к цене бронирования
  4. Независимо от значения флага B_ApplyCommission

Пример: Цена от Яндекса (roomPrice) = 10 000 ₽. Договор: N_Discount = 10%, B_ApplyCommission = 0 (выключено). Ожидаемое поведение: комиссия НЕ применяется. Фактическое поведение: комиссия применяется. Результат в БД: N_Price = 9 000 ₽ (10 000 минус 10%), N_Discount = 10%.

Рекомендации

  1. Если комиссия НЕ должна применяться к бронированиям из Яндекс Путешествий — укажите в договоре N_Discount = 0 или не привязывайте договор к каналу

  2. Если нужна проверка B_ApplyCommission — требуется доработка процедуры UpdateReservationYandexTravel: добавить в условие выборки процента комиссии проверку AND B_ApplyCommission = 1


Полный цикл данных: Яндекс Путешествия → БД → 1С

Схема передачи данных

Схема передачи данных

Ниже приведён детальный пример прохождения данных бронирования через все слои системы.

Пример бронирования

Исходные условия (из agent_comment):

  • Стоимость бронирования: 28 500 ₽
  • Скидка по "Совместной акции": 143 ₽
  • Стоимость с учётом акции: 28 357 ₽
  • Вознаграждение Яндекса: 4 987 ₽
  • Номер: "Семейный 3 комнатный", 3 ночи (17-20 февраля 2026)

1. Данные от Яндекс Путешествий (JSON)

Основные поля запроса:

  • booking_ref: YA-XXXX-XXXX-XXXX:0
  • status: CONFIRMED
  • customer_info: ФИО гостя, email, телефон
  • room_stays: информация о номере (id, даты заезда/выезда, категория номера, тариф, гости)
  • booking_price: total_amount=28357, yandex_fee=4987, total_discount_value=143, payable_online=28357
  • discounts: скидка 143₽ по причине «Совместная акция»

Расшифровка полей booking_price:

Поле Значение Описание
total_amount 28 357 ₽ Сумма, которую платит гость
yandex_fee 4 987 ₽ Комиссия Яндекса (после скидки)
total_discount_value 143 ₽ Скидка по "Совместной акции" из комиссии Яндекса
payable_online 28 357 ₽ Оплата онлайн (через Яндекс)

2. Обработка в модуле интеграции с Яндекс Путешествиями

Модуль обработки бронирований выполняет следующие действия:

  1. Парсинг данных от Яндекса — извлекаются поля из JSON-ответа: сумма оплаты гостя, комиссия Яндекса, скидка

  2. Расчёт полной стоимости — к сумме оплаты гостя прибавляется скидка, чтобы получить базовую цену до скидки:

    • Полная стоимость = 28 357 + 143 = 28 500 ₽
  3. Расчёт процента комиссии — определяется как отношение суммы комиссии и скидки к полной стоимости:

    • Процент комиссии = (4 987 + 143) / 28 500 × 100 = 18%
  4. Формирование данных для сохранения — модуль бизнес-логики формирует данные для передачи в БД:

Параметр Значение Описание
Стоимость номера 28 500 ₽ Полная стоимость до скидки
Процент комиссии 18% Рассчитанный процент
Комиссия канала 4 987 ₽ Фактическая комиссия Яндекса
Скидка от канала 143 ₽ Скидка гостю из комиссии

3. Сохранение в БД (SQL)

Процедура: dbo.UpdateReservationYandexTravel

Входные параметры: roomPrice=28500 (FullAmount), discountPercent=18 (от Яндекса), channelFee=4987, channelDiscount=143.

Расчёт: сумма скидки = roomPrice × discountPercent / 100 = 5 130; цена = roomPrice − сумма скидки = 23 370.

Сохраняются поля: N_Price=23 370 (доход отеля), N_SourcePrice=28 500 (полная стоимость), N_Discount=18%, N_ChannelFee=4 987, N_ChannelDiscount=143.

Результат в таблице Reservations:

Поле Значение Описание
N_Price 23 370 ₽ Доход отеля (полная цена минус вся комиссия)
N_SourcePrice 28 500 ₽ Полная стоимость до скидки
N_Discount 18% Процент комиссии
N_ChannelFee 4 987 ₽ Фактическая комиссия канала
N_ChannelDiscount 143 ₽ Скидка от канала

4. Экспорт в 1С (hmsExport)

Процедура: dbo.ExportReservationsByDateUntil

Расчёт: Данные экспорта формируются на основе полей бронирования. Для корректного отражения в 1С используются фактические суммы: оплата гостя (total_amount) и фактическая комиссия (yandex_fee).

XML-ответ API /export/SellingByDateUntil.aspx:

Возвращаются поля: N_ID=42270583, D_FROM=20260217140000, D_UNTIL=20260220120000, N_Price=28357 (оплата гостя), N_SourcePrice=28500, N_Discount=18, N_Commission=4987 (фактическая комиссия), N_ChannelDiscount=143, V_ContragentName=Яндекс Путешествия, V_Guest=Иван Иванов, V_RoomTypeName=Семейный 3 комнатный.


5. Документы в 1С

Создаётся: "Отчёт комиссионера о продажах"

Реквизит Значение Источник
Контрагент Яндекс Путешествия V_ContragentName
Услуги.Сумма 28 357 ₽ N_Price (оплата гостя)
Услуги.Количество 3 ночи D_UNTIL - D_FROM
Услуги.Цена 9 452,33 ₽ Сумма / Количество
Услуги.СуммаВознаграждения 4 987 ₽ N_Commission (факт. комиссия)
К перечислению комитенту 23 370 ₽ Сумма - Вознаграждение

6. Итоговое распределение средств

Движение денежных средств (бронь YA-XXXX-XXXX-XXXX):

Операция Сумма Примечание
Гость заплатил Яндексу 28 357 ₽ total_amount
Яндекс удерживает комиссию 4 987 ₽ yandex_fee (фактическая комиссия)
Яндекс перечисляет отелю 23 370 ₽ total_amount − yandex_fee

В 1С отражается:

  • Сумма реализации: 28 357 ₽ (оплата гостя = total_amount)
  • Вознаграждение агента: 4 987 ₽ (фактическая комиссия = yandex_fee)
  • К перечислению комитенту: 23 370 ₽ (доход отеля)

Важно: В 1С отражается ФАКТИЧЕСКАЯ комиссия (4 987 ₽), а не базовая (5 130 ₽). Скидка 143 ₽ учтена в уменьшении комиссии агента.


7. Сводная таблица трансформации данных

Этап Поле Значение Формула / Источник
Яндекс API total_amount 28 357 ₽ Оплата гостя
yandex_fee 4 987 ₽ Комиссия Яндекса (фактическая)
total_discount_value 143 ₽ Скидка "Совместная акция"
C# (расчёт) FullAmount 28 500 ₽ total_amount + total_discount_value
YandexFeePercent 18% (yandex_fee + discount) / FullAmount × 100
SQL (INSERT) @roomPrice 28 500 ₽ FullAmount
@discountPercent 18% YandexFeePercent
@price 23 370 ₽ @roomPrice - (@roomPrice × @discountPercent / 100)
Reservations N_Price 23 370 ₽ Доход отеля
N_SourcePrice 28 500 ₽ Полная стоимость
N_Discount 18% Процент комиссии
N_ChannelFee 4 987 ₽ Фактическая комиссия канала
N_ChannelDiscount 143 ₽ Скидка от канала
Экспорт 1С N_Price 28 357 ₽ total_amount (оплата гостя)
N_Commission 4 987 ₽ yandex_fee (фактическая комиссия)
Документ 1С Сумма 28 357 ₽ N_Price (оплата гостя)
СуммаВознаграждения 4 987 ₽ N_Commission (фактическая комиссия)
К перечислению 23 370 ₽ Сумма - СуммаВознаграждения (доход отеля)

8. Отображение в интерфейсе FrontDesk24

Для брони YA-XXXX-XXXX-XXXX в интерфейсе FrontDesk24 будут отображены следующие данные:

Карточка бронирования (MastheadPanel)

Поле Значение Источник данных
Стоимость 23 370 ₽ Reservation.Price (N_Price из БД)
Скидка 18% Reservation.Discount
Источник Яндекс Путешествия (иконка) Reservation.Source
Категория номера Семейный 3 комнатный Reservation.RoomTypeName
Период 17.02.2026 – 20.02.2026 Reservation.From, Reservation.Until
Гостей 3 Reservation.GuestsCount

Фронтенд (MastheadPanel.ts): в редактор цены устанавливается значение price = 23 370.

Бэкенд (Reservation.cs): свойство Price = 23 370 (N_Price), Discount = 18 (N_Discount), вычисляемое свойство DiscountedPrice возвращает Price (цена уже со скидкой).

Список начислений (AccrualsPanel)

После создания брони автоматически создаётся начисление за проживание:

Дата Сумма Комментарий Услуга Оплачено
31.01.2026 23 370 ₽ Оплата проживания Проживание Да ✓

Создание начисления (SQL: dbo.AutoCashReservationPrice): Сумма начисления берётся из N_Price = 23 370 (доход отеля, а не полная цена).

Логика отображения (AccrualsPanel.ts):

  • Цветовая индикация статуса оплаты:
    • accrual-prepayed — предоплата
    • accrual-payed — оплачено полностью ← этот статус для нашей брони
    • accrual-overpayed — переплата
  • Поле "Платит агент" (B_ContragentIsPayer = 1) отмечено для начислений от Яндекс Путешествий

Модель данных (Accrual.cs): Свойства: Sum = 23 370, Payed = 23 370 (из PaymentEntries), IsPaid = true (начисление закрыто платежом, т.к. Payed >= Sum), NotPayed = 0 (Sum − Payed).

Список платежей (PaymentsPanel)

При получении брони с онлайн-оплатой (PayableOnline > 0) платёж создаётся автоматически:

Дата Сумма Тип платежа Комментарий
31.01.2026 28 357 ₽ (настроенный) Предоплата из Яндекс Путешествий

Логика создания платежа (MsSqlContext.cs:BookingSavePayment): Если PayableOnline > 0, создаётся платёж. Сумма платежа берётся из PayableOnline (то, что заплатил гость) = 28 357.

SQL-процедура: dbo.AddOrderPayed

Распределение платежа:

  • Платёж: 28 357 ₽ (PayableOnline)
  • Привязано к начислению: 23 370 ₽ (закрывает «Оплата проживания»)
  • Остаток (переплата): 4 987 ₽ (= yandex_fee, не привязан)

Важно: Платёж записывается на полную сумму оплаты гостя (28 357 ₽), но к начислению привязывается только сумма дохода отеля (23 370 ₽). Разница 4 987 ₽ — это комиссия Яндекса, которую они удержат при перечислении.

Модель данных (Payment.cs): Свойства: Sum = 28 357, PaymentTypeName (из настроек канала), AccrualEntries (связь с начислением на 23 370).

Баланс бронирования

Показатель Значение Формула
К оплате 23 370 ₽ Reservation.ToPay
Оплачено 23 370 ₽ Reservation.Payed
Не оплачено 0 ₽ Reservation.NotPayed
Переплата 4 987 ₽ Платёж - Начисление

Начисление помечается как оплаченное (IsPaid = true) сразу после создания платежа.


Postman-коллекция для тестирования API

Для удобства тестирования и изучения API доступна готовая коллекция Postman:

📦 ShelterCloud_1C_Export_API.postman_collection.json

Что входит в коллекцию

1. Реализация проживания

  • SellingByDateUntil.aspx — по дате выезда (одна дата и период)
  • SellingByDate.aspx — по дате создания (для счетов)

2. Кассовые операции

  • CashByDate.aspx — платежи по дате

3. Дополнительные услуги

  • ExtraServices.aspx — по дате оказания
  • ExtraServicesByDateUntil.aspx — по дате выезда

4. Справочники

  • Agents.aspx — список агентов

5. Примеры с реальными данными

  • Бронь YA-7693-6545-9378:0 из Яндекс Путешествий
  • Полная стоимость: 5700 руб, скидка: 570 руб
  • Гость платит: 5130 руб, комиссия Яндекса: 872.10 руб
  • Доход отеля: 4257.90 руб

Как использовать

  1. Импортируйте коллекцию в Postman (File → Import → выберите JSON-файл)

  2. Настройте переменные:

  3. Выберите запрос из коллекции и нажмите Send

  4. Изучите примеры ответов во вкладке "Examples" каждого запроса

Структура ответов API

Все эндпоинты возвращают данные в формате XML:

<?xml version="1.0" encoding="utf-8"?>
<Answer>
  <Content>
    <ArrayOfContentElement>
      <ContentElement Key="N_ID" Value="123456" />
      <ContentElement Key="N_Price" Value="5700" />
      <ContentElement Key="V_Guest" Value="test shelter" />
      ...
    </ArrayOfContentElement>
  </Content>
  <ErrorCode>0</ErrorCode>
</Answer>

ErrorCode:

  • 0 — успешно
  • 1 — неверный токен
  • 2+ — другие ошибки

Версия и поддержка

Обработка разработана для работы с API FrontDesk24 (ShelterCloud). При изменении API на стороне ShelterCloud может потребоваться обновление обработки.

Документация сгенерирована автоматически на основе анализа кода обработки и серверной части.