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

OpenAPI: справочник методов

Два описания контракта: федерация (tenant API) и CPA-API.

Федерация (tenant API) · CPA-API · все разделы документации

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

Версия описания: 1.0.0.

Адрес: https://api.recca.ru.

Скачать описание (YAML)

Программный интерфейс арендатора: каталог офферов, пользователи и реферальные ссылки, приём лидов и конверсий, значки, промокоды, 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 — Все подсистемы работают.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • status string, обязательное — Общее состояние. Допустимо: ok, degraded.
      • database string, обязательное — База данных. Допустимо: ok, error.
      • cache string, обязательное — Кэш. Допустимо: ok, unavailable, error.
      • jwks string, обязательное — Ключи подписи токенов. Допустимо: ok, missing.
      • timestamp string (date-time), обязательное — Время проверки.
  • 503 — Хотя бы одна подсистема работает с перебоями.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное — Полезная нагрузка ответа.

Пример запроса

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_ref string, обязательное — Подписанная ссылка-метка из адреса лендинга (`recca_ref`).
  • event_type string, обязательное — Тип события в вашей системе. Пример: order_placed.
  • amount_rub number, обязательное — Сумма заказа в рублях.
  • external_id string, обязательное — Ключ идемпотентности: уникален в пределах вашей организации.
  • metadata object — Произвольные данные о конверсии.

Ответы

  • 200 — Повтор: конверсия уже была принята, возвращён прежний результат.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • conversion_id string, обязательное — Идентификатор конверсии в Recca.
      • idempotent boolean, обязательное — true, если это повторный вызов и конверсия уже была принята.
      • bonus_amount_rub number, обязательное — Начисленный бонус, рубли.
      • bonus_transaction_id string, nullable — Идентификатор бонусной операции; null, если бонус не начислен.
      • partner_user_id string, обязательное — Идентификатор партнёра, которому начислен бонус.
  • 201 — Принято впервые, бонус начислен.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • conversion_id string, обязательное — Идентификатор конверсии в Recca.
      • idempotent boolean, обязательное — true, если это повторный вызов и конверсия уже была принята.
      • bonus_amount_rub number, обязательное — Начисленный бонус, рубли.
      • bonus_transaction_id string, nullable — Идентификатор бонусной операции; null, если бонус не начислен.
      • partner_user_id string, обязательное — Идентификатор партнёра, которому начислен бонус.
  • 400 — Некорректное тело запроса или недействительный `recca_ref`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — Метка принадлежит другой организации, значок не активен или у ключа нет нужного права.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 429 — Превышен лимит запросов.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 404 — Конверсия не найдена в вашей организации.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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_type string, обязательное Допустимо: authorization_code.
  • code string, обязательное
  • redirect_uri string (uri), обязательное

Ответы

  • 200 — Токен доступа выдан.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное — Полезная нагрузка ответа.

