iiko Loyalty (Card) API: как подключить программу лояльности

Программа лояльности в iiko — это не только скидка на чеке. Через iiko Loyalty (Card) API бонусами, купонами и персональными предложениями можно управлять снаружи: из бота, из доставки, из ИИ-администратора. Разбираем по шагам, где взять ключ, что реально умеет API, а что придётся закрывать другими способами.

Гость сделал три заказа и пропал. Другой оставил у вас 40 тысяч за месяц, а вы даже не поздоровались с ним по имени. Программа лояльности iiko умеет чинить обе истории — но только если её вывести за пределы кассы. Именно для этого существует iiko Loyalty API (в интерфейсе и документации он же iiko Card / iikoCard). Ниже — как он устроен и как подключить его без танцев с бубном.

Что такое iiko Loyalty и чем Card отличается от Transport

У iiko несколько API, и их постоянно путают. Чтобы не терять время, держите в голове это разделение:

Ключевое: программа лояльности iiko живёт в облаке iikoCard, а не в вашем локальном сервере iikoOffice. Поэтому API называется облачным, а точка входа — api-ru.iiko.services (для России). Начисление и списание бонусов — это всегда обращение в облако.

Где взять ключ и как авторизоваться

Доступ к iiko api лояльность даёт не логин-пароль от кассы, а API-логин (apiLogin) — длинная строка, которую генерируют в личном кабинете iiko или запрашивают у вашего аккаунт-менеджера / интегратора. Один apiLogin может открывать доступ сразу к нескольким организациям под вашим юрлицом.

Схема авторизации простая и одинаковая для всех облачных методов iiko:

1. Получаете токен. Метод POST /api/1/access_token, в теле — ваш apiLogin. В ответ приходит token.
2. Живёт токен ~1 час. Его кэшируют и переиспользуют, а не запрашивают на каждый чих — иначе упрётесь в лимиты.
3. Дальше все запросы идут с заголовком Authorization: Bearer <token>.
4. Узнаёте organizationId. Метод POST /api/1/organizations вернёт список организаций и их идентификаторы — почти каждый метод лояльности требует organizationId.

Практичный совет: apiLogin — это фактически ключ от кошелька ваших гостей. Не зашивайте его в код мобильного приложения или в браузерную часть сайта. Только на сервере, только в переменных окружения. Утёкший apiLogin — это чужие руки в вашей бонусной системе.

Что реально умеет iiko Loyalty API

Documentация большая, но 90% задач кафе и доставки закрывают несколько методов. Вот рабочий минимум:

Найти и завести гостя

• /api/1/loyalty/iiko/customer/info — найти гостя по телефону, карте, email или ID. Отдаёт баланс бонусов, категорию, историю.
• /api/1/loyalty/iiko/customer/create_or_update — создать нового или обновить данные. Сюда попадает гость, который впервые оставил у вас телефон.

Считать и списывать бонусы

• /api/1/loyalty/iiko/calculate — самый важный метод для доставки. Передаёте состав заказа и гостя — получаете, сколько бонусов начислить, сколько можно списать, какие скидки и купоны применимы. Ничего не меняет, просто считает.
• Фактическое списание/начисление происходит, когда заказ уходит в iiko через Transport API с привязанным гостем и рассчитанной программой лояльности.

Купоны и промокоды

• /api/1/loyalty/iiko/coupons/series и методы проверки конкретного купона — чтобы промокод из рассылки или из чата с гостем срабатывал в заказе, а не был просто красивой строчкой.

Программы, категории, маркетинговые кампании

• Списки программ лояльности, категорий гостей (например, «VIP», «Новичок»), настроенных в iikoCard. По категории удобно сегментировать рассылки и предложения.

Пошаговый план подключения

Если вы владелец и хотите понимать, что происходит (даже если руками делает подрядчик), держите чек-лист:

1. Проверьте, что лояльность настроена в iikoCard. Если бонусов нет в самой кассе — API нечего отдавать. Заведите хотя бы одну программу начисления (например, 5% бонусами) и правило списания.
2. Получите apiLogin в кабинете iiko или у менеджера. Уточните, что это ключ именно Loyalty/iikoCard, а не только Transport.
3. Проверьте токен вручную. Любой человек с Postman за 5 минут дёрнет access_token и organizations — если organizationId вернулся, доступ живой.
4. Свяжите канал сбора телефонов. Сайт, бот, доставка — везде, где гость оставляет номер, этот номер должен уходить в customer/create_or_update. Иначе база лояльности не растёт.
5. Включите расчёт бонусов в оформлении заказа. Через calculate — чтобы гость видел «спишется 200 бонусов» ещё до подтверждения.
6. Проверьте на реальном заказе. Сделайте тестовый заказ на свой номер, спишите бонусы, убедитесь, что баланс изменился и в кассе, и в API.

Честно: что закрывает API, а что — нет

API — это доступ к данным и расчётам. Он не будет сам звонить гостю, писать поздравление с днём рождения или уговаривать вернуться. Всю «человеческую» часть лояльности делает то, что вы поверх API построите.

Вот здесь и появляется практическая польза. Когда гость в чате спрашивает «а бонусами можно оплатить?» или «сколько у меня накоплено?», кто-то должен сходить в iiko card по API и ответить сразу, а не через два часа. У нас в «Людочке» ИИ-администратор как раз подтягивает баланс и правила лояльности из iiko в момент разговора — гость получает точную цифру и сразу оформляет заказ со списанием, без ручного участия оператора. Это не магия API, это надстройка над ним: сам iiko молчит, пока его не спросят.

Три частые грабли

• Гость дублируется. Один и тот же человек с телефона в TG и с телефона на сайте создаётся дважды, бонусы размазываются. Всегда ищите гостя через customer/info перед созданием.
• Списание считается на клиенте. Никогда не верьте расчёту скидки на стороне сайта — только calculate от iiko. Иначе гость «нарисует» себе скидку.
• Токен запрашивается на каждый запрос. Кэшируйте на час. Иначе поймаете троттлинг в час пик.

Итог: с чего начать завтра

Если у вас уже стоит iiko, подключение iiko loyalty — это не месяцы разработки, а несколько понятных шагов: настроить программу в iikoCard, получить apiLogin, научиться получать токен и считать бонусы в заказе. Дальше вопрос в том, кто будет с этими данными общаться с гостем — рассылка, бот или ИИ-администратор. API даёт цифры и правила; ценность появляется, когда эти цифры вовремя доходят до конкретного человека и превращаются в повторный заказ.