Настройка iikoCard для лояльности

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

Но перед первой синхронизацией нужно активировать модуль iikoCard на стороне iiko — это делается один раз. Гайд занимает 10–15 минут.

Что должно работать в итоге

После полной настройки:

• Misea → iiko (автоматически): начислили баллы через /loyalty → касса видит изменение через ~1 секунду.
• iiko → Misea (через webhook): кассир списал бонусы при оплате → ваш баланс в Misea обновился, гостю пришёл push-уведомление о списании.
• Касса: при сканировании Apple Wallet карты гостя iikoFront находит контрагента, показывает имя и баланс, предлагает начислить или списать бонусы.

Шаг 1. Проверьте что iikoCard включён в iikoOffice

1. Откройте iikoOffice → раздел Розничные продажи → Лояльность → iikoCard.
2. Перейдите на вкладку «Основные настройки».
3. Поставьте галку «iikoCard включён».
4. Проверьте что заполнены поля:
   • Адрес сервера iikoCard: https://m1.iiko.cards (стандартное значение)
   • Подключение к RabbitMQ: amqps://m1mq.iiko.cards:5671
5. Сохраните и подождите 1–2 минуты, пока iikoServer установит соединение.

Проверка подключения

В iikoOffice → раздел iikoCard → вкладка «Диагностика подключения». Все четыре строки должны быть «Успешно» (зелёные):

• Идентификатор CRM — должен быть числовой CrmID
• Возможность обмена с RabbitMQ
• Возможность обмена с iiko.cards
• Активность слушателей MQ reader

Если есть красные строки — обратитесь к вашему iiko-партнёру: подключение модуля требует серверной активации.

Шаг 2. Создайте бонусную программу на iiko.biz

1. Откройте iiko.biz — это отдельный портал от iikoOffice (модуль iikoCard живёт там).
2. Войдите тем же логином, которым подключали интеграцию в Misea.
3. В левой панели: iikoCard → Программы → Создать.

Заполните:

• Наименование: например, «Кешбэк Misea» (название отобразится на бонусном счёте гостя)
• Период действия: от сегодня, дата окончания — например, через 5 лет (бессрочно фактически)
• Тип программы: ⚠ выберите «Бонусная программа (на счёте накапливаются бонусы)». Не «Скидки» — это другая логика. Не «Денежная» — это депозит.
• Статус программы: ✓ «Действует»
• Курс обмена бонусов: ✓ «Активен» — если хотите явно прописать «1 бонус = 1 ₽». Можно оставить выключенным, тогда курс по умолчанию.

Опционально:

• Приветственный бонус — начисление новым гостям при регистрации.
• Уведомления при изменении баланса → ✓ «Отправлять push гостям» + ✓ «Webhook» (для связи обратно с Misea, см. Шаг 4).

Нажмите «Сохранить».

Шаг 3. Настройте акции (правила начисления и списания)

Программа без акций — это пустой кошелёк. Касса не сможет начислить или списать бонусы, потому что не знает по какому правилу.

В iiko.biz → iikoCard → Программы → «Кешбэк Misea» → раздел «Маркетинговые акции». Создайте две акции:

Акция 1 — начисление кешбэка

• Название: «Кешбэк 5%»
• Условие: «При оплате заказа» (или «При создании заказа», зависит от вашей бизнес-логики)
• Действие: «Пополнить счёт на процент от заказа» = 5% (или сколько хотите)
• При необходимости — ограничения: минимальный чек, исключённые категории блюд

Акция 2 — оплата бонусами

• Название: «Оплата бонусами»
• Условие: «Гость хочет оплатить со счёта»
• Действие: «Оплата со счёта»
• Лимит: например, не более 50% от чека (защита от полной оплаты бонусами)

После создания акций касса будет автоматически предлагать обе операции при работе с гостем.

Шаг 4. Прописать webhook URL (для синхронизации обратно)