Пример запроса

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 — Профиль пользователя в пределах выданных прав.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное — Полезная нагрузка ответа.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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 — Права и организация ключа.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное — Полезная нагрузка ответа.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
  • 403 — Код `IP_NOT_ALLOWED`: адрес клиента не входит в разрешённые диапазоны ключа.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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 — Страница каталога.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • offers array<object>, обязательное
        • id string, обязательное — Идентификатор оффера.
        • shop_id string, обязательное — Идентификатор витрины.
        • slug string, nullable — Короткое имя оффера в адресе.
        • title string, обязательное — Название.
        • description string, nullable — Описание.
        • price number, nullable — Цена.
        • price_max number, nullable — Верхняя граница цены.
        • currency_code string, nullable — Код валюты.
        • visibility string, обязательное — Видимость; в API отдаются только публичные. Допустимо: public.
        • site_url string, nullable — Адрес страницы оффера.
        • metadata object, nullable — Дополнительные данные оффера.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет права `offers:read`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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`.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • offer object, обязательное
        • id string, обязательное — Идентификатор оффера.
        • shop_id string, обязательное — Идентификатор витрины.
        • slug string, nullable — Короткое имя оффера в адресе.
        • title string, обязательное — Название.
        • description string, nullable — Описание.
        • price number, nullable — Цена.
        • price_max number, nullable — Верхняя граница цены.
        • currency_code string, nullable — Код валюты.
        • visibility string, обязательное — Видимость; в API отдаются только публичные. Допустимо: public.
        • site_url string, nullable — Адрес страницы оффера.
        • metadata object, nullable — Дополнительные данные оффера.
        • bonus_policy object, обязательное
          • commission_pct number, обязательное Пример: 5.
          • currency string, обязательное Пример: RUB.
          • policy_version string, обязательное Пример: mvp-v1.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет права `offers:read`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Оффер не найден, не публичный или принадлежит другой организации.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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_id string, обязательное

Ответы

  • 200 — Повтор: возвращена та же ссылка (`deeplink_id` прежний).
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • url string (uri), обязательное — Адрес лендинга на сайте арендатора. Всегда https, домен — из списка разрешённых источников организации. Строится из шаблона ссылки организации или оффера.
      • signed_ref string, обязательное — Подписанный токен, который идёт в адресе как `recca_ref=...`.
      • deeplink_id string, обязательное — Постоянный идентификатор ссылки: не меняется при повторном выпуске для той же пары «пользователь + оффер».
  • 201 — Создана новая ссылка.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • url string (uri), обязательное — Адрес лендинга на сайте арендатора. Всегда https, домен — из списка разрешённых источников организации. Строится из шаблона ссылки организации или оффера.
      • signed_ref string, обязательное — Подписанный токен, который идёт в адресе как `recca_ref=...`.
      • deeplink_id string, обязательное — Постоянный идентификатор ссылки: не меняется при повторном выпуске для той же пары «пользователь + оффер».
  • 400 — Код `INVALID_TEMPLATE` (домен не из списка разрешённых или нет `{ref}`) либо `INVALID_INPUT`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — Код `INSUFFICIENT_SCOPE` или `USER_NOT_MEMBER_OF_TENANT`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Код `OFFER_NOT_FOUND`: оффер не найден.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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.

Тело запроса

  • email string (email) — Почта пользователя.
  • vk_id string — Идентификатор пользователя во ВКонтакте.
  • first_name string, обязательное — Имя.
  • last_name string — Фамилия.
  • email_verified boolean, обязательное — Должно быть true, чтобы Recca искала пользователя по почте. При false почта лишь сохраняется как предложенная, поиска по ней нет.
  • marketing_consent boolean — Согласие пользователя на рассылки.

Ответы

  • 200 — Найден существующий пользователь.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • tenant_recca_id string, обязательное — Непрозрачный идентификатор пользователя для вашей организации, 16 символов. Храните его как внешний ключ в своей базе. Внутренний идентификатор Recca вам не виден.
      • is_new boolean, обязательное — true — Recca создала нового управляемого пользователя; false — найден существующий.
      • claim_required boolean, обязательное — true, пока пользователь не завершил подтверждение аккаунта в Recca. Управляемому пользователю можно выпускать ссылки, но войти на recca.ru он не может.
  • 201 — Создан новый управляемый пользователь.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • tenant_recca_id string, обязательное — Непрозрачный идентификатор пользователя для вашей организации, 16 символов. Храните его как внешний ключ в своей базе. Внутренний идентификатор Recca вам не виден.
      • is_new boolean, обязательное — true — Recca создала нового управляемого пользователя; false — найден существующий.
      • claim_required boolean, обязательное — true, пока пользователь не завершил подтверждение аккаунта в Recca. Управляемому пользователю можно выпускать ссылки, но войти на recca.ru он не может.
  • 400 — Код `INVALID_INPUT`: нет `first_name` либо не указаны ни `email`, ни `vk_id`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — Код `INSUFFICIENT_SCOPE`: у ключа нет нужного права.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 409 — Код `EMAIL_BELONGS_TO_DIFFERENT_USER`: почта уже принадлежит другому пользователю Recca. Нужно подтверждение аккаунта.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Не найдено или недоступно вашей организации.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Пользователь не найден или недоступен.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 404 — Пользователь не найден или недоступен.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Пользователь не найден или недоступен.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Пользователь не найден или недоступен.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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_ref string, обязательное — Подписанный токен из параметра `recca_ref` адреса лендинга.
  • external_id string, обязательное — Ваш ключ идемпотентности для этой отправки формы.
  • lead_source string — Источник лида: form_submit, phone_call, chat_message и другие.
  • contact object — Контактные данные, которые вы собрали у посетителя.
  • metadata object — Произвольные данные о лиде.

Ответы

  • 200 — Повтор: лид уже был принят.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • lead_id string, обязательное — Идентификатор лида в Recca.
      • idempotent boolean, обязательное — true, если лид уже был принят ранее.
      • referrer_user_id string, обязательное — Внутренний идентификатор партнёра-источника. Закрытое поле: не храните и не показывайте его; для CRM берите `tenant_recca_id` из `/users/{id}/leads`.
  • 201 — Лид создан.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • lead_id string, обязательное — Идентификатор лида в Recca.
      • idempotent boolean, обязательное — true, если лид уже был принят ранее.
      • referrer_user_id string, обязательное — Внутренний идентификатор партнёра-источника. Закрытое поле: не храните и не показывайте его; для CRM берите `tenant_recca_id` из `/users/{id}/leads`.
  • 400 — Код `INVALID_INPUT` или `INVALID_SIGNED_REF`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — Код `INSUFFICIENT_SCOPE`, `TENANT_MISMATCH` или `BADGE_NOT_ACTIVE`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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 — Страница лидов.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • leads array<object>, обязательное
        • id string, обязательное — Идентификатор лида.
        • organization_id string, обязательное — Идентификатор организации.
        • referrer_id string, обязательное — Идентификатор партнёра-источника.
        • offer_id string, nullable — Идентификатор оффера.
        • external_id string, nullable — Идентификатор лида в вашей системе.
        • type string, обязательное — Тип лида. Допустимо: direct, agent, coauthor, inquiry.
        • status string, обязательное — Статус лида. Допустимо: new, processed, converted, rejected.
        • metadata object, nullable — Дополнительные данные.
        • created_at string (date-time), обязательное — Время создания.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — Код `INSUFFICIENT_SCOPE` или `USER_NOT_MEMBER_OF_TENANT`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Неизвестный `tenant_recca_id`.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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 — Карточка лида.
    • success boolean, обязательное — Всегда true. Допустимо: true.
    • data object, обязательное
      • lead object, обязательное
        • id string, обязательное — Идентификатор лида.
        • organization_id string, обязательное — Идентификатор организации.
        • referrer_id string, обязательное — Идентификатор партнёра-источника.
        • offer_id string, nullable — Идентификатор оффера.
        • external_id string, nullable — Идентификатор лида в вашей системе.
        • type string, обязательное — Тип лида. Допустимо: direct, agent, coauthor, inquiry.
        • status string, обязательное — Статус лида. Допустимо: new, processed, converted, rejected.
        • metadata object, nullable — Дополнительные данные.
        • created_at string (date-time), обязательное — Время создания.
  • 401 — Код `MISSING_TENANT_KEY` или `INVALID_TENANT_KEY`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — Код `INSUFFICIENT_SCOPE`: у ключа нет нужного права.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Лид не найден или принадлежит другой организации.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 404 — Материал не найден или недоступен.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Не найдено или недоступно вашей организации.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Не найдено или недоступно.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Не найдено или недоступно.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 404 — Значок не найден.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

В 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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 404 — Программа или пользователь не найдены.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Код не найден.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 404 — Пользователь не найден или недоступен.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

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`: ключ не передан или недействителен.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.
  • 403 — У ключа нет нужного права либо функция не подключена в тарифе.
  • 429 — Код `RATE_LIMIT_EXCEEDED`: превышен лимит запросов ключа. Повторите через `Retry-After` секунд.
    • success boolean, обязательное — Всегда false. Допустимо: false.
    • error object, обязательное — Описание ошибки.
      • code string, обязательное — Машинный код ошибки.
      • message string, обязательное — Текст ошибки.
      • details object — Подробности ошибки.

