OpenAPI: справочник методов
Два описания контракта: федерация (tenant API) и CPA-API.
Федерация (tenant API) · CPA-API · все разделы документации
Федерация (tenant API)
Программный интерфейс арендатора: каталог офферов, пользователи и реферальные ссылки, приём лидов и конверсий, значки, промокоды, OAuth-вход.
Аутентификация: ключ арендатора в заголовке `X-Recca-Tenant-Key`. Организация определяется по ключу. Ключ доверенный и не предназначен для браузера конечного пользователя. Каждый метод требует определённого права ключа (поле «Право ключа»).
Лимиты: запросы к `/federation/v1/*` считаются по ключу, не более 1000 в минуту на тарифе по умолчанию (верхние тарифы — больше). Остаток возвращается в заголовках `X-RateLimit-Limit` и `X-RateLimit-Remaining`; при превышении — ответ 429 и заголовок `Retry-After` в секундах. Проба `/federation/v1/health` в лимит не входит.
Ошибки приходят в едином формате: `{"success": false, "error": {"code", "message", "details"}}`.
Состояние
Проба живости без ключа.
GET /federation/v1/health Проба живости
Проверка работоспособности без ключа: общее состояние и состояние базы данных, кэша и ключей подписи токенов. Если хотя бы одна подсистема работает с перебоями, ответ 503.
Без ключа.
Ответы
-
200— Все подсистемы работают.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
statusstring, обязательное — Общее состояние. Допустимо:ok,degraded. -
databasestring, обязательное — База данных. Допустимо:ok,error. -
cachestring, обязательное — Кэш. Допустимо:ok,unavailable,error. -
jwksstring, обязательное — Ключи подписи токенов. Допустимо:ok,missing. -
timestampstring (date-time), обязательное — Время проверки.
-
-
-
503— Хотя бы одна подсистема работает с перебоями.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное — Полезная нагрузка ответа.
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/health' Пример ответа 200
{
"success": true,
"data": {
"status": "ok",
"database": "ok",
"cache": "ok",
"jwks": "ok",
"timestamp": "2026-01-15T10:00:00Z"
}
} Конверсии
Приём и отмена конверсий.
POST /federation/v1/conversions Передать конверсию
Повторный вызов с тем же `external_id` не создаёт вторую конверсию: приходит ответ 200 с прежним результатом. Бонус партнёру начисляется при первом приёме (201). Идемпотентность — по паре «организация + `external_id`».
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: conversions:write.
Тело запроса
-
recca_refstring, обязательное — Подписанная ссылка-метка из адреса лендинга (`recca_ref`). -
event_typestring, обязательное — Тип события в вашей системе. Пример:order_placed. -
amount_rubnumber, обязательное — Сумма заказа в рублях. -
external_idstring, обязательное — Ключ идемпотентности: уникален в пределах вашей организации. -
metadataobject — Произвольные данные о конверсии.
Ответы
-
200— Повтор: конверсия уже была принята, возвращён прежний результат.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
conversion_idstring, обязательное — Идентификатор конверсии в Recca. -
idempotentboolean, обязательное — true, если это повторный вызов и конверсия уже была принята. -
bonus_amount_rubnumber, обязательное — Начисленный бонус, рубли. -
bonus_transaction_idstring, nullable — Идентификатор бонусной операции; null, если бонус не начислен. -
partner_user_idstring, обязательное — Идентификатор партнёра, которому начислен бонус.
-
-
-
201— Принято впервые, бонус начислен.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
conversion_idstring, обязательное — Идентификатор конверсии в Recca. -
idempotentboolean, обязательное — true, если это повторный вызов и конверсия уже была принята. -
bonus_amount_rubnumber, обязательное — Начисленный бонус, рубли. -
bonus_transaction_idstring, nullable — Идентификатор бонусной операции; null, если бонус не начислен. -
partner_user_idstring, обязательное — Идентификатор партнёра, которому начислен бонус.
-
-
-
400— Некорректное тело запроса или недействительный `recca_ref`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— Метка принадлежит другой организации, значок не активен или у ключа нет нужного права.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
429— Превышен лимит запросов.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Conversions.Register. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/conversions' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "recca_ref": "<recca_ref>", "event_type": "order_placed", "amount_rub": 0, "external_id": "<external_id>", "metadata": {} }' Пример ответа 200
{
"success": true,
"data": {
"conversion_id": "<conversion_id>",
"idempotent": true,
"bonus_amount_rub": 1,
"bonus_transaction_id": "<bonus_transaction_id>",
"partner_user_id": "<partner_user_id>"
}
} POST /federation/v1/conversions/{external_id}/reverse Отменить конверсию по внешнему идентификатору
Отменяет начисления партнёру и агенту по ранее принятой конверсии. Повторная отмена той же конверсии отклоняется.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: conversions:reverse.
Параметры
-
external_id(path, string, обязательный) — Идентификатор конверсии в вашей системе — тот же, что передавался при приёме.
Ответы
-
200— Результат отмены с изменениями в учёте. -
400— Некорректное тело запроса либо конверсия уже отменена. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
404— Конверсия не найдена в вашей организации. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Conversions.Reverse. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/conversions/%3Cexternal_id%3E/reverse' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" OAuth
Вход пользователя Recca на сайте арендатора по OAuth.
POST /oauth/token Обменять код авторизации на токен доступа
Завершает вход по OAuth: меняет одноразовый `code`, полученный после согласия пользователя, на токен доступа. `redirect_uri` должен совпадать с тем, что передавался при запросе согласия.
Заголовок X-Recca-Tenant-Key с ключом арендатора.
Тело запроса
-
grant_typestring, обязательное Допустимо:authorization_code. -
codestring, обязательное -
redirect_uristring (uri), обязательное
Ответы
-
200— Токен доступа выдан.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное — Полезная нагрузка ответа.
-
Пример запроса
curl -X POST 'https://api.recca.ru/oauth/token' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "grant_type": "authorization_code", "code": "<code>", "redirect_uri": "https://example.com/" }' Пример ответа 200
{
"success": true,
"data": {}
} GET /oauth/authorize Данные экрана согласия
Публичная проверка перед экраном согласия: проверяет `client_id`, `redirect_uri` и `scope`, возвращает данные экрана согласия либо 302 на страницу согласия. Сессия не нужна.
Без ключа.
Параметры
-
client_id(query, string, обязательный) — Идентификатор приложения арендатора. -
redirect_uri(query, string, обязательный) — Адрес возврата после согласия; должен быть зарегистрирован у приложения. -
scope(query, string, обязательный) — Запрашиваемые права, через пробел. -
state(query, string) — Произвольная строка: вернётся без изменений в адресе возврата, защищает от подмены запроса.
Ответы
-
200— Данные экрана согласия. -
302— Перенаправление на страницу согласия. -
400— Недействительные `client_id`, `redirect_uri` или `scope`.
Пример запроса
curl -X GET 'https://api.recca.ru/oauth/authorize?client_id=%3Cclient_id%3E&redirect_uri=%3Credirect_uri%3E&scope=%3Cscope%3E' POST /oauth/consent Подтвердить или отклонить запрос авторизации
Нужна сессия пользователя платформы (Bearer-токен или сессионная кука). Отозванная сессия согласия выдать не может; при работе по куке проверяется источник запроса (защита от CSRF).
Токен доступа в заголовке Authorization: Bearer.
Ответы
-
200— Адрес возврата `redirect_to` вида `<redirect_uri>?code=…&state=…`. -
400— Некорректное тело запроса, `client_id`, `redirect_uri` или `scope`. -
401— Нет сессии или она отозвана (код `SESSION_REVOKED`). -
403— Аккаунт заблокирован либо источник запроса отклонён.
Пример запроса
curl -X POST 'https://api.recca.ru/oauth/consent' \
-H "Authorization: Bearer $RECCA_ACCESS_TOKEN" Профиль
Профиль и права текущего ключа.
GET /federation/v1/users/me Профиль пользователя, вошедшего через OAuth
Возвращает профиль пользователя, вошедшего через OAuth, в пределах прав, которые он выдал приложению.
Заголовок X-Recca-Tenant-Key с ключом арендатора.
Ответы
-
200— Профиль пользователя в пределах выданных прав.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное — Полезная нагрузка ответа.
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/users/me' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {}
} GET /federation/v1/self Права и организация текущего ключа
Если у ключа задан непустой список разрешённых IP-диапазонов, запрос с другого адреса получает 403 `IP_NOT_ALLOWED` с адресом клиента в `details.client_ip`.
Заголовок X-Recca-Tenant-Key с ключом арендатора.
Ответы
-
200— Права и организация ключа.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное — Полезная нагрузка ответа.
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен. -
403— Код `IP_NOT_ALLOWED`: адрес клиента не входит в разрешённые диапазоны ключа. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Self.Get. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/self' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {}
} Офферы
Каталог офферов арендатора.
GET /federation/v1/offers Список офферов арендатора
Нужно право `offers:read`. Возвращает публичные офферы витрин вашей организации. Черновики и скрытые офферы не отдаются никому, включая владельца.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: offers:read.
Параметры
-
shop_id(query, string) — Идентификатор витрины: оставить офферы только этой витрины. -
q(query, string) — Поиск по названию оффера, без учёта регистра. -
skip(query, integer) — Сколько записей пропустить с начала списка. По умолчанию 0. -
take(query, integer) — Сколько записей вернуть. По умолчанию 20, максимум 100.
Ответы
-
200— Страница каталога.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
offersarray<object>, обязательное-
idstring, обязательное — Идентификатор оффера. -
shop_idstring, обязательное — Идентификатор витрины. -
slugstring, nullable — Короткое имя оффера в адресе. -
titlestring, обязательное — Название. -
descriptionstring, nullable — Описание. -
pricenumber, nullable — Цена. -
price_maxnumber, nullable — Верхняя граница цены. -
currency_codestring, nullable — Код валюты. -
visibilitystring, обязательное — Видимость; в API отдаются только публичные. Допустимо:public. -
site_urlstring, nullable — Адрес страницы оффера. -
metadataobject, nullable — Дополнительные данные оффера.
-
-
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет права `offers:read`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Offers.List. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/offers' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {
"offers": [
{
"id": "<id>",
"shop_id": "<shop_id>",
"slug": "<slug>",
"title": "<title>",
"description": "<description>",
"price": 1,
"price_max": 1,
"currency_code": "<currency_code>",
"visibility": "public",
"site_url": "<site_url>",
"metadata": {}
}
]
}
} GET /federation/v1/offers/{id} Оффер с политикой комиссии
Нужно право `offers:read`. Возвращает публичный оффер вашей организации вместе с политикой комиссии (`bonus_policy`).
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: offers:read.
Параметры
-
id(path, string, обязательный) — Идентификатор оффера.
Ответы
-
200— Оффер с полем `bonus_policy`.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
offerobject, обязательное-
idstring, обязательное — Идентификатор оффера. -
shop_idstring, обязательное — Идентификатор витрины. -
slugstring, nullable — Короткое имя оффера в адресе. -
titlestring, обязательное — Название. -
descriptionstring, nullable — Описание. -
pricenumber, nullable — Цена. -
price_maxnumber, nullable — Верхняя граница цены. -
currency_codestring, nullable — Код валюты. -
visibilitystring, обязательное — Видимость; в API отдаются только публичные. Допустимо:public. -
site_urlstring, nullable — Адрес страницы оффера. -
metadataobject, nullable — Дополнительные данные оффера. -
bonus_policyobject, обязательное-
commission_pctnumber, обязательное Пример:5. -
currencystring, обязательное Пример:RUB. -
policy_versionstring, обязательное Пример:mvp-v1.
-
-
-
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет права `offers:read`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Оффер не найден, не публичный или принадлежит другой организации.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/offers/%3Cid%3E' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {
"offer": {
"id": "<id>",
"shop_id": "<shop_id>",
"slug": "<slug>",
"title": "<title>",
"description": "<description>",
"price": 1,
"price_max": 1,
"currency_code": "<currency_code>",
"visibility": "public",
"site_url": "<site_url>",
"metadata": {},
"bonus_policy": {
"commission_pct": 5,
"currency": "RUB",
"policy_version": "mvp-v1"
}
}
}
} Реферальные ссылки
Выпуск реферальных ссылок для участников.
POST /federation/v1/users/{id}/referral-links Выпустить реферальную ссылку для участника
Повторный вызов для той же пары «пользователь + оффер» возвращает тот же `deeplink_id`, а `signed_ref` каждый раз новый — так задумано. Пользователь должен быть участником вашей организации (иметь активный или ожидающий значок), иначе 403 `USER_NOT_MEMBER_OF_TENANT`. Адрес строится из шаблона ссылки лендинга организации (или оффера): только https, домен из списка разрешённых источников, обязательный плейсхолдер `{ref}`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: users:impersonate.
Параметры
-
id(path, string, обязательный) — `tenant_recca_id` пользователя — 16 символов base62 (рекомендуется) либо внутренний идентификатор Recca (для совместимости; будет отключён в IV квартале 2026).
Тело запроса
-
offer_idstring, обязательное
Ответы
-
200— Повтор: возвращена та же ссылка (`deeplink_id` прежний).-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
urlstring (uri), обязательное — Адрес лендинга на сайте арендатора. Всегда https, домен — из списка разрешённых источников организации. Строится из шаблона ссылки организации или оффера. -
signed_refstring, обязательное — Подписанный токен, который идёт в адресе как `recca_ref=...`. -
deeplink_idstring, обязательное — Постоянный идентификатор ссылки: не меняется при повторном выпуске для той же пары «пользователь + оффер».
-
-
-
201— Создана новая ссылка.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
urlstring (uri), обязательное — Адрес лендинга на сайте арендатора. Всегда https, домен — из списка разрешённых источников организации. Строится из шаблона ссылки организации или оффера. -
signed_refstring, обязательное — Подписанный токен, который идёт в адресе как `recca_ref=...`. -
deeplink_idstring, обязательное — Постоянный идентификатор ссылки: не меняется при повторном выпуске для той же пары «пользователь + оффер».
-
-
-
400— Код `INVALID_TEMPLATE` (домен не из списка разрешённых или нет `{ref}`) либо `INVALID_INPUT`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— Код `INSUFFICIENT_SCOPE` или `USER_NOT_MEMBER_OF_TENANT`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Код `OFFER_NOT_FOUND`: оффер не найден.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → ReferralLinks.Create. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/users/%3Cid%3E/referral-links' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "offer_id": "<offer_id>" }' Пример ответа 200
{
"success": true,
"data": {
"url": "https://example.com/",
"signed_ref": "<signed_ref>",
"deeplink_id": "<deeplink_id>"
}
} Пользователи
Пользователи арендатора, их бонусы и реферальное дерево. Адресуются непрозрачным идентификатором `tenant_recca_id`.
POST /federation/v1/users/upsert Связать или создать пользователя арендатора в Recca
Возвращает непрозрачный идентификатор пользователя для вашей организации (`tenant_recca_id`): храните его в своей базе как внешний ключ. Внутренний идентификатор Recca не передаётся никогда. Порядок поиска: сначала по `vk_id`, затем по `email` (только при `email_verified=true`). Если совпадения нет, создаётся управляемый пользователь с `claim_required=true`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: users:upsert.
Тело запроса
-
emailstring (email) — Почта пользователя. -
vk_idstring — Идентификатор пользователя во ВКонтакте. -
first_namestring, обязательное — Имя. -
last_namestring — Фамилия. -
email_verifiedboolean, обязательное — Должно быть true, чтобы Recca искала пользователя по почте. При false почта лишь сохраняется как предложенная, поиска по ней нет. -
marketing_consentboolean — Согласие пользователя на рассылки.
Ответы
-
200— Найден существующий пользователь.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
tenant_recca_idstring, обязательное — Непрозрачный идентификатор пользователя для вашей организации, 16 символов. Храните его как внешний ключ в своей базе. Внутренний идентификатор Recca вам не виден. -
is_newboolean, обязательное — true — Recca создала нового управляемого пользователя; false — найден существующий. -
claim_requiredboolean, обязательное — true, пока пользователь не завершил подтверждение аккаунта в Recca. Управляемому пользователю можно выпускать ссылки, но войти на recca.ru он не может.
-
-
-
201— Создан новый управляемый пользователь.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
tenant_recca_idstring, обязательное — Непрозрачный идентификатор пользователя для вашей организации, 16 символов. Храните его как внешний ключ в своей базе. Внутренний идентификатор Recca вам не виден. -
is_newboolean, обязательное — true — Recca создала нового управляемого пользователя; false — найден существующий. -
claim_requiredboolean, обязательное — true, пока пользователь не завершил подтверждение аккаунта в Recca. Управляемому пользователю можно выпускать ссылки, но войти на recca.ru он не может.
-
-
-
400— Код `INVALID_INPUT`: нет `first_name` либо не указаны ни `email`, ни `vk_id`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— Код `INSUFFICIENT_SCOPE`: у ключа нет нужного права.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
409— Код `EMAIL_BELONGS_TO_DIFFERENT_USER`: почта уже принадлежит другому пользователю Recca. Нужно подтверждение аккаунта.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Users.Upsert. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/users/upsert' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "email": "user@example.com", "vk_id": "<vk_id>", "first_name": "<first_name>", "last_name": "<last_name>", "email_verified": true, "marketing_consent": true }' Пример ответа 200
{
"success": true,
"data": {
"tenant_recca_id": "<tenant_recca_id>",
"is_new": true,
"claim_required": true
}
} GET /federation/v1/users Список пользователей арендатора
Нужно право `profile:read`. Список пользователей вашей организации; вместо внутренних идентификаторов Recca отдаются непрозрачные `tenant_recca_id`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: profile:read.
Ответы
-
200— Список пользователей (идентификаторы `tenant_recca_id`). -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/users' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" GET /federation/v1/users/{id} Карточка пользователя
Нужно право `profile:read`. Карточка пользователя, ранее связанного с вашей организацией методом `users/upsert`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: profile:read.
Параметры
-
id(path, string, обязательный) — `tenant_recca_id` пользователя — 16 символов base62 (рекомендуется) либо внутренний идентификатор Recca (для совместимости; будет отключён в IV квартале 2026).
Ответы
-
200— Карточка пользователя. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Не найдено или недоступно вашей организации. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Users.Get. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/users/%3Cid%3E' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" GET /federation/v1/users/{id}/bonus-balance Бонусный баланс пользователя
Нужно право `bonuses:read`. Бонусный баланс пользователя с разбивкой.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: bonuses:read.
Параметры
-
id(path, string, обязательный) — `tenant_recca_id` пользователя — 16 символов base62 (рекомендуется) либо внутренний идентификатор Recca (для совместимости; будет отключён в IV квартале 2026).
Ответы
-
200— Баланс с разбивкой. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Пользователь не найден или недоступен. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/users/%3Cid%3E/bonus-balance' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" POST /federation/v1/users/{id}/embed-session Выпустить сессию для встроенного кабинета
Нужно право `users:impersonate`. Выпускает токен сессии, с которым пользователь работает во встроенном кабинете на вашем сайте.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: users:impersonate.
Параметры
-
id(path, string, обязательный) — `tenant_recca_id` пользователя — 16 символов base62 (рекомендуется) либо внутренний идентификатор Recca (для совместимости; будет отключён в IV квартале 2026).
Ответы
-
200— Токен сессии встроенного кабинета. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
404— Пользователь не найден или недоступен. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/users/%3Cid%3E/embed-session' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" GET /federation/v1/users/{id}/tree Реферальное дерево пользователя
Нужно право `users:read`. Реферальное дерево пользователя; узлы названы идентификаторами `tenant_recca_id`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: users:read.
Параметры
-
id(path, string, обязательный) — `tenant_recca_id` пользователя — 16 символов base62 (рекомендуется) либо внутренний идентификатор Recca (для совместимости; будет отключён в IV квартале 2026).
Ответы
-
200— Узлы дерева с идентификаторами `tenant_recca_id`. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Пользователь не найден или недоступен. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Users.Tree. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/users/%3Cid%3E/tree' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" GET /federation/v1/users/{id}/tree/stats Статистика реферального дерева
Нужно право `users:read`. Сводка по реферальному дереву пользователя: глубина и число участников.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: users:read.
Параметры
-
id(path, string, обязательный) — `tenant_recca_id` пользователя — 16 символов base62 (рекомендуется) либо внутренний идентификатор Recca (для совместимости; будет отключён в IV квартале 2026).
Ответы
-
200— Глубина и число участников. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Пользователь не найден или недоступен. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/users/%3Cid%3E/tree/stats' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Лиды
Приём лидов с сайта арендатора и чтение их статусов.
POST /federation/v1/leads Передать лид
Идемпотентно по паре «организация + `external_id`». Перед созданием лида проверяется подпись `recca_ref`, принадлежность вашей организации и активность значка партнёра.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: leads:write.
Тело запроса
-
recca_refstring, обязательное — Подписанный токен из параметра `recca_ref` адреса лендинга. -
external_idstring, обязательное — Ваш ключ идемпотентности для этой отправки формы. -
lead_sourcestring — Источник лида: form_submit, phone_call, chat_message и другие. -
contactobject — Контактные данные, которые вы собрали у посетителя. -
metadataobject — Произвольные данные о лиде.
Ответы
-
200— Повтор: лид уже был принят.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
lead_idstring, обязательное — Идентификатор лида в Recca. -
idempotentboolean, обязательное — true, если лид уже был принят ранее. -
referrer_user_idstring, обязательное — Внутренний идентификатор партнёра-источника. Закрытое поле: не храните и не показывайте его; для CRM берите `tenant_recca_id` из `/users/{id}/leads`.
-
-
-
201— Лид создан.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
lead_idstring, обязательное — Идентификатор лида в Recca. -
idempotentboolean, обязательное — true, если лид уже был принят ранее. -
referrer_user_idstring, обязательное — Внутренний идентификатор партнёра-источника. Закрытое поле: не храните и не показывайте его; для CRM берите `tenant_recca_id` из `/users/{id}/leads`.
-
-
-
400— Код `INVALID_INPUT` или `INVALID_SIGNED_REF`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— Код `INSUFFICIENT_SCOPE`, `TENANT_MISMATCH` или `BADGE_NOT_ACTIVE`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Leads.Create. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/leads' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "recca_ref": "<recca_ref>", "external_id": "<external_id>", "lead_source": "<lead_source>", "contact": {}, "metadata": {} }' Пример ответа 200
{
"success": true,
"data": {
"lead_id": "<lead_id>",
"idempotent": true,
"referrer_user_id": "<referrer_user_id>"
}
} GET /federation/v1/users/{id}/leads Лиды конкретного партнёра
В пути можно указать `tenant_recca_id` или (для совместимости) внутренний идентификатор пользователя. Пользователь должен быть участником вашей организации. Выдаются только лиды вашей организации.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: users:read.
Параметры
-
id(path, string, обязательный) — `tenant_recca_id` пользователя — 16 символов base62 (рекомендуется) либо внутренний идентификатор Recca (для совместимости; будет отключён в IV квартале 2026). -
skip(query, integer) — Сколько записей пропустить с начала списка. По умолчанию 0. -
take(query, integer) — Сколько записей вернуть. По умолчанию 20, максимум 100. -
status(query, string) — Фильтр по статусу лида: new, processed, converted, rejected. Допустимо: new, processed, converted, rejected.
Ответы
-
200— Страница лидов.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
leadsarray<object>, обязательное-
idstring, обязательное — Идентификатор лида. -
organization_idstring, обязательное — Идентификатор организации. -
referrer_idstring, обязательное — Идентификатор партнёра-источника. -
offer_idstring, nullable — Идентификатор оффера. -
external_idstring, nullable — Идентификатор лида в вашей системе. -
typestring, обязательное — Тип лида. Допустимо:direct,agent,coauthor,inquiry. -
statusstring, обязательное — Статус лида. Допустимо:new,processed,converted,rejected. -
metadataobject, nullable — Дополнительные данные. -
created_atstring (date-time), обязательное — Время создания.
-
-
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— Код `INSUFFICIENT_SCOPE` или `USER_NOT_MEMBER_OF_TENANT`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Неизвестный `tenant_recca_id`.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Users.ListLeads. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/users/%3Cid%3E/leads' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {
"leads": [
{
"id": "<id>",
"organization_id": "<organization_id>",
"referrer_id": "<referrer_id>",
"offer_id": "<offer_id>",
"external_id": "<external_id>",
"type": "direct",
"status": "new",
"metadata": {},
"created_at": "2026-01-15T10:00:00Z"
}
]
}
} GET /federation/v1/leads/{id} Карточка лида
Чужой или несуществующий идентификатор даёт 404 — по ответу нельзя узнать, существует ли такой лид.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: leads:read.
Параметры
-
id(path, string, обязательный) — Идентификатор лида.
Ответы
-
200— Карточка лида.-
successboolean, обязательное — Всегда true. Допустимо:true. -
dataobject, обязательное-
leadobject, обязательное-
idstring, обязательное — Идентификатор лида. -
organization_idstring, обязательное — Идентификатор организации. -
referrer_idstring, обязательное — Идентификатор партнёра-источника. -
offer_idstring, nullable — Идентификатор оффера. -
external_idstring, nullable — Идентификатор лида в вашей системе. -
typestring, обязательное — Тип лида. Допустимо:direct,agent,coauthor,inquiry. -
statusstring, обязательное — Статус лида. Допустимо:new,processed,converted,rejected. -
metadataobject, nullable — Дополнительные данные. -
created_atstring (date-time), обязательное — Время создания.
-
-
-
-
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— Код `INSUFFICIENT_SCOPE`: у ключа нет нужного права.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Лид не найден или принадлежит другой организации.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/leads/%3Cid%3E' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {
"lead": {
"id": "<id>",
"organization_id": "<organization_id>",
"referrer_id": "<referrer_id>",
"offer_id": "<offer_id>",
"external_id": "<external_id>",
"type": "direct",
"status": "new",
"metadata": {},
"created_at": "2026-01-15T10:00:00Z"
}
}
} Промоматериалы
Промоматериалы, доступные арендатору.
GET /federation/v1/assets Список промоматериалов
Нужно право `promo:read`. Список промоматериалов, доступных вашей организации.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: promo:read.
Ответы
-
200— Список материалов. -
401— Ключ не передан или недействителен. -
403— У ключа нет нужного права либо функция не подключена в тарифе. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/assets' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" POST /federation/v1/assets/{id}/download Получить временную ссылку на материал
Нужно право `promo:read`. Выдаёт временную подписанную ссылку на скачивание материала.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: promo:read.
Параметры
-
id(path, string, обязательный) — Идентификатор промоматериала.
Ответы
-
200— Временная ссылка на скачивание. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
404— Материал не найден или недоступен. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/assets/%3Cid%3E/download' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Значки
Значки участников арендатора.
GET /federation/v1/badges Список значков
Нужно право `badges:read`. Список значков вашей организации.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: badges:read.
Ответы
-
200— Список значков. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/badges' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" POST /federation/v1/badges Создать или выдать значок
Нужно право `badges:write`. Создаёт значок или выдаёт его участнику.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: badges:write.
Ответы
-
200— Созданный значок. -
400— Некорректное тело запроса. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/badges' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" GET /federation/v1/badges/{id} Получить значок
Нужно право `badges:read`. Возвращает один значок вашей организации.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: badges:read.
Параметры
-
id(path, string, обязательный) — Идентификатор значка.
Ответы
-
200— Значок. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Не найдено или недоступно вашей организации. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/badges/%3Cid%3E' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" PATCH /federation/v1/badges/{id} Изменить значок
Нужно право `badges:write`. Изменяет значок вашей организации.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: badges:write.
Параметры
-
id(path, string, обязательный) — Идентификатор значка.
Ответы
-
200— Обновлённый значок. -
400— Некорректное тело запроса. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Не найдено или недоступно. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X PATCH 'https://api.recca.ru/federation/v1/badges/%3Cid%3E' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" DELETE /federation/v1/badges/{id} Удалить значок
Нужно право `badges:write`. Удаляет значок вашей организации.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: badges:write.
Параметры
-
id(path, string, обязательный) — Идентификатор значка.
Ответы
-
200— Удалено. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Не найдено или недоступно. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X DELETE 'https://api.recca.ru/federation/v1/badges/%3Cid%3E' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" POST /federation/v1/badges/{id}/request-public Запросить публичную страницу значка
Нужно право `badges:write`. Запрашивает публичную страницу значка для его владельца.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: badges:write.
Параметры
-
id(path, string, обязательный) — Идентификатор значка.
Ответы
-
200— Результат запроса публичной страницы. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
404— Значок не найден. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
В Go SDK: federation → Badges.RequestPublic. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/badges/%3Cid%3E/request-public' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Промокоды
Промокоды и промопрограммы.
POST /federation/v1/promo/issue Выдать промокод пользователю
Нужно право `promo:issue`. Выдаёт пользователю промокод по одной из промопрограмм организации.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: promo:issue.
Ответы
-
200— Выданный промокод. -
400— Некорректное тело запроса. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
404— Программа или пользователь не найдены. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/promo/issue' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" GET /federation/v1/promo/programs Список промопрограмм
Нужно право `promo:read`. Список промопрограмм вашей организации.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: promo:read.
Ответы
-
200— Список программ. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/promo/programs' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" POST /federation/v1/promo/validate Проверить пару «промокод — реферальный код»
Нужно право `promo:validate`. Проверяет пару «промокод — реферальный код» и возвращает результат проверки.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: promo:validate.
Ответы
-
200— Результат проверки. -
400— Некорректное тело запроса. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Код не найден. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/promo/validate' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" GET /federation/v1/users/{id}/promo-codes Промокоды пользователя
Нужно право `promo:read`. Промокоды, выданные пользователю.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: promo:read.
Параметры
-
id(path, string, обязательный) — `tenant_recca_id` пользователя — 16 символов base62 (рекомендуется) либо внутренний идентификатор Recca (для совместимости; будет отключён в IV квартале 2026).
Ответы
-
200— Список промокодов. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
404— Пользователь не найден или недоступен. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/users/%3Cid%3E/promo-codes' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Витрины
Витрины, привязанные к арендатору.
GET /federation/v1/shops Список витрин арендатора
Нужно право `shops:read`. Список витрин, привязанных к вашей организации.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: shops:read.
Ответы
-
200— Список витрин. -
401— Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
-
403— У ключа нет нужного права либо функция не подключена в тарифе. -
429— Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.-
successboolean, обязательное — Всегда false. Допустимо:false. -
errorobject, обязательное — Описание ошибки.-
codestring, обязательное — Машинный код ошибки. -
messagestring, обязательное — Текст ошибки. -
detailsobject — Подробности ошибки.
-
-
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/shops' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" CPA-API
Расчётный слой CPA для сети-арендатора: партнёры, офферы, ссылки, клики, конверсии, балансы, выплаты, статистика, вебхуки. Аутентификация — ключ арендатора в заголовке `X-Recca-Tenant-Key`. Организация выводится из ключа; слага в путях нет. ⚠ Ключ ДОВЕРЕННЫЙ и не предназначен для браузера конечного пользователя: один ключ адресует любого партнёра сети параметром. Разграничение по людям — работа интегратора (модель B headless). ⚠ Через границу не проходят персональные данные: ни имя, ни почта, ни телефон, ни адрес — ни партнёра, ни его клиента. Партнёр адресуется непрозрачным `external_id`.
self
Проба живости, версия контракта, настройка вебхуков.
GET /cpa/self Проба живости и версия контракта
Не входит в бюджет запросов — иначе мониторинг тратил бы лимит сети.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:self:read.
Ответы
-
200— Сеть доступна-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
contract_versionstring, обязательное — Сверяйте при запуске; расхождение — повод перечитать контракт. -
environmentstring, обязательное — Среда, в которую вы пришли. Отвечает СЕРВЕР, а не ваша конфигурация: адрес клиента можно перепутать, этот ответ — нет. Приёмочный набор SDK (`cpatest.Conformance`) создаёт данные — партнёра, конверсию, заявку на выплату — и обязан идти только туда, где здесь `sandbox`. Допустимо:production,staging,sandbox. -
network_idstring, обязательное — Непрозрачный идентификатор вашей сети на нашей стороне. ⚠ Имя без слова `external` намеренно: в остальном контракте `external_id` — это идентификатор, который назначаете ВЫ, а сеть заводится у нас. -
scopesarray<string>, обязательное -
agent_basestring, обязательное — От чего считается нога рекрутёра: `margin` — от маржи оператора, `payout` — от выплаты блогеру. Настройка сети, меняется оператором в кабинете; умолчание — `margin`. ⚠ Потолок ноги при ЛЮБОЙ базе остаётся маржой: нога платится из денег оператора, и процент от выплаты, превысивший маржу, означал бы доплату из его кармана. Допустимо:margin,payout. -
agent_holdobject — Когда нога рекрутёра становится доступной к выводу. Настройка сети.-
modestring, обязательное — `follow_conversion` — по холду самой конверсии (умолчание); `own_days` — свой срок сети. Допустимо:follow_conversion,own_days. -
daysinteger, nullable, обязательное — Число дней при `own_days`, иначе `null`. ⚠ Действующий срок — максимум из этого числа и холда конверсии: короче холда нельзя, потому что отмена откатывает только НЕВЫПЛАЧЕННУЮ ногу.
-
-
min_payout_rubinteger — Порог выплаты сети. Настраивается оператором в кабинете. -
rate_limit_per_mininteger, обязательное — Бюджет запросов ВАШЕГО ключа в минуту — то самое число, по которому принимается решение о `429`. Берите его отсюда, а не из таблицы величин: там гарантированный минимум и потолок, а здесь ваш фактический порог. -
webhook_configuredboolean — Настроен ли адрес для событий. Пишет его `PUT /cpa/self/webhook`.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Self.Get. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/self' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {
"contract_version": "<contract_version>",
"environment": "production",
"network_id": "<network_id>",
"scopes": [
"<строка>"
],
"agent_base": "margin",
"agent_hold": {
"mode": "follow_conversion",
"days": 1
},
"min_payout_rub": 1,
"rate_limit_per_min": 1,
"webhook_configured": true
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} PUT /cpa/self/webhook Куда слать события `cpa.*`
Секрет подписи выдаётся в ответе ОДИН раз — при первой установке и при каждой ротации. Сохраните его сразу: повторно он не показывается.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:self:write.
Тело запроса
-
urlstring (uri), обязательное — Адрес, на который сеть будет отправлять вебхуки. Пример:https://example.com/hooks/recca. -
rotate_secretboolean — true — выпустить новый секрет подписи. Пример:false.
Ответы
-
200— Адрес сохранён-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
urlstring (uri), обязательное -
eventsarray<string>, обязательное -
secretstring, nullable — ⚠ Показывается ОДИН раз — при установке и при каждой ротации. Сохраните сразу: повторно не выдаётся.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Self.SetWebhook. Гайд по Go SDK.
Пример запроса
curl -X PUT 'https://api.recca.ru/federation/v1/cpa/self/webhook' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "url": "https://example.com/hooks/recca", "rotate_secret": false }' Пример ответа 200
{
"success": true,
"data": {
"url": "https://example.com/",
"events": [
"cpa.conversion.approved"
],
"secret": "<secret>"
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} partners
Партнёры сети — вебмастеры, агенты, рекламодатели.
GET /cpa/partners Список партнёров
Кормит в том числе экран рекрутёра «мои блогеры» — фильтр `recruiter_external_id`. Отдаёт только партнёров, заведённых по API: у заведённого оператором в кабинете нет `external_id`, то есть адресовать его вы не можете. ⚠ Параметры разбираются СТРОГО, как и тела: неизвестный параметр — 400 `INVALID_INPUT`. Опечатка в имени фильтра иначе вернула бы полный список под видом отфильтрованного, и рекрутёр увидел бы чужих блогеров, ничего не заметив.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:partners:read.
Параметры
-
role(query, string) — ⚠ «Инфлюенсер» отдельной ролью не является — это `webmaster`. Допустимы только `webmaster` и `agent`; иная роль — 400 `INVALID_INPUT`, а не пустой список. Допустимо: advertiser, webmaster, agent. -
recruiter_external_id(query, string) — Оставить только партнёров, приведённых этим вебмастером (его `external_id`). -
status(query, string) — Фильтр по участию партнёра в сети. Допустимо: active, suspended, pending. -
limit(query, integer) — Размер страницы. Без параметра — 50. -
offset(query, integer) — Сколько записей пропустить с начала списка. По умолчанию 0.
Ответы
-
200— Страница списка-
successboolean, обязательное Допустимо:true. -
dataarray<object>, обязательное-
external_idstring, обязательное -
tenant_recca_idstring, обязательное — Наш непрозрачный идентификатор этого человека В ВАШЕЙ СЕТИ. Им адресуются общие методы федерации `/federation/v1/users/{id}/…` (дерево, баланс бонусов, ссылки) — если вы их используете. ⚠ Суррогат разный у разных сетей по построению: связать по нему одного человека между сетями нельзя, и это не недосмотр. -
rolestring, обязательное — ⚠ «Инфлюенсер» отдельной ролью не является — это `webmaster`. Источник трафика остаётся на стороне интегратора. ⚠ `agent` УСТАРЕЛ: новых агентов не заводится, приглашает любой вебмастер. Значение встретится в чтении только у партнёров, заведённых до перевода, и уйдёт из словаря следующей версией. Допустимо:advertiser,webmaster,agent. -
partner_statestring, обязательное — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо:active,inactive. -
statusstring, обязательное — Участие партнёра НА НАШЕЙ стороне. `active` — роль выдана и заявка принята; `pending` — роль есть, а заявка ещё в очереди оператора (бывает, если приём при заведении не прошёл); `suspended` — оператор снял роль. ⚠ Право работать требует ОБОИХ: и этого поля, и вашего `partner_state`. Своим `partner_state` вы это поле не меняете. Допустимо:active,suspended,pending. -
recruiter_external_idstring, nullable -
created_atstring (date-time), обязательное
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
429— Исчерпан бюджет запросов-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Partners.List. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/partners' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": [
{
"external_id": "<external_id>",
"tenant_recca_id": "<tenant_recca_id>",
"role": "advertiser",
"partner_state": "active",
"status": "active",
"recruiter_external_id": "<recruiter_external_id>",
"created_at": "2026-01-15T10:00:00Z"
}
],
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} POST /cpa/partners Завести партнёра или обновить его (upsert по `external_id`)
Идемпотентен по `external_id`. ⚠ `partner_state` — ВАШ признак («человек у нас ушёл»); санкцию оператора он не снимает: это другое поле, и право работать требует активности обоих. ⚠⚠ На УЖЕ заведённом партнёре меняются только ваши поля — `partner_state` и рекрутёр. Присланный с `role: agent` процент `agent_percent`, отличный от текущей личной ставки, отбивается 400 `INVALID_INPUT` с именем поля: ставку за приглашённых задаёт оператор в кабинете, применить её значило бы откатывать его решение каждой вашей синхронизацией, а проглотить молча — оставить вас в уверенности, что вы поменяли то, чего не меняли. ⚠ Роль `agent` устарела: партнёр, заведённый с `role: agent`, записывается ВЕБМАСТЕРОМ и возвращается с `role: webmaster`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:partners:write.
Тело запроса
-
external_idstring, обязательное — ⚠ Ключ идемпотентности и единственный способ адресовать человека. Алфавит ограничен намеренно: свободное поле — это щель, через которую персональные данные приезжают не дверью. ⚠⚠ Алфавит ограничивает ФОРМУ, а не смысл: `79991234567` его проходит. Пример:partner-42. -
rolestring, обязательное — ⚠ `advertiser` здесь НЕ принимается, хотя в чтении такая роль есть: рекламодатели заводятся оператором в кабинете (раздел «Что делается в кабинете, а не по API») — у них карточка-витрина, офферы и условия, то есть решения, которых машинная дверь не принимает. ⚠ `agent` — deprecated: принимается ради совместимости со старыми версиями SDK и записывается как `webmaster`; присланный с ним `agent_percent` становится личной ставкой вебмастера за приглашённых. Шлите `webmaster`. Допустимо:webmaster,agent. Пример:webmaster. -
partner_statestring — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо:active,inactive. -
recruiter_external_idstring, nullable — Кто привёл этого партнёра — вебмастер этой сети. Обязан быть УЖЕ заведённым партнёром сети (вербует любой вебмастер, отдельной роли рекрутёра нет) — иначе 404 `PARTNER_NOT_FOUND` либо 400 `INVALID_INPUT`. 400 и тогда, когда партнёр указан рекрутёром самому себе или двое указаны рекрутёрами друг друга. Нога вебмастера-рекрутёра платится по общей ставке сети (по умолчанию 0 — не платится). Молча проглотить его нельзя: рекрутёр, «не прикрепившийся» без ошибки, обнаруживается по деньгам. ⚠ Смена рекрутёра действует ВПЕРЁД: уже начисленные ноги заморожены на момент конверсии. ⚠ Три состояния ключа: отсутствие — «не меняем», строка — «прикрепить или сменить», `null` — ОТКРЕПИТЬ. Открепление действует вперёд, как и смена; открепить неприкреплённого — 200 без изменений. -
agent_percentnumber — Только вместе с устаревшей `role: agent`: становится ЛИЧНОЙ ставкой вебмастера за приглашённых (при создании). С `role: webmaster` игнорируется — личную ставку задаёт оператор в кабинете. Пример:10.
Ответы
-
200— Партнёр уже был — обновлено то, чем распоряжаетесь вы. ⚠ Роль, участие и санкция оператора при этом НЕ трогаются.-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное — ⚠ Ни имени, ни почты, ни телефона здесь нет и не будет — см. раздел 3 контракта.-
external_idstring, обязательное -
tenant_recca_idstring, обязательное — Наш непрозрачный идентификатор этого человека В ВАШЕЙ СЕТИ. Им адресуются общие методы федерации `/federation/v1/users/{id}/…` (дерево, баланс бонусов, ссылки) — если вы их используете. ⚠ Суррогат разный у разных сетей по построению: связать по нему одного человека между сетями нельзя, и это не недосмотр. -
rolestring, обязательное — ⚠ «Инфлюенсер» отдельной ролью не является — это `webmaster`. Источник трафика остаётся на стороне интегратора. ⚠ `agent` УСТАРЕЛ: новых агентов не заводится, приглашает любой вебмастер. Значение встретится в чтении только у партнёров, заведённых до перевода, и уйдёт из словаря следующей версией. Допустимо:advertiser,webmaster,agent. -
partner_statestring, обязательное — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо:active,inactive. -
statusstring, обязательное — Участие партнёра НА НАШЕЙ стороне. `active` — роль выдана и заявка принята; `pending` — роль есть, а заявка ещё в очереди оператора (бывает, если приём при заведении не прошёл); `suspended` — оператор снял роль. ⚠ Право работать требует ОБОИХ: и этого поля, и вашего `partner_state`. Своим `partner_state` вы это поле не меняете. Допустимо:active,suspended,pending. -
recruiter_external_idstring, nullable -
created_atstring (date-time), обязательное
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
201— Партнёр заведён впервые. Различайте 201 и 200, если ведёте собственный журнал: повтор безопасен, но событием не является.-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное — ⚠ Ни имени, ни почты, ни телефона здесь нет и не будет — см. раздел 3 контракта.-
external_idstring, обязательное -
tenant_recca_idstring, обязательное — Наш непрозрачный идентификатор этого человека В ВАШЕЙ СЕТИ. Им адресуются общие методы федерации `/federation/v1/users/{id}/…` (дерево, баланс бонусов, ссылки) — если вы их используете. ⚠ Суррогат разный у разных сетей по построению: связать по нему одного человека между сетями нельзя, и это не недосмотр. -
rolestring, обязательное — ⚠ «Инфлюенсер» отдельной ролью не является — это `webmaster`. Источник трафика остаётся на стороне интегратора. ⚠ `agent` УСТАРЕЛ: новых агентов не заводится, приглашает любой вебмастер. Значение встретится в чтении только у партнёров, заведённых до перевода, и уйдёт из словаря следующей версией. Допустимо:advertiser,webmaster,agent. -
partner_statestring, обязательное — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо:active,inactive. -
statusstring, обязательное — Участие партнёра НА НАШЕЙ стороне. `active` — роль выдана и заявка принята; `pending` — роль есть, а заявка ещё в очереди оператора (бывает, если приём при заведении не прошёл); `suspended` — оператор снял роль. ⚠ Право работать требует ОБОИХ: и этого поля, и вашего `partner_state`. Своим `partner_state` вы это поле не меняете. Допустимо:active,suspended,pending. -
recruiter_external_idstring, nullable -
created_atstring (date-time), обязательное
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
429— Исчерпан бюджет запросов-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Partners.Upsert. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/cpa/partners' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "external_id": "partner-42", "role": "webmaster", "partner_state": "active", "recruiter_external_id": "<recruiter_external_id>", "agent_percent": 10 }' Пример ответа 200
{
"success": true,
"data": {
"external_id": "<external_id>",
"tenant_recca_id": "<tenant_recca_id>",
"role": "advertiser",
"partner_state": "active",
"status": "active",
"recruiter_external_id": "<recruiter_external_id>",
"created_at": "2026-01-15T10:00:00Z"
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} GET /cpa/partners/{external_id} Карточка партнёра
Возвращает партнёра сети по вашему `external_id`. Неизвестный партнёр — 404 `PARTNER_NOT_FOUND`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:partners:read.
Параметры
-
external_id(path, string, обязательный) — Ваш идентификатор партнёра (`external_id`), тот же, что при заведении.
Ответы
-
200— Карточка-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное — ⚠ Ни имени, ни почты, ни телефона здесь нет и не будет — см. раздел 3 контракта.-
external_idstring, обязательное -
tenant_recca_idstring, обязательное — Наш непрозрачный идентификатор этого человека В ВАШЕЙ СЕТИ. Им адресуются общие методы федерации `/federation/v1/users/{id}/…` (дерево, баланс бонусов, ссылки) — если вы их используете. ⚠ Суррогат разный у разных сетей по построению: связать по нему одного человека между сетями нельзя, и это не недосмотр. -
rolestring, обязательное — ⚠ «Инфлюенсер» отдельной ролью не является — это `webmaster`. Источник трафика остаётся на стороне интегратора. ⚠ `agent` УСТАРЕЛ: новых агентов не заводится, приглашает любой вебмастер. Значение встретится в чтении только у партнёров, заведённых до перевода, и уйдёт из словаря следующей версией. Допустимо:advertiser,webmaster,agent. -
partner_statestring, обязательное — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо:active,inactive. -
statusstring, обязательное — Участие партнёра НА НАШЕЙ стороне. `active` — роль выдана и заявка принята; `pending` — роль есть, а заявка ещё в очереди оператора (бывает, если приём при заведении не прошёл); `suspended` — оператор снял роль. ⚠ Право работать требует ОБОИХ: и этого поля, и вашего `partner_state`. Своим `partner_state` вы это поле не меняете. Допустимо:active,suspended,pending. -
recruiter_external_idstring, nullable -
created_atstring (date-time), обязательное
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Partners.Get. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/partners/%3Cexternal_id%3E' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {
"external_id": "<external_id>",
"tenant_recca_id": "<tenant_recca_id>",
"role": "advertiser",
"partner_state": "active",
"status": "active",
"recruiter_external_id": "<recruiter_external_id>",
"created_at": "2026-01-15T10:00:00Z"
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} GET /cpa/partners/{external_id}/balance Баланс партнёра
Возвращает баланс партнёра сети по вашему `external_id`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:partners:read.
Параметры
-
external_id(path, string, обязательный) — Ваш идентификатор партнёра (`external_id`), тот же, что при заведении.
Ответы
-
200— Доступно, в холде, выплачено, порог-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
available_rubinteger, обязательное — Ровно то, что можно запросить к выплате сейчас. -
on_hold_rubinteger, обязательное — Станет доступным по истечении холда конверсий; отдельного запроса не нужно. -
paid_total_rubinteger, обязательное -
min_payout_rubinteger, обязательное — Порог сети. Читайте отсюда, а не из своей константы. -
can_requestboolean, обязательное
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Partners.Balance. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/partners/%3Cexternal_id%3E/balance' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {
"available_rub": 1,
"on_hold_rub": 1,
"paid_total_rub": 1,
"min_payout_rub": 1,
"can_request": true
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} offers
Каталог офферов и креативы.
GET /cpa/offers Каталог офферов
⚠⚠ Проекция выбирается параметром `view`, а не выводится из присутствия фильтра. Умолчание `partner` БЕЗОПАСНОЕ: партнёрская проекция не несёт `revenue_rate` и маржи никогда.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:offers:read.
Параметры
-
view(query, string) — Проекция оффера: `partner` (по умолчанию) или `advertiser`. Для `advertiser` нужен `advertiser_id`. Допустимо: partner, advertiser. -
advertiser_id(query, string) — Обязателен при `view=advertiser`: рекламодателю отдаются офферы его собственных витрин. ⚠ Идентификатор НАШ, а не ваш — карточку рекламодателя заводит оператор в кабинете, и внешнего идентификатора вы для неё не присылаете. Берите значение из поля `advertiser_id` любого оффера. Неизвестный — 404 `ADVERTISER_NOT_FOUND`, а не пустой список. -
limit(query, integer) — Размер страницы. Без параметра — 50. -
offset(query, integer) — Сколько записей пропустить с начала списка. По умолчанию 0.
Ответы
-
200— Страница каталога-
successboolean, обязательное Допустимо:true. -
dataarray<any>, обязательное -
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Offers.ListForPartner (view=partner), Offers.ListForAdvertiser (view=advertiser). Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/offers' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": [
"<строка>"
],
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} GET /cpa/offers/{id} Условия оффера
Возвращает условия одного оффера. Проекция зависит от параметра `view`: партнёрская или рекламодательская.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:offers:read.
Параметры
-
id(path, string, обязательный) — Идентификатор оффера из `GET /cpa/offers`. -
view(query, string) — Проекция оффера: `partner` (по умолчанию) или `advertiser`. Для `advertiser` нужен `advertiser_id`. Допустимо: partner, advertiser. -
advertiser_id(query, string) — Обязателен при `view=advertiser`: без него — 400 `INVALID_INPUT` (`details.field: advertiser_id`); идентификатор не того рекламодателя, которому принадлежит оффер, — 404 `ADVERTISER_NOT_FOUND`.
Ответы
-
200— Оффер-
successboolean, обязательное Допустимо:true. -
data, обязательное -
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Offers.GetForPartner (view=partner), Offers.GetForAdvertiser (view=advertiser). Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/offers/%3Cid%3E' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": "<data>",
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} GET /cpa/offers/{id}/creatives Креативы и посадочные оффера
⚠ Оффер «по запросу» (`access_mode: request`): материалы (посадочные и креативы, из которых собирается ссылка) отдаются только паре с одобренной заявкой сети. Пару называет `partner_external_id`; без него или без одобрения ответ — пустой список, а не ошибка. Карточка оффера (методы 6 и 7) при этом доступна целиком.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:offers:read.
Параметры
-
id(path, string, обязательный) — Идентификатор оффера из `GET /cpa/offers`. -
partner_external_id(query, string) — Партнёр, для которого запрошены материалы. Нужен только для офферов «по запросу»; у открытого оффера игнорируется.
Ответы
-
200— Список креативов-
successboolean, обязательное Допустимо:true. -
dataarray<object>, обязательное-
idstring, обязательное -
kindstring, обязательное Допустимо:banner,landing,text,video,other. -
titlestring, обязательное -
descriptionstring, nullable -
urlstring (uri), nullable — ⚠ `null` у текстового креатива: у рекламного текста файла нет по построению. Ветвитесь по `kind` — у `text` заполнено поле `text`. -
textstring, nullable -
mime_typestring, nullable -
widthinteger, nullable -
heightinteger, nullable -
is_defaultboolean — Основная посадочная. У креативов всегда `false` — понятие принадлежит лендам. -
created_atstring (date-time), nullable
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Offers.Creatives. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/offers/%3Cid%3E/creatives' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": [
{
"id": "<id>",
"kind": "banner",
"title": "<title>",
"description": "<description>",
"url": "https://example.com/",
"text": "<text>",
"mime_type": "<mime_type>",
"width": 1,
"height": 1,
"is_default": true,
"created_at": "2026-01-15T10:00:00Z"
}
],
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} traffic
Ссылки и клики.
POST /cpa/links Стабильная ссылка партнёра на оффер
Идемпотентен по паре «партнёр + оффер»: повтор возвращает ту же ссылку, а не вторую. Показывать и редиректить её должен ВАШ домен. ⚠ Партнёр, у которого право работать снято (ваш `partner_state: inactive` либо санкция оператора), ссылку не получает — 409 `PARTNER_NOT_ACTIVE`. Уже выпущенные ссылки при этом остаются в природе: отключение у вас — не отзыв ссылок.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:links:write.
Тело запроса
-
partner_external_idstring, обязательное — Ваш идентификатор партнёра (`external_id`). Пример:partner-42. -
offer_idstring, обязательное — Идентификатор оффера из `GET /cpa/offers`. Пример:offer_01.
Ответы
-
200— Ссылка на эту пару уже была — та же самая-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
codestring, обязательное -
target_urlstring (uri), обязательное — Адрес перехода НА НАШЕЙ стороне (`/go/{code}`). Брендированную ссылку рисует ваш домен; на переходе он либо ведёт сюда, либо зовёт метод 10 и получает уже разрешённый адрес рекламодателя. ⚠⚠ Это НЕ посадочная оффера, и подмена стоила бы денег: уведи вы клиента прямо на посадочную, переход не был бы засчитан — ни клика, ни атрибуции, ни выплаты блогеру, и ни одной ошибки в ответ. Хост адреса зависит от сети: если у сети подключён СВОЙ ДОМЕН адрес строится на нём — `https://<домен сети>/go/{code}`, иначе на базе платформы (`https://api.recca.ru/go/{code}`). Формат остаётся абсолютным `uri`; значение берите из ответа как есть и не собирайте адрес сами. Ранее выданные адреса на базе платформы работают бессрочно. -
partner_external_idstring, обязательное -
offer_idstring, обязательное -
created_atstring (date-time), обязательное
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
201— Ссылка выпущена-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
codestring, обязательное -
target_urlstring (uri), обязательное — Адрес перехода НА НАШЕЙ стороне (`/go/{code}`). Брендированную ссылку рисует ваш домен; на переходе он либо ведёт сюда, либо зовёт метод 10 и получает уже разрешённый адрес рекламодателя. ⚠⚠ Это НЕ посадочная оффера, и подмена стоила бы денег: уведи вы клиента прямо на посадочную, переход не был бы засчитан — ни клика, ни атрибуции, ни выплаты блогеру, и ни одной ошибки в ответ. Хост адреса зависит от сети: если у сети подключён СВОЙ ДОМЕН адрес строится на нём — `https://<домен сети>/go/{code}`, иначе на базе платформы (`https://api.recca.ru/go/{code}`). Формат остаётся абсолютным `uri`; значение берите из ответа как есть и не собирайте адрес сами. Ранее выданные адреса на базе платформы работают бессрочно. -
partner_external_idstring, обязательное -
offer_idstring, обязательное -
created_atstring (date-time), обязательное
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
409— Состояние не допускает операцию-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Links.Create. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/cpa/links' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "partner_external_id": "partner-42", "offer_id": "offer_01" }' Пример ответа 200
{
"success": true,
"data": {
"code": "<code>",
"target_url": "https://example.com/",
"partner_external_id": "<partner_external_id>",
"offer_id": "<offer_id>",
"created_at": "2026-01-15T10:00:00Z"
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} POST /cpa/clicks Зарегистрировать переход
⚠ НЕ идемпотентен по умолчанию: два перехода одного человека — два клика. Пришлите `client_click_id`, если ваш фронт может продублировать вызов.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:clicks:write.
Тело запроса
-
partner_external_idstring, обязательное — Ваш идентификатор партнёра (`external_id`). Пример:partner-42. -
offer_idstring, обязательное — Идентификатор оффера из `GET /cpa/offers`. Пример:offer_01. -
client_click_idstring — Необязательный ключ идемпотентности отправителя. Прислали — повтор возвращает ТОТ ЖЕ клик (200 вместо 201); не прислали — каждый вызов новый переход. Нужен там, где ваш фронт может продублировать вызов: дубль стоит не строки в таблице, а расхода капа оффера. ⚠⚠ Ключ принадлежит ПАРЕ «партнёр + оффер»: тот же ключ с другой парой — 409 `IDEMPOTENT_MISMATCH`, а не сохранённый переход. Иначе опечатка в счётчике вернула бы вам адрес чужого рекламодателя, а конверсию мы приписали бы не тому партнёру. Пример:ya-123456. -
sub_idstring — Ваша метка источника №1. Пример:s1. -
sub_id_2string — Ваша метка источника №2. Пример:s2. -
sub_id_3string — Ваша метка источника №3. Пример:s3. -
sub_id_4string — Ваша метка источника №4. Пример:s4. -
sub_id_5string — Ваша метка источника №5. Пример:s5. -
sub_id_6string — Ваша метка источника №6. Пример:s6. -
sub_id_7string — Ваша метка источника №7. Пример:s7. -
sub_id_8string — Ваша метка источника №8. Пример:s8. -
sub_id_9string — Ваша метка источника №9. Пример:s9. -
sub_id_10string — Ваша метка источника №10. Пример:s10. -
countrystring — ISO 3166-1 alpha-2. ⚠⚠ Адрес посетителя и строка его браузера дверью НЕ принимаются: раздел 3 контракта запрещает персональные данные «ни партнёра, ни его клиента», а IP — именно они. Страна и есть та величина, ради которой адрес читают; присылайте её. Пример:RU.
Ответы
-
200— Повтор по `client_click_id` — тот же переход, новой строки нет.-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
click_idstring, nullable, обязательное — ⚠ `null` при `status: trafficback`. Отбитый переход до рекламодателя не дошёл и конверсию породить не может — выдать по нему идентификатор значило бы пообещать невозможное. -
statusstring, обязательное — `trafficback` — переход принят и записан, но к рекламодателю не отправлен: исчерпан кап либо не подошло гео. Это НЕ ошибка запроса, поэтому код ответа успешный. Допустимо:open,trafficback. -
reasonstring, nullable — Почему переход отбит (`cap`, `geo`, `access_required`). `null` у обычного. `access_required` — оффер выдаётся по запросу, а у пары нет одобренной заявки сети. Перечень открыт: новые значения добавляются без смены версии контракта, неизвестное читайте как «переход отбит». -
redirect_urlstring (uri), nullable, обязательное — Куда отправить посетителя. ⚠ `null` означает «вести некуда»: кап исчерпан, а запасного адреса рекламодатель не объявил. Показывайте свою страницу. -
expires_atstring (date-time), nullable — Конец окна атрибуции этого перехода. -
created_atstring (date-time), обязательное -
offer_idstring -
partner_external_idstring
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
201— Клик зарегистрирован-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
click_idstring, nullable, обязательное — ⚠ `null` при `status: trafficback`. Отбитый переход до рекламодателя не дошёл и конверсию породить не может — выдать по нему идентификатор значило бы пообещать невозможное. -
statusstring, обязательное — `trafficback` — переход принят и записан, но к рекламодателю не отправлен: исчерпан кап либо не подошло гео. Это НЕ ошибка запроса, поэтому код ответа успешный. Допустимо:open,trafficback. -
reasonstring, nullable — Почему переход отбит (`cap`, `geo`, `access_required`). `null` у обычного. `access_required` — оффер выдаётся по запросу, а у пары нет одобренной заявки сети. Перечень открыт: новые значения добавляются без смены версии контракта, неизвестное читайте как «переход отбит». -
redirect_urlstring (uri), nullable, обязательное — Куда отправить посетителя. ⚠ `null` означает «вести некуда»: кап исчерпан, а запасного адреса рекламодатель не объявил. Показывайте свою страницу. -
expires_atstring (date-time), nullable — Конец окна атрибуции этого перехода. -
created_atstring (date-time), обязательное -
offer_idstring -
partner_external_idstring
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
409— Состояние не допускает операцию-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
429— Исчерпан бюджет запросов-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Clicks.Create. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/cpa/clicks' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "partner_external_id": "partner-42", "offer_id": "offer_01", "client_click_id": "ya-123456", "sub_id": "s1", "sub_id_2": "s2", "sub_id_3": "s3", "sub_id_4": "s4", "sub_id_5": "s5", "sub_id_6": "s6", "sub_id_7": "s7", "sub_id_8": "s8", "sub_id_9": "s9", "sub_id_10": "s10", "country": "RU" }' Пример ответа 200
{
"success": true,
"data": {
"click_id": "<click_id>",
"status": "open",
"reason": "<reason>",
"redirect_url": "https://example.com/",
"expires_at": "2026-01-15T10:00:00Z",
"created_at": "2026-01-15T10:00:00Z",
"offer_id": "<offer_id>",
"partner_external_id": "<partner_external_id>"
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} conversions
Приём результата, чтение и отмена.
GET /cpa/conversions Список конверсий
Список конверсий сети с фильтрами по партнёру, рекламодателю, офферу, статусу и периоду; постраничный.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:conversions:read.
Параметры
-
partner_external_id(query, string) — Неизвестный партнёр — 404 `PARTNER_NOT_FOUND`, а не пустой список: опечатка в идентификаторе и «конверсий не было» — разные факты. -
advertiser_id(query, string) — Наш идентификатор рекламодателя — см. `GET /cpa/offers`. -
offer_id(query, string) — Оставить только конверсии по этому офферу. -
status(query, string) — Фильтр по статусу конверсии. Допустимо: pending, hold, approved, declined, not_found. -
from(query, string) — Момент в ISO-8601, строка до 64 знаков. Не разбирается как момент — 400 `INVALID_INPUT`. -
to(query, string) — То же, что `from`. -
limit(query, integer) — Размер страницы. Без параметра — 50. -
offset(query, integer) — Сколько записей пропустить с начала списка. По умолчанию 0.
Ответы
-
200— Страница списка-
successboolean, обязательное Допустимо:true. -
dataarray<object>, обязательное-
external_idstring, обязательное -
goalstring, обязательное -
statusstring, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо:pending,hold,approved,declined,not_found. -
partner_external_idstring, nullable -
offer_idstring -
advertiser_idstring -
payout_rubinteger -
sum_rubnumber, nullable -
sub_idstring, nullable -
created_atstring (date-time), обязательное -
occurred_atstring (date-time), nullable -
hold_untilstring (date-time), nullable
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Фильтр назвал партнёра или рекламодателя, которого в этой сети нет. Пустой список на опечатку читался бы как «данных нет».-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
500— Сбой на нашей стороне; денежная операция не совершена-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Conversions.List. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/conversions' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": [
{
"external_id": "<external_id>",
"goal": "<goal>",
"status": "pending",
"partner_external_id": "<partner_external_id>",
"offer_id": "<offer_id>",
"advertiser_id": "<advertiser_id>",
"payout_rub": 1,
"sum_rub": 1,
"sub_id": "<sub_id>",
"created_at": "2026-01-15T10:00:00Z",
"occurred_at": "2026-01-15T10:00:00Z",
"hold_until": "2026-01-15T10:00:00Z"
}
],
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} POST /cpa/conversions Принять результат
Идемпотентен по тройке «сеть + `external_id` + `goal`». ⚠ Повтор с ДРУГИМИ параметрами — 409 `IDEMPOTENT_MISMATCH`, а не успех. ⚠ Неизвестный `click_id` (в этой сети такого клика нет) — 400 `INVALID_INPUT` с `details.field: click_id`, а не 404. ⚠⚠ Вердикт клиента «конверсия валидна» входом не является: сумма, цель и оффер сверяются с условиями. Качество трафика помечается `fraud_flags` и само по себе не блокирует.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:conversions:write.
Тело запроса
-
click_idstring, обязательное — Идентификатор перехода из ответа `POST /cpa/clicks`. Пример:c_8f2a91. -
external_idstring, обязательное — Ваш номер заказа. ⚠ Пространство номеров общее для СЕТИ: у двух рекламодателей со сквозной нумерацией они пересекутся — добавьте свой префикс. Префикс `recca:` зарезервирован. Пример:order-100500. -
statusstring, обязательное — Подтверждение — любое значение вне списков ожидания и отмены; `pending`/`wait`/`waiting`/`on_hold` — ждём; `cancel`/`reject` — отмена. Пример:approved. -
goalstring, nullable — ⚠ Три состояния: ключа нет — цель по умолчанию; `""` — пустая цель; значение — названная. Присутствие ключа значимо. Пример:purchase. -
sum_rubnumber, nullable — ⚠ «Не передали» и `0` — разные факты. Обязательна для процентных моделей. Пример:2490. -
sub_idstring — Ваша метка заказа. Пример:campaign-7. -
occurred_atstring (date-time) — Когда событие случилось у вас. Не прислали — берём момент приёма, а поле в ответе остаётся `null`: «не сказали» и «случилось тогда-то» — разные утверждения. Отчёты и окна считаются по `occurred_at ?? created_at`. ⚠ Время из будущего отбивается. Пример:2026-01-15T10:00:00Z.
Ответы
-
200— Идемпотентный повтор — та же конверсия-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
external_idstring, обязательное -
goalstring, обязательное -
statusstring, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо:pending,hold,approved,declined,not_found. -
partner_external_idstring, nullable -
offer_idstring -
advertiser_idstring -
payout_rubinteger, обязательное -
sum_rubnumber, nullable -
sub_idstring, nullable -
created_atstring (date-time), обязательное -
occurred_atstring (date-time), nullable -
hold_untilstring (date-time), nullable -
revenue_rubinteger, обязательное — Тройка ставок сходится: `payout_rub + margin_rub == revenue_rub`. -
margin_rubinteger, обязательное -
agent_legobject-
external_idstring, обязательное — Рекрутёр -
amount_rubinteger, обязательное -
basestring, обязательное — От чего считалась ЭТА нога — значение заморожено на момент конверсии. Текущая настройка сети в `GET /cpa/self` может быть уже другой: условия действуют вперёд, а карточка объясняет записанное. Допустимо:margin,payout. -
percentnumber, nullable, обязательное — Ставка, по которой ногу посчитали. `null` — нога записана до того, как условия стали замораживаться (значения не существует, и подставлять текущую ставку было бы враньём). -
hold_untilstring (date-time), nullable, обязательное — Когда нога станет доступной рекрутёру к выводу. `null` — то же, что у `percent`.
-
-
fraud_flagsarray<string> — Пометки качества трафика; сами по себе не блокируют.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
201— Конверсия создана-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
external_idstring, обязательное -
goalstring, обязательное -
statusstring, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо:pending,hold,approved,declined,not_found. -
partner_external_idstring, nullable -
offer_idstring -
advertiser_idstring -
payout_rubinteger, обязательное -
sum_rubnumber, nullable -
sub_idstring, nullable -
created_atstring (date-time), обязательное -
occurred_atstring (date-time), nullable -
hold_untilstring (date-time), nullable -
revenue_rubinteger, обязательное — Тройка ставок сходится: `payout_rub + margin_rub == revenue_rub`. -
margin_rubinteger, обязательное -
agent_legobject-
external_idstring, обязательное — Рекрутёр -
amount_rubinteger, обязательное -
basestring, обязательное — От чего считалась ЭТА нога — значение заморожено на момент конверсии. Текущая настройка сети в `GET /cpa/self` может быть уже другой: условия действуют вперёд, а карточка объясняет записанное. Допустимо:margin,payout. -
percentnumber, nullable, обязательное — Ставка, по которой ногу посчитали. `null` — нога записана до того, как условия стали замораживаться (значения не существует, и подставлять текущую ставку было бы враньём). -
hold_untilstring (date-time), nullable, обязательное — Когда нога станет доступной рекрутёру к выводу. `null` — то же, что у `percent`.
-
-
fraud_flagsarray<string> — Пометки качества трафика; сами по себе не блокируют.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
409— Состояние не допускает операцию-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
429— Исчерпан бюджет запросов-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
500— Сбой на нашей стороне; денежная операция не совершена-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Conversions.Create. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/cpa/conversions' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "click_id": "c_8f2a91", "external_id": "order-100500", "status": "approved", "goal": "purchase", "sum_rub": 2490, "sub_id": "campaign-7", "occurred_at": "2026-01-15T10:00:00Z" }' Пример ответа 200
{
"success": true,
"data": {
"external_id": "<external_id>",
"goal": "<goal>",
"status": "pending",
"partner_external_id": "<partner_external_id>",
"offer_id": "<offer_id>",
"advertiser_id": "<advertiser_id>",
"payout_rub": 1,
"sum_rub": 1,
"sub_id": "<sub_id>",
"created_at": "2026-01-15T10:00:00Z",
"occurred_at": "2026-01-15T10:00:00Z",
"hold_until": "2026-01-15T10:00:00Z",
"revenue_rub": 1,
"margin_rub": 1,
"agent_leg": {
"external_id": "<external_id>",
"amount_rub": 1,
"base": "margin",
"percent": 1,
"hold_until": "2026-01-15T10:00:00Z"
},
"fraud_flags": [
"<строка>"
]
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} GET /cpa/conversions/{external_id} Конверсия с тройкой ставок и ногой рекрутёра
Возвращает одну конверсию по вашему номеру заказа вместе с тремя ставками и долей рекрутёра.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:conversions:read.
Параметры
-
external_id(path, string, обязательный) — Ваш номер заказа (`external_id`), тот же, что при передаче конверсии. -
goal(query, string) — Конверсия адресуется тройкой «сеть + external_id + цель». Без параметра ищется цель по умолчанию.
Ответы
-
200— Конверсия-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
external_idstring, обязательное -
goalstring, обязательное -
statusstring, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо:pending,hold,approved,declined,not_found. -
partner_external_idstring, nullable -
offer_idstring -
advertiser_idstring -
payout_rubinteger, обязательное -
sum_rubnumber, nullable -
sub_idstring, nullable -
created_atstring (date-time), обязательное -
occurred_atstring (date-time), nullable -
hold_untilstring (date-time), nullable -
revenue_rubinteger, обязательное — Тройка ставок сходится: `payout_rub + margin_rub == revenue_rub`. -
margin_rubinteger, обязательное -
agent_legobject-
external_idstring, обязательное — Рекрутёр -
amount_rubinteger, обязательное -
basestring, обязательное — От чего считалась ЭТА нога — значение заморожено на момент конверсии. Текущая настройка сети в `GET /cpa/self` может быть уже другой: условия действуют вперёд, а карточка объясняет записанное. Допустимо:margin,payout. -
percentnumber, nullable, обязательное — Ставка, по которой ногу посчитали. `null` — нога записана до того, как условия стали замораживаться (значения не существует, и подставлять текущую ставку было бы враньём). -
hold_untilstring (date-time), nullable, обязательное — Когда нога станет доступной рекрутёру к выводу. `null` — то же, что у `percent`.
-
-
fraud_flagsarray<string> — Пометки качества трафика; сами по себе не блокируют.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Conversions.Get. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/conversions/%3Cexternal_id%3E' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": {
"external_id": "<external_id>",
"goal": "<goal>",
"status": "pending",
"partner_external_id": "<partner_external_id>",
"offer_id": "<offer_id>",
"advertiser_id": "<advertiser_id>",
"payout_rub": 1,
"sum_rub": 1,
"sub_id": "<sub_id>",
"created_at": "2026-01-15T10:00:00Z",
"occurred_at": "2026-01-15T10:00:00Z",
"hold_until": "2026-01-15T10:00:00Z",
"revenue_rub": 1,
"margin_rub": 1,
"agent_leg": {
"external_id": "<external_id>",
"amount_rub": 1,
"base": "margin",
"percent": 1,
"hold_until": "2026-01-15T10:00:00Z"
},
"fraud_flags": [
"<строка>"
]
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} POST /cpa/conversions/{external_id}/cancel Отклонить конверсию или оформить возврат
Идемпотентна: повторная отмена ничего не меняет. Отменённая конверсия терминальна — новое подтверждение оформляется новым `external_id`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:conversions:reverse.
Параметры
-
external_id(path, string, обязательный) — Ваш номер заказа (`external_id`), тот же, что при передаче конверсии.
Тело запроса
-
goalstring — Цель, по которой отменяется конверсия, если у заказа их несколько. Пример:purchase. -
reasonstring — Причина отмены, свободный текст. Пример:Заказ возвращён покупателем.
Ответы
-
200— Отменено-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
external_idstring, обязательное -
goalstring, обязательное -
statusstring, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо:pending,hold,approved,declined,not_found. -
partner_external_idstring, nullable -
offer_idstring -
advertiser_idstring -
payout_rubinteger, обязательное -
sum_rubnumber, nullable -
sub_idstring, nullable -
created_atstring (date-time), обязательное -
occurred_atstring (date-time), nullable -
hold_untilstring (date-time), nullable -
revenue_rubinteger, обязательное — Тройка ставок сходится: `payout_rub + margin_rub == revenue_rub`. -
margin_rubinteger, обязательное -
agent_legobject-
external_idstring, обязательное — Рекрутёр -
amount_rubinteger, обязательное -
basestring, обязательное — От чего считалась ЭТА нога — значение заморожено на момент конверсии. Текущая настройка сети в `GET /cpa/self` может быть уже другой: условия действуют вперёд, а карточка объясняет записанное. Допустимо:margin,payout. -
percentnumber, nullable, обязательное — Ставка, по которой ногу посчитали. `null` — нога записана до того, как условия стали замораживаться (значения не существует, и подставлять текущую ставку было бы враньём). -
hold_untilstring (date-time), nullable, обязательное — Когда нога станет доступной рекрутёру к выводу. `null` — то же, что у `percent`.
-
-
fraud_flagsarray<string> — Пометки качества трафика; сами по себе не блокируют.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
409— Состояние не допускает операцию-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
500— Сбой на нашей стороне; денежная операция не совершена-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Conversions.Cancel. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/cpa/conversions/%3Cexternal_id%3E/cancel' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "goal": "purchase", "reason": "Заказ возвращён покупателем" }' Пример ответа 200
{
"success": true,
"data": {
"external_id": "<external_id>",
"goal": "<goal>",
"status": "pending",
"partner_external_id": "<partner_external_id>",
"offer_id": "<offer_id>",
"advertiser_id": "<advertiser_id>",
"payout_rub": 1,
"sum_rub": 1,
"sub_id": "<sub_id>",
"created_at": "2026-01-15T10:00:00Z",
"occurred_at": "2026-01-15T10:00:00Z",
"hold_until": "2026-01-15T10:00:00Z",
"revenue_rub": 1,
"margin_rub": 1,
"agent_leg": {
"external_id": "<external_id>",
"amount_rub": 1,
"base": "margin",
"percent": 1,
"hold_until": "2026-01-15T10:00:00Z"
},
"fraud_flags": [
"<строка>"
]
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} payouts
Заявки на выплату.
GET /cpa/payouts История заявок на выплату
История заявок на выплату; можно отфильтровать по партнёру и статусу, постраничный.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:payouts:read.
Параметры
-
partner_external_id(query, string) — Неизвестный партнёр — 404 `PARTNER_NOT_FOUND`, а не пустой список. -
status(query, string) — Фильтр по статусу заявки на выплату. Допустимо: requested, approved, paid, rejected. -
limit(query, integer) — Размер страницы истории заявок. Без параметра — 20. -
offset(query, integer) — Сколько записей пропустить с начала списка. По умолчанию 0.
Ответы
-
200— Страница списка-
successboolean, обязательное Допустимо:true. -
dataarray<object>, обязательное-
idstring, обязательное -
partner_external_idstring, обязательное -
amount_rubinteger, обязательное -
statusstring, обязательное Допустимо:requested,approved,paid,rejected. -
period_fromstring (date) -
period_tostring (date) -
created_atstring (date-time), обязательное -
paid_atstring (date-time), nullable
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Payouts.List. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/payouts' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": [
{
"id": "<id>",
"partner_external_id": "<partner_external_id>",
"amount_rub": 1,
"status": "requested",
"period_from": "<period_from>",
"period_to": "<period_to>",
"created_at": "2026-01-15T10:00:00Z",
"paid_at": "2026-01-15T10:00:00Z"
}
],
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} POST /cpa/payouts Заявка на выплату
Личность заявки — сеть + `partner_external_id` + период (`period_from`..`period_to`); сумма в неё НЕ входит. ⚠ Повтор той же личности с другой суммой — 409 `IDEMPOTENT_MISMATCH`, а не новая заявка. ⚠ Отметку «выплачено» ставит оператор в кабинете: деньги уходят с его счёта, и подтверждает это человек.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:payouts:write.
Тело запроса
-
partner_external_idstring, обязательное — Ваш идентификатор партнёра (`external_id`). Пример:partner-42. -
amount_rubinteger, обязательное — Сумма заявки в рублях. Пример:5000. -
period_fromstring (date), обязательное — Начало периода, за который заявлена выплата (дата). Пример:2026-01-01. -
period_tostring (date), обязательное — Конец периода (дата). Пример:2026-01-31.
Ответы
-
200— Идемпотентный повтор — та же заявка-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
idstring, обязательное -
partner_external_idstring, обязательное -
amount_rubinteger, обязательное -
statusstring, обязательное Допустимо:requested,approved,paid,rejected. -
period_fromstring (date) -
period_tostring (date) -
created_atstring (date-time), обязательное -
paid_atstring (date-time), nullable
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
201— Заявка создана-
successboolean, обязательное Допустимо:true. -
dataobject, обязательное-
idstring, обязательное -
partner_external_idstring, обязательное -
amount_rubinteger, обязательное -
statusstring, обязательное Допустимо:requested,approved,paid,rejected. -
period_fromstring (date) -
period_tostring (date) -
created_atstring (date-time), обязательное -
paid_atstring (date-time), nullable
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
409— Состояние не допускает операцию-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Payouts.Create. Гайд по Go SDK.
Пример запроса
curl -X POST 'https://api.recca.ru/federation/v1/cpa/payouts' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" \
-H 'Content-Type: application/json' \
-d '{ "partner_external_id": "partner-42", "amount_rub": 5000, "period_from": "2026-01-01", "period_to": "2026-01-31" }' Пример ответа 200
{
"success": true,
"data": {
"id": "<id>",
"partner_external_id": "<partner_external_id>",
"amount_rub": 1,
"status": "requested",
"period_from": "<period_from>",
"period_to": "<period_to>",
"created_at": "2026-01-15T10:00:00Z",
"paid_at": "2026-01-15T10:00:00Z"
},
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
} statistics
Отчёты.
GET /cpa/statistics Отчёт
Считается по `occurred_at ?? created_at`: досланная пачкой вчерашняя конверсия попадает во вчерашний день, а не в сегодняшний. Без `from` берутся последние 30 дней. `from` позже `to` — 400 `INVALID_INPUT`. Неизвестный `partner_external_id` — 404 `PARTNER_NOT_FOUND`.
Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:stats:read.
Параметры
-
group_by(query, string, обязательный) — Разрез отчёта: по офферу, по партнёру или по дню. Допустимо: offer, partner, day. -
partner_external_id(query, string) — Оставить только данные этого партнёра (его `external_id`). -
advertiser_id(query, string) — Оставить только данные этого рекламодателя. -
offer_id(query, string) — Оставить только данные по этому офферу. -
from(query, string (date)) — Начало периода, дата (ГГГГ-ММ-ДД). -
to(query, string (date)) — Конец периода, дата (ГГГГ-ММ-ДД).
Ответы
-
200— Строки отчёта-
successboolean, обязательное Допустимо:true. -
dataarray<object>, обязательное-
keystring, обязательное — Идентификатор группы — оффер, партнёр или дата. -
clicksinteger, обязательное -
conversionsinteger, обязательное -
approvedinteger, обязательное -
payout_rubinteger, обязательное -
revenue_rubinteger, обязательное — Выручка группы. Приходит ВСЕГДА: ключ арендатора принадлежит оператору сети, а оператору выручка видна. ⚠ Прежняя редакция обещала «только в операторском разрезе» — партнёрского разреза у этой двери нет вовсе. Партнёру эта дверь не отдаётся; партнёрская проекция ставок — у офферов, и выручки рекламодателя в ней нет.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
400— Вход не прошёл проверку-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
401— Ключа нет, он пуст или отозван-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
403— Нет права, продукт не подключён или приостановлен-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
404— Сущность не найдена в этой сети-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
-
500— Сбой на нашей стороне; денежная операция не совершена-
successboolean, обязательное Допустимо:false. -
errorobject, обязательное-
codestring, обязательное — Перечень собирается из `utils/cpa-federation-error-codes.ts`. Значение и HTTP-статус каждого кода — часть контракта; описания — в разделе документации разработчика об ошибках. Допустимо:MISSING_TENANT_SCOPE,INSUFFICIENT_SCOPE,FEATURE_NOT_AVAILABLE,PRODUCT_PAUSED,RATE_LIMIT_EXCEEDED,INTERNAL_ERROR,INVALID_INPUT,PII_NOT_ACCEPTED,RESERVED_EXTERNAL_ID,OCCURRED_AT_OUT_OF_WINDOW,PARTNER_NOT_FOUND,PARTNER_NOT_ACTIVE,ADVERTISER_NOT_FOUND,OFFER_NOT_FOUND,CONVERSION_NOT_FOUND,PAYOUT_NOT_FOUND,UNKNOWN_GOAL,GOAL_DISABLED,WINDOW_EXPIRED,ALREADY_CONVERTED,EXTERNAL_ID_CONFLICT,ILLEGAL_TRANSITION,IDEMPOTENT_MISMATCH,BELOW_MIN_PAYOUT,INSUFFICIENT_BALANCE,REVERSAL_FAILED. -
messagestring, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является. -
details— Называет поле поимённо, если отказ про вход.
-
-
metaobject, обязательное-
request_idstring, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме. -
totalinteger -
countinteger -
offsetinteger -
limitinteger -
has_moreboolean -
truncatedboolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
-
-
В Go SDK: cpa → Statistics.Get. Гайд по Go SDK.
Пример запроса
curl -X GET 'https://api.recca.ru/federation/v1/cpa/statistics?group_by=offer' \
-H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY" Пример ответа 200
{
"success": true,
"data": [
{
"key": "<key>",
"clicks": 1,
"conversions": 1,
"approved": 1,
"payout_rub": 1,
"revenue_rub": 1
}
],
"meta": {
"request_id": "<request_id>",
"total": 1,
"count": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"truncated": true
}
}