Чтобы Misea знала о списаниях/начислениях на кассе (а не только наоборот) — пропишите webhook URL.

1. В iiko.biz → iikoCard → Программы → Кешбэк Misea → редактировать.
2. В блоке «Уведомления» → ✓ «Отправлять гостям уведомление на webhook при изменении баланса».
3. Найдите поле для URL webhook'а — впишите:

https://api.misea.ru/api/v1/iiko/webhooks/balance?token=<ВАШ_СЕКРЕТ>

Секрет (token=...) для вашего тенанта запросите у поддержки Misea — он генерируется при подключении интеграции iiko. Это защита от подделки уведомлений: только запросы с правильным токеном принимаются.

После сохранения попросите кассира провести тестовое списание 1 бонуса в iikoFront → проверьте в Misea (/loyalty/participants → найти гостя) что баланс уменьшился. Если работает — синхронизация полная.

Шаг 5. Проверка на кассе

Создайте тестовый чек:

1. iikoFront → новый заказ.
2. Кнопка «Гость» → введите 13-значный номер карты гостя вручную или поднесите его iPhone с открытой Apple Wallet картой к сканеру штрих-кодов.
3. На экране должно появиться имя гостя и его баланс.
4. При закрытии чека — должны появиться кнопки «Начислить бонусы» и (если у гостя есть баланс) «Оплатить бонусами».

Если что-то из этого не отображается — см. раздел «Решение проблем» ниже.

Что Misea делает автоматически (вам ничего не нужно)

• Создаёт контрагента в iikoCard при первой операции с балансом или при первом заказе.
• Привязывает виртуальную карту (13-значный номер) к контрагенту.
• Обновляет имя, фамилию, отчество, телефон, email, дату рождения — когда гость заполняет профиль через гостевое приложение или вы редактируете его в Misea.
• При любом изменении баланса в Misea — синхронизирует с iiko-кошельком (через topup или chargeoff).
• При получении webhook'а от iiko — обновляет баланс в Misea и пересобирает карту в Apple Wallet.

То есть весь Misea-pipeline работает «из коробки» после шагов 1–4 выше. Ничего настраивать в самой Misea не нужно.

Решение проблем

На кассе видно имя гостя, но кнопок «бонусы» нет

→ Не созданы акции (см. Шаг 3). Программа должна содержать как минимум одну акцию типа «начисление» и одну типа «оплата».

Касса говорит «Гость не найден» по номеру карты

→ Проверьте в iiko.biz → iikoCard → Гости что контрагент с таким номером есть. Если нет — попросите гостя сделать любое действие в Misea (например, открыть гостевое приложение), это триггернёт автоматический push в iiko.

Сканер не читает QR с экрана iPhone

→ Часть старых лазерных сканеров не читают экранные коды. Workaround: вводить номер карты руками (он есть на самой карте мелким текстом под QR). Долгосрочно — заменить сканер на image-sensor модель.

Webhook не приходит

→ Проверьте в iiko.biz → iikoCard → Программы что галка «webhook при изменении баланса» сохранена. URL должен точно совпадать с тем что выдала поддержка Misea. Уведомления приходят только когда баланс действительно изменился (operation на кассе) — простое создание заказа без оплаты не триггерит.

Ошибка «Organization not found» в логах

→ Это значит iikoCard CRM ещё не зарегистрирован для вашей организации (Шаг 1 не завершён). Перепроверьте «Диагностику подключения» — все строки должны быть зелёные.

Дополнительно

• Бонусы и кешбэк в Misea — настройки на стороне Misea (% начисления, лимиты, срок жизни).
• Карта лояльности в Apple Wallet — конструктор дизайна карты.
• Интеграция iiko — обзор — общая архитектура связки.

Если что-то не получается — напишите в поддержку Misea, приложите скрин «Диагностика подключения» из iikoOffice. Это покрывает 90% типичных проблем.