Пример запроса

curl -X GET 'https://api.recca.ru/federation/v1/shops' \
  -H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY"

CPA-API

Версия описания: 2026-10-02.

Адрес: https://api.recca.ru/federation/v1 · https://api-sandbox.recca.ru/federation/v1.

Скачать описание (YAML)

Расчётный слой CPA для сети-арендатора: партнёры, офферы, ссылки, клики, конверсии, балансы, выплаты, статистика, вебхуки. Аутентификация — ключ арендатора в заголовке `X-Recca-Tenant-Key`. Организация выводится из ключа; слага в путях нет. ⚠ Ключ ДОВЕРЕННЫЙ и не предназначен для браузера конечного пользователя: один ключ адресует любого партнёра сети параметром. Разграничение по людям — работа интегратора (модель B headless). ⚠ Через границу не проходят персональные данные: ни имя, ни почта, ни телефон, ни адрес — ни партнёра, ни его клиента. Партнёр адресуется непрозрачным `external_id`.

self

Проба живости, версия контракта, настройка вебхуков.

GET /cpa/self Проба живости и версия контракта

Не входит в бюджет запросов — иначе мониторинг тратил бы лимит сети.

Заголовок X-Recca-Tenant-Key с ключом арендатора. Право ключа: cpa:self:read.

Ответы

  • 200 — Сеть доступна
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • contract_version string, обязательное — Сверяйте при запуске; расхождение — повод перечитать контракт.
      • environment string, обязательное — Среда, в которую вы пришли. Отвечает СЕРВЕР, а не ваша конфигурация: адрес клиента можно перепутать, этот ответ — нет. Приёмочный набор SDK (`cpatest.Conformance`) создаёт данные — партнёра, конверсию, заявку на выплату — и обязан идти только туда, где здесь `sandbox`. Допустимо: production, staging, sandbox.
      • network_id string, обязательное — Непрозрачный идентификатор вашей сети на нашей стороне. ⚠ Имя без слова `external` намеренно: в остальном контракте `external_id` — это идентификатор, который назначаете ВЫ, а сеть заводится у нас.
      • scopes array<string>, обязательное
      • agent_base string, обязательное — От чего считается нога рекрутёра: `margin` — от маржи оператора, `payout` — от выплаты блогеру. Настройка сети, меняется оператором в кабинете; умолчание — `margin`. ⚠ Потолок ноги при ЛЮБОЙ базе остаётся маржой: нога платится из денег оператора, и процент от выплаты, превысивший маржу, означал бы доплату из его кармана. Допустимо: margin, payout.
      • agent_hold object — Когда нога рекрутёра становится доступной к выводу. Настройка сети.
        • mode string, обязательное — `follow_conversion` — по холду самой конверсии (умолчание); `own_days` — свой срок сети. Допустимо: follow_conversion, own_days.
        • days integer, nullable, обязательное — Число дней при `own_days`, иначе `null`. ⚠ Действующий срок — максимум из этого числа и холда конверсии: короче холда нельзя, потому что отмена откатывает только НЕВЫПЛАЧЕННУЮ ногу.
      • min_payout_rub integer — Порог выплаты сети. Настраивается оператором в кабинете.
      • rate_limit_per_min integer, обязательное — Бюджет запросов ВАШЕГО ключа в минуту — то самое число, по которому принимается решение о `429`. Берите его отсюда, а не из таблицы величин: там гарантированный минимум и потолок, а здесь ваш фактический порог.
      • webhook_configured boolean — Настроен ли адрес для событий. Пишет его `PUT /cpa/self/webhook`.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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.

Тело запроса

  • url string (uri), обязательное — Адрес, на который сеть будет отправлять вебхуки. Пример: https://example.com/hooks/recca.
  • rotate_secret boolean — true — выпустить новый секрет подписи. Пример: false.

