Для разработчика сайта
Что умеет публичный API, как устроен ключ, почему заказ нельзя задвоить и как получить полную спецификацию.
Страница для того, кто делает витрину. Здесь — подход и правила; полная спецификация с адресами методов, полями и примерами выдаётся вместе с ключом, по запросу от заведения или его разработчика.
Выложенное на витрине описание методов помогает не столько интегратору, сколько тому, кто ищет чужие интеграции. Разработчику оно нужно один раз и приходит за минуты; поисковому роботу — незачем. Напишите нам, и получите описание в тот же день.
Авторизация
Вход по ключу интеграции. Ключ принадлежит одному заведению: чужие данные через него недостижимы по устройству системы, а не «по проверке в коде».
- ключ выдаётся в бэк-офисе заведением и показывается один раз;
- секретная часть хранится у нас хешем — восстановить её нельзя, можно только выпустить новую;
- отзыв мгновенный: отозванный ключ перестаёт работать до следующего запроса;
- ключ живёт на сервере витрины. В браузере гостя, в мобильном приложении и в репозитории ему не место.
Если ключ попал в общий чат, в публичный репозиторий или в клиентский код — отзовите его и выпустите новый. Это одна кнопка, и это дешевле любых последствий.
Что умеет интеграция
| Возможность | Что даёт витрине |
|---|---|
| Меню | Категории, блюда, цены, модификаторы, фото — уже без снятых с продажи позиций |
| Приём заказов | Заказ уходит одним обращением и получает номер |
| Изменение и отмена | Пока заведение не приняло заказ |
| Проверка промокода | Скидка на витрине и на кассе считается одинаково |
| Сообщение об оплате | Оплата на стороне витрины связывается со способом оплаты заведения |
| Признак приёма | Принимает ли заведение заказы прямо сейчас |
| Статусы обратно | Принят, готовится, передан курьеру — уведомления уходят витрине и подписаны общим секретом |
Идемпотентность
Каждый заказ витрина сопровождает собственным ключом операции. Повторная отправка с тем же ключом не создаёт второй заказ — это защита от двойного нажатия, обрыва связи и повторов очереди.
Практическое следствие: при обрыве не бойтесь повторить запрос. Бояться нужно обратного — сгенерировать новый ключ операции для того же заказа гостя.
Что важно знать при разработке
- позиция определяется кодом, а не названием: названия меняются, коды нет;
- модификаторы передаются отдельно от блюда, со своими кодами и ценами;
- цена строки — это деньги: сервер сверяет её и не додумывает;
- стоп-лист живой: меню запрашивают перед показом, а не кэшируют на сутки;
- незаполненный обязательный выбор не приводит к отказу — заказ придёт, а администратор выберет вариант сам;
- на частоту запросов есть ограничения, а на повторные промахи при проверке промокодов — отдельный заслон. Нормальной витрине они не мешают; цикл перебора упирается в них сразу.
Ошибки
Ответы об ошибках описательные: видно, какая именно позиция не прошла и почему. При интеграции логируйте тело ответа целиком — это экономит часы переписки.
Единственное исключение — неверный ключ: на него приходит короткий ответ без подробностей. Это сделано намеренно, чтобы по форме ошибки нельзя было понять, подошёл ключ или нет.
Проверка перед запуском
- Получить меню и показать его на витрине, включая стоп-лист.
- Отправить тестовый заказ и увидеть его в панели кассы.
- Повторить отправку с тем же ключом операции и убедиться, что второго заказа нет.
- Проверить промокод — действительный и просроченный.
- Сообщить об оплате и увидеть, что заказ закрылся нужным способом оплаты.
- Проверить поведение при обрыве: остановить ответ на середине и повторить запрос.