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

Федерация (tenant API)

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

Федеративная дверь — это серверное API сети: вы заводите своих людей в Recca, передаёте заявки и конверсии и читаете то, что сеть о них знает. Адреса — https://api.recca.ru/federation/v1/…, доступ по ключу в заголовке X-Recca-Tenant-Key (см. «Ключи, права и лимиты»). Для денежной CPA-сети есть отдельная дверь /federation/v1/cpa/* — она описана в разделе «CPA-API».

Модель: сеть, участник, суррогат

Каждый ваш пользователь становится участником сети. Recca выдаёт ему суррогат tenant_recca_id — 16 символов, свой для каждой сети. Храните его рядом со своей записью о человеке и подставляйте в пути /federation/v1/users/{id}/…. Сырой внутренний идентификатор Recca тоже принимается, но признан устаревшим (заголовки Deprecation/Sunset, срок — до 31.12.2026).

Видно вам только то, что относится к вашей сети: участники, вступившие через вас, их заявки и конверсии. Участник другой сети отвечает 403 USER_NOT_MEMBER_OF_TENANT (или NOT_A_MEMBER на методах ассетов — это один и тот же отказ, обрабатывайте оба) либо 404 NOT_FOUND. Почта человека в ответах скрыта и появляется только при праве profile:email, которое самообслуживанием не выдаётся.

Пользователи

POST /federation/v1/users/upsert (право users:upsert) заводит человека или находит существующего и возвращает суррогат. Нужен хотя бы один способ опознать человека и first_name.

ПолеЧто это
email, email_verifiedпочта и признак, что вы её подтвердили
vk_id, yandex_id, telegram_idвнешние идентификаторы, до 50 символов
phoneтелефон в формате E.164
first_name, last_name, avatar_url, screen_name, marketing_consentпрофиль
recca_refреферальная метка из формы регистрации: ставит человека в реферальное дерево под привёдшим

Ответ: 201, если человек создан, и 200, если найден. В data — tenant_recca_id, is_new, claim_required и profile. Одну почту нельзя привязать к двум разным людям: конфликт даст 409 EMAIL_BELONGS_TO_DIFFERENT_USER (для телефона — PHONE_BELONGS_TO_DIFFERENT_USER).

curl -s -X POST https://api.recca.ru/federation/v1/users/upsert \
  -H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"anna@example.com","email_verified":true,"first_name":"Анна"}'

Чтение:

  • GET /federation/v1/users — список участников, skip/take (до 100), право profile:read;
  • GET /federation/v1/users/{id} — профиль участника с tenant_recca_id, право profile:read;
  • GET /federation/v1/shops — витрины сети, право shops:read.

Заявки

POST /federation/v1/leads (право leads:write) принимает заявку с вашего сайта: обязательны recca_ref (метка привёдшего) и external_id (ваш номер заявки, до 200 символов), дополнительно lead_source, metadata и контакт заявителя (name, phone в E.164, email, внешние идентификаторы). Повтор с тем же external_id возвращает 200 и idempotent: true, первый вызов — 201.

Чтение: GET /federation/v1/leads/{id} (право leads:read) и GET /federation/v1/users/{id}/leads (право users:read, параметры skip, take, status) — заявки, привязанные к участнику.

Конверсии и откат

POST /federation/v1/conversions (право conversions:write) фиксирует событие, за которое начисляется вознаграждение. Обязательны event_type, external_id (ваш номер события) и amount_rub (число). Привязка к привёдшему задаётся одним из двух способов:

  • recca_ref — метка из реферальной ссылки (поток по реферальному дереву);
  • promo_code или attribution_token вместе с user_id — поток реферальных программ (см. «Реферальные программы»).

Нельзя передавать recca_ref вместе с promo_code/attribution_token. external_id не должен начинаться с recca: — это пространство платформы (400 RESERVED_EXTERNAL_ID). Повтор с тем же external_id идемпотентен: 200 вместо 201. В ответе — conversion_id, idempotent, суммы каскада (cascade_amount_rub, cascade_legs_count, legs) и attribution_source.

POST /federation/v1/conversions/{external_id}/reverse (право conversions:reverse) откатывает конверсию целиком или частично. Тело: reason (обязательно, до 500 символов), amount_to_reverse (необязательно; без него откатывается всё) и reversal_id (имя частичного отката: латиница, цифры и _.:-, до 64 символов). Типичные отказы: 404 CONVERSION_NOT_FOUND, 409 NOT_REVERSIBLE, 400 AMOUNT_EXCEEDS_ORIGINAL.

Балансы, дерево, бонусы

  • GET /federation/v1/users/{id}/bonus-balance (право bonuses:read) — разбивка по валютам, total_available_rub и total_wallet_cleared_rub. Деньги читает отдельное право, promo:read баланс не открывает.
  • GET /federation/v1/users/{id}/tree (право users:read) — нисходящее реферальное дерево по уровням. Параметр depth — от 1 до 5. В ответе levels, total_downline, depth_used, а если дерево обрезано по глубине — hit_depth_cap: true.
  • GET /federation/v1/users/{id}/tree/stats (право users:read) — сводные числа по дереву.

Офферы, бейджи, материалы

  • GET /federation/v1/offers и GET /federation/v1/offers/{id} (право offers:read) — каталог предложений видимых витрин; фильтры shop_id и q.
  • GET /federation/v1/badges, POST /federation/v1/badges, GET|PATCH|DELETE /federation/v1/badges/{id}, POST /federation/v1/badges/{id}/request-public — бейджи партнёрства (права badges:read и badges:write).
  • GET /federation/v1/assets и POST /federation/v1/assets/{id}/download (право promo:read) — промо-материалы.

Сессия для виджетов и ссылки

  • POST /federation/v1/users/{id}/embed-session (право users:impersonate) выдаёт короткий токен (expires_in — 600 секунд) для встраиваемых виджетов от имени участника вашей сети. Подробности — в разделе «JS и виджеты».
  • POST /federation/v1/users/{id}/referral-links (право users:impersonate) создаёт реферальную ссылку участника на оффер; в теле обязателен offer_id.

Вебхуки

Обратный канал — вебхуки с событиями сети (заявки, бонусы, конверсии): адрес и секрет задаются в кабинете, подпись и повторы описаны в разделе «Вебхуки».

Идемпотентность и повторы

Все записи, у которых есть ваш external_id, безопасно повторять: сеть узнаёт событие по паре «ваша сеть + external_id». Повторяйте запрос при 429, 500 и сетевых сбоях, сохраняя тот же external_id; на 4xx кроме 429 повтор бесполезен, пока вы не исправите запрос.

См. также