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