Recca Разработчикам
Меню

Реферальные программы

Коды, погашение и откат: реферальные программы в вашем продукте.

Реферальная программа сети — набор правил «что получает приведённый и что получает привёдший». Участники сети получают личные коды, приведённый вводит код при покупке, а ваш сервер сообщает Recca об оплате и при возврате отменяет начисление. Все методы — https://api.recca.ru/federation/v1/… с ключом в X-Recca-Tenant-Key.

Правила самих программ (размер скидки и вознаграждения, глубина каскада, кому доступна программа) настраиваются в кабинете, через API они только читаются.

Как это связано

  1. Программа — правила. Читаются методом GET /federation/v1/promo/programs.
  2. Код — личный (один на участника и программу) или кампанейный (без привёдшего, выпускает владелец сети).
  3. Проверка — POST /federation/v1/promo/validate: годится ли код сейчас и что он даёт.
  4. Погашение — POST /federation/v1/conversions с кодом: фиксирует оплату и начисляет вознаграждение каскадом.
  5. Откат — 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_FOUND404кода нет в вашей сети
CODE_INACTIVE, CODE_NOT_STARTED, CODE_EXPIRED, CODE_EXHAUSTED409код выключен, ещё не начал действовать, истёк или исчерпан
SELF_REFERRAL409клиент — сам привёдший
PROGRAM_INACTIVE409программа выключена
REDEMPTION_NOT_FOUND404погашение с таким идентификатором в вашей сети не найдено
ATTRIBUTION_TOKEN_NOT_FOUND404токен не соответствует проверенному погашению
ATTRIBUTION_TOKEN_MISMATCH403токен выдан другому клиенту
REDEMPTION_REVERSED409прежнее погашение уже отменено и повторно не используется
INVALID_COMMISSION_CONFIG400настройки вознаграждения сети не складываются в пригодный каскад; причина на стороне сети
NO_REFERRER_TO_REWARD409кампанийный код с анонимным получателем: награждать и приписывать конверсию некому
LEG_AMOUNT_MISMATCH409нога каскада уже есть с другой суммой; повторный расчёт дал иное число, и отчитываться о неначисленных деньгах нельзя
TENANT_HAS_NO_SHOP500у сети нет витрины, к которой привязать бонусный счёт; причина на стороне сети

Вознаграждение распределяется по уровням каскада в пределах глубины программы; ранги участников (множители) считаются на момент начисления.

Откат

При возврате денег вызовите 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. Участник должен быть в вашей сети.

См. также