Telegram-бот для уведомлений о новых заказах доставки

В этом руководстве мы соберём Telegram-бота, который присылает сообщение, когда в ресторане появляется новый заказ доставки. Бот не содержит сложной логики: он принимает уведомление от iiko и пересылает его в ваш Telegram-чат.

Руководство рассчитано на начинающих — каждый шаг описан словами и подкреплён готовой командой curl, которую можно скопировать и выполнить.

Что вы получите

В конце у вас будет:

сообщение в Telegram вида «Новый заказ доставки № 12345» с составом заказа;
понимание, как iiko отправляет вебхуки и как их принимать и фильтровать.

Как это работает

iiko присылает HTTP-запрос на ваш адрес (вебхук), когда создаётся или изменяется заказ доставки.
Ваш сервер смотрит на событие и решает, интересное ли оно (новый заказ).
Если да — отправляет сообщение в Telegram.

Что понадобится

Что	Где взять
`appId` и `clientSecret` приложения	Портал разработчика iiko
`apiKey`	iikoWeb → «Интеграции» → «API-ключи»
Токен Telegram-бота	`@BotFather` в Telegram
Публичный адрес для вебхука	Хостинг, либо `ngrok` для локальной отладки

Как получить доступ к iiko API

Зарегистрируйтесь на портале разработчика и заполните данные компании.
Создайте приложение — получите appId и одноразовый clientSecret. Секрет показывается только один раз, сразу после создания приложения. Сохраните его в надёжном месте; если потеряли — перевыпустите в портале (старый секрет перестанет работать).
В iikoWeb перейдите в «Интеграции» → «API-ключи» и создайте API-ключ — это apiKey. Ключ определяет, к каким организациям ресторана будет доступ у токена.
Эти три значения понадобятся в Шаге 1 для получения токена.

Шаг 1. Получение токена доступа

Токен нужен для всех остальных запросов к iiko API. Он действует 1 час, после чего нужно запросить новый (отдельного механизма обновления без повторного запроса нет).

Метод: POST /api/v2/access_token.

curl -X POST "https://api-ru.iiko.services/api/v2/access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "ВАШ_APP_ID",
    "clientSecret": "ВАШ_CLIENT_SECRET",
    "apiKey": "ВАШ_API_KEY"
  }'

Ответ:

{
  "correlationId": "8a24d2a9-0000-0000-0000-000000000000",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Поле token подставляйте в заголовок Authorization всех следующих запросов:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Шаг 2. Получение списка организаций

Организация — это ресторан. Запрос достаточно выполнить один раз и сохранить id нужной организации (UUID). Тело запроса можно оставить пустым — тогда вернутся все организации, доступные вашему API-логину.

Метод: POST /api/1/organizations.

curl -X POST "https://api-ru.iiko.services/api/1/organizations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответ (сокращённо):

{
  "correlationId": "8a24d2a9-0000-0000-0000-000000000000",
  "organizations": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000000",
      "name": "Ресторан «У моря»"
    }
  ]
}

Запомните id организации — он понадобится при настройке вебхуков.

Шаг 3. Создание Telegram-бота

В Telegram найдите бота @BotFather.
Отправьте команду /newbot и следуйте подсказкам: задайте имя и username бота.
@BotFather пришлёт токен вида 123456789:AAH.... Это пароль бота — не публикуйте его.
Напишите своему боту любое сообщение — так между вами и ботом появится чат.

Чтобы бот знал, куда отправлять уведомления, нужен chat_id. Проще всего получить его, открыв ссылку:

https://api.telegram.org/bot<ТОКЕН>/getUpdates

и найдя в ответе поле "chat":{"id":...}.

Шаг 4. Настройка вебхуков iiko

Вебхук — это адрес, на который iiko будет присылать уведомления. Подписаться можно двумя способами: через интерфейс iikoWeb или методом POST /api/1/webhooks/update_settings.

Подробный разбор обоих способов, поля запроса, проверка подлинности запросов и ограничения — в руководстве «Вебхуки iiko». Здесь приведём короткий вариант через API (укажите organizationId из Шага 2 и адрес вашего сервера):

