API программ лояльности

Программы лояльности в МойСклад — это бонусные баллы, приветственные начисления и накопительные скидки, привязанные к контрагенту. Через JSON API 1.2 вы управляете ими сущностями bonusprogram и bonustransaction. Разберём модель данных, начисление и списание баллов и интеграцию с розничными продажами.

Модель лояльности в МойСклад

Лояльность строится вокруг трёх объектов. Программа лояльности (bonusprogram) задаёт правила: сколько баллов начисляется за покупку и сколько можно списать. Бонусная транзакция (bonustransaction) фиксирует каждое движение баллов. А накопленный баланс лежит в поле контрагента.

Такое разделение даёт аудируемость: по сумме завершённых транзакций всегда можно восстановить баланс и объяснить, откуда взялась каждая единица баллов. Это критично для сверок с внешними системами и для разбора спорных ситуаций с покупателями.

Программа лояльности: bonusprogram

Список программ доступен по адресу GET /api/remap/1.2/entity/bonusprogram. В программе описаны ключевые параметры начисления и списания баллов:

• active — включена ли программа;
• welcomeBonusesEnabled — приветственные баллы новым участникам;
• ставки начисления и лимиты списания на покупку;
• agentTags — группы контрагентов, на которых распространяется программа.

Одновременно может быть активна одна бонусная программа — это упрощает расчёт, но требует внимания при миграции правил. Прежде чем начислять баллы, проверьте, что нужная программа существует и active.

Начисление и списание: bonustransaction

Каждое движение баллов — отдельная бонусная транзакция. Создаётся POST /api/remap/1.2/entity/bonustransaction. Ключевые поля:

• transactionType — EARNING (начисление) или SPENDING (списание);
• bonusValue — количество баллов;
• agent — ссылка на контрагента (meta);
• bonusProgram — ссылка на программу;
• categoryType — REGULAR или WELCOME.

Пример тела начисления:

{"transactionType":"EARNING","bonusValue":150,"agent":{"meta":{...}},"bonusProgram":{"meta":{...}}}

У транзакции есть статус (transactionStatus): например, COMPLETED для завершённых. Баланс bonusPoints контрагента пересчитывается на основе завершённых транзакций.

Лояльность в рознице

В точке продаж баллы начисляются и списываются автоматически при оформлении розничной продажи (retaildemand). Если вы строите свою кассу через POS API, лояльность нужно связать с чеком.

1. идентифицируете покупателя — находите контрагента (по телефону, карте, штрихкоду);
2. рассчитываете доступные к списанию баллы по правилам программы;
3. применяете списание/начисление в момент закрытия чека;
4. создаёте бонусные транзакции, привязанные к продаже.

Важно соблюдать лимиты: программа ограничивает максимальную долю чека, оплачиваемую баллами. Эти лимиты берите из bonusprogram, а не зашивайте в код.

Фильтрация и отчётность по баллам

JSON API 1.2 позволяет выбирать транзакции по контрагенту и периоду через параметр filter. Это основа отчётов по лояльности:

GET /entity/bonustransaction?filter=agent=https://api.moysklad.ru/api/remap/1.2/entity/counterparty/{id}

• фильтр по moment — движения баллов за период;
• фильтр по transactionType — отдельно начисления и списания;
• order и limit/offset — пагинация больших выборок.

Приветственные баллы и статусы транзакций

Помимо начислений за покупку, программа умеет дарить приветственные баллы. Они включаются флагом welcomeBonusesEnabled в bonusprogram и создаются транзакцией с categoryType = WELCOME. Так вы мотивируете покупателя вступить в программу и сразу использовать баллы.

У бонусной транзакции есть жизненный цикл, отражённый в transactionStatus:

• для корректной отмены начисления создавайте компенсирующую транзакцию, а не удаляйте исходную задним числом;
• при возврате товара списанные баллы возвращаются обратной транзакцией;
• всегда сверяйте итоговый баланс с суммой завершённых транзакций.

Интеграция с внешними системами

Чаще всего лояльность синхронизируют с сайтом или CRM: покупатель видит баланс баллов в личном кабинете, а начисления с онлайн-заказов попадают в МойСклад.

Для near-real-time синхронизации подпишитесь на вебхуки по bonustransaction и counterparty — тогда изменения баланса в МойСклад мгновенно долетают до сайта.

Итог

API программ лояльности МойСклад — это связка из bonusprogram (правила), bonustransaction (движения) и баланса контрагента. Управлять баллами нужно только транзакциями, соблюдать лимиты программы и не трогать производный баланс напрямую. Для интеграции с сайтом и кассой пригодятся фильтры и вебхуки.

Мы разрабатываем такие интеграции на стороне 1С-Битрикс и внешних сервисов: личный кабинет с балансом баллов, начисление за онлайн-заказы, оплата баллами и синхронизация через вебхуки. Спроектируем модель лояльности так, чтобы баланс на сайте и в МойСклад всегда сходился.