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

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. Мы не знаем, кто из ваших пользователей сейчас за экраном, и проверить не можем. Отсюда два следствия, и оба обязательны:

  1. Ключ не предназначен для браузера вашего пользователя. Он живёт на вашем сервере. Положив его во фронтенд, вы отдадите каждому блогеру доступ к данным всех остальных.
  2. Ваш сервер обязан не пускать блогера 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_rub10 000 000 ₽
Предел sub_id и external_id конверсии200 символов
Предел external_id партнёра64 символа, алфавит [A-Za-z0-9_.:-]
Зарезервированный префикс external_idrecca:

⚠ Бюджет запросов считается по организации, а не по адресу отправителя: несколько ваших серверов делят общий счёт. Ответ 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.

#МетодСкоупКого кормит
1GET /federation/v1/cpa/selfcpa:self:readпроба живости, версия контракта, настройки сети
2POST /federation/v1/cpa/partnerscpa:partners:writeрегистрация партнёра (upsert по external_id) и его деактивация
3GET /federation/v1/cpa/partnerscpa:partners:readрекрутёр: мои блогеры (recruiter_external_id)
4GET /federation/v1/cpa/partners/{external_id}cpa:partners:readкарточка партнёра
5GET /federation/v1/cpa/partners/{external_id}/balancecpa:partners:readдоступно · в холде · выплачено · порог
6GET /federation/v1/cpa/offerscpa:offers:readблогер: каталог · рекламодатель: свои офферы
7GET /federation/v1/cpa/offers/{id}cpa:offers:readусловия, цели, гео, разрешённый трафик
8GET /federation/v1/cpa/offers/{id}/creativescpa:offers:readбаннеры и посадочные
9POST /federation/v1/cpa/linkscpa:links:writeстабильная ссылка партнёра на оффер
10POST /federation/v1/cpa/clickscpa:clicks:writeпереход по вашей брендированной ссылке
11POST /federation/v1/cpa/conversionscpa:conversions:writeприём результата
12GET /federation/v1/cpa/conversionscpa:conversions:readсписок с фильтрами
13GET /federation/v1/cpa/conversions/{external_id}cpa:conversions:readтройка ставок и нога рекрутёра
14POST /federation/v1/cpa/conversions/{external_id}/cancelcpa:conversions:reverseрекламодатель: отклонить или вернуть
15POST /federation/v1/cpa/payoutscpa:payouts:writeзаявка на выплату
16GET /federation/v1/cpa/payoutscpa:payouts:readистория заявок
17GET /federation/v1/cpa/statisticscpa:stats:readотчёт: group_by: offer|partner|day
18PUT /federation/v1/cpa/self/webhookcpa: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_ratepayout_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/links409 PARTNER_NOT_ACTIVE
10 POST /federation/v1/cpa/clicks409 PARTNER_NOT_ACTIVE
11 POST /federation/v1/cpa/conversionsпринимается и оплачивается

⚠⚠ Третья строка — решение, а не недосмотр. Клик — момент, когда сеть принимает трафик, и принимать его от того, кого вы отключили, незачем. А конверсия приходит ПОСЛЕ клика: трафик уже был куплен и доставлен, и отказ платить за него был бы не санкцией, а присвоением чужой работы.

Оффер «по запросу». Оператор может перевести оффер в режим «по запросу»: ссылка выдаётся только партнёру с одобренной заявкой. Для пары без одобрения:

МетодОтвет
POST /federation/v1/cpa/links409 PARTNER_NOT_ACTIVE с названием оффера в сообщении
POST /federation/v1/cpa/clicks201, переход отбит: 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_versionstringверсия контракта; сверяйте при запуске
environmentproduction · staging · sandboxсреда, в которую вы пришли; отвечает сервер, а не ваша конфигурация
network_idstringнаш непрозрачный идентификатор вашей сети
scopesstring[]права ключа
agent_basemargin · payoutот чего считается нога рекрутёра
agent_hold{mode, days}когда нога рекрутёра станет доступной: follow_conversion — по холду конверсии, own_days — свой срок (days), иначе days: null
min_payout_rubintegerпорог выплаты сети
rate_limit_per_minintegerваш фактический бюджет запросов в минуту
webhook_configuredbooleanнастроен ли адрес для событий

Ошибки: 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. Секрет подписи приходит в ответе один раз — при первой установке и при каждой ротации; повторно он не выдаётся.

