CPA-API
Партнёры, офферы, ссылки, клики, конверсии, выплаты и статистика сети.
Аудитория: разработчик интеграции на стороне CPA-сети. Машиночитаемая форма контракта — OpenAPI.
1. Что здесь есть и чего здесь нет
Дверь даёт расчётный слой: партнёры, офферы, ссылки, клики, конверсии, балансы, выплаты, статистика, вебхуки. Ваши люди — рекламодатели, рекрутёры, вебмастеры, инфлюенсеры — работают на вашем сайте и о Recca не знают.
Операторская работа остаётся в кабинете Recca (app.recca.ru), и это
выбор формы сделки, а не пробел в API. Что именно — раздел 13.
2. Аутентификация
POST /federation/v1/cpa/conversions HTTP/1.1
Host: api.recca.ru
X-Recca-Tenant-Key: <ключ арендатора>
Content-Type: application/json
Ключ выдаётся один раз в открытом виде; у нас хранится только его хеш. Организация выводится из ключа — слага в адресах нет, и перебрать чужие сети нельзя по построению.
⚠⚠ Ключ доверенный, и разграничение по людям — ваша работа. Один ключ
адресует любого вашего партнёра параметром partner_external_id. Мы не знаем,
кто из ваших пользователей сейчас за экраном, и проверить не можем. Отсюда два
следствия, и оба обязательны:
- Ключ не предназначен для браузера вашего пользователя. Он живёт на вашем сервере. Положив его во фронтенд, вы отдадите каждому блогеру доступ к данным всех остальных.
- Ваш сервер обязан не пускать блогера A к данным блогера B. Это модель B (headless).
Три причины закрытой двери различаются намеренно:
| Ответ | Значит |
|---|---|
401 MISSING_TENANT_SCOPE | ключа нет, он пуст или отозван |
403 INSUFFICIENT_SCOPE | ключ есть, права на этот метод у него нет |
403 FEATURE_NOT_AVAILABLE | продукт «CPA-сеть» не подключён |
403 PRODUCT_PAUSED | продукт подключён, но приостановлен (обычно — неуплата) |
3. Граница персональных данных
Через границу не проходит ни имя, ни почта, ни телефон, ни адрес — ни
партнёра, ни его клиента. В Recca живут непрозрачный external_id, суммы и
факты.
| Вы присылаете | Мы храним |
|---|---|
external_id партнёра | его, как есть |
external_id заказа | его, как есть |
суммы, цели, страну, sub_id | их |
| имя, почту, телефон, ФИО, реквизиты | никогда |
Практические следствия:
- свободные поля (
external_id,sub_id…sub_id_10— до десяти,metadata) имеют объявленный алфавит и длину; значение вне алфавита отбивается400 INVALID_INPUT, распознанное персональное —400 PII_NOT_ACCEPTED; - ⚠ проверка ограничивает форму, а не смысл: строка вроде
79991234567алфавит проходит. Обязательство не присылать персональные данные — договорное; - читаемые подписи партнёров в операторском кабинете подгружает браузер оператора запросом к вашему резолверу. Наш сервер к нему не ходит и ваших имён не видит ни в памяти, ни в журналах, ни в резервной копии;
- ⚠⚠ поэтому «непрозрачный ярлык, чтобы оператор узнавал блогера» мы тоже НЕ
принимаем: поле
display_labelотбивается400 PII_NOT_ACCEPTEDнаравне с почтой. Это выглядит избыточным и таковым не является —ivan_petrovопределяет человека, а ник инфлюенсера и есть его публичная личность, и принять поле «на всякий случай» значило бы завести у нас хранилище персональных данных, которым никто не пользуется. Отказ приходит на первом же вызове, а не обнаруживается через месяц по тому, что ярлыки никуда не доезжают; - договоры, ИНН и паспорта партнёров остаются у вас — гейт подписанного договора на выплате у нас по умолчанию выключен.
⚠ Полезное следствие для вас: наша утечка не стоит ничего без вашего
справочника. Дамп даёт строку «blg_8f3a заработал 4 200 ₽» — утверждение
без субъекта. И обратное: уничтожив у себя отображение external_id → человек,
вы обезличиваете наши данные задним числом, во всех копиях сразу.
4. Конверт ответа
Успех:
{
"success": true,
"data": { "…": "…" },
"meta": { "request_id": "req_01K5…", "total": 1, "count": 1, "offset": 0, "limit": 20 }
}
Отказ:
{
"success": false,
"error": { "code": "WINDOW_EXPIRED", "message": "attribution window has expired", "details": null },
"meta": { "request_id": "req_01K5…" }
}
meta.request_idприходит и на успехе, и на отказе. Он же уходит в заголовкеX-Request-Id. Сообщая о проблеме, называйте его: по нему находится вся цепочка на нашей стороне. ⚠ Два отказа формируются до того, как запрос дойдёт до метода, и тела сmetaу них нет: «ключ не предъявлен» (401) и «исчерпан бюджет» (429). Идентификатор там всё равно есть — в заголовкеX-Request-Id, который ставится раньше всего прочего. Читайте его из заголовка, а не из тела, и он найдётся в любом ответе, включая те, что формирует не наш код.- Ветвитесь по
error.code, а не поmessage. Текст сообщения — диагностика для человека, он меняется. Полный перечень кодов — раздел 12. - Тела запросов разбираются строго: неизвестное поле —
400 INVALID_INPUT. Молча проглоченная опечатка в имени поля означала бы операцию, прошедшую не так, как вы думали, и узнали бы вы об этом по деньгам.
5. Величины контракта
Числа ниже взяты из кода двери. Версия контракта отдаётся в GET /federation/v1/cpa/self.
| Величина | Значение |
|---|---|
| Бюджет запросов на ключ, гарантированный минимум | 1000 в минуту |
Бюджет при plan_tier уровня организации | 3000 в минуту |
| Фактический бюджет вашего ключа | поле rate_limit_per_min в GET /federation/v1/cpa/self |
| Окно свежести подписи постбэка | 5 мин в обе стороны |
| Окно допуска подписи вебхука | 300 с в обе стороны |
Потолок sum_rub | 10 000 000 ₽ |
Предел sub_id и external_id конверсии | 200 символов |
Предел external_id партнёра | 64 символа, алфавит [A-Za-z0-9_.:-] |
Зарезервированный префикс external_id | recca: |
⚠ Бюджет запросов считается по организации, а не по адресу отправителя:
несколько ваших серверов делят общий счёт. Ответ 429 несёт Retry-After в
секундах и заголовки X-RateLimit-Limit / X-RateLimit-Remaining; берите
паузу из заголовка, а не из своей константы. Проба живости GET /federation/v1/cpa/self в
счёт не входит — иначе мониторинг тратил бы ваш бюджет.
⚠ Окно — 60 секунд от вашего первого запроса, а не календарная минута: арендаторы не сбрасываются одновременно. Счёт атомарный, то есть объявленный порог и есть применяемый.
⚠⚠ Две строки про бюджет в таблице выше — разные величины, и нужна вам
вторая. Гарантированный минимум — то, что мы обещаем при любом раскладе;
3000 — потолок при plan_tier уровня организации. От чего порог зависит
сегодня, это plan_tier, а не подключённый продукт, и совпадают они не
всегда. Поэтому единственный ответ на «сколько именно у меня» —
rate_limit_per_min в ответе GET /federation/v1/cpa/self и заголовок X-RateLimit-Limit:
оба приходят из той же функции, которая принимает решение о 429. Нужен
порог выше — напишите нам, поднимается он по письменному запросу.
6. Идемпотентность
Ключ идемпотентности в теле запроса, а не в заголовке. Заголовочный
Idempotency-Key мы не заводим: у нас уже был SDK, ставивший его на каждый
POST, — и ни один роут его не читал. Механизм, который выглядит существующим и
ничего не делает, хуже отсутствующего.
| Операция | Ключ | Повтор |
|---|---|---|
| Конверсия | (сеть, external_id, goal) | возвращает ту же конверсию |
| Выплата | (partner_external_id, period_from..period_to); amount_rub сверяется, в ключ не входит | возвращает ту же заявку; с другой суммой — 409 IDEMPOTENT_MISMATCH |
| Клик | client_click_id, необязателен | без него каждый вызов — новый клик |
⚠⚠ Повтор с другими параметрами — это 409 IDEMPOTENT_MISMATCH, а не
успех. Примитив, молча возвращающий существующую операцию под другую сумму,
отчитывается о деньгах, которых в кошельке нет. Хотите другую сумму — это
другая операция, у неё другой ключ.
⚠ У выплаты сумма в ключ не входит — входит период. Прежняя редакция этой
таблицы называла сумму частью ключа и противоречила сама себе: будь она в
ключе, заявка на другую сумму за тот же период была бы новой операцией, и
IDEMPOTENT_MISMATCH не случался бы никогда.
⚠ Ключ конверсии не меняется. Цель с включённым «несколько
конверсий с одного клика» не трогает строку таблицы выше: повтор того же
заказа по-прежнему схлопывается в тройку (сеть, external_id, goal), а
ВТОРОЙ заказ той же цели — это другая конверсия со своим external_id, не
повтор.
Повтор и переход конверсии — разные вещи. Повтор — тот же номер заказа с
запросом, который уже исполнен: тот же статус либо статус, до которого
конверсия уже дошла. Подтверждение (approved) ставит конверсию в холд, а по
его истечении она становится доступной к выплате; то же подтверждение,
досланное после холда, — повтор: 200, та же конверсия, деньги не
двигаются . Смена статуса, которой ещё не было, — переход, и
сумму на нём передавать можно: заказ в ожидании (pending) подтверждается
итоговой суммой. Недопустимый переход — 409 ILLEGAL_TRANSITION: отменённую
конверсию не подтвердить, подтверждённую не вернуть в ожидание.
⚠ Клик идемпотентным по умолчанию не является, и это сказано прямо: два
перехода одного человека — два клика, а не один. Если ваш фронт может
продублировать вызов, пришлите свой client_click_id.
7. Три состояния поля, а не два
У goal и sum_rub различаются «не передали», «передали пустым» и
«передали значение». Это не педантизм: от различия зависит и ставка, и
строка подписи.
| Поле | «не передали» | «пусто / ноль» | «значение» |
|---|---|---|---|
goal | ключа нет в теле → цель по умолчанию | "" | "2" |
sum_rub | ключа нет → сумма неизвестна | 0 — сумма известна и равна нулю | 12.5 |
sub_id | ключа нет | "" — совпадает с «не передали» | "tg" |
В Go это значит Goal *string, SumRUB *int64, но SubID string: у третьего
поля различать нечего.
⚠ Деньги — целые копейки, а не float64. Дробная сумма в подписи едет
лексической формой (12.5, не 12.50) — см. вектор sum_fractional.
8. Два времени
occurred_at — необязательное время, когда событие случилось у вас.
Не прислали — берём момент приёма. Капы, когорты и отчёты считают по
occurred_at ?? created_at.
Это нужно тем, кто досылает конверсии пачкой после сбоя: без него вчерашний заказ попал бы в сегодняшний отчёт и в сегодняшний кап.
9. Перечень методов
Все пути — от https://api.recca.ru/federation/v1.
| # | Метод | Скоуп | Кого кормит |
|---|---|---|---|
| 1 | GET /federation/v1/cpa/self | cpa:self:read | проба живости, версия контракта, настройки сети |
| 2 | POST /federation/v1/cpa/partners | cpa:partners:write | регистрация партнёра (upsert по external_id) и его деактивация |
| 3 | GET /federation/v1/cpa/partners | cpa:partners:read | рекрутёр: мои блогеры (recruiter_external_id) |
| 4 | GET /federation/v1/cpa/partners/{external_id} | cpa:partners:read | карточка партнёра |
| 5 | GET /federation/v1/cpa/partners/{external_id}/balance | cpa:partners:read | доступно · в холде · выплачено · порог |
| 6 | GET /federation/v1/cpa/offers | cpa:offers:read | блогер: каталог · рекламодатель: свои офферы |
| 7 | GET /federation/v1/cpa/offers/{id} | cpa:offers:read | условия, цели, гео, разрешённый трафик |
| 8 | GET /federation/v1/cpa/offers/{id}/creatives | cpa:offers:read | баннеры и посадочные |
| 9 | POST /federation/v1/cpa/links | cpa:links:write | стабильная ссылка партнёра на оффер |
| 10 | POST /federation/v1/cpa/clicks | cpa:clicks:write | переход по вашей брендированной ссылке |
| 11 | POST /federation/v1/cpa/conversions | cpa:conversions:write | приём результата |
| 12 | GET /federation/v1/cpa/conversions | cpa:conversions:read | список с фильтрами |
| 13 | GET /federation/v1/cpa/conversions/{external_id} | cpa:conversions:read | тройка ставок и нога рекрутёра |
| 14 | POST /federation/v1/cpa/conversions/{external_id}/cancel | cpa:conversions:reverse | рекламодатель: отклонить или вернуть |
| 15 | POST /federation/v1/cpa/payouts | cpa:payouts:write | заявка на выплату |
| 16 | GET /federation/v1/cpa/payouts | cpa:payouts:read | история заявок |
| 17 | GET /federation/v1/cpa/statistics | cpa:stats:read | отчёт: group_by: offer|partner|day |
| 18 | PUT /federation/v1/cpa/self/webhook | cpa:self:write | куда слать события cpa.* |
Перечень выведен обходом по ролям участников сети (вебмастер, рекрутёр, рекламодатель, оператор): у каждого экрана кабинета участника есть метод, который его кормит. Каждый метод описан подробно в разделе 9.6; у оффера две проекции, поэтому методов в SDK двадцать при восемнадцати дверях.
9.1. Роли партнёров
role ∈ {advertiser, webmaster, agent}.
⚠ «Инфлюенсер» — не отдельная роль, а вебмастер. Поверхности совпадают до
строчки: каталог, ссылка, конверсии, баланс, выплата; отличается источник
трафика, и он остаётся у вас. Значение influencer в параметре role не принимается: 400 INVALID_INPUT.
9.2. Деактивация и приостановка — разные поля
| Поле | Кто пишет | Значит |
|---|---|---|
partner_state ∈ {active, inactive} | вы, через POST /federation/v1/cpa/partners | «человек у нас ушёл» |
status ∈ {active, pending, suspended} | оператор, в кабинете | «наказан за фрод» |
Право работать = оба активны. Одним полем это сделать нельзя: upsert из API молча снимал бы санкцию оператора.
⚠ Поэтому повторный POST /federation/v1/cpa/partners на уже заведённого партнёра меняет
только ваши поля — partner_state и рекрутёра. Санкцию оператора он не
трогает: иначе ваша ночная синхронизация возвращала бы в строй отклонённого
партнёра, и ни одна сторона не увидела бы ошибки. Другая role или другой
agent_percent у действующего агента — не молчаливое игнорирование, а
400 INVALID_INPUT с полем role / agent_percent: их меняет оператор в
кабинете. Следствие для синхронизации: пересылая роль со своей стороны, вы
получите отказ на партнёре, которого оператор перевёл в агенты.
Рекрутёр — три состояния ключа recruiter_external_id:
| в теле | значит |
|---|---|
| ключа нет | рекрутёр не меняется |
| строка | прикрепить или сменить; рекрутёр обязан быть уже заведённым агентом этой сети |
null | открепить |
Открепление и смена действуют вперёд: агент перестаёт получать ногу с
будущих конверсий партнёра, уже начисленное заморожено на момент конверсии.
Открепить неприкреплённого — 200, ничего не меняется. То же действие есть у
оператора в кабинете, на карточке партнёра, и оба попадают в журнал изменений
сети.
⚠ pending — третье состояние, а не оттенок первых двух: роль выдана, а
заявка ещё в очереди оператора. Оно означает «ещё не работает», но санкции
за ним нет, и сообщать о ней было бы неправдой.
⚠ Рекламодателя POST /federation/v1/cpa/partners не заводит: у него карточка-витрина,
офферы и условия — решения, которые принимает оператор в кабинете. role
здесь принимает только webmaster и agent; в ЧТЕНИИ роль advertiser
встречается.
9.3. Две проекции оффера
GET /federation/v1/cpa/offers принимает view, и умолчание — безопасное:
view | Кому | Есть в ответе | Нет в ответе |
|---|---|---|---|
partner (умолчание) | блогеру | payout_rate, правила трафика, гео, цели, статистика оффера | revenue_rate, маржа, postback_secret |
advertiser | рекламодателю | его собственная revenue_rate | payout_rate, маржа оператора |
⚠⚠ Ставка рекламодателя не попадает в партнёрскую проекцию никогда. Блогер,
увидевший revenue_rate, вычисляет вашу маржу. Проекция выбирается параметром,
а не выводится из присутствия фильтра: решение по побочному признаку однажды
разойдётся молча.
⚠ Кому ваш сервер отдаёт какую проекцию — решаете вы (см. раздел 2). Мы гарантируем, что безопасная проекция существует и не течёт.
Поле целей multiple_per_click есть в ОБЕИХ проекциях (и в
панели S2S рекламодателя, и в витрине вебмастера): цель с true принимает
несколько оплачиваемых конверсий с одного клика — каждый заказ со своим
external_id платится отдельно. У целей без флага поведение прежнее: один
клик оплачивается один раз на цель (см. ALREADY_CONVERTED в разделе 12).
Расход капов оффера не меняется: каждая конверсия считается в лимитах как
обычная.
Поле целей disabled есть ТОЛЬКО в рекламодательской проекции
(и в панели S2S): оператор сети может временно выключить цель, не удаляя её.
Новые конверсии по выключенной цели получают 409 GOAL_DISABLED (раздел 12);
уже записанные подтверждаются и возвращаются как раньше — ставки, холд и
история сохраняются. Партнёрской проекции поля нет намеренно: там выключенная
цель скрыта целиком, потому что это поверхность «выбираю, куда лить», и цели,
которая не принимает конверсии, там делать нечего. Цель 1 (ставка самого
оффера) выключить нельзя.
9.4. Рекламодатель адресуется НАШИМ идентификатором
advertiser_id — не advertiser_external_id, и слово «external» опущено
намеренно. Во всём остальном контракте external_id означает идентификатор,
который назначаете вы; у рекламодателя такого нет и быть не может:
карточку заводит оператор в кабинете (раздел 13), то есть вы её нам не
присылаете. Поле с чужим именем принимало бы ваш код рекламодателя и отвечало
пустым списком — обещание, которого система не выполняет.
Значение приходит в каждом оффере полем advertiser_id; храните
соответствие один раз при заведении рекламодателя. Новой работы это не добавляет:
наши offer_id вы храните и так — их требуют методы 7–11.
⚠ Неизвестный advertiser_id — 404 ADVERTISER_NOT_FOUND, а не пустой
список: опечатка в идентификаторе и «у рекламодателя нет офферов» — разные
факты, и второй ответ на первый вопрос вы прочитали бы как отсутствие данных.
9.5. Право работать проверяется на выдаче ссылки и на переходе
Раздел 9.2 говорит, что право работать = активны оба поля. Вот где это применяется:
| Метод | Партнёр неактивен |
|---|---|
9 POST /federation/v1/cpa/links | 409 PARTNER_NOT_ACTIVE |
10 POST /federation/v1/cpa/clicks | 409 PARTNER_NOT_ACTIVE |
11 POST /federation/v1/cpa/conversions | принимается и оплачивается |
⚠⚠ Третья строка — решение, а не недосмотр. Клик — момент, когда сеть принимает трафик, и принимать его от того, кого вы отключили, незачем. А конверсия приходит ПОСЛЕ клика: трафик уже был куплен и доставлен, и отказ платить за него был бы не санкцией, а присвоением чужой работы.
Оффер «по запросу». Оператор может перевести оффер в режим «по запросу»: ссылка выдаётся только партнёру с одобренной заявкой. Для пары без одобрения:
| Метод | Ответ |
|---|---|
POST /federation/v1/cpa/links | 409 PARTNER_NOT_ACTIVE с названием оффера в сообщении |
POST /federation/v1/cpa/clicks | 201, переход отбит: status: trafficback, reason: access_required, click_id: null |
GET /federation/v1/cpa/offers/{id}/creatives | пустой список без partner_external_id или без одобренной заявки |
GET /federation/v1/cpa/offers/{id} | карточка оффера отдаётся целиком |
Через POST /federation/v1/cpa/clicks проверка выполняется на каждом вызове. Закрыть оффер для одного вебмастера оператор может и остановкой пары «вебмастер × оффер» (для вас это тот же PARTNER_NOT_ACTIVE).
9.6. Методы подробно
Общее для всех методов:
- Базовый адрес —
https://api.recca.ru/federation/v1; песочница —https://api-sandbox.recca.ru/federation/v1. Во всех примерах ключ лежит в переменной окруженияRECCA_CPA_KEY(значение видаrtk_live_…печатать в код нельзя). - Ответ всегда в конверте из раздела 4:
success,data,meta.request_id. У списков вmetaестьtotal,count,offset,limit,has_moreиtruncated. - Тела запросов и строки запроса разбираются строго: неизвестное поле или параметр —
400 INVALID_INPUTс именем поля вerror.details. Персональное значение в любом поле —400 PII_NOT_ACCEPTED. - Коды ошибок перечислены в разделе 12; у каждого метода ниже названы только характерные.
- Идентификаторы партнёров — ваши
external_id; идентификаторы офферов и рекламодателей — наши, их берут из ответов. - В колонке «Роль» указано, чей экран обычно кормит метод: вебмастер (партнёр), рекрутёр (вебмастер, привёдший других), рекламодатель, оператор сети.
9.6.1. Self.Get — проба и самоописание ключа
GET /federation/v1/cpa/self · скоуп cpa:self:read · роль: оператор сети (интегратор), мониторинг.
Отвечает ключу о нём самом: сеть, права, версия контракта, среда, настройки и бюджет запросов. В бюджет запросов не входит — им можно проверять живость без расхода лимита.
Параметров нет.
| Поле ответа | Тип | Что значит |
|---|---|---|
contract_version | string | версия контракта; сверяйте при запуске |
environment | production · staging · sandbox | среда, в которую вы пришли; отвечает сервер, а не ваша конфигурация |
network_id | string | наш непрозрачный идентификатор вашей сети |
scopes | string[] | права ключа |
agent_base | margin · payout | от чего считается нога рекрутёра |
agent_hold | {mode, days} | когда нога рекрутёра станет доступной: follow_conversion — по холду конверсии, own_days — свой срок (days), иначе days: null |
min_payout_rub | integer | порог выплаты сети |
rate_limit_per_min | integer | ваш фактический бюджет запросов в минуту |
webhook_configured | boolean | настроен ли адрес для событий |
Ошибки: MISSING_TENANT_SCOPE, INSUFFICIENT_SCOPE, FEATURE_NOT_AVAILABLE, PRODUCT_PAUSED.
Идемпотентность: чтение; повторять можно сколько угодно.
curl -s "https://api.recca.ru/federation/v1/cpa/self" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Self.Get.
9.6.2. Self.SetWebhook — адрес для событий cpa.*
PUT /federation/v1/cpa/self/webhook · скоуп cpa:self:write · роль: оператор сети (интегратор).
Задаёт адрес, на который сеть шлёт события раздела 10. Секрет подписи приходит в ответе один раз — при первой установке и при каждой ротации; повторно он не выдаётся.
| Поле запроса | Тип | Обязательно | Ограничения |
|---|---|---|---|
url | string | да | до 2000 символов; только HTTPS, адреса внутренних сетей и localhost не принимаются |
rotate_secret | boolean | нет | true — выпустить новый секрет; по умолчанию false |
| Поле ответа | Тип | Что значит |
|---|---|---|
url | string | сохранённый адрес |
events | string[] | события, которые придут: cpa.conversion.approved, cpa.conversion.declined, cpa.conversion.reversed, cpa.payout.paid |
secret | string · null | секрет подписи; только при первой установке и ротации |
Ошибки: INVALID_INPUT (адрес не прошёл проверку).
Идемпотентность и повтор: метод не повторяется автоматически — ответ с секретом нельзя получить второй раз. Не получили ответ — вызовите снова с rotate_secret: true.
curl -s -X PUT "https://api.recca.ru/federation/v1/cpa/self/webhook" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/recca/webhook","rotate_secret":false}'
В Go SDK: Self.SetWebhook.
9.6.3. Partners.Upsert — завести партнёра или обновить
POST /federation/v1/cpa/partners · скоуп cpa:partners:write · роль: вебмастер и рекрутёр.
Регистрирует партнёра по вашему external_id или обновляет его. На уже заведённом партнёре меняются только ваши поля — partner_state и рекрутёр; роль, участие и санкцию оператора метод не трогает (см. 9.2).
| Поле запроса | Тип | Обязательно | Ограничения |
|---|---|---|---|
external_id | string | да | ^[A-Za-z0-9_.:-]{1,64}$; ключ идемпотентности |
role | webmaster · agent | да | advertiser не принимается; agent устарел — партнёр записывается вебмастером, шлите webmaster |
partner_state | active · inactive | нет | «человек у вас ушёл»; санкцию оператора не снимает |
recruiter_external_id | string · null | нет | уже заведённый партнёр сети; не сам себе; ключа нет — не меняем, строка — прикрепить или сменить, null — открепить; действует вперёд |
agent_percent | number | нет | 0–100; только вместе с устаревшей role: agent, при webmaster игнорируется |
| Поле ответа | Тип | Что значит |
|---|---|---|
external_id | string | ваш идентификатор |
tenant_recca_id | string | наш непрозрачный идентификатор человека в вашей сети |
role | advertiser · webmaster · agent | роль; в чтении встречается и advertiser |
partner_state | active · inactive | ваш признак |
status | active · pending · suspended | участие на нашей стороне |
recruiter_external_id | string · null | рекрутёр |
created_at | date-time | момент заведения |
Ошибки: INVALID_INPUT (в том числе чужие role и agent_percent у действующего партнёра, рекрутёр самому себе), PARTNER_NOT_FOUND (рекрутёр не заведён), PII_NOT_ACCEPTED.
Идемпотентность и повтор: идемпотентен по external_id; 201 — партнёр заведён впервые, 200 — уже был. Повторять безопасно.
curl -s -X POST "https://api.recca.ru/federation/v1/cpa/partners" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY" \
-H "Content-Type: application/json" \
-d '{"external_id":"blg_8f3a","role":"webmaster","partner_state":"active"}'
В Go SDK: Partners.Upsert.
9.6.4. Partners.List — список партнёров
GET /federation/v1/cpa/partners · скоуп cpa:partners:read · роль: рекрутёр («мои блогеры»), оператор.
Отдаёт партнёров, заведённых по API: у заведённого оператором в кабинете external_id нет, адресовать его нельзя.
| Параметр | Тип | Обязательно | Ограничения |
|---|---|---|---|
role | webmaster · agent | нет | другое значение — 400 INVALID_INPUT |
status | active · pending · suspended | нет | участие на нашей стороне |
recruiter_external_id | string | нет | ^[A-Za-z0-9_.:-]{1,64}$; фильтр «мои блогеры» |
limit | integer | нет | 1–200, по умолчанию 50 |
offset | integer | нет | от 0 |
Ответ — массив карточек партнёра (поля как в 9.6.3). Неизвестный параметр — 400 INVALID_INPUT: опечатка в фильтре иначе вернула бы полный список под видом отфильтрованного.
Ошибки: INVALID_INPUT.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/partners?recruiter_external_id=blg_8f3a&limit=50" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Partners.List.
9.6.5. Partners.Get — карточка партнёра
GET /federation/v1/cpa/partners/{external_id} · скоуп cpa:partners:read · роль: вебмастер, рекрутёр.
| Параметр | Где | Тип | Обязательно | Ограничения |
|---|---|---|---|---|
external_id | путь | string | да | ^[A-Za-z0-9_.:-]{1,64}$ |
Ответ — карточка партнёра (поля как в 9.6.3); по ней видно оба поля права работать — partner_state и status.
Ошибки: PARTNER_NOT_FOUND.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/partners/blg_8f3a" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Partners.Get.
9.6.6. Partners.Balance — баланс партнёра
GET /federation/v1/cpa/partners/{external_id}/balance · скоуп cpa:partners:read · роль: вебмастер, рекрутёр.
| Параметр | Где | Тип | Обязательно | Ограничения |
|---|---|---|---|---|
external_id | путь | string | да | ^[A-Za-z0-9_.:-]{1,64}$ |
| Поле ответа | Тип | Что значит |
|---|---|---|
available_rub | integer | ровно то, что можно запросить к выплате сейчас |
on_hold_rub | integer | станет доступным по истечении холда; отдельного запроса не нужно |
paid_total_rub | integer | выплачено за всё время |
min_payout_rub | integer | порог сети: читайте отсюда, а не из своей константы |
can_request | boolean | можно ли подать заявку на выплату |
Ошибки: PARTNER_NOT_FOUND.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/partners/blg_8f3a/balance" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Partners.Balance.
9.6.7. Offers.ListForPartner — каталог для партнёра
GET /federation/v1/cpa/offers?view=partner · скоуп cpa:offers:read · роль: вебмастер («выбираю, куда лить»).
Партнёрская проекция безопасна по построению: в ней нет ставки рекламодателя, маржи и капов. Это умолчание, параметр view можно не передавать.
| Параметр | Тип | Обязательно | Ограничения |
|---|---|---|---|
view | partner · advertiser | нет | по умолчанию partner |
advertiser_id | string | нет | до 120 символов; наш идентификатор рекламодателя, сужает каталог до его офферов |
limit | integer | нет | 1–200, по умолчанию 50 |
offset | integer | нет | от 0 |
| Поле ответа (элемент массива) | Тип | Что значит |
|---|---|---|
id, name | string | идентификатор и название оффера |
advertiser_id | string | наш идентификатор рекламодателя |
payout_model | cpa · cpl · revshare | модель выплаты |
payout_rate | {kind, value_rub, value_percent} | ставка партнёру: kind — fixed или percent |
goals | массив | цели: code, name, is_milestone (веха — без выплаты, payout_rate: null), multiple_per_click, payout_rate, hold_days |
geo | {mode, countries} | any — весь мир, allow — только перечисленные, deny — кроме перечисленных |
allowed_traffic, disallowed_traffic | string[] | разрешённые и запрещённые виды трафика |
hold_days, attribution_window_days | integer · null | холд и окно атрибуции |
Ошибки: INVALID_INPUT, ADVERTISER_NOT_FOUND (неизвестный advertiser_id — не пустой список).
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/offers?view=partner&limit=50" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Offers.ListForPartner.
9.6.8. Offers.ListForAdvertiser — офферы рекламодателя
GET /federation/v1/cpa/offers?view=advertiser&advertiser_id=… · скоуп cpa:offers:read · роль: рекламодатель.
Рекламодателю отдаются офферы его собственных витрин и его собственная ставка. payout_rate и маржа оператора в этой проекции не приходят никогда.
| Параметр | Тип | Обязательно | Ограничения |
|---|---|---|---|
view | advertiser | да | без view=advertiser вы получите партнёрскую проекцию |
advertiser_id | string | да | до 120 символов; наш идентификатор: берите из поля advertiser_id любого оффера |
limit, offset | integer | нет | как в 9.6.7 |
| Поле ответа (элемент массива) | Тип | Что значит |
|---|---|---|
id, name, advertiser_id | string | как в 9.6.7 |
payout_model | cpa · cpl · revshare | модель |
revenue_rate | {kind, value_rub, value_percent} | ставка рекламодателя |
goals | массив | code, name, is_milestone, multiple_per_click, disabled (цель выключена оператором — новые конверсии получают 409 GOAL_DISABLED), revenue_rate, hold_days |
geo, hold_days, attribution_window_days | как в 9.6.7 |
Ошибки: INVALID_INPUT (нет advertiser_id при view=advertiser), ADVERTISER_NOT_FOUND.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/offers?view=advertiser&advertiser_id=shop_demo01" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Offers.ListForAdvertiser.
9.6.9. Offers.GetForPartner — условия оффера для партнёра
GET /federation/v1/cpa/offers/{id}?view=partner · скоуп cpa:offers:read · роль: вебмастер.
| Параметр | Где | Тип | Обязательно | Ограничения |
|---|---|---|---|---|
id | путь | string | да | идентификатор оффера |
view | строка запроса | partner · advertiser | нет | по умолчанию partner |
Ответ — один оффер в партнёрской проекции (поля как в 9.6.7): условия, цели, гео, разрешённый трафик.
Ошибки: OFFER_NOT_FOUND.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/offers/off_demo01?view=partner" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Offers.GetForPartner.
9.6.10. Offers.GetForAdvertiser — условия оффера для рекламодателя
GET /federation/v1/cpa/offers/{id}?view=advertiser&advertiser_id=… · скоуп cpa:offers:read · роль: рекламодатель.
| Параметр | Где | Тип | Обязательно | Ограничения |
|---|---|---|---|---|
id | путь | string | да | идентификатор оффера |
view | строка запроса | advertiser | да | |
advertiser_id | строка запроса | string | да | наш идентификатор рекламодателя; должен быть владельцем этого оффера |
Ответ — оффер в проекции рекламодателя (поля как в 9.6.8). Чужой идентификатор получит 404 ADVERTISER_NOT_FOUND: ставки чужих карточек перебором не открываются.
Ошибки: INVALID_INPUT (нет advertiser_id), OFFER_NOT_FOUND, ADVERTISER_NOT_FOUND.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/offers/off_demo01?view=advertiser&advertiser_id=shop_demo01" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Offers.GetForAdvertiser.
9.6.11. Offers.Creatives — креативы и посадочные оффера
GET /federation/v1/cpa/offers/{id}/creatives · скоуп cpa:offers:read · роль: вебмастер.
Один список: посадочные идут первыми, дальше креативы.
| Параметр | Где | Тип | Обязательно | Ограничения |
|---|---|---|---|---|
id | путь | string | да | идентификатор оффера |
partner_external_id | строка запроса | string | для оффера «по запросу» | ^[A-Za-z0-9_.:-]{1,64}$; партнёр, для которого запрашиваются материалы |
Оффер может быть «по запросу»: ссылка на него выдаётся только партнёру с одобренной заявкой. Материалы такого оффера отдаются только по паре с одобренной заявкой: без partner_external_id или без одобрения ответ — пустой список (не ошибка), а карточку оффера метод 9.6.9 по-прежнему отдаёт целиком.
| Поле ответа (элемент массива) | Тип | Что значит |
|---|---|---|
id, title | string | идентификатор и название |
kind | banner · landing · text · video · other | вид; ветвитесь по нему |
description | string · null | описание |
url | string · null | адрес файла; null у текстового креатива |
text | string · null | текст — у kind: text |
mime_type, width, height | параметры файла, могут быть null | |
is_default | boolean | основная посадочная; у креативов всегда false |
created_at | date-time · null |
Ошибки: OFFER_NOT_FOUND.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/offers/off_demo01/creatives?partner_external_id=blg_8f3a" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Offers.Creatives.
9.6.12. Links.Create — стабильная ссылка партнёра на оффер
POST /federation/v1/cpa/links · скоуп cpa:links:write · роль: вебмастер.
| Поле запроса | Тип | Обязательно | Ограничения |
|---|---|---|---|
partner_external_id | string | да | ^[A-Za-z0-9_.:-]{1,64}$; партнёр должен быть заведён |
offer_id | string | да | 1–120 символов |
| Поле ответа | Тип | Что значит |
|---|---|---|
code | string | код ссылки |
target_url | string | адрес перехода на нашей стороне (/go/{code}); брендированную ссылку рисует ваш домен, значение берите из ответа как есть |
partner_external_id, offer_id | string | пара |
created_at | date-time |
Не подменяйте target_url адресом посадочной оффера: такой переход не будет засчитан — ни клика, ни атрибуции, ни выплаты, и ошибки не будет.
Ошибки: PARTNER_NOT_FOUND, PARTNER_NOT_ACTIVE (право работать снято; то же при оффере «по запросу» без одобренной заявки и при оффере, закрытом оператором для этого партнёра; уже выпущенные ссылки остаются), OFFER_NOT_FOUND, INVALID_INPUT.
Идемпотентность и повтор: идемпотентен по паре «партнёр + оффер»; 201 — выпущена, 200 — та же, что была. Повторять безопасно.
curl -s -X POST "https://api.recca.ru/federation/v1/cpa/links" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY" \
-H "Content-Type: application/json" \
-d '{"partner_external_id":"blg_8f3a","offer_id":"off_demo01"}'
В Go SDK: Links.Create.
9.6.13. Clicks.Create — зарегистрировать переход
POST /federation/v1/cpa/clicks · скоуп cpa:clicks:write · роль: вебмастер (переход по вашей брендированной ссылке).
| Поле запроса | Тип | Обязательно | Ограничения |
|---|---|---|---|
partner_external_id | string | да | ^[A-Za-z0-9_.:-]{1,64}$ |
offer_id | string | да | 1–120 символов |
client_click_id | string | нет | до 200 символов; ваш ключ идемпотентности |
sub_id, sub_id_2 … sub_id_10 | string | нет | до 200 символов каждое |
country | string | нет | ISO 3166-1 alpha-2, ровно 2 символа |
Адрес посетителя и строку его браузера дверь не принимает — они относятся к персональным данным. Присылайте страну.
| Поле ответа | Тип | Что значит |
|---|---|---|
click_id | string · null | идентификатор перехода; null при status: trafficback |
status | open · trafficback | trafficback — переход записан, но к рекламодателю не отправлен (кап исчерпан, не подошло гео или нет доступа к офферу «по запросу»); это не ошибка запроса |
reason | string · null | причина отбоя: cap, geo или access_required (оффер «по запросу», у пары нет одобренной заявки); перечень открыт — неизвестное значение читайте как «переход отбит»; у обычного перехода null |
redirect_url | string · null | куда отправить посетителя; null — вести некуда, покажите свою страницу |
expires_at | date-time · null | конец окна атрибуции |
created_at, offer_id, partner_external_id |
Ошибки: PARTNER_NOT_FOUND, PARTNER_NOT_ACTIVE, OFFER_NOT_FOUND, IDEMPOTENT_MISMATCH (тот же client_click_id с другой парой «партнёр + оффер»), INVALID_INPUT, RATE_LIMIT_EXCEEDED.
Идемпотентность и повтор: без client_click_id не идемпотентен — два вызова это два перехода и двойной расход капа. С client_click_id повтор возвращает тот же клик (200 вместо 201). Автоматически не повторяйте без этого ключа.
curl -s -X POST "https://api.recca.ru/federation/v1/cpa/clicks" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY" \
-H "Content-Type: application/json" \
-d '{"partner_external_id":"blg_8f3a","offer_id":"off_demo01","client_click_id":"ck-0001","sub_id":"campaign-1","country":"RU"}'
В Go SDK: Clicks.Create.
9.6.14. Conversions.Create — принять результат
POST /federation/v1/cpa/conversions · скоуп cpa:conversions:write · роль: рекламодатель (его события), вебмастер (его результат).
Вердикт клиента «конверсия валидна» входом не является: сумма, цель и оффер сверяются с условиями. Качество трафика помечается fraud_flags и само по себе не блокирует.
| Поле запроса | Тип | Обязательно | Ограничения |
|---|---|---|---|
click_id | string | да | 1–120 символов; идентификатор перехода |
external_id | string | да | 1–200 символов; ваш номер заказа, общий для сети; префикс recca: зарезервирован |
status | string | да | 1–64 символа: pending, wait, waiting, on_hold — ожидание; cancel, reject — отмена; любое другое — подтверждение |
goal | string · null | нет | до 64 символов; ключа нет — цель по умолчанию, значимо присутствие ключа |
sum_rub | number · null | нет | 0 … 10 000 000; обязательна для процентных моделей; «не передали» и 0 — разные факты |
sub_id | string | нет | до 200 символов |
occurred_at | date-time | нет | не из будущего, не старше 90 дней; не прислали — берётся момент приёма |
| Поле ответа | Тип | Что значит |
|---|---|---|
external_id, goal | string | номер заказа и цель; вместе с сетью они адресуют конверсию |
status | pending · hold · approved · declined · not_found | состояние; declined — отклонена или возвращена |
partner_external_id, offer_id, advertiser_id | ||
payout_rub, revenue_rub, margin_rub | integer | тройка ставок: payout_rub + margin_rub == revenue_rub |
sum_rub, sub_id | как присланы | |
created_at, occurred_at, hold_until | date-time · null | occurred_at — null, если вы его не присылали |
agent_leg | object · null | нога рекрутёра: external_id, amount_rub, base, percent, hold_until |
fraud_flags | string[] | пометки качества трафика |
Ошибки: INVALID_INPUT (в том числе неизвестный click_id — искать надо в своём журнале переходов), RESERVED_EXTERNAL_ID, OCCURRED_AT_OUT_OF_WINDOW, UNKNOWN_GOAL, GOAL_DISABLED, WINDOW_EXPIRED, ALREADY_CONVERTED, EXTERNAL_ID_CONFLICT, ILLEGAL_TRANSITION, IDEMPOTENT_MISMATCH, PII_NOT_ACCEPTED, RATE_LIMIT_EXCEEDED.
Идемпотентность и повтор: идемпотентна по тройке «сеть + external_id + goal»; 201 — создана, 200 — повтор той же операции (в том числе то же подтверждение, досланное после холда). Повтор с другими параметрами — 409 IDEMPOTENT_MISMATCH. Повторять безопасно; WINDOW_EXPIRED повторять бессмысленно.
curl -s -X POST "https://api.recca.ru/federation/v1/cpa/conversions" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY" \
-H "Content-Type: application/json" \
-d '{"click_id":"clk_a1b2c3","external_id":"order-10421","status":"approved","goal":"sale","sum_rub":5000}'
В Go SDK: Conversions.Create.
9.6.15. Conversions.List — список конверсий
GET /federation/v1/cpa/conversions · скоуп cpa:conversions:read · роль: оператор, рекламодатель, вебмастер.
| Параметр | Тип | Обязательно | Ограничения |
|---|---|---|---|
partner_external_id | string | нет | ^[A-Za-z0-9_.:-]{1,64}$; неизвестный партнёр — 404, а не пустой список |
advertiser_id | string | нет | до 120 символов; наш идентификатор рекламодателя |
offer_id | string | нет | до 120 символов |
status | pending · hold · approved · declined · not_found | нет | |
from, to | string | нет | момент ISO-8601, до 64 символов |
limit | integer | нет | 1–200, по умолчанию 50 |
offset | integer | нет | от 0 |
Ответ — массив конверсий: external_id, goal, status, partner_external_id, offer_id, advertiser_id, payout_rub, sum_rub, sub_id, created_at, occurred_at, hold_until. Тройки ставок и ноги рекрутёра в списке нет — они в 9.6.16.
Ошибки: INVALID_INPUT (в том числе from/to не момент ISO-8601), PARTNER_NOT_FOUND, ADVERTISER_NOT_FOUND.
Идемпотентность: чтение; повтор безопасен. Слишком широкий список может не уложиться во время ответа — сузьте выборку фильтрами.
curl -s "https://api.recca.ru/federation/v1/cpa/conversions?partner_external_id=blg_8f3a&status=hold&limit=50" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Conversions.List.
9.6.16. Conversions.Get — конверсия с тройкой ставок и ногой рекрутёра
GET /federation/v1/cpa/conversions/{external_id} · скоуп cpa:conversions:read · роль: оператор, рекламодатель, рекрутёр.
| Параметр | Где | Тип | Обязательно | Ограничения |
|---|---|---|---|---|
external_id | путь | string | да | до 200 символов; номер заказа |
goal | строка запроса | string | нет | до 64 символов; без параметра ищется цель по умолчанию |
Ответ — подробная конверсия: поля списка из 9.6.15 плюс revenue_rub, margin_rub, agent_leg и fraud_flags (как в 9.6.14).
Ошибки: CONVERSION_NOT_FOUND, INVALID_INPUT.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/conversions/order-10421?goal=sale" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Conversions.Get.
9.6.17. Conversions.Cancel — отклонить конверсию или оформить возврат
POST /federation/v1/cpa/conversions/{external_id}/cancel · скоуп cpa:conversions:reverse · роль: рекламодатель.
| Параметр | Где | Тип | Обязательно | Ограничения |
|---|---|---|---|---|
external_id | путь | string | да | номер заказа |
goal | тело | string | нет | до 64 символов; цель отменяемой конверсии |
reason | тело | string | нет | 1–500 символов; без него записывается «cancelled via CPA API» |
Тело можно не передавать. Ответ — подробная конверсия (как в 9.6.16) в состоянии declined. Отменённая конверсия терминальна: новое подтверждение оформляется новым external_id.
Ошибки: CONVERSION_NOT_FOUND, ILLEGAL_TRANSITION, REVERSAL_FAILED (500: денежная операция не совершена, повторите), INVALID_INPUT.
Идемпотентность и повтор: идемпотентна — повторная отмена ничего не меняет. Повторять безопасно.
curl -s -X POST "https://api.recca.ru/federation/v1/cpa/conversions/order-10421/cancel" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY" \
-H "Content-Type: application/json" \
-d '{"goal":"sale","reason":"order returned"}'
В Go SDK: Conversions.Cancel.
9.6.18. Payouts.Create — заявка на выплату
POST /federation/v1/cpa/payouts · скоуп cpa:payouts:write · роль: вебмастер, рекрутёр.
| Поле запроса | Тип | Обязательно | Ограничения |
|---|---|---|---|
partner_external_id | string | да | 1–200 символов; партнёр должен быть заведён |
amount_rub | integer | да | от 1; не меньше порога сети (min_payout_rub) и не больше доступного |
period_from, period_to | string | да | даты YYYY-MM-DD; period_from не позже period_to |
| Поле ответа | Тип | Что значит |
|---|---|---|
id | string | идентификатор заявки (одна заявка — один id, даже если деньги списаны с нескольких кошельков) |
partner_external_id, amount_rub | ||
status | requested · approved · paid · rejected | |
period_from, period_to | date | |
created_at, paid_at | date-time · null |
Отметку «выплачено» ставит оператор в кабинете.
Ошибки: PARTNER_NOT_FOUND, BELOW_MIN_PAYOUT, INSUFFICIENT_BALANCE, IDEMPOTENT_MISMATCH, INVALID_INPUT.
Идемпотентность и повтор: личность заявки — сеть, партнёр и период; сумма в ключ не входит, а сверяется. Повтор с той же суммой — 200, та же заявка; с другой суммой за тот же период — 409 IDEMPOTENT_MISMATCH.
curl -s -X POST "https://api.recca.ru/federation/v1/cpa/payouts" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY" \
-H "Content-Type: application/json" \
-d '{"partner_external_id":"blg_8f3a","amount_rub":5000,"period_from":"2026-09-01","period_to":"2026-09-30"}'
В Go SDK: Payouts.Create.
9.6.19. Payouts.List — история заявок
GET /federation/v1/cpa/payouts · скоуп cpa:payouts:read · роль: вебмастер, рекрутёр, оператор.
| Параметр | Тип | Обязательно | Ограничения |
|---|---|---|---|
partner_external_id | string | нет | до 200 символов; неизвестный партнёр — 404 |
status | requested · approved · paid · rejected | нет | |
limit | integer | нет | 1–100, по умолчанию 20 |
offset | integer | нет | от 0 |
Ответ — массив заявок (поля как в 9.6.18). Страница здесь меньше, чем у остальных списков: потолок 100, умолчание 20.
Ошибки: INVALID_INPUT, PARTNER_NOT_FOUND.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/payouts?partner_external_id=blg_8f3a&status=paid" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Payouts.List.
9.6.20. Statistics.Get — отчёт
GET /federation/v1/cpa/statistics · скоуп cpa:stats:read · роль: оператор сети (ключ принадлежит оператору, поэтому выручка в отчёте видна всегда).
Считается по occurred_at, а при его отсутствии по моменту приёма: досланная пачкой вчерашняя конверсия попадает во вчерашний день.
| Параметр | Тип | Обязательно | Ограничения |
|---|---|---|---|
group_by | offer · partner · day | да | |
partner_external_id | string | нет | до 64 символов; неизвестный партнёр — 404 |
advertiser_id | string | нет | до 120 символов |
offer_id | string | нет | до 120 символов |
from, to | string | нет | даты YYYY-MM-DD, to включительно; from не позже to; без from берутся последние 30 дней |
| Поле ответа (элемент массива) | Тип | Что значит |
|---|---|---|
key | string | идентификатор группы: оффер, партнёр или дата |
clicks, conversions, approved | integer | переходы, конверсии, подтверждённые |
payout_rub, revenue_rub | integer | выплаты партнёрам и выручка группы |
Ошибки: INVALID_INPUT, PARTNER_NOT_FOUND.
Идемпотентность: чтение; повтор безопасен.
curl -s "https://api.recca.ru/federation/v1/cpa/statistics?group_by=day&from=2026-09-01&to=2026-09-30" \
-H "X-Recca-Tenant-Key: $RECCA_CPA_KEY"
В Go SDK: Statistics.Get.
10. Вебхуки cpa.*
Без них переход hold → approved вы узнаёте только опросом: его делает наша
джоба по расписанию, а не ваш запрос.
Адрес настраивается PUT /federation/v1/cpa/self/webhook; секрет выдаётся один раз в ответе.
| Событие | Когда |
|---|---|
cpa.conversion.approved | истёк холд, конверсия подтверждена |
cpa.conversion.declined | отклонена рекламодателем или антифродом |
cpa.conversion.reversed | прошёл возврат, начисление отменено |
cpa.payout.paid | оператор отметил выплату оплаченной |
⚠ declined и reversed — разные события при ОДНОМ статусе конверсии
(ConversionStatus не знает reversed намеренно). Различие
существенно для учёта: в первом случае денег партнёру не начисляли вовсе, во
втором — начислили и вернули.
Конверт
Он общий для всех событий платформы, а не только для cpa.*:
{
"event_id": "fwd_01K…",
"event_type": "cpa.conversion.approved",
"event_version": "1",
"organization_id": "org_01K…",
"occurred_at": "2026-09-21T00:00:00.000Z",
"delivered_at": "2026-09-21T00:00:30.000Z",
"data": { "external_id": "order-0751", "goal": "1", "payout_rub": 500 }
}
⚠⚠ occurred_at и delivered_at — разные факты, и сводить отчёт нужно по
первому. Доставка идёт с повторами: первая попытка уходит через 30 секунд,
четвёртая — на следующий день. Взяв дату доставки, вы положите вчерашнюю
конверсию в сегодняшний отчёт, и расхождение с вашими же числами будет
невидимым.
⚠ event_id — идентификатор ДОСТАВКИ, и он устойчив: повторная попытка
приходит с тем же. По нему и стоит дедуплицировать у себя.
У события cpa.payout.paid в data.payout_id лежит идентификатор ЗАЯВКИ —
тот же, что вернул POST /federation/v1/cpa/payouts. Заявка может списываться с нескольких
кошельков партнёра, и событие уходит одно: когда выплачена последняя часть.
Подпись:
X-Recca-Signature: t=<unix_seconds>,v1=<hex64>
v1 = HMAC-SHA256(secret, "<t>.<сырое тело запроса>")
⚠⚠ Подписывается сырое тело, байт в байт. Распарсив JSON и пересобрав его
перед проверкой, вы получите несходящуюся подпись — и это будет выглядеть как
«у Recca сломалась подпись». Golden-вектор raw_body_signed_verbatim закрепляет
именно этот случай.
Метка времени вне окна допуска (раздел 5) — подпись не принимается: это защита от повтора перехваченной доставки.
11. Подпись постбэка (прямая дверь рекламодателя)
Основная дверь приёма результата для вас — тенантная (POST /federation/v1/cpa/conversions,
аутентификация ключом). Ниже — HMAC-дверь для рекламодателей, которые шлют
постбэк напрямую, минуя ваш бэкенд.
канон = click_id:external_id:status:sum_rub:sub_id[:goal[:timestamp]]
подпись = HMAC-SHA256(postback_secret, канон), hex
заголовок = X-CPA-Signature
Форму называет число сегментов, и решает присутствие ключа, а не его значение:
| Сегментов | Когда |
|---|---|
| 5 | ни цели, ни метки времени |
| 6 | цель передана (в том числе пустой) |
| 7 | передана метка времени — тогда цель идёт шестой, пустой, если её не было |
⚠ Семь сегментов при метке — не украшение: иначе шесть означали бы одновременно «цель» и «метку», а различить их по содержимому нельзя (цель бывает числовой), и проверяющий ошибался бы молча, то есть на деньгах.
Заголовки X-CPA-Timestamp (метка, секунды Unix) и X-CPA-Key-Id
(current | previous) необязательны. После ротации прежний секрет
принимается ещё семь суток — менять его в CRM можно не в ту же секунду.
Golden-векторы: cpa-signature-vectors.json
и cpa-webhook-vectors.json. Оба собраны живыми
функциями Recca; ваш клиент обязан получать те же строки байт в байт. Векторы
покрывают: пять сегментов, пустую и названную цель, отсутствующую сумму, ноль,
дробную сумму, метку времени с целью и без, прежний слот секрета и токен
GET-двери.
12. Коды ошибок
| Код | HTTP |
|---|---|
MISSING_TENANT_SCOPE | 401 |
INSUFFICIENT_SCOPE | 403 |
FEATURE_NOT_AVAILABLE | 403 |
PRODUCT_PAUSED | 403 |
RATE_LIMIT_EXCEEDED | 429 |
INTERNAL_ERROR | 500 |
INVALID_INPUT | 400 |
PII_NOT_ACCEPTED | 400 |
RESERVED_EXTERNAL_ID | 400 |
OCCURRED_AT_OUT_OF_WINDOW | 400 |
PARTNER_NOT_FOUND | 404 |
PARTNER_NOT_ACTIVE | 409 |
ADVERTISER_NOT_FOUND | 404 |
OFFER_NOT_FOUND | 404 |
CONVERSION_NOT_FOUND | 404 |
PAYOUT_NOT_FOUND | 404 |
UNKNOWN_GOAL | 400 |
GOAL_DISABLED | 409 |
WINDOW_EXPIRED | 409 |
ALREADY_CONVERTED | 409 |
EXTERNAL_ID_CONFLICT | 409 |
ILLEGAL_TRANSITION | 409 |
IDEMPOTENT_MISMATCH | 409 |
BELOW_MIN_PAYOUT | 400 |
INSUFFICIENT_BALANCE | 409 |
REVERSAL_FAILED | 500 |
MISSING_TENANT_SCOPE · HTTP 401
Заголовок X-Recca-Tenant-Key отсутствует, пуст или назвал ключ, которого нет. До обработки запроса дело не дошло.
Что делать: Проверьте, что ключ уходит в заголовке, а не в строке запроса, и что он не был отозван. Ключ выдаётся один раз в открытом виде; если значение утрачено — выпустите новый в кабинете, старый при этом перестаёт действовать.
INSUFFICIENT_SCOPE · HTTP 403
Ключ действителен, но у него нет права, которого требует метод. Право каждого метода названо в таблице контракта колонкой «Скоуп».
Что делать: Сверьте набор скоупов ключа с таблицей методов. Скоупы CPA-двери начинаются на cpa: и не пересекаются с реферальными (offers:read, conversions:write) намеренно: ключ реферальной интеграции не должен молча получать денежную дверь CPA.
FEATURE_NOT_AVAILABLE · HTTP 403
У организации, которой принадлежит ключ, не подключён продукт «CPA-сеть», либо она не является CPA-сетью.
Что делать: Это состояние подписки, а не запроса: повтор не поможет. Продукт подключается в кабинете оператора. До подключения дверь закрыта целиком, включая пробу GET /federation/v1/cpa/self.
PRODUCT_PAUSED · HTTP 403
Продукт «CPA-сеть» подключён, но приостановлен — как правило, за неуплату.
Что делать: Отличается от FEATURE_NOT_AVAILABLE намеренно: там продукта нет вовсе, здесь он есть и снимается оплатой. Данные никуда не делись; дверь откроется тем же ключом сразу после возобновления.
RATE_LIMIT_EXCEEDED · HTTP 429
Исчерпан бюджет запросов ключа за минуту. Ответ несёт Retry-After с паузой в секундах и заголовки X-RateLimit-Limit / X-RateLimit-Remaining.
Что делать: Берите паузу из Retry-After, а не из своей константы. Счёт ведётся по организации, а не по адресу отправителя: несколько ваших серверов делят общий бюджет. Проба живости GET /federation/v1/cpa/self в счёт не входит.
INTERNAL_ERROR · HTTP 500
Сбой на нашей стороне: запрос дошёл, но обработать его не удалось. Денежная операция при этом не совершена.
Что делать: Повторите запрос позже — операции с ключом идемпотентности повтор переносят. Если повторяется, сообщите оператору meta.request_id из ответа: по нему находится вся цепочка на нашей стороне.
INVALID_INPUT · HTTP 400
Тело или параметры не прошли проверку: не хватает обязательного поля, значение не того типа, длиннее допустимого либо содержит символы вне объявленного алфавита. Неизвестное поле в теле — тоже отказ: тела разбираются строго.
Что делать: error.details называет поле поимённо. Строгий разбор тела выбран намеренно: молча проглоченная опечатка в имени поля — это операция, которая прошла не так, как вы думали, и узнали бы вы об этом по деньгам.
PII_NOT_ACCEPTED · HTTP 400
В свободном поле распознано персональное данное — почта, телефон или похожая на них строка. Мы таких значений не принимаем.
Что делать: Через границу идут только непрозрачные идентификаторы, суммы и факты. Подставьте свой external_id вместо контакта. ⚠ Проверка по форме ограничивает вид значения, а не его смысл: строка вроде 79991234567 алфавит проходит, и обязательство её не присылать — договорное, а не машинное.
RESERVED_EXTERNAL_ID · HTTP 400
external_id начинается с зарезервированного префикса. Это пространство ключей принадлежит внутренним операциям платформы.
Что делать: Возьмите любой свой префикс. Столкновение ключей на денежной операции молчаливо в ОБЕ стороны: занятый вами ключ превратил бы нашу операцию в идемпотентное попадание, и наоборот — поэтому граница отбивается, а не переписывается.
OCCURRED_AT_OUT_OF_WINDOW · HTTP 400
occurred_at глубже 90 дней назад. Окно времени события — от 90 дней назад до сейчас (+5 минут допуска на расходящиеся часы); конверсия вне окна не принимается (иначе бэкдейтинг клал конверсию в чужой день отчёта и ел кап того дня).
Что делать: Отправляйте событие с датой внутри окна. Досыл зависшей очереди сутками позже остаётся легальным: указывайте фактическое время события, пока оно моложе 90 дней; более старое — согласуйте с оператором сети вручную.
PARTNER_NOT_FOUND · HTTP 404
Партнёра с таким external_id в этой сети нет.
Что делать: Партнёр заводится POST /federation/v1/cpa/partners — метод идемпотентен по external_id, поэтому вызвать его повторно безопасно. Проверьте, что идентификатор совпадает буквально: сравнение точное, регистр значим.
PARTNER_NOT_ACTIVE · HTTP 409
Партнёр в сети есть, но работать сейчас не может: либо вы сами перевели его в partner_state: inactive, либо оператор снял роль (status не active), либо его заявка ещё в очереди оператора (status: pending).
Что делать: Текущее состояние отдаёт GET /federation/v1/cpa/partners/{external_id} — там оба поля, и право работать требует обоих. Своё вы меняете повторным POST /federation/v1/cpa/partners с partner_state: active; чужое снимает оператор в кабинете, и обойти это из API нельзя намеренно: иначе ваша синхронизация возвращала бы в строй отклонённого партнёра. ⚠ Отказ касается ВЫДАЧИ ссылки и приёма перехода. Конверсия по уже состоявшемуся клику принимается и оплачивается: трафик был доставлен до отключения, и не заплатить за него значило бы присвоить работу.
ADVERTISER_NOT_FOUND · HTTP 404
Рекламодателя с таким advertiser_id в этой сети нет.
Что делать: Рекламодатели заводятся оператором в кабинете и в API не создаются (см. раздел «Что делается в кабинете, а не по API»), поэтому идентификатор у них НАШ, а не ваш: возьмите его из ответа GET /federation/v1/cpa/offers (поле advertiser_id) или из карточки рекламодателя в кабинете. ⚠ Ответ 404, а не пустой список: опечатка в идентификаторе и «у рекламодателя нет офферов» — разные факты.
OFFER_NOT_FOUND · HTTP 404
Оффера с таким идентификатором нет, он не принадлежит вашей сети, у него не заведены условия CPA либо (методы ссылки и клика) у него нет посадки — адреса, куда вести посетителя; тогда текст ошибки говорит has no landing URL.
Что делать: Список доступных офферов отдаёт GET /federation/v1/cpa/offers. Оффер без посадки чинит оператор сети в настройках оффера, повтор запроса этого не исправит. ⚠ На HMAC-двери тот же код приезжает с 400 — там он означает «адрес постбэка не принадлежит ни одной сети» и отвечается до резолва арендатора; здесь арендатор уже известен, поэтому 404.
CONVERSION_NOT_FOUND · HTTP 404
Конверсии с таким external_id в этой сети нет — либо номер другой, либо цель другая, либо подтверждение не доехало.
Что делать: Конверсия адресуется тройкой «сеть + external_id + цель». Если вы отменяете конверсию по цели, отличной от первой, укажите goal — иначе ищется цель по умолчанию.
PAYOUT_NOT_FOUND · HTTP 404
Заявки на выплату с таким идентификатором в этой сети нет.
Что делать: Список заявок отдаёт GET /federation/v1/cpa/payouts; там же их идентификаторы.
UNKNOWN_GOAL · HTTP 400
В запросе указана цель, которой у оффера нет.
Что делать: Список целей — в GET /federation/v1/cpa/offers/{id}. Ставка «по умолчанию» вместо неизвестной цели не подставляется намеренно: заплатить по чужой ставке хуже, чем отказать.
GOAL_DISABLED · HTTP 409
Цель выключена оператором сети, а конверсии по ней раньше не было: новые конверсии по выключенной цели не принимаются.
Что делать: Состояние конфликта, а не кривой запрос: ставки и история цели сохранены, приём остановлен. Попросите оператора включить цель либо шлите другую. Уже записанные конверсии по ней подтверждаются и возвращаются как раньше — отказ касается только новых.
WINDOW_EXPIRED · HTTP 409
Клик состоялся раньше, чем позволяет окно атрибуции оффера: заказ пришёл, но связывать его с этим переходом уже поздно.
Что делать: Окно названо в условиях оффера. Задним числом конверсия не засчитывается; если ваш цикл сделки длиннее окна — окно меняет оператор в кабинете.
ALREADY_CONVERTED · HTTP 409
По этому переходу уже засчитана конверсия на ту же цель, но с другим external_id; ответ называет номер заказа, занявший пару. Один клик оплачивается один раз на цель — если у цели не включено «несколько конверсий с одного клика» (multiple_per_click в проекциях оффера, включает оператор). У включённой цели каждый заказ платится своей конверсией, и этот код от неё не приходит вовсе.
Что делать: Продолжение воронки — пришлите другую цель (goal), а не новый номер заказа. Тот же заказ — пришлите прежний external_id, и повтор попадёт в идемпотентность. Если с одного клика должно платиться несколько заказов одной цели — попросите оператора включить цели multiple_per_click.
EXTERNAL_ID_CONFLICT · HTTP 409
Этот external_id уже занят в сети по этой же цели — но другим оффером, не тем, что в запросе.
Что делать: Пространство номеров общее для СЕТИ, а не для оффера, поэтому у двух рекламодателей со сквозной нумерацией с единицы номера пересекутся. Добавьте к external_id собственный префикс рекламодателя.
ILLEGAL_TRANSITION · HTTP 409
Запрошенный переход статуса невозможен — например, подтвердить конверсию, по которой уже прошёл возврат.
Что делать: Текущий статус отдаёт GET /federation/v1/cpa/conversions/{external_id}. Отменённая конверсия терминальна: новое подтверждение оформляется новым external_id.
IDEMPOTENT_MISMATCH · HTTP 409
Операция с таким ключом идемпотентности уже была, но её параметры отличаются от присланных сейчас — чаще всего сумма.
Что делать: Успех «чужой» операции хуже отказа: он сообщил бы о деньгах, которых в кошельке нет. У заявки на выплату личность — партнёр и ПЕРИОД: за один период заявка одна. Повторяете ту же — пришлите ту же сумму; нужна другая — это заявка за другой период.
BELOW_MIN_PAYOUT · HTTP 400
Запрошенная сумма меньше минимальной выплаты сети. Порог отдаётся полем min_payout_rub в GET /federation/v1/cpa/partners/{external_id}/balance.
Что делать: Читайте порог из ответа баланса, а не из своей константы: оператор меняет его в кабинете, и захардкоженное значение однажды разойдётся.
INSUFFICIENT_BALANCE · HTTP 409
Доступного остатка партнёра не хватает на запрошенную сумму. Начисления в холде доступными не считаются.
Что делать: Сверьтесь с available_rub в балансе — это ровно то, что можно запросить сейчас. on_hold_rub станет доступным, когда истечёт холд конверсий, и отдельного запроса для этого не нужно.
REVERSAL_FAILED · HTTP 500
Возврат начался, но не завершился на нашей стороне.
Что делать: Повторите запрос: отмена идемпотентна и повторная ничего не испортит. Если повторяется — сообщите оператору meta.request_id.
13. Что делается в кабинете Recca, а не по API
Без этого раздела перечень читается как неполный API. Он не неполный — это
форма сделки: операторскую работу делает ваш сотрудник в готовом кабинете
на app.recca.ru, потому что рисовать свою админку по нашим методам вы не
захотели.
| # | Операция | Почему не в API |
|---|---|---|
| 1 | Рекламодатели: завести, список, правка | требует контактов и реквизитов — то есть ровно тех данных, которые граница не пропускает |
| 2 | Офферы: создать, условия и ставки, публикация, пауза | правка меняет обещание, уже данное вебмастерам; решение операторское навсегда |
| 3 | Креативы и посадочные: загрузка и правка | часть правки оффера |
| 4 | Отметка «выплачено» и запуск выплаты | деньги уходят с вашего счёта, и подтверждает это человек |
| 5 | Приостановка партнёра (санкция) | отдельно от вашей деактивации — см. 9.2 |
| 6 | Настройки сети: антифрод, уровни, холд, база ноги рекрутёра | конфигурация, а не операция |
| 7 | Ставка рекрутёра, white-label, персональные лимиты, журнал постбэков | там же |
⚠ В варианте «всё по API» методов было бы 25 вместо 18.
14. Сценарии приёмки
| Сценарий | Цепочка | Что в ответе доказывает |
|---|---|---|
| 1. Лид | partners → оффер cpl с целью registration, заведён оператором → links → clicks → conversions | GET /federation/v1/cpa/conversions/{external_id}: payout_rub + margin_rub == revenue_rub, partner_external_id — тот, кто привёл трафик |
| 2. Рекрутёр | partners (рекрутёр) → partners (вебмастер с recruiter_external_id) → оффер → клик → конверсия | конверсия несёт agent_leg {external_id, amount_rub, base, percent, hold_until}; amount == min(round(base × percent), margin_rub) — потолок маржой действует при ЛЮБОЙ базе. Чем является base, говорит GET /federation/v1/cpa/self → agent_base; когда нога станет доступной — agent_hold там же |
| 3. Целевое действие | offers (cpa, цели) → клик → conversions с goal | ставка цели, hold_until; после холда — approved и вебхук cpa.conversion.approved |
| 4. Revshare | offers (revshare, ставка рекламодателя R % и партнёра P %, условные числа) → клик → conversions с sum_rub | revenue = R % · sum, payout = P % · sum, margin = (R − P) % · sum |
| 5. Несколько конверсий с одного клика | offers — цель с multiple_per_click: true (включает оператор) → клик → ДВЕ conversions с одним click_id, одной целью, разными external_id → отмена одной | обе конверсии со своей payout_rub/hold_until; повтор того же external_id — идемпотентен; после отмены одной вторая жива; у цели без флага вторая даёт 409 ALREADY_CONVERTED с номером занявшего заказа |
Каждая цепочка проверяется программой, а не глазами: набор cpatest.Conformance
в Go-SDK прогоняется против песочницы и печатает request_id каждого шага.
15. Версионирование
Путь версионируется: /federation/v1/cpa/*. Ломающие правки едут новой
мажорной версией пути; прежняя живёт не менее двенадцати месяцев с заголовками
Deprecation и Sunset. Правила целиком —
«Ключи, права и лимиты», раздел «Версии API».
Версия контракта (дата) меняется на каждой
правке, включая совместимую, и отдаётся в GET /federation/v1/cpa/self. Сверяйте её при
запуске: расхождение версии — повод перечитать этот документ, а не повод для
тревоги.
Там же — environment: production, staging или sandbox, среда, в
которую вы пришли (с версии 2026-09-24). Отвечает сервер, а не ваша
конфигурация: адрес клиента можно перепутать, этот ответ — нет. Код, который
создаёт данные ради проверки (приёмочный набор SDK создаёт партнёра, одобренную
конверсию и заявку на выплату), обязан идти только туда, где здесь sandbox.
Что считается совместимой правкой
- новое необязательное поле в запросе;
- новое поле в ответе;
- новый код ошибки на новом условии;
- новый метод.
Что считается ломающей
- поле ответа исчезло или сменило тип;
- прежде необязательное поле стало обязательным;
- код ошибки сменил HTTP-статус или значение;
- изменилась строка канона подписи.
⚠ Именно поэтому у вас есть golden-векторы: ломающая правка подписи сделает их красными у вас, а не у нас.