Как подключить API Анкоры к своей системе

API — способ подключить к программе лояльности любую систему, для которой нет готовой интеграции: свою кассу, 1С, CRM, сайт или сценарий в Zapier и Make. Через API внешняя система находит клиента по телефону или QR карты, проводит продажу со скидкой и списанием бонусов, возвращает покупки, продаёт абонементы и подписки. А вебхуки сами присылают ей новых клиентов и каждую операцию по карте.

Запросы к API пишет разработчик — по документации с примерами. От владельца нужно три вещи: включить API, передать ключ и решить, какие операции ключу разрешить.

Шаг 1. Включите API

В кабинете откройте «Интеграции» → «API и Zapier» и нажмите «Включить API». Анкора создаст ключ доступа — длинную строку, которая начинается с ak_.

Шаг 2. Передайте ключ разработчику

Ключ — в блоке «Ключ доступа». Передавайте его только тем, кто настраивает интеграцию, и не размещайте в коде сайта или мобильного приложения: ключ открывает доступ ко всей клиентской базе.

Шаг 3. Решите, что открыть ключу

Чтение, начисление за покупки, списание бонусов, штампы, абонементы, подписки и визиты работают с любым ключом. Две группы операций обходят правила программы, поэтому выключены — их включают в блоке «Права ключа»:

• «Управление балансами» — начисление вручную, установка и корректировка кэшбэка, баллов и штампов, изменение суммы покупок для ступеней. Нужно, например, чтобы перенести балансы из старой программы лояльности.
• «Возвраты и отмены» — возврат покупки, возврат абонемента, отмена подписки. Нужно кассе, которая проводит возвраты.

Не уверены — оставьте выключенными: внешняя система получит понятную ошибку, и право можно включить позже.

Шаг 4. Проверьте подключение

Первый запрос разработчика — GET /account. Он вернёт название бизнеса, состояние подписки и то, разрешены ли сейчас операции. Если подписка Анкоры закончилась, чтение продолжит работать, а начисления и списания будут отклоняться, пока подписка не продлена.

Шаг 5. Подключите вебхуки, если нужны

Вебхуки нужны, когда внешняя система должна узнавать о событиях сразу: CRM — о новом клиенте, сайт — об изменении баланса. В блоке «Вебхуки» укажите адрес вашей системы (только https), выберите события и нажмите «Добавить подписку». Кнопка «Отправить тестовое событие» сразу покажет, принимает ли адрес запросы, а «Последние доставки» — что и когда ушло.

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

Шаг 6. Следите за журналом

Кнопка «Журнал» вверху страницы показывает каждое начисление, списание и отказ с причиной: клиент не найден, не хватило бонусов, операция выключена в правах ключа. Журнал хранится 14 дней.

Что умеет API

• Клиенты и карты: вся база с балансами, профиль клиента, поиск по телефону и номеру карты, создание и правка клиента.
• Покупки: продажа одним запросом — скидка по ступени, списание кэшбэка и баллов, начисление с оплаченной суммы — и возврат по номеру чека.
• Бонусы: начисление и списание кэшбэка и баллов, штампы и награды.
• Абонементы, подписки и визиты статуса гостя — те же операции, что у кассира.
• Справочники: все настройки механик программ, точки продаж, акции.
• История операций и вебхуки о новых клиентах, изменениях профиля и операциях.

Повтор запроса после сбоя связи не спишет бонусы второй раз: у покупок есть номер чека, у остальных операций — ключ повтора. Подробности, примеры запросов, ответов и ошибок — в документации API.