curl -X POST "https://api-ru.iiko.services/api/1/webhooks/update_settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "ID_ОРГАНИЗАЦИИ",
    "webHooksUri": "https://ваш-домен.ru/webhook"
  }'

Важно: адрес из webHooksUri должен быть доступен из интернета. Для локальной отладки удобно использовать ngrok:

ngrok http 8080

Шаг 5. Обработка события «новый заказ доставки»

Когда заказ доставки создаётся или изменяется, iiko присылает на ваш адрес HTTP-запрос с типом события DeliveryOrderUpdate. Тело запроса — массив событий; каждое событие выглядит так:

[
  {
    "eventType": "DeliveryOrderUpdate",
    "eventTime": "2026-10-09 14:15:22.123",
    "organizationId": "a1b2c3d4-0000-0000-0000-000000000000",
    "correlationId": "8a24d2a9-0000-0000-0000-000000000000",
    "eventInfo": {
      "id": "9f8e7d6c-0000-0000-0000-000000000000",
      "externalNumber": "12345",
      "organizationId": "a1b2c3d4-0000-0000-0000-000000000000",
      "creationStatus": "Success",
      "order": {
        "number": 12345,
        "status": "New",
        "phone": "+7 900 000-00-00",
        "whenCreated": "2026-10-09 14:15:22",
        "sum": 1230.5,
        "items": []
      }
    }
  }
]

Ключевые поля:

eventType — тип события; для заказов доставки всегда DeliveryOrderUpdate;
eventInfo.creationStatus — статус создания заказа; детали заказа (eventInfo.order) заполнены, когда он равен Success;
eventInfo.order.status — статус заказа; новый заказ имеет статус New;
eventInfo.order.number — номер заказа;
eventInfo.order.items — состав заказа.

Чтобы уведомлять только о новых заказах, ваш сервер должен:

прочитать eventType и убедиться, что это DeliveryOrderUpdate;
взять eventInfo.order.status и проверить, что он равен New;
ответить HTTP-кодом 200 — иначе iikoCloud посчитает доставку неуспешной и повторит отправку.

Вебхук приходит на каждое изменение заказа, поэтому статус одного и того же заказа можно отслеживать в последующих событиях по его eventInfo.id или номеру.

Шаг 6. Отправка уведомления в Telegram

Когда вы отфильтровали новый заказ, отправьте сообщение в Telegram:

curl -X POST "https://api.telegram.org/bot<ТОКЕН>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "<CHAT_ID>",
    "text": "Новый заказ доставки №12345"
  }'

Проверка и отладка

Поднимите локальный сервер (например, на порту 8080) и пробросьте его через ngrok.
Укажите адрес ngrok в webHooksUri (Шаг 4).
Создайте тестовый заказ доставки в iiko — на ваш сервер должен прийти вебхук.
Если сообщение в Telegram не пришло, проверяйте по порядку: дошёл ли вебхук до сервера (смотрите логи), равен ли eventInfo.order.status значению New, верные ли chat_id и токен бота.

Частые ошибки

Ошибка	Что значит и что делать
`401 Unauthorized`	Токен неверный или истёк. Получите новый по Шагу 1.
Вебхук не приходит	Адрес `webHooksUri` недоступен из интернета или подписка не сохранилась. Проверьте `webhooks/settings` и доступность адреса.
iiko API повторяет отправку	Ваш сервер не отвечает кодом `200`. Возвращайте `200` сразу после приёма.
Сообщение не уходит в Telegram	Проверьте токен бота, `chat_id` и что бот не заблокирован.

Что дальше

Вебхуки iiko — какие бывают события и как настроить приём.
Справочник по API — все методы iikoCloud.
Портал разработчика — управление приложениями и ключами.

Что вы получите​

Как это работает​

Что понадобится​

Как получить доступ к iiko API​

Шаг 1. Получение токена доступа​

Шаг 2. Получение списка организаций​

Шаг 3. Создание Telegram-бота​

Шаг 4. Настройка вебхуков iiko​

Шаг 5. Обработка события «новый заказ доставки»​

Шаг 6. Отправка уведомления в Telegram​

Проверка и отладка​

Частые ошибки​

Что дальше​