iikoTransport API: как принимать внешние заказы в iiko

Если у вас на кассе iiko, а заказы капают из сайта, чат-бота, агрегатора или голосового ассистента — вручную вбивать их в терминал больно и дорого. iikoTransport API решает это: заказ прилетает в iiko сам, кухня видит его на экране, курьеру считается доставка. Разбираем без лишней воды, как это устроено и что нужно, чтобы завести.

Что такое iikoTransport и зачем он вам

iikoTransport (он же iiko Cloud API, iikoCloud) — это облачный интерфейс, через который любая внешняя система может «разговаривать» с вашей iiko: узнавать меню, стоп-листы, создавать заказы на доставку и самовывоз, отслеживать их статусы. Проще говоря, это дверь, через которую заказ с сайта или из мессенджера попадает прямо в производственный контур ресторана, минуя ручной ввод.

Важно не путать два разных API iiko. Есть iikoCard/Loyalty — про бонусы, скидки и программу лояльности. И есть iikoTransport — именно про внешние заказы iiko. Для приёма заказов вам нужен второй. На практике владельцы часто узнают об этом, когда интегратор просит «apiLogin транспорта», а в личном кабинете лежит только ключ лояльности.

Короткое правило: если задача — «принять заказ и отправить его на кухню», это iikoTransport. Если «начислить бонусы гостю» — это Loyalty. Один ключ не заменяет другой.

Что нужно на старте: apiLogin и токен

Вся работа с iiko cloud api строится вокруг одного секретного значения — apiLogin. Это не логин-пароль сотрудника, а отдельный ключ интеграции.

Где взять apiLogin

• apiLogin выдаётся в личном кабинете iiko (apiweb / кабинет интеграций) для конкретного юрлица и приложения.
• Если вы работаете через франчайзи или партнёра iiko — ключ запрашивается у них, иногда через заявку в поддержку.
• Один apiLogin может обслуживать несколько ресторанов (организаций) под вашим аккаунтом.

Как получить токен доступа

Дальше логика простая. Сначала меняете apiLogin на временный токен, потом с этим токеном дёргаете все остальные методы.

• Базовый адрес для России: https://api-ru.iiko.services/api/1/
• Метод POST /access_token, в теле — ваш apiLogin. В ответ приходит token.
• Токен живёт около 60 минут. Его кладут в заголовок Authorization: Bearer <token> ко всем запросам и обновляют по истечении срока, а не запрашивают на каждый чих.

Типичная ошибка новичков — брать новый токен перед каждым заказом. iiko это не любит и может отвечать ограничениями по частоте. Правильно — кэшировать токен и перевыпускать раз в ~50 минут.

Базовый маршрут заказа: от организации до кухни

Чтобы iiko api заказы заработали, нужно пройти цепочку из нескольких запросов. Порядок почти всегда такой:

Ключевой момент: в заказе вы передаёте не название блюда текстом, а его productId из номенклатуры. Поэтому меню сначала выгружают и сопоставляют (маппят) с тем, что показывают гостю на сайте или в боте. Если в iiko у «Маргариты» один ID, а на сайте другой артикул — заказ либо не пройдёт, либо уйдёт не то блюдо.

Доставка, самовывоз и оплата

В теле /deliveries/create вы указываете тип обслуживания: доставка на адрес или самовывоз. Для доставки iiko ждёт структурированный адрес — улицу, дом, иногда через справочник улиц города. Здесь легко получить «самовывоз вместо доставки», если поля адреса заполнены не так, как ждёт касса. Оплату можно пометить как наличные, картой курьеру или уже оплаченную онлайн — тип оплаты тоже берётся из справочника /payment_types.

Статусы и вебхуки: как узнать, что с заказом

Создать заказ — половина дела. Дальше важно понимать, приняла ли его кухня, готовится ли он, ушёл ли курьер. Есть два пути:

• Опрос (polling) — периодически спрашивать /deliveries/by_id. Просто, но нагружает API и даёт задержку.
• Вебхуки — iiko сама шлёт вам уведомление на ваш URL, когда статус заказа меняется (принят, готовится, приготовлен, доставлен, отменён). Это правильный способ для живых сценариев.

Именно на статусах строятся полезные автоматизации: сообщить гостю «заказ готовится», запросить отзыв после «доставлен», поднять тревогу, если заказ завис в «новом» и никто его не подтвердил. Без обработки статусов интеграция получается однонаправленной — заказ отправили и забыли.

Частые грабли и как их обойти

• Перепутан ключ. Взяли apiLogin от лояльности вместо транспорта — заказы не создаются. Проверьте, что ключ именно для iikoTransport.
• Протухший токен. Через час всё «ломается». Лечится кэшированием и обновлением токена по таймеру.
• Неверный terminalGroupId. Заказ уходит «в пустоту», потому что указан терминал закрытой точки или другого юрлица.
• Рассинхрон меню. Поменяли блюдо в iiko, а маппинг на сайте остался старый. Номенклатуру нужно перечитывать регулярно, а не один раз при запуске.
• Стоп-листы. Блюдо в стопе, но внешняя система об этом не знает — гость заказывает то, чего нет. Отдельный метод стоп-листов решает проблему.
• Адрес доставки. Неправильная структура адреса превращает доставку в самовывоз или роняет заказ.

Делать самому или через готовое решение

iikoTransport — не самый сложный API, но и не «за вечер». Реально работающая интеграция — это токены, маппинг меню, обработка стоп-листов, вебхуки статусов, обработка ошибок и отмен. Для одного ресторана это несколько дней работы разработчика, плюс поддержка при каждом обновлении меню.

Поэтому многие берут не голый API, а сервис, который уже умеет говорить с iiko. Например, наша Людочка — ИИ-администратор для кафе и доставки — принимает заказ прямо в переписке или голосом, сама подставляет блюда из вашей номенклатуры и через iikoTransport отправляет готовый заказ на кассу. Гость пишет «две пиццы и колу на такой-то адрес» — заказ появляется в iiko без ручного ввода, а по статусам из вебхуков Людочка сообщает гостю, что заказ готовится и когда выехал курьер.

Что здесь честно стоит различать: сам факт создания заказа и его статусы — это работа iikoTransport API. А распознавание живой речи гостя, уточнение адреса, сбор корзины из свободного текста и общение по ходу — это уже слой поверх, который делает ассистент. API довозит заказ до кухни; удобство для гостя добавляет то, что стоит перед API.

Мини-чек-лист перед запуском

• Получен apiLogin именно для iikoTransport.
• Токен кэшируется и обновляется по таймеру.
• Известны organizationId и terminalGroupId нужной точки.
• Меню выгружено и сопоставлено с позициями на сайте/в боте.
• Настроена регулярная синхронизация меню и стоп-листов.
• Заведены вебхуки статусов и логика уведомлений гостю.
• Протестированы доставка, самовывоз и отмена заказа.

Если пройти этот список, внешние заказы будут падать в iiko стабильно, а вы перестанете терять деньги на ручном вводе и опечатках в адресах.