iiko
August 7, 2021

Подключение внешних интеграций к серверу Айко (iiko) по API

Айко предоставляет сторонним разработчикам возможность подключаться к своим серверам и получать доступ к данным ресторанов. В этом посте — обзор программных интерфейсов (API) и как Семён Фудов подключается к ресторанам.

Доступные программные интерфейсы Айко

Айко предоставляет доступ к нескольким программным интерфейсам (API, Application Programming Interface), по ссылкам открывается официальная документация:

Еще есть непубличные API, о которых знают только "свои", но это уже другая история. Семён Фудов чаще всего использует первые три интерфейса, далее — подробности подключения.

Подключение iikoServer API

Серверное API (iikoServer API) используется для выгрузки номенклатуры ресторана (списки точек, продуктов, полуфабрикатов, товаров, технологические карты и др.), получения доступа к документам (приходные и расходные накладные, акты приготовления и реализации, инвентаризации и др.), получения доступа к кассовым сменам, построения различных отчетов (OLAP и не только).

По сути аккаунт iikoServer API — это обычный аккаунт пользователя iikoOffice (BackOffice). Список прав доступа для этого аккаунта зависит от того, какие возможности должна получить внешняя интеграция. Обычно Семён Фудов подключается с правами как у администратора ресторана, как минимум нужны следующие права (список прав доступа):

  • B_RPT — Просмотр отчетов
  • B_CASR — Право просматривать отчеты по продажам
  • B_PER — Доступ к разделу "Сотрудники"
  • B_VN — Просмотр номенклатурных справочников
  • B_VOTR — Просматривать OLAP-отчет по проводкам

Важное замечание в официальной документации:

При авторизации вы занимаете один слот лицензии. Токен, который вы получаете при авторизации, можно использовать до того момента, пока он не перестанет работать. И если у вас только одна лицензия сервера, а вы уже получили токен, следующее обращение к серверу за токеном вызовет ошибку. Если вам негде хранить токен при работе с сервером API, рекомендуем вам разлогиниться, что приводит к отпусканию лицензии.

На практике это означает, что в час пик, когда, к примеру, все оплаченные лицензии Айко используются операторами колл-центра, внешняя интеграция не сможет запросить токен доступа — все слоты лицензии окажутся занятыми. В большинстве случаев ресторанная сеть оплачивает дополнительные слоты лицензии (для руководства, для администраторов, для маркетологов и/или др.), одного из этих слотов будет достаточно — слот обычно "занимается" только на время выгрузки данных и построения отчетов (десятки секунд), после чего "отпускается".

Чтобы подключить Семёна Фудова к серверному апи iikoServer API, нужно создать нового пользователя Айко (в примере — semenfudov) и предоставить следующие данные:

'server_api_credentials' => [
    'proto'  => 'https',  # Протокол, почти всегда https
    'server' => 'XXXXX-co.iiko.it',  # Адрес сервера Айко
    'port'   => '443',  # Порт подключения, почти всегда 443
    'login'  => 'semenfudov',  # Имя пользователя Айко для интеграции
    'pass'   => 'password'  # Пароль пользователя, задать сложный
]

Как проверить успешность подключения? Открыть в браузере ссылку вида: https://XXXXX-co.iiko.it/resto/api/auth?login=semen-fudov&pass=73db5d5193049e6e76937a9b23b4c93802c2af1f, где pass — это хэш пароля (хэш пароля можно получить тут). Если все правильно настроено, в ответе сервер Айко вернёт токен доступа, что-то вроде такого: 4627c222-446e-81c9-017b-532e82a3836c

Подключение iikoTransport API

Новое доставочное API (iikoTransport API или iikoCloud API) предоставляет практически такой же функционал, как и старое апи. Была изменена архитектура решения, некоторые старые методы исключены, некоторые новые — добавлены. Примеры нововведений: смена типа оплаты для заказа, переназначение курьера, частичная выгрузка заказов за последний час и др.

Для большинства отчетов Fudov Smart и курьерского приложения Fudov Man требуется именно подключение iikoTransport API.

Это новое апи. Да, в нём есть отличные функции, но есть и нерешенные проблемы: веб-интерфейс администратора в iikoWeb сбоит, есть случаи, когда отдельные точки ресторанных сетей "не видны" через iikoTransport API. Однако компания iiko рекомендует всем доставкам использовать именно iikoTransport API (а не iikoDelivery API) — это апи активно поддерживается и развивается.

Более того, с июля 2022 года компания iiko прекратила подключение новых клиентов к старому iikoBizAPI. Для новых клиентов возможно только подключение к iikoTransport API.

Включение iikoTransport API требует от администратора дополнительных действий, описанных в официальных инструкциях:

Чтобы подключить Семёна Фудова к новому доставочному апи iikoTransport API, нужно предоставить следующие данные:

'transport_api_credentials' => [
    'api_login' => 'fb42943c9dd748d482e0a44e729463c2'
]

Длинная последовательность цифр и букв — это "API логин" или "API ключ". Создаётся этот логин в интерфейсе iikoWeb. Что важно сделать при создании ключа:

  1. Понятно назвать ключ, например, "API логин для курьерского приложения Fudov Man". Чтобы потом среди десятков ключей найти нужный.
  2. В поле "Email" указать почту support@fudov.ru, чтобы нам на почту пришло письмо, когда необходимо будет продлить срок действия ключа.
  3. Поле "Источник заказа" оставить пустым.
Пример создания API ключа для курьерского приложения Fudov Man в интерфейсе iikoWeb

Подключение iikoBizAPI (iikoDelivery API)

Старое доставочное API (iikoBizAPI или iikoDelivery API) используется для получения данных доставки — номенклатуры, типов оплаты, заказов, курьеров, маркетинговых источников и др.

Внешние интеграции обращаются методами iikoDelivery API не напрямую к Айко, а через посредника — через специальный интеграционный модуль iikoDelivery API Коннектор, который приобретается в магазине приложений Айко. Одной лицензии Коннектора (~500 рублей в месяц) хватит для всех внешних интеграций: для отчетов и курьерского веб-приложения Семёна Фудова, сайта, агрегаторов доставки.

Чтобы подключить Семёна Фудова к доставочному апи iikoDelivery API, нужно предоставить следующие данные:

'delivery_api_credentials' => [
    'server'      => 'iiko.biz',  # Адрес Biz-сервера Айко
    'port'        => '9900',  # Порт подключения, почти всегда 9900
    'user_id'     => 'username',  # Имя пользователя API iikoDelivery
    'user_secret' => 'userpass'  # Пароль пользователя API iikoDelivery
]

Как проверить успешность подключения? Открыть в браузере ссылку вида: https://iiko.biz:9900/api/0/auth/access_token?user_id=USERNAME&user_secret=USERPASS. Если все правильно настроено, в ответе сервер Айко вернёт токен доступа, что-то вроде такого: "FaMR8FwdpihgQbYWDmRqgvCfbHP611x65vyd1_DYbFDFi9KqrGlWroaMexL79nwp2hYOXtK0EdRf0LcMggxWjO3ZUdh_Zf6kuXtFtmqEs_k1"