Telegram бот для iiko: анализ продаж и поиск опозданий доставок

Сделали Telegram бота, который подключается к iiko, анализирует продажи "за вчера", находит опоздания доставок и отправляет SMS сообщения клиентам с извинениями и подарком внутри.

Постановка задачи и поиск решения

Мы начали этот проект после запроса одного из клиентов:

Дмитрий, нам нужно автоматизировать процесс отправки SMS сообщений с купонами на бесплатную пиццу тем клиентам, к кому мы опоздали по акции "30 минут или пицца в подарок".

Первоначальный набросок алгоритма:

1. Клиент оформляет заказ по акции "30 минут или пицца в подарок".
2. Пиццерия готовит заказ и доставляет его.
3. В случае опоздания заказ помечается как "Заказ с опозданием".
4. Telegram бот на следующее утро анализирует заказы "за вчера", понимает объем "опозданий" и генерирует через iiko.biz необходимое количество уникальных купонов на бесплатную пиццу со сроком действия 14 дней.
5. Далее бот отправляет SMS с этими купонами: по одному каждому клиенту.
6. Через 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:

1. Авторизация в iiko Server API — /resto/api/auth.
2. Выгрузка OLAP отчета — /resto/api/v2/reports/olap.
3. Освобождение лицензии Server API — /resto/api/logout.
4. Авторизация в iiko Delivery API — /api/0/auth/access_token.
5. Поиск клиента по номеру телефона — /api/0/customers/get_customer_by_phone.
6. Добавить клиенту подарочную категорию — /api/0/customers/customerId/add_category.
7. Отправить клиенту 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-сервер, и бот будет обновлён до последней версии.

Результат

Задача решена, получен следующий результат:

1. Каждое утро по местному времени бот выгружает из Айко данные о продажах "за вчера".
2. Каждый заказ проверяется на опоздание. Если (Delivery.ActualTime - Delivery.PrintTime > 30 минут), значит это опоздание.
3. Для каждого заказа с опозданием бот находит клиента, назначает этому клиенту специальную подарочную категорию и отправляет ему SMS сообщение с извинениями и инструкцией, как получить бесплатную пиццу.
4. Бот формирует отчет о своей работе и отправляет его руководителю доставки.
5. В отчёте "Акции и промокоды" Семёна Фудова отображается статистика применения подарочной категории: сколько было назначений и использований за отчетный период.

Подведение итогов

Семён Фудов умеет разрабатывать Telegram ботов для самых разных задач. У нас уже работают боты, которые:

1. Собирают внутренние логи Семёна Фудова для мониторинга производительности.
2. Оповещают курьеров доставки о новых назначенных заказах.
3. Выгружают данные о продажах для импорта во внешние системы анализа данных (Power BI и др.)
4. И теперь — находят опоздания и отправляют SMS сообщения клиентам с извинениями и подарками внутри.

Если у вас есть идея разработать собственного Телеграм бота для ресторана, доставки или кафе — пишите на почту hello@fudov.ru, обсудим!