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

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

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

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

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

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

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

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

• URL конечной точки API
• ID ресторана внутри 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 и обновляет список официантов из кадровой системы сети — имена, должности и внешние ID сотрудников, соответствующие R-Keeper. Официанты не создаются в Fooodo вручную; список в административной панели доступен только для чтения.
• Атрибуция заказа происходит при получении или обновлении заказа из R-Keeper. Ответ R-Keeper о статусе заказа содержит ID назначенного официанта; 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 с — пять попыток за ~17 минут. Более медленный ритм выбран намеренно: оплаченный заказ находится в процессе сверки, а не блокирует обслуживание, поэтому мы даём 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, а не заменяет его.