Поле запросаТипОбязательноОграничения
urlstringдадо 2000 символов; только HTTPS, адреса внутренних сетей и localhost не принимаются
rotate_secretbooleanнетtrue — выпустить новый секрет; по умолчанию false
Поле ответаТипЧто значит
urlstringсохранённый адрес
eventsstring[]события, которые придут: cpa.conversion.approved, cpa.conversion.declined, cpa.conversion.reversed, cpa.payout.paid
secretstring · 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_idstringда^[A-Za-z0-9_.:-]{1,64}$; ключ идемпотентности
rolewebmaster · agentдаadvertiser не принимается; agent устарел — партнёр записывается вебмастером, шлите webmaster
partner_stateactive · inactiveнет«человек у вас ушёл»; санкцию оператора не снимает
recruiter_external_idstring · nullнетуже заведённый партнёр сети; не сам себе; ключа нет — не меняем, строка — прикрепить или сменить, null — открепить; действует вперёд
agent_percentnumberнет0–100; только вместе с устаревшей role: agent, при webmaster игнорируется
Поле ответаТипЧто значит
external_idstringваш идентификатор
tenant_recca_idstringнаш непрозрачный идентификатор человека в вашей сети
roleadvertiser · webmaster · agentроль; в чтении встречается и advertiser
partner_stateactive · inactiveваш признак
statusactive · pending · suspendedучастие на нашей стороне
recruiter_external_idstring · nullрекрутёр
created_atdate-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 нет, адресовать его нельзя.

ПараметрТипОбязательноОграничения
rolewebmaster · agentнетдругое значение — 400 INVALID_INPUT
statusactive · pending · suspendedнетучастие на нашей стороне
recruiter_external_idstringнет^[A-Za-z0-9_.:-]{1,64}$; фильтр «мои блогеры»
limitintegerнет1–200, по умолчанию 50
offsetintegerнетот 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_rubintegerровно то, что можно запросить к выплате сейчас
on_hold_rubintegerстанет доступным по истечении холда; отдельного запроса не нужно
paid_total_rubintegerвыплачено за всё время
min_payout_rubintegerпорог сети: читайте отсюда, а не из своей константы
can_requestbooleanможно ли подать заявку на выплату

Ошибки: 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 можно не передавать.

ПараметрТипОбязательноОграничения
viewpartner · advertiserнетпо умолчанию partner
advertiser_idstringнетдо 120 символов; наш идентификатор рекламодателя, сужает каталог до его офферов
limitintegerнет1–200, по умолчанию 50
offsetintegerнетот 0
Поле ответа (элемент массива)ТипЧто значит
id, namestringидентификатор и название оффера
advertiser_idstringнаш идентификатор рекламодателя
payout_modelcpa · 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_trafficstring[]разрешённые и запрещённые виды трафика
hold_days, attribution_window_daysinteger · 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 и маржа оператора в этой проекции не приходят никогда.

ПараметрТипОбязательноОграничения
viewadvertiserдабез view=advertiser вы получите партнёрскую проекцию
advertiser_idstringдадо 120 символов; наш идентификатор: берите из поля advertiser_id любого оффера
limit, offsetintegerнеткак в 9.6.7
Поле ответа (элемент массива)ТипЧто значит
id, name, advertiser_idstringкак в 9.6.7
payout_modelcpa · 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, titlestringидентификатор и название
kindbanner · landing · text · video · otherвид; ветвитесь по нему
descriptionstring · nullописание
urlstring · nullадрес файла; null у текстового креатива
textstring · nullтекст — у kind: text
mime_type, width, heightпараметры файла, могут быть null
is_defaultbooleanосновная посадочная; у креативов всегда false
created_atdate-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_idstringда^[A-Za-z0-9_.:-]{1,64}$; партнёр должен быть заведён
offer_idstringда1–120 символов
Поле ответаТипЧто значит
codestringкод ссылки
target_urlstringадрес перехода на нашей стороне (/go/{code}); брендированную ссылку рисует ваш домен, значение берите из ответа как есть
partner_external_id, offer_idstringпара
created_atdate-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_idstringда^[A-Za-z0-9_.:-]{1,64}$
offer_idstringда1–120 символов
client_click_idstringнетдо 200 символов; ваш ключ идемпотентности
sub_id, sub_id_2 … sub_id_10stringнетдо 200 символов каждое
countrystringнетISO 3166-1 alpha-2, ровно 2 символа

Адрес посетителя и строку его браузера дверь не принимает — они относятся к персональным данным. Присылайте страну.