Ответы

  • 200 — Адрес сохранён
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • url string (uri), обязательное
      • events array<string>, обязательное
      • secret string, nullable — ⚠ Показывается ОДИН раз — при установке и при каждой ротации. Сохраните сразу: повторно не выдаётся.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Страница списка
    • success boolean, обязательное Допустимо: true.
    • data array<object>, обязательное
      • external_id string, обязательное
      • tenant_recca_id string, обязательное — Наш непрозрачный идентификатор этого человека В ВАШЕЙ СЕТИ. Им адресуются общие методы федерации `/federation/v1/users/{id}/…` (дерево, баланс бонусов, ссылки) — если вы их используете. ⚠ Суррогат разный у разных сетей по построению: связать по нему одного человека между сетями нельзя, и это не недосмотр.
      • role string, обязательное — ⚠ «Инфлюенсер» отдельной ролью не является — это `webmaster`. Источник трафика остаётся на стороне интегратора. ⚠ `agent` УСТАРЕЛ: новых агентов не заводится, приглашает любой вебмастер. Значение встретится в чтении только у партнёров, заведённых до перевода, и уйдёт из словаря следующей версией. Допустимо: advertiser, webmaster, agent.
      • partner_state string, обязательное — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо: active, inactive.
      • status string, обязательное — Участие партнёра НА НАШЕЙ стороне. `active` — роль выдана и заявка принята; `pending` — роль есть, а заявка ещё в очереди оператора (бывает, если приём при заведении не прошёл); `suspended` — оператор снял роль. ⚠ Право работать требует ОБОИХ: и этого поля, и вашего `partner_state`. Своим `partner_state` вы это поле не меняете. Допустимо: active, suspended, pending.
      • recruiter_external_id string, nullable
      • created_at string (date-time), обязательное
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 429 — Исчерпан бюджет запросов
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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_id string, обязательное — ⚠ Ключ идемпотентности и единственный способ адресовать человека. Алфавит ограничен намеренно: свободное поле — это щель, через которую персональные данные приезжают не дверью. ⚠⚠ Алфавит ограничивает ФОРМУ, а не смысл: `79991234567` его проходит. Пример: partner-42.
  • role string, обязательное — ⚠ `advertiser` здесь НЕ принимается, хотя в чтении такая роль есть: рекламодатели заводятся оператором в кабинете (раздел «Что делается в кабинете, а не по API») — у них карточка-витрина, офферы и условия, то есть решения, которых машинная дверь не принимает. ⚠ `agent` — deprecated: принимается ради совместимости со старыми версиями SDK и записывается как `webmaster`; присланный с ним `agent_percent` становится личной ставкой вебмастера за приглашённых. Шлите `webmaster`. Допустимо: webmaster, agent. Пример: webmaster.
  • partner_state string — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо: active, inactive.
  • recruiter_external_id string, nullable — Кто привёл этого партнёра — вебмастер этой сети. Обязан быть УЖЕ заведённым партнёром сети (вербует любой вебмастер, отдельной роли рекрутёра нет) — иначе 404 `PARTNER_NOT_FOUND` либо 400 `INVALID_INPUT`. 400 и тогда, когда партнёр указан рекрутёром самому себе или двое указаны рекрутёрами друг друга. Нога вебмастера-рекрутёра платится по общей ставке сети (по умолчанию 0 — не платится). Молча проглотить его нельзя: рекрутёр, «не прикрепившийся» без ошибки, обнаруживается по деньгам. ⚠ Смена рекрутёра действует ВПЕРЁД: уже начисленные ноги заморожены на момент конверсии. ⚠ Три состояния ключа: отсутствие — «не меняем», строка — «прикрепить или сменить», `null` — ОТКРЕПИТЬ. Открепление действует вперёд, как и смена; открепить неприкреплённого — 200 без изменений.
  • agent_percent number — Только вместе с устаревшей `role: agent`: становится ЛИЧНОЙ ставкой вебмастера за приглашённых (при создании). С `role: webmaster` игнорируется — личную ставку задаёт оператор в кабинете. Пример: 10.

