Коннектор R-Keeper

R-Keeper — это живая эталонная реализация контракта POS-коннектора Fooodo: единственный коннектор, работающий в продакшене сегодня, и та форма, на которую ориентируется каждый новый коннектор. Сам контракт не зависит от конкретного POS; новые коннекторы разрабатываются под конкретного заказчика и оцениваются по запросу. На этой странице описано, как на самом деле работает цикл R-Keeper: какие данные пересекают границу, в каком направлении и чего ожидать при возникновении проблем. Названия методов, специфичных для POS, приведены для R-Keeper; эквиваленты в других коннекторах соответствуют тем же операциям контракта коннектора. Поставщики POS-систем, оценивающие возможность подключения своей системы, должны начать с требований к интеграции POS — это спецификация уровня оценки, для которой данная страница является живым справочником.

Что Fooodo запрашивает у R-Keeper

Это вызовы только для чтения — Fooodo никогда не изменяет меню, цены, модификаторы или справочные данные R-Keeper.

Что Fooodo записывает в R-Keeper

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

Конфигурация на уровне ресторана

Учётные данные R-Keeper хранятся в конфигурации ресторана. Каждый ресторан в Fooodo содержит:

• URL конечной точки API
• Идентификатор ресторана внутри R-Keeper
• Необязательную конечную точку лояльного ценообразования
• Необязательный код программы карты лояльности
• Необязательный код позиции меню для маршрутизации чаевых

Разные рестораны в одной компании Fooodo могут указывать на разные экземпляры R-Keeper. Именно так сегодня работают сети с несколькими точками.

Расписание синхронизации R-Keeper

Интеграция выполняет опросы и отправку данных по нескольким различным расписаниям. Операторы и инженеры партнёрской поддержки должны знать их, поскольку они определяют, как быстро изменение в бэк-офисе отображается в клиентском приложении — и как быстро заказ из клиентского приложения появляется на терминале.

Записи из Fooodo в R-Keeper не планируются — они отправляются сразу после наступления события (создан заказ, оплачен заказ, отправлено сообщение) и повторяются с задержкой при отказе R-Keeper. Бюджеты повторных попыток описаны в разделе Обработка сбоев ниже.

Лояльное ценообразование на уровне стола

Столы могут подключиться к лояльному ценообразованию двумя способами, и ресторан может использовать оба варианта одновременно:

• Применение карты постфактум. Если стол настроен с кодом карты лояльности на уровне ресторана, Fooodo применяет карту после экспорта заказа — R-Keeper пересчитывает позиции с учётом логики скидки карты, и Fooodo отражает скорректированные итоги для гостя. Заказ экспортируется один раз, а затем обновляется.
• Альтернативные цены через URL. Если стол настроен с URL коннектора лояльного ценообразования, Fooodo запрашивает у R-Keeper меню с ценами лояльности до того, как гость видит цены. Корзина, цены модификаторов, итоги — всё, что видит гость, уже является ценой лояльности. Это путь с меньшей задержкой, и именно его мы применяем при подключении новых сетей.

Независимо от того, какой вариант использует стол, скидки по купонам корректно накладываются поверх: гость с картой лояльности всё равно может использовать купон, и скидка по купону поступает в R-Keeper независимо от пути лояльности. Так было не всегда — в старых сборках купоны были привязаны к постфактумному пути и пропускались на столах с маршрутизацией через URL — поэтому партнёры, переходящие со старого развёртывания, должны убедиться, что их сторона R-Keeper учитывает оба эффекта.

Лояльное ценообразование поступает из R-Keeper. Fooodo не ведёт параллельную таблицу скидок.

Персонал и атрибуция заказов

Fooodo фиксирует, какой официант связан с каждым заказом, чтобы административные отчёты могли разбивать данные об обслуживании и чаевых по сотрудникам. Процесс состоит из двух частей:

• Синхронизация справочника персонала выполняется ежедневно в 08:45 и обновляет список официантов из кадровой системы сети — имена, должности и внешние идентификаторы сотрудников, соответствующие R-Keeper. Официанты не создаются в Fooodo вручную; список в административной панели доступен только для чтения.
• Атрибуция заказа происходит при получении или обновлении заказа из R-Keeper. Ответ R-Keeper о статусе заказа содержит идентификатор назначенного официанта; Fooodo сопоставляет его с синхронизированным справочником персонала и записывает атрибуцию в заказ. Дочерние заказы при разделении счёта наследуют официанта родительского заказа.

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

Обработка сбоев

Интеграция разработана с учётом кратковременной недоступности R-Keeper. На практике встречаются три режима сбоев:

Заблокированные заказы

R-Keeper возвращает специфические коды ошибок (2219 или 13), когда официант открыл заказ на терминале бэк-офиса. Реакция Fooodo:

• Перевести заказ в статус Locked
• Повторять экспорт по расписанию с экспоненциальной задержкой (5 с → 10 с → 20 с → 40 с → 80 с — пять попыток, ~155 секунд суммарно)
• Если все повторные попытки исчерпаны, перевести в статус Error

В штатном режиме блокировки длятся секунды. Устойчивая блокировка обычно означает, что официант ушёл, оставив заказ открытым на терминале; решение — закрыть его непосредственно в R-Keeper.

Повторные попытки отметки об оплате

Когда R-Keeper отклоняет вызов PostPayOrder (чаще всего потому, что заказ заблокирован на терминале), Fooodo повторяет попытку по более медленному расписанию: 60 с → 120 с → 180 с → 240 с → 300 с — пять попыток за ~15 минут. Более медленная периодичность выбрана намеренно: оплаченный заказ находится в процессе сверки, а не блокирует обслуживание, поэтому мы даём R-Keeper время освободиться.

Если все пять попыток исчерпаны, заказ переходит в статус Error. Платёж в Fooodo при этом зафиксирован; R-Keeper требует быстрой ручной сверки со стороны официанта.

Ресторан недоступен

Если R-Keeper недоступен или ресторан перешёл в офлайн, Fooodo автоматически переводит ресторан в режим только для чтения (это фиксирует ежеминутная проверка доступности):

• Клиентское меню по-прежнему загружается из кэша — гости не видят сломанной страницы
• Новые заказы блокируются на этапе оформления с понятным сообщением
• Обновления существующих заказов ставятся в очередь, а не теряются

Как только R-Keeper восстанавливается, операции из очереди выполняются, и ресторан возвращается в нормальный режим — вмешательство оператора не требуется.

Журналирование

Интеграция ведёт структурированные журналы в четырёх разрезах: полный след запросов и ответов, поток только сбоев, поток в разрезе заказа и поток переходов состояний. При обращениях в партнёрскую поддержку журнал запросов — это первое место для поиска: наиболее распространённая причина «заказ не дошёл до кухни» — кратковременный сбой R-Keeper, который не покрыл бюджет повторных попыток, и поток сбоев сразу это показывает.

Режим мока для разработки

Среды разработки могут работать с полностью замоканным трафиком R-Keeper — это удобно для партнёров-интеграторов, которые хотят тестировать клиентское приложение Fooodo без живого экземпляра R-Keeper. Стейджинг повторяет продакшен, обращаясь к тестовой среде R-Keeper; продакшен никогда не работает в режиме мока.

Что видит кухня

Контракт таков: заказ, созданный через Fooodo, поступает в R-Keeper неотличимо от заказа, созданного на терминале. Та же маршрутизация на принтер, то же поведение KDS, те же отчёты. Кухонному персоналу не нужно знать о существовании Fooodo, а официанты продолжают работать с R-Keeper точно так же, как и прежде.

Это сделано намеренно. Интеграция невидима по замыслу; операционная система расширяет R-Keeper, а не заменяет его.