Поле ответаТипЧто значит
click_idstring · nullидентификатор перехода; null при status: trafficback
statusopen · trafficbacktrafficback — переход записан, но к рекламодателю не отправлен (кап исчерпан, не подошло гео или нет доступа к офферу «по запросу»); это не ошибка запроса
reasonstring · nullпричина отбоя: cap, geo или access_required (оффер «по запросу», у пары нет одобренной заявки); перечень открыт — неизвестное значение читайте как «переход отбит»; у обычного перехода null
redirect_urlstring · nullкуда отправить посетителя; null — вести некуда, покажите свою страницу
expires_atdate-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_idstringда1–120 символов; идентификатор перехода
external_idstringда1–200 символов; ваш номер заказа, общий для сети; префикс recca: зарезервирован
statusstringда1–64 символа: pending, wait, waiting, on_hold — ожидание; cancel, reject — отмена; любое другое — подтверждение
goalstring · nullнетдо 64 символов; ключа нет — цель по умолчанию, значимо присутствие ключа
sum_rubnumber · nullнет0 … 10 000 000; обязательна для процентных моделей; «не передали» и 0 — разные факты
sub_idstringнетдо 200 символов
occurred_atdate-timeнетне из будущего, не старше 90 дней; не прислали — берётся момент приёма
Поле ответаТипЧто значит
external_id, goalstringномер заказа и цель; вместе с сетью они адресуют конверсию
statuspending · hold · approved · declined · not_foundсостояние; declined — отклонена или возвращена
partner_external_id, offer_id, advertiser_id
payout_rub, revenue_rub, margin_rubintegerтройка ставок: payout_rub + margin_rub == revenue_rub
sum_rub, sub_idкак присланы
created_at, occurred_at, hold_untildate-time · nulloccurred_at — null, если вы его не присылали
agent_legobject · nullнога рекрутёра: external_id, amount_rub, base, percent, hold_until
fraud_flagsstring[]пометки качества трафика

Ошибки: 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_idstringнет^[A-Za-z0-9_.:-]{1,64}$; неизвестный партнёр — 404, а не пустой список
advertiser_idstringнетдо 120 символов; наш идентификатор рекламодателя
offer_idstringнетдо 120 символов
statuspending · hold · approved · declined · not_foundнет
from, tostringнетмомент ISO-8601, до 64 символов
limitintegerнет1–200, по умолчанию 50
offsetintegerнетот 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_idstringда1–200 символов; партнёр должен быть заведён
amount_rubintegerдаот 1; не меньше порога сети (min_payout_rub) и не больше доступного
period_from, period_tostringдадаты YYYY-MM-DD; period_from не позже period_to
Поле ответаТипЧто значит
idstringидентификатор заявки (одна заявка — один id, даже если деньги списаны с нескольких кошельков)
partner_external_id, amount_rub
statusrequested · approved · paid · rejected
period_from, period_todate
created_at, paid_atdate-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_idstringнетдо 200 символов; неизвестный партнёр — 404
statusrequested · approved · paid · rejectedнет
limitintegerнет1–100, по умолчанию 20
offsetintegerнетот 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_byoffer · partner · dayда
partner_external_idstringнетдо 64 символов; неизвестный партнёр — 404
advertiser_idstringнетдо 120 символов
offer_idstringнетдо 120 символов
from, tostringнетдаты YYYY-MM-DD, to включительно; from не позже to; без from берутся последние 30 дней
Поле ответа (элемент массива)ТипЧто значит
keystringидентификатор группы: оффер, партнёр или дата
clicks, conversions, approvedintegerпереходы, конверсии, подтверждённые
payout_rub, revenue_rubintegerвыплаты партнёрам и выручка группы

Ошибки: 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_SCOPE401
INSUFFICIENT_SCOPE403
FEATURE_NOT_AVAILABLE403
PRODUCT_PAUSED403
RATE_LIMIT_EXCEEDED429
INTERNAL_ERROR500
INVALID_INPUT400
PII_NOT_ACCEPTED400
RESERVED_EXTERNAL_ID400
OCCURRED_AT_OUT_OF_WINDOW400
PARTNER_NOT_FOUND404
PARTNER_NOT_ACTIVE409
ADVERTISER_NOT_FOUND404
OFFER_NOT_FOUND404
CONVERSION_NOT_FOUND404
PAYOUT_NOT_FOUND404
UNKNOWN_GOAL400
GOAL_DISABLED409
WINDOW_EXPIRED409
ALREADY_CONVERTED409
EXTERNAL_ID_CONFLICT409
ILLEGAL_TRANSITION409
IDEMPOTENT_MISMATCH409
BELOW_MIN_PAYOUT400
INSUFFICIENT_BALANCE409
REVERSAL_FAILED500

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 → conversionsGET /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. Revshareoffers (revshare, ставка рекламодателя R % и партнёра P %, условные числа) → клик → conversions с sum_rubrevenue = 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-векторы: ломающая правка подписи сделает их красными у вас, а не у нас.