Реферальные программы
Коды, погашение и откат: реферальные программы в вашем продукте.
Реферальная программа сети — набор правил «что получает приведённый и что получает привёдший». Участники сети получают личные коды, приведённый вводит код при покупке, а ваш сервер сообщает Recca об оплате и при возврате отменяет начисление. Все методы — https://api.recca.ru/federation/v1/… с ключом в X-Recca-Tenant-Key.
Правила самих программ (размер скидки и вознаграждения, глубина каскада, кому доступна программа) настраиваются в кабинете, через API они только читаются.
Как это связано
- Программа — правила. Читаются методом
GET /federation/v1/promo/programs. - Код — личный (один на участника и программу) или кампанейный (без привёдшего, выпускает владелец сети).
- Проверка —
POST /federation/v1/promo/validate: годится ли код сейчас и что он даёт. - Погашение —
POST /federation/v1/conversionsс кодом: фиксирует оплату и начисляет вознаграждение каскадом. - Откат —
POST /federation/v1/conversions/{external_id}/reverse: возвращает начисленное при возврате денег.
Права ключа: promo:read (программы, коды участника, материалы), promo:issue (выпуск личного кода), promo:validate (проверка), conversions:write (погашение), conversions:reverse (откат), bonuses:read (баланс).
Программы
GET /federation/v1/promo/programs (право promo:read) возвращает активные программы вашей сети, до 100, по убыванию приоритета. Для каждой — id, name, slug, unit, discount_for_referee, referee_gift, reward_for_referrer, currency, cascade_depth, eligibility, eligible_member_tier_ids, priority, valid_from, valid_until, code_generation_policy. Единица unit — percent, days или fixed_amount.
Коды
Выпуск личного кода. POST /federation/v1/promo/issue (право promo:issue), тело { "user_id": "…", "program_id": "…" }; program_id необязателен — тогда берётся самая приоритетная действующая программа, подходящая участнику по рангу. Метод идемпотентен: повтор для той же тройки (сеть, участник, программа) возвращает тот же код.
{ "success": true, "data": { "code": "ABC0123XYZ", "program_id": "trprog_…", "code_id": "…", "created": true, "link": "https://app.recca.ru/r/ABC0123XYZ" } }
Отказы: 403 USER_NOT_MEMBER_OF_TENANT (участник не в вашей сети), 404 NO_ELIGIBLE_PROGRAM, 404 PROGRAM_NOT_FOUND, 409 PROGRAM_INACTIVE, а также 403 CODE_ISSUED_BY_OWNER и 403 CODE_NOT_AVAILABLE_YET: у программы выключена выдача кодов по запросу — их выпускает владелец, ждать придётся его.
Чтение кодов участника. GET /federation/v1/users/{id}/promo-codes (право promo:read).
Ссылка на оффер. Для реферальной ссылки не на программу, а на конкретный оффер используйте POST /federation/v1/users/{id}/referral-links (право users:impersonate): тело { "offer_id": "…" }.
Проверка кода
curl -s -X POST https://api.recca.ru/federation/v1/promo/validate \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" -H "Content-Type: application/json" \
-d '{"code":"ABC0123XYZ","user_id":"<tenant_recca_id клиента>"}'
code обязателен, user_id — суррогат клиента (нужен, чтобы отсечь самореферал). Ответ всегда 200, годность — в поле valid:
valid: true— приходятprogram_id,unit,discount_value, а такжеcurrency,attribution_tokenиexpires_at, если они есть. Скидку по этим данным применяет ваша корзина — логика корзины остаётся на вашей стороне.valid: false— приходитreason:not_found,inactive,not_started,expired,exhausted,self_referral,program_inactive,rate_limited.
attribution_token связывает проверку с последующей оплатой, и необработанный код не нужно повторно передавать. Токен привязан к клиенту: чужой токен вернёт 403 ATTRIBUTION_TOKEN_MISMATCH.
Погашение
После оплаты сообщите о ней конверсией:
curl -s -X POST https://api.recca.ru/federation/v1/conversions \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" -H "Content-Type: application/json" \
-d '{"event_type":"purchase","external_id":"order-1001","amount_rub":5000,"user_id":"<tenant_recca_id клиента>","attribution_token":"<токен из validate>"}'
Обязательны event_type, external_id, amount_rub и user_id; привязка — promo_code или attribution_token (вместе с recca_ref их передавать нельзя). Ответ 201 при создании и 200 при повторе с тем же external_id (idempotent: true). В data: conversion_id, redemption_id, program_id, cascade_amount_rub, cascade_legs_count, legs, partner_user_id, attribution_source: "tenant_referral". Повтор того же external_id с другой суммой вернёт 409 IDEMPOTENT_MISMATCH.
Отказы погашения, на которые стоит ветвиться:
| Код | Статус | Смысл |
|---|---|---|
CODE_NOT_FOUND | 404 | кода нет в вашей сети |
CODE_INACTIVE, CODE_NOT_STARTED, CODE_EXPIRED, CODE_EXHAUSTED | 409 | код выключен, ещё не начал действовать, истёк или исчерпан |
SELF_REFERRAL | 409 | клиент — сам привёдший |
PROGRAM_INACTIVE | 409 | программа выключена |
REDEMPTION_NOT_FOUND | 404 | погашение с таким идентификатором в вашей сети не найдено |
ATTRIBUTION_TOKEN_NOT_FOUND | 404 | токен не соответствует проверенному погашению |
ATTRIBUTION_TOKEN_MISMATCH | 403 | токен выдан другому клиенту |
REDEMPTION_REVERSED | 409 | прежнее погашение уже отменено и повторно не используется |
INVALID_COMMISSION_CONFIG | 400 | настройки вознаграждения сети не складываются в пригодный каскад; причина на стороне сети |
NO_REFERRER_TO_REWARD | 409 | кампанийный код с анонимным получателем: награждать и приписывать конверсию некому |
LEG_AMOUNT_MISMATCH | 409 | нога каскада уже есть с другой суммой; повторный расчёт дал иное число, и отчитываться о неначисленных деньгах нельзя |
TENANT_HAS_NO_SHOP | 500 | у сети нет витрины, к которой привязать бонусный счёт; причина на стороне сети |
Вознаграждение распределяется по уровням каскада в пределах глубины программы; ранги участников (множители) считаются на момент начисления.
Откат
При возврате денег вызовите POST /federation/v1/conversions/{external_id}/reverse с external_id исходной конверсии и телом { "reason": "возврат по заказу 1001" }. Без amount_to_reverse откатывается вся конверсия; с ним — часть (каждое следующее частичное отменяйте со своим reversal_id). Ответ: conversion_id, status, reversed_amount_rub, legs, unreversed_legs, idempotent. Повтор безопасен. Если по какой-то ноге выплата уже прошла, автоматически её не отменить (деньги ушли за пределы платформы): такая нога попадает в unreversed_legs, а status становится partial_reversed.
Отказы: 404 CONVERSION_NOT_FOUND, 409 NOT_REVERSIBLE, 400 AMOUNT_EXCEEDS_ORIGINAL, 500 REVERSAL_FAILED (повтор оправдан).
Баланс участника
GET /federation/v1/users/{id}/bonus-balance (право bonuses:read) показывает начисленное по валютам, total_available_rub и total_wallet_cleared_rub. Участник должен быть в вашей сети.
См. также
- Федерация (tenant API) — методы федерации и суррогаты
- Ключи, права и лимиты — права и лимиты ключа
- Вебхуки — события о конверсиях и откатах
- Быстрый старт — первый вызов