Подключение внешних интеграций к серверу Айко (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. Что важно сделать при создании ключа:
- Понятно назвать ключ, например, "API логин для курьерского приложения Fudov Man". Чтобы потом среди десятков ключей найти нужный.
- В поле "Email" указать почту support@fudov.ru, чтобы нам на почту пришло письмо, когда необходимо будет продлить срок действия ключа.
- Поле "Источник заказа" оставить пустым.
Подключение 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"