Telegram бот для iiko: анализ продаж и поиск опозданий доставок
Сделали Telegram бота, который подключается к iiko, анализирует продажи "за вчера", находит опоздания доставок и отправляет SMS сообщения клиентам с извинениями и подарком внутри.
Постановка задачи и поиск решения
Мы начали этот проект после запроса одного из клиентов:
Дмитрий, нам нужно автоматизировать процесс отправки SMS сообщений с купонами на бесплатную пиццу тем клиентам, к кому мы опоздали по акции "30 минут или пицца в подарок".
Первоначальный набросок алгоритма:
- Клиент оформляет заказ по акции "30 минут или пицца в подарок".
- Пиццерия готовит заказ и доставляет его.
- В случае опоздания заказ помечается как "Заказ с опозданием".
- Telegram бот на следующее утро анализирует заказы "за вчера", понимает объем "опозданий" и генерирует через iiko.biz необходимое количество уникальных купонов на бесплатную пиццу со сроком действия 14 дней.
- Далее бот отправляет SMS с этими купонами: по одному каждому клиенту.
- Через 14 дней бот формирует отчет по каждому дню, где видно, сколько купонов отправлено клиентам, сколько из них активировано в течение этих 14 дней: количество и сумма.
Уточняем в документации iiko API, какими методами можно реализовать алгоритм. Запрашиваем консультации у официальной поддержки Айко и у дилера. Первые изменения:
- В Айко нет метки "Заказ с опозданием". Поэтому факт опоздания будет определяться автоматически на основании временных меток заказа.
- SMS сообщения можно рассылать от имени ресторана через Айко или через любой смс-гейт. Выбираем первый вариант.
Самое главное изменение касается логики получения скидки. Автоматизировать выдачу индивидуальных промокодов в Айко нельзя, поэтому выход из ситуации — создать специальную "подарочную" категорию и назначать эту категорию клиентам при опозданиях. После получения подарка (бесплатной пиццы) категория автоматически "снимается".
Чтобы разобраться с опозданиями, выгружаем из OLAP отчета все столбцы, которые связаны с метками времени:
{ "CloseTime": "2022-02-01T15:16:18.215", # Фактическое время доставки "Delivery.ActualTime": "2022-02-01T15:18:39.693", "Delivery.BillTime": "2022-02-01T14:25:02.329", # Время печати накладной "Delivery.CloseTime": "2022-02-01T15:18:40.1", # Время закрытия доставки # Время окончания приготовления "Delivery.CookingFinishTime": "2022-02-01T15:16:15.621", "Delivery.CustomerName": "Виктория", "Delivery.CustomerPhone": "+79141234567", "Delivery.Delay": 64, # Опоздание доставки(мин) # Отклонение от сроков доставки # фактическое от прогнозируемого (мин) "Delivery.DiffBetweenActualDeliveryTimeAndPredictedDeliveryTime": null, # Планируемое время доставки "Delivery.ExpectedTime": "2022-02-01T14:14:18.108", "Delivery.Number": 1, # Прогнозируемое время окончания готовки заказа "Delivery.PredictedCookingCompleteTime": null, "Delivery.PredictedDeliveryTime": null, # Прогнозируемое время доставки "Delivery.PrintTime": "2022-02-01T15:16:15.621", # Время печати доставки "Delivery.SendTime": "2022-02-01T15:16:18.371", # Время отправки доставки "Delivery.WayDuration": 2, # Время в пути(мин) "OpenDate.Typed": "2022-02-01", "OpenTime": "2022-02-01T13:11:16", # Время открытия "OrderServiceType": "DELIVERY_BY_COURIER", "OrderTime.OrderLength": 125, "PrechequeTime": "2022-02-01T15:16:15.621" # Время пречека }
Принимаем решение, что будем считать опозданием случай, когда разница между метками времени Delivery.ActualTime и Delivery.PrintTime превышает контрольное время 30 минут.
Разработка Телеграм бота
Пытаемся реализовать алгоритм минимально возможным количеством вызовов API. Одного "доставочного" API (iikoBizApi), который подключается к колл-центру, недостаточно — нужен OLAP отчет. А он формируется на основании кассовых смен, которых в колл-центре нет, смены есть только на точках продаж. Поэтому потребуется подключение к Server API.
Итоговая последовательность вызовов iiko API:
- Авторизация в iiko Server API — /resto/api/auth.
- Выгрузка OLAP отчета — /resto/api/v2/reports/olap.
- Освобождение лицензии Server API — /resto/api/logout.
- Авторизация в iiko Delivery API — /api/0/auth/access_token.
- Поиск клиента по номеру телефона — /api/0/customers/get_customer_by_phone.
- Добавить клиенту подарочную категорию — /api/0/customers/customerId/add_category.
- Отправить клиенту SMS сообщение — /api/0/organization/id/send_sms.
OLAP отчет выгружаем со следующими фильтрами:
"filters": { "OpenDate.Typed": { "filterType": "DateRange", "periodType": "CUSTOM", "from": "2022-01-01", "to": "2022-01-01", "includeLow": "true", "includeHigh": "true" }, "OrderDeleted": { "filterType": "IncludeValues", "values": ["NOT_DELETED"] }, "OrderServiceType": { "filterType": "IncludeValues", "values": ["DELIVERY_BY_COURIER"] }, "OperationType": { "filterType": "ExcludeValues", "values": ["STORNED", "NO_PAYMENT"] } }
Тестируем бота две недели на "живых" данных, исправляем обнаруженные корнер-кейсы и ошибки (пустое имя или телефон, несколько номеров телефонов у клиента, ограничение длины сообщения в Telegram 4096 символов и др.).
Остается настроить GitHub Actions, чтобы разработчик больше думал про код, а не про инфраструктуру. После каждого изменения в коде GitHub оповестит production-сервер, и бот будет обновлён до последней версии.
Результат
Задача решена, получен следующий результат:
- Каждое утро по местному времени бот выгружает из Айко данные о продажах "за вчера".
- Каждый заказ проверяется на опоздание. Если (Delivery.ActualTime - Delivery.PrintTime > 30 минут), значит это опоздание.
- Для каждого заказа с опозданием бот находит клиента, назначает этому клиенту специальную подарочную категорию и отправляет ему SMS сообщение с извинениями и инструкцией, как получить бесплатную пиццу.
- Бот формирует отчет о своей работе и отправляет его руководителю доставки.
- В отчёте "Акции и промокоды" Семёна Фудова отображается статистика применения подарочной категории: сколько было назначений и использований за отчетный период.
Подведение итогов
Семён Фудов умеет разрабатывать Telegram ботов для самых разных задач. У нас уже работают боты, которые:
- Собирают внутренние логи Семёна Фудова для мониторинга производительности.
- Оповещают курьеров доставки о новых назначенных заказах.
- Выгружают данные о продажах для импорта во внешние системы анализа данных (Power BI и др.)
- И теперь — находят опоздания и отправляют SMS сообщения клиентам с извинениями и подарками внутри.
Если у вас есть идея разработать собственного Телеграм бота для ресторана, доставки или кафе — пишите на почту hello@fudov.ru, обсудим!