Omnis

YCLIENTS

Что это за документ

Этот документ нужен компании, которая уже ведет бизнес в YCLIENTS и хочет подключить филиал к Omnis. После подключения Omnis получает данные из YCLIENTS и использует их для витрины, записи, заказов, складов, остатков и финансового учета.

YCLIENTS остается основным источником данных. Это значит, что сотрудники, услуги, товары, расписание, склады, остатки, записи и финансовые операции управляются в YCLIENTS, а Omnis хранит синхронизированное зеркало.

YCLIENTS как основной источник данных в Omnis
На скриншоте схема подключения и два потока данных: рабочие данные приходят из YCLIENTS в Omnis, а новые заказы из Omnis отправляются обратно в YCLIENTS как записи.

Что появляется в Omnis после подключения

После первичной синхронизации Omnis получает:

  • сотрудников;
  • услуги;
  • товары;
  • склады;
  • актуальные остатки на складах;
  • записи и визиты;
  • клиентов;
  • финансовые операции.

Эти данные используются существующими разделами Omnis. Например, товары и услуги попадают в каталог и клиентскую витрину, клиенты попадают в клиентскую базу, записи отображаются в календаре, а финансовые операции попадают в журнал финансового учета. Финансовые операции YCLIENTS разделяются на доходы и расходы по направлению операции. В журнале Omnis сумма хранится положительной, а доход или расход определяется категорией финансовой операции. Если YCLIENTS не передает отдельную категорию товара или услуги, Omnis помещает импортированную позицию в корневую категорию каталога. Для импортированных услуг Omnis создает группы записи и связывает их с сотрудниками YCLIENTS. Клиентская витрина получает доступные даты напрямую из YCLIENTS и показывает только дни, где YCLIENTS вернул свободное время. Точные временные слоты Omnis запрашивает у YCLIENTS только для выбранного дня, чтобы не делать лишние запросы при открытии оформления заказа. Если YCLIENTS временно недоступен при загрузке расписания, Omnis использует локальное расписание как fallback для витрины. Если YCLIENTS доступен и корректно вернул пустой список дат или времени, Omnis считает это актуальным ответом и не подставляет локальное расписание вместо него. Локальная синхронизация расписания также остается зеркалом для календаря и диагностики. Базовая цена услуги из YCLIENTS записывается в базовую себестоимость товара в Omnis. Для товаров Omnis берет себестоимость YCLIENTS. Витринные цены Omnis формирует собственными правилами ценообразования и не импортирует их напрямую из YCLIENTS. Для товаров с остатками Omnis создает складские записи по фактическому количеству, которое YCLIENTS передает по складам. Такие записи используются как обычные остатки Omnis и обновляются следующей сверкой YCLIENTS.

Заказы, импортированные из записей YCLIENTS, получают источник заказа YCLIENTS. В состав такого заказа попадают услуги и товары из визита YCLIENTS. Если визит в YCLIENTS состоялся и полностью оплачен, Omnis помечает заказ как закрытый и оплаченный. Для импортированных записей и финансовых операций дата создания в Omnis берется из YCLIENTS. Служебные события и связки интеграции при этом показывают время обработки данных в Omnis. Это отличает их от заказов, созданных в Omnis.

Как подключаются филиалы

Подключение выполняется через приложение Omnis в YCLIENTS. В Omnis Manager пользователь видит ссылку на приложение YCLIENTS, открывает его, выбирает филиал и подтверждает подключение. На центральной странице пользователь выбирает свой Omnis-домен, подтверждает выбор, после чего попадает в Omnis Manager на страницу привязки YCLIENTS.

Само сопоставление в connector не означает, что интеграция подключена. Omnis создает подключение только после успешной активации интеграции через YCLIENTS Marketplace API. Если параметры перехода фейковые или активация не подтверждена YCLIENTS, филиал не появится как подключенный.

Одна компания Omnis может быть связана с несколькими филиалами YCLIENTS. Для этого в настройках приложения YCLIENTS нужно включить подключение интеграции в нескольких филиалах. Каждый филиал хранится как отдельное подключение, но данные попадают в одну компанию Omnis и используются общей витриной, календарем, заказами, складами и финансовым учетом. Если интеграцию отключили в Omnis, филиалы получают статус disconnected, но уже загруженные товары, услуги, записи, склады, финансы и связки остаются в Omnis. Чтобы подключить YCLIENTS заново, пользователь снова открывает приложение Omnis в YCLIENTS и проходит marketplace flow; локальной кнопки повторного включения в Omnis нет.

В Omnis состояние подключения видно в разделе:

Система -> Настройки -> YCLIENTS