Ответы

  • 200 — Партнёр уже был — обновлено то, чем распоряжаетесь вы. ⚠ Роль, участие и санкция оператора при этом НЕ трогаются.
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное — ⚠ Ни имени, ни почты, ни телефона здесь нет и не будет — см. раздел 3 контракта.
      • external_id string, обязательное
      • tenant_recca_id string, обязательное — Наш непрозрачный идентификатор этого человека В ВАШЕЙ СЕТИ. Им адресуются общие методы федерации `/federation/v1/users/{id}/…` (дерево, баланс бонусов, ссылки) — если вы их используете. ⚠ Суррогат разный у разных сетей по построению: связать по нему одного человека между сетями нельзя, и это не недосмотр.
      • role string, обязательное — ⚠ «Инфлюенсер» отдельной ролью не является — это `webmaster`. Источник трафика остаётся на стороне интегратора. ⚠ `agent` УСТАРЕЛ: новых агентов не заводится, приглашает любой вебмастер. Значение встретится в чтении только у партнёров, заведённых до перевода, и уйдёт из словаря следующей версией. Допустимо: advertiser, webmaster, agent.
      • partner_state string, обязательное — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо: active, inactive.
      • status string, обязательное — Участие партнёра НА НАШЕЙ стороне. `active` — роль выдана и заявка принята; `pending` — роль есть, а заявка ещё в очереди оператора (бывает, если приём при заведении не прошёл); `suspended` — оператор снял роль. ⚠ Право работать требует ОБОИХ: и этого поля, и вашего `partner_state`. Своим `partner_state` вы это поле не меняете. Допустимо: active, suspended, pending.
      • recruiter_external_id string, nullable
      • created_at string (date-time), обязательное
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 201 — Партнёр заведён впервые. Различайте 201 и 200, если ведёте собственный журнал: повтор безопасен, но событием не является.
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное — ⚠ Ни имени, ни почты, ни телефона здесь нет и не будет — см. раздел 3 контракта.
      • external_id string, обязательное
      • tenant_recca_id string, обязательное — Наш непрозрачный идентификатор этого человека В ВАШЕЙ СЕТИ. Им адресуются общие методы федерации `/federation/v1/users/{id}/…` (дерево, баланс бонусов, ссылки) — если вы их используете. ⚠ Суррогат разный у разных сетей по построению: связать по нему одного человека между сетями нельзя, и это не недосмотр.
      • role string, обязательное — ⚠ «Инфлюенсер» отдельной ролью не является — это `webmaster`. Источник трафика остаётся на стороне интегратора. ⚠ `agent` УСТАРЕЛ: новых агентов не заводится, приглашает любой вебмастер. Значение встретится в чтении только у партнёров, заведённых до перевода, и уйдёт из словаря следующей версией. Допустимо: advertiser, webmaster, agent.
      • partner_state string, обязательное — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо: active, inactive.
      • status string, обязательное — Участие партнёра НА НАШЕЙ стороне. `active` — роль выдана и заявка принята; `pending` — роль есть, а заявка ещё в очереди оператора (бывает, если приём при заведении не прошёл); `suspended` — оператор снял роль. ⚠ Право работать требует ОБОИХ: и этого поля, и вашего `partner_state`. Своим `partner_state` вы это поле не меняете. Допустимо: active, suspended, pending.
      • recruiter_external_id string, nullable
      • created_at string (date-time), обязательное
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 429 — Исчерпан бюджет запросов
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Карточка
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное — ⚠ Ни имени, ни почты, ни телефона здесь нет и не будет — см. раздел 3 контракта.
      • external_id string, обязательное
      • tenant_recca_id string, обязательное — Наш непрозрачный идентификатор этого человека В ВАШЕЙ СЕТИ. Им адресуются общие методы федерации `/federation/v1/users/{id}/…` (дерево, баланс бонусов, ссылки) — если вы их используете. ⚠ Суррогат разный у разных сетей по построению: связать по нему одного человека между сетями нельзя, и это не недосмотр.
      • role string, обязательное — ⚠ «Инфлюенсер» отдельной ролью не является — это `webmaster`. Источник трафика остаётся на стороне интегратора. ⚠ `agent` УСТАРЕЛ: новых агентов не заводится, приглашает любой вебмастер. Значение встретится в чтении только у партнёров, заведённых до перевода, и уйдёт из словаря следующей версией. Допустимо: advertiser, webmaster, agent.
      • partner_state string, обязательное — Признак ИНТЕГРАТОРА: «человек у нас ушёл». Санкцию оператора не снимает — это отдельное поле. Допустимо: active, inactive.
      • status string, обязательное — Участие партнёра НА НАШЕЙ стороне. `active` — роль выдана и заявка принята; `pending` — роль есть, а заявка ещё в очереди оператора (бывает, если приём при заведении не прошёл); `suspended` — оператор снял роль. ⚠ Право работать требует ОБОИХ: и этого поля, и вашего `partner_state`. Своим `partner_state` вы это поле не меняете. Допустимо: active, suspended, pending.
      • recruiter_external_id string, nullable
      • created_at string (date-time), обязательное
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Доступно, в холде, выплачено, порог
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • available_rub integer, обязательное — Ровно то, что можно запросить к выплате сейчас.
      • on_hold_rub integer, обязательное — Станет доступным по истечении холда конверсий; отдельного запроса не нужно.
      • paid_total_rub integer, обязательное
      • min_payout_rub integer, обязательное — Порог сети. Читайте отсюда, а не из своей константы.
      • can_request boolean, обязательное
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Страница каталога
    • success boolean, обязательное Допустимо: true.
    • data array<any>, обязательное
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Оффер
    • success boolean, обязательное Допустимо: true.
    • data , обязательное
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Список креативов
    • success boolean, обязательное Допустимо: true.
    • data array<object>, обязательное
      • id string, обязательное
      • kind string, обязательное Допустимо: banner, landing, text, video, other.
      • title string, обязательное
      • description string, nullable
      • url string (uri), nullable — ⚠ `null` у текстового креатива: у рекламного текста файла нет по построению. Ветвитесь по `kind` — у `text` заполнено поле `text`.
      • text string, nullable
      • mime_type string, nullable
      • width integer, nullable
      • height integer, nullable
      • is_default boolean — Основная посадочная. У креативов всегда `false` — понятие принадлежит лендам.
      • created_at string (date-time), nullable
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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_id string, обязательное — Ваш идентификатор партнёра (`external_id`). Пример: partner-42.
  • offer_id string, обязательное — Идентификатор оффера из `GET /cpa/offers`. Пример: offer_01.

