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

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

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

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

• iikoServer API ("серверное апи")
• iikoTransport API или iikoCloud API ("новое доставочное апи", развивается)
• iikoBizAPI или iikoDelivery API ("старое доставочное апи", не развивается)
• iikoCard API
• Front Web API
• iikoFront API SDK

Еще есть непубличные 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 требует от администратора дополнительных действий, описанных в официальных инструкциях:

• https://ru.iiko.help/articles/#!iikoweb/iikotransport
• https://ru.iiko.help/articles/#!api-documentations/connect-to-iiko-cloud

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

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

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

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

Подключение 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"