Страница настройки интеграции YCLIENTS
На скриншоте: страница YCLIENTS в Omnis Manager со статусом филиала, вкладками обзора, связок и событий, а также кнопками обычной и полной синхронизации.

На странице отображаются:

  • статус подключения;
  • список филиалов YCLIENTS;
  • ID приложения YCLIENTS для каждого филиала;
  • время последней синхронизации;
  • состояние синхронизации по доменам;
  • события webhook и ручных запусков;
  • внешние связки между YCLIENTS и Omnis.

Как работает синхронизация

Omnis использует два механизма синхронизации.

Первый механизм - входящие события YCLIENTS. Когда в YCLIENTS меняется запись, товар, сотрудник, складская или финансовая операция, Omnis сохраняет событие и обновляет соответствующую область данных.

Второй механизм - ручная или периодическая сверка. Она нужна как страховка от пропущенных webhook-событий и для первичного переноса данных.

На странице YCLIENTS есть две кнопки запуска ручной сверки. Кнопка Синхронизировать запускает обычную сверку: Omnis использует сохраненные курсоры доменов и запрашивает только новые или измененные данные там, где YCLIENTS поддерживает такой режим. Эта кнопка подходит для регулярного обновления после уже выполненной первичной загрузки. Кнопка Полная синхронизация запускает сверку с начала: Omnis игнорирует сохраненные курсоры и заново проходит все доступные области данных. Она нужна для первичной загрузки, восстановления после пропущенных данных или проверки корректности связок, но может выполняться дольше и делать больше запросов к YCLIENTS.

Расписание синхронизируется фоновой задачей: Omnis загружает дни порциями, делает паузы при лимитах YCLIENTS, обновляет прогресс на странице интеграции и продолжает до завершения. Если синхронизация услуг или сотрудников изменила связки, Omnis возвращает курсор расписания к текущей дате, чтобы не пропустить ближайшие дни. Клиентская база YCLIENTS также загружается постранично. Omnis делает паузы между пачками страниц и сохраняет курсор, если YCLIENTS временно ограничивает частоту запросов.

Каждая внешняя сущность получает связку с локальной сущностью Omnis. Такая связка защищает от дублей при повторной синхронизации.

Что значит YCLIENTS primary

Для импортированных данных YCLIENTS считается главным источником. Если данные отличаются, Omnis принимает версию YCLIENTS.

Практически это означает:

  • услуги, товары, сотрудники, расписание, склады, остатки и финансы лучше редактировать в YCLIENTS;
  • Omnis может показывать эти данные и использовать их в витрине;
  • Omnis не должен перезаписывать бизнес-данные YCLIENTS без явного действия;
  • локальные витринные настройки Omnis можно хранить отдельно, если они не конфликтуют с данными YCLIENTS.

Как работает создание заказа из Omnis

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

Если YCLIENTS подтверждает запись, Omnis сохраняет связку между локальным заказом и внешним. Источник локального заказа при этом не меняется на YCLIENTS, потому что бизнес-инициатором заказа остается Omnis. Комментарий к записи YCLIENTS отправляется обычным текстом с источником заказа, номером заказа и текущим статусом оплаты. Если email клиента в Omnis не указан, Omnis отправляет в YCLIENTS технический email на домене omnis-commerce.ru, но не сохраняет его как контакт клиента. В первой части такого email используется UID клиента Omnis. Если заказ еще не связан с клиентом, Omnis использует технический fallback по номеру или UID заказа.

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

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

Когда заказ, созданный в Omnis, закрывается, Omnis списывает локальные остатки и отправляет в YCLIENTS складскую продажу по тем же товарам и складам. Заказы, импортированные из YCLIENTS, обратно не списываются, чтобы не создать дубль внешней операции. Следующая синхронизация товаров получает из YCLIENTS обновленные фактические остатки и отражает их в Omnis.

Что делать при ошибках

Ошибки синхронизации видны на странице YCLIENTS. Там можно посмотреть последние события и связки, которые ожидают сопоставления. Ошибка отдельной области синхронизации не отключает интеграцию: филиал остается подключенным, а проблема фиксируется в событиях и последней ошибке филиала. Журнал событий можно очистить на вкладке События; это удаляет только записи журнала и не затрагивает подключение, связки или импортированные данные.

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

После исправления данных или подтверждения связки синхронизацию можно запустить вручную.

Для заказов, созданных в Omnis и не принятых YCLIENTS, ошибка хранится в событиях интеграции и в pending-связке заказа. Это нормальный защитный режим: Omnis сохраняет данные клиента, даже если внешний сервис временно недоступен.