Ответы

  • 200 — Ссылка на эту пару уже была — та же самая
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • code string, обязательное
      • target_url string (uri), обязательное — Адрес перехода НА НАШЕЙ стороне (`/go/{code}`). Брендированную ссылку рисует ваш домен; на переходе он либо ведёт сюда, либо зовёт метод 10 и получает уже разрешённый адрес рекламодателя. ⚠⚠ Это НЕ посадочная оффера, и подмена стоила бы денег: уведи вы клиента прямо на посадочную, переход не был бы засчитан — ни клика, ни атрибуции, ни выплаты блогеру, и ни одной ошибки в ответ. Хост адреса зависит от сети: если у сети подключён СВОЙ ДОМЕН адрес строится на нём — `https://<домен сети>/go/{code}`, иначе на базе платформы (`https://api.recca.ru/go/{code}`). Формат остаётся абсолютным `uri`; значение берите из ответа как есть и не собирайте адрес сами. Ранее выданные адреса на базе платформы работают бессрочно.
      • partner_external_id string, обязательное
      • offer_id string, обязательное
      • created_at string (date-time), обязательное
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 201 — Ссылка выпущена
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • code string, обязательное
      • target_url string (uri), обязательное — Адрес перехода НА НАШЕЙ стороне (`/go/{code}`). Брендированную ссылку рисует ваш домен; на переходе он либо ведёт сюда, либо зовёт метод 10 и получает уже разрешённый адрес рекламодателя. ⚠⚠ Это НЕ посадочная оффера, и подмена стоила бы денег: уведи вы клиента прямо на посадочную, переход не был бы засчитан — ни клика, ни атрибуции, ни выплаты блогеру, и ни одной ошибки в ответ. Хост адреса зависит от сети: если у сети подключён СВОЙ ДОМЕН адрес строится на нём — `https://<домен сети>/go/{code}`, иначе на базе платформы (`https://api.recca.ru/go/{code}`). Формат остаётся абсолютным `uri`; значение берите из ответа как есть и не собирайте адрес сами. Ранее выданные адреса на базе платформы работают бессрочно.
      • partner_external_id string, обязательное
      • offer_id string, обязательное
      • created_at string (date-time), обязательное
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 409 — Состояние не допускает операцию
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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_id string, обязательное — Ваш идентификатор партнёра (`external_id`). Пример: partner-42.
  • offer_id string, обязательное — Идентификатор оффера из `GET /cpa/offers`. Пример: offer_01.
  • client_click_id string — Необязательный ключ идемпотентности отправителя. Прислали — повтор возвращает ТОТ ЖЕ клик (200 вместо 201); не прислали — каждый вызов новый переход. Нужен там, где ваш фронт может продублировать вызов: дубль стоит не строки в таблице, а расхода капа оффера. ⚠⚠ Ключ принадлежит ПАРЕ «партнёр + оффер»: тот же ключ с другой парой — 409 `IDEMPOTENT_MISMATCH`, а не сохранённый переход. Иначе опечатка в счётчике вернула бы вам адрес чужого рекламодателя, а конверсию мы приписали бы не тому партнёру. Пример: ya-123456.
  • sub_id string — Ваша метка источника №1. Пример: s1.
  • sub_id_2 string — Ваша метка источника №2. Пример: s2.
  • sub_id_3 string — Ваша метка источника №3. Пример: s3.
  • sub_id_4 string — Ваша метка источника №4. Пример: s4.
  • sub_id_5 string — Ваша метка источника №5. Пример: s5.
  • sub_id_6 string — Ваша метка источника №6. Пример: s6.
  • sub_id_7 string — Ваша метка источника №7. Пример: s7.
  • sub_id_8 string — Ваша метка источника №8. Пример: s8.
  • sub_id_9 string — Ваша метка источника №9. Пример: s9.
  • sub_id_10 string — Ваша метка источника №10. Пример: s10.
  • country string — ISO 3166-1 alpha-2. ⚠⚠ Адрес посетителя и строка его браузера дверью НЕ принимаются: раздел 3 контракта запрещает персональные данные «ни партнёра, ни его клиента», а IP — именно они. Страна и есть та величина, ради которой адрес читают; присылайте её. Пример: RU.

Ответы

  • 200 — Повтор по `client_click_id` — тот же переход, новой строки нет.
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • click_id string, nullable, обязательное — ⚠ `null` при `status: trafficback`. Отбитый переход до рекламодателя не дошёл и конверсию породить не может — выдать по нему идентификатор значило бы пообещать невозможное.
      • status string, обязательное — `trafficback` — переход принят и записан, но к рекламодателю не отправлен: исчерпан кап либо не подошло гео. Это НЕ ошибка запроса, поэтому код ответа успешный. Допустимо: open, trafficback.
      • reason string, nullable — Почему переход отбит (`cap`, `geo`, `access_required`). `null` у обычного. `access_required` — оффер выдаётся по запросу, а у пары нет одобренной заявки сети. Перечень открыт: новые значения добавляются без смены версии контракта, неизвестное читайте как «переход отбит».
      • redirect_url string (uri), nullable, обязательное — Куда отправить посетителя. ⚠ `null` означает «вести некуда»: кап исчерпан, а запасного адреса рекламодатель не объявил. Показывайте свою страницу.
      • expires_at string (date-time), nullable — Конец окна атрибуции этого перехода.
      • created_at string (date-time), обязательное
      • offer_id string
      • partner_external_id string
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 201 — Клик зарегистрирован
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • click_id string, nullable, обязательное — ⚠ `null` при `status: trafficback`. Отбитый переход до рекламодателя не дошёл и конверсию породить не может — выдать по нему идентификатор значило бы пообещать невозможное.
      • status string, обязательное — `trafficback` — переход принят и записан, но к рекламодателю не отправлен: исчерпан кап либо не подошло гео. Это НЕ ошибка запроса, поэтому код ответа успешный. Допустимо: open, trafficback.
      • reason string, nullable — Почему переход отбит (`cap`, `geo`, `access_required`). `null` у обычного. `access_required` — оффер выдаётся по запросу, а у пары нет одобренной заявки сети. Перечень открыт: новые значения добавляются без смены версии контракта, неизвестное читайте как «переход отбит».
      • redirect_url string (uri), nullable, обязательное — Куда отправить посетителя. ⚠ `null` означает «вести некуда»: кап исчерпан, а запасного адреса рекламодатель не объявил. Показывайте свою страницу.
      • expires_at string (date-time), nullable — Конец окна атрибуции этого перехода.
      • created_at string (date-time), обязательное
      • offer_id string
      • partner_external_id string
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 409 — Состояние не допускает операцию
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 429 — Исчерпан бюджет запросов
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Страница списка
    • success boolean, обязательное Допустимо: true.
    • data array<object>, обязательное
      • external_id string, обязательное
      • goal string, обязательное
      • status string, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо: pending, hold, approved, declined, not_found.
      • partner_external_id string, nullable
      • offer_id string
      • advertiser_id string
      • payout_rub integer
      • sum_rub number, nullable
      • sub_id string, nullable
      • created_at string (date-time), обязательное
      • occurred_at string (date-time), nullable
      • hold_until string (date-time), nullable
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Фильтр назвал партнёра или рекламодателя, которого в этой сети нет. Пустой список на опечатку читался бы как «данных нет».
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 500 — Сбой на нашей стороне; денежная операция не совершена
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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_id string, обязательное — Идентификатор перехода из ответа `POST /cpa/clicks`. Пример: c_8f2a91.
  • external_id string, обязательное — Ваш номер заказа. ⚠ Пространство номеров общее для СЕТИ: у двух рекламодателей со сквозной нумерацией они пересекутся — добавьте свой префикс. Префикс `recca:` зарезервирован. Пример: order-100500.
  • status string, обязательное — Подтверждение — любое значение вне списков ожидания и отмены; `pending`/`wait`/`waiting`/`on_hold` — ждём; `cancel`/`reject` — отмена. Пример: approved.
  • goal string, nullable — ⚠ Три состояния: ключа нет — цель по умолчанию; `""` — пустая цель; значение — названная. Присутствие ключа значимо. Пример: purchase.
  • sum_rub number, nullable — ⚠ «Не передали» и `0` — разные факты. Обязательна для процентных моделей. Пример: 2490.
  • sub_id string — Ваша метка заказа. Пример: campaign-7.
  • occurred_at string (date-time) — Когда событие случилось у вас. Не прислали — берём момент приёма, а поле в ответе остаётся `null`: «не сказали» и «случилось тогда-то» — разные утверждения. Отчёты и окна считаются по `occurred_at ?? created_at`. ⚠ Время из будущего отбивается. Пример: 2026-01-15T10:00:00Z.

