Федерация (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 повтор бесполезен, пока вы не исправите запрос.
См. также
- Ключи, права и лимиты — права ключа и коды ошибок
- Реферальные программы — реферальные программы поверх федерации
- Вебхуки — события федерации
- CPA-API — машинная дверь CPA-сети
- Справочник OpenAPI — описание методов