Ответы

  • 200 — Идемпотентный повтор — та же конверсия
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • external_id string, обязательное
      • goal string, обязательное
      • status string, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо: pending, hold, approved, declined, not_found.
      • partner_external_id string, nullable
      • offer_id string
      • advertiser_id string
      • payout_rub integer, обязательное
      • sum_rub number, nullable
      • sub_id string, nullable
      • created_at string (date-time), обязательное
      • occurred_at string (date-time), nullable
      • hold_until string (date-time), nullable
      • revenue_rub integer, обязательное — Тройка ставок сходится: `payout_rub + margin_rub == revenue_rub`.
      • margin_rub integer, обязательное
      • agent_leg object
        • external_id string, обязательное — Рекрутёр
        • amount_rub integer, обязательное
        • base string, обязательное — От чего считалась ЭТА нога — значение заморожено на момент конверсии. Текущая настройка сети в `GET /cpa/self` может быть уже другой: условия действуют вперёд, а карточка объясняет записанное. Допустимо: margin, payout.
        • percent number, nullable, обязательное — Ставка, по которой ногу посчитали. `null` — нога записана до того, как условия стали замораживаться (значения не существует, и подставлять текущую ставку было бы враньём).
        • hold_until string (date-time), nullable, обязательное — Когда нога станет доступной рекрутёру к выводу. `null` — то же, что у `percent`.
      • fraud_flags array<string> — Пометки качества трафика; сами по себе не блокируют.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 201 — Конверсия создана
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • external_id string, обязательное
      • goal string, обязательное
      • status string, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо: pending, hold, approved, declined, not_found.
      • partner_external_id string, nullable
      • offer_id string
      • advertiser_id string
      • payout_rub integer, обязательное
      • sum_rub number, nullable
      • sub_id string, nullable
      • created_at string (date-time), обязательное
      • occurred_at string (date-time), nullable
      • hold_until string (date-time), nullable
      • revenue_rub integer, обязательное — Тройка ставок сходится: `payout_rub + margin_rub == revenue_rub`.
      • margin_rub integer, обязательное
      • agent_leg object
        • external_id string, обязательное — Рекрутёр
        • amount_rub integer, обязательное
        • base string, обязательное — От чего считалась ЭТА нога — значение заморожено на момент конверсии. Текущая настройка сети в `GET /cpa/self` может быть уже другой: условия действуют вперёд, а карточка объясняет записанное. Допустимо: margin, payout.
        • percent number, nullable, обязательное — Ставка, по которой ногу посчитали. `null` — нога записана до того, как условия стали замораживаться (значения не существует, и подставлять текущую ставку было бы враньём).
        • hold_until string (date-time), nullable, обязательное — Когда нога станет доступной рекрутёру к выводу. `null` — то же, что у `percent`.
      • fraud_flags array<string> — Пометки качества трафика; сами по себе не блокируют.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 409 — Состояние не допускает операцию
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 429 — Исчерпан бюджет запросов
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 500 — Сбой на нашей стороне; денежная операция не совершена
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Конверсия
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • external_id string, обязательное
      • goal string, обязательное
      • status string, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо: pending, hold, approved, declined, not_found.
      • partner_external_id string, nullable
      • offer_id string
      • advertiser_id string
      • payout_rub integer, обязательное
      • sum_rub number, nullable
      • sub_id string, nullable
      • created_at string (date-time), обязательное
      • occurred_at string (date-time), nullable
      • hold_until string (date-time), nullable
      • revenue_rub integer, обязательное — Тройка ставок сходится: `payout_rub + margin_rub == revenue_rub`.
      • margin_rub integer, обязательное
      • agent_leg object
        • external_id string, обязательное — Рекрутёр
        • amount_rub integer, обязательное
        • base string, обязательное — От чего считалась ЭТА нога — значение заморожено на момент конверсии. Текущая настройка сети в `GET /cpa/self` может быть уже другой: условия действуют вперёд, а карточка объясняет записанное. Допустимо: margin, payout.
        • percent number, nullable, обязательное — Ставка, по которой ногу посчитали. `null` — нога записана до того, как условия стали замораживаться (значения не существует, и подставлять текущую ставку было бы враньём).
        • hold_until string (date-time), nullable, обязательное — Когда нога станет доступной рекрутёру к выводу. `null` — то же, что у `percent`.
      • fraud_flags array<string> — Пометки качества трафика; сами по себе не блокируют.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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`), тот же, что при передаче конверсии.

Тело запроса

  • goal string — Цель, по которой отменяется конверсия, если у заказа их несколько. Пример: purchase.
  • reason string — Причина отмены, свободный текст. Пример: Заказ возвращён покупателем.

Ответы

  • 200 — Отменено
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • external_id string, обязательное
      • goal string, обязательное
      • status string, обязательное — `pending` — вы сообщили о событии, но не подтвердили его; денежной ноги ещё нет. `hold` — подтверждено, выплата зарезервирована, идут часы холда. `approved` — холд истёк, выплата доступна. `declined` — отклонено или возвращено (в том числе методом 14; отдельного `reversed` нет: два имени одного состояния разошлись бы). ⚠ `not_found` встречается только у конверсий, пришедших ПРЯМЫМ постбэком рекламодателя с неизвестным нам переходом; метод 11 таких строк не создаёт — он отвечает отказом. Допустимо: pending, hold, approved, declined, not_found.
      • partner_external_id string, nullable
      • offer_id string
      • advertiser_id string
      • payout_rub integer, обязательное
      • sum_rub number, nullable
      • sub_id string, nullable
      • created_at string (date-time), обязательное
      • occurred_at string (date-time), nullable
      • hold_until string (date-time), nullable
      • revenue_rub integer, обязательное — Тройка ставок сходится: `payout_rub + margin_rub == revenue_rub`.
      • margin_rub integer, обязательное
      • agent_leg object
        • external_id string, обязательное — Рекрутёр
        • amount_rub integer, обязательное
        • base string, обязательное — От чего считалась ЭТА нога — значение заморожено на момент конверсии. Текущая настройка сети в `GET /cpa/self` может быть уже другой: условия действуют вперёд, а карточка объясняет записанное. Допустимо: margin, payout.
        • percent number, nullable, обязательное — Ставка, по которой ногу посчитали. `null` — нога записана до того, как условия стали замораживаться (значения не существует, и подставлять текущую ставку было бы враньём).
        • hold_until string (date-time), nullable, обязательное — Когда нога станет доступной рекрутёру к выводу. `null` — то же, что у `percent`.
      • fraud_flags array<string> — Пометки качества трафика; сами по себе не блокируют.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 409 — Состояние не допускает операцию
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 500 — Сбой на нашей стороне; денежная операция не совершена
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Страница списка
    • success boolean, обязательное Допустимо: true.
    • data array<object>, обязательное
      • id string, обязательное
      • partner_external_id string, обязательное
      • amount_rub integer, обязательное
      • status string, обязательное Допустимо: requested, approved, paid, rejected.
      • period_from string (date)
      • period_to string (date)
      • created_at string (date-time), обязательное
      • paid_at string (date-time), nullable
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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_id string, обязательное — Ваш идентификатор партнёра (`external_id`). Пример: partner-42.
  • amount_rub integer, обязательное — Сумма заявки в рублях. Пример: 5000.
  • period_from string (date), обязательное — Начало периода, за который заявлена выплата (дата). Пример: 2026-01-01.
  • period_to string (date), обязательное — Конец периода (дата). Пример: 2026-01-31.

Ответы

  • 200 — Идемпотентный повтор — та же заявка
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • id string, обязательное
      • partner_external_id string, обязательное
      • amount_rub integer, обязательное
      • status string, обязательное Допустимо: requested, approved, paid, rejected.
      • period_from string (date)
      • period_to string (date)
      • created_at string (date-time), обязательное
      • paid_at string (date-time), nullable
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 201 — Заявка создана
    • success boolean, обязательное Допустимо: true.
    • data object, обязательное
      • id string, обязательное
      • partner_external_id string, обязательное
      • amount_rub integer, обязательное
      • status string, обязательное Допустимо: requested, approved, paid, rejected.
      • period_from string (date)
      • period_to string (date)
      • created_at string (date-time), обязательное
      • paid_at string (date-time), nullable
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 409 — Состояние не допускает операцию
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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 — Строки отчёта
    • success boolean, обязательное Допустимо: true.
    • data array<object>, обязательное
      • key string, обязательное — Идентификатор группы — оффер, партнёр или дата.
      • clicks integer, обязательное
      • conversions integer, обязательное
      • approved integer, обязательное
      • payout_rub integer, обязательное
      • revenue_rub integer, обязательное — Выручка группы. Приходит ВСЕГДА: ключ арендатора принадлежит оператору сети, а оператору выручка видна. ⚠ Прежняя редакция обещала «только в операторском разрезе» — партнёрского разреза у этой двери нет вовсе. Партнёру эта дверь не отдаётся; партнёрская проекция ставок — у офферов, и выручки рекламодателя в ней нет.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 400 — Вход не прошёл проверку
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 401 — Ключа нет, он пуст или отозван
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 403 — Нет права, продукт не подключён или приостановлен
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 404 — Сущность не найдена в этой сети
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `true` означает, что выдача НЕПОЛНА: мы упёрлись в потолок просмотра, и `total` — сколько успели посчитать, а не сколько есть. Молчать об этом нельзя: список без части партнёров неотличим от списка, в котором их нет. Поле приходит ВСЕГДА, в том числе со значением `false`: «мы посмотрели всё» — это утверждение, а не отсутствие оговорки. Увидели `true` — сообщите нам.
  • 500 — Сбой на нашей стороне; денежная операция не совершена
    • success boolean, обязательное Допустимо: false.
    • error object, обязательное
      • code string, обязательное — Перечень собирается из `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.
      • message string, обязательное — Диагностика для человека. ⚠ Ветвиться нужно по `code`: текст меняется без предупреждения и частью контракта не является.
      • details — Называет поле поимённо, если отказ про вход.
    • meta object, обязательное
      • request_id string, обязательное — Приходит и на успехе, и на отказе; дублируется заголовком `X-Request-Id`. Называйте его, сообщая о проблеме.
      • total integer
      • count integer
      • offset integer
      • limit integer
      • has_more boolean
      • truncated boolean — ⚠ `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
  }
}