Recca Поддержка
Меню

Постбэк рекламодателя: как передавать конверсии в сеть

Адрес постбэка, подпись, статусы и цели: как рекламодателю передавать сети Recca результаты заказов из CRM и проверить приём.

Чтобы настроить постбэк, ваш сервер должен сообщать сети о каждом подтверждённом заказе: постбэк — это запрос на адрес оффера («URL для постбека» в кабинете), «заказ такой-то состоялся». Сеть не видит вашу CRM и ничего не знает о продаже, пока вы о ней не сообщите. Статья собирает всё об S2S-интеграции: как это работает, как настроить, какие бывают статусы и как проверить.

Как считается конверсия

ШагКтоЧто происходит
1. Переходпартнёрчеловек приходит по ссылке; сеть создаёт клик и передаёт его идентификатор click_id параметром в адресе вашего сайта
2. Сохранениевыclick_id сохраняется в заказе рядом с его номером: это единственная нить между переходом и продажей
3. Постбэкваш серверзаказ подтверждён: вы вызываете адрес постбэка оффера с click_id, номером заказа и статусом
4. Холдсетьвознаграждение считается по условиям оффера и резервируется на срок холда
5. Выплатасетьхолд закончился: деньги доступны партнёру

Постбэк без click_id сеть отклонит с ошибкой 400 INVALID_INPUT. Если click_id пришёл, но такого перехода нет, продажа запишется как конверсия без найденного перехода (в кабинете статус «клик не найден»): привязки к партнёру нет, и денег никто не получает. Чаще всего параметр теряется между лендингом и формой оплаты, поэтому проверьте, что он доживает до создания заказа.

Быстрый старт

Всё нужное находится на странице «Приём результата (S2S)» в кабинете рекламодателя.

  1. В карточке оффера скопируйте «URL для постбека» вида https://api.recca.ru/cpa/postback/<offer_id>.
  2. Нажмите «Выпустить секрет» (если секрет уже есть, кнопка называется «Выпустить новый секрет») и сохраните его сразу: он показывается один раз.
  3. Научите сайт сохранять click_id из адреса в заказ, как utm-метки.
  4. Отправляйте постбэк при подтверждении заказа: подписанным POST или GET-ссылкой (ниже).
  5. Проверьте: блок «Проверить интеграцию», затем «Журнал постбеков».

Два способа отправки

POST с подписьюGET-ссылка
Кому подходитесть разработчикв CRM есть только поле «URL постбэка»
Параметрытело JSONстрока запроса
Проверка правподпись HMAC в заголовкетокен secure в адресе
Секретне покидает ваш сервертокен виден в журналах промежуточных серверов
Статусрекомендуемыйзапасной

POST с подписью

POST https://api.recca.ru/cpa/postback/<offer_id>
Content-Type: application/json
X-CPA-Signature: <подпись>
X-CPA-Timestamp: <метка времени, необязательно>

{
  "click_id": "clk_a1b2c3",
  "external_id": "order-10421",
  "status": "confirmed",
  "sum_rub": 5000,
  "sub_id": null
}
ПолеОбязательноЧто это
click_idдаидентификатор перехода, пришедший вам в ссылке
external_idдаваш номер заказа; повтор с тем же номером не создаёт вторую конверсию
statusдастатус заказа, см. раздел «Статусы»
sum_rubдля процентных моделейсумма заказа в рублях, число от 0 до 10 000 000
sub_idнетметка партнёра, если вы получали её в ссылке
goalнеткод цели воронки; не передан — основная ставка оффера

Номер заказа и метка — до 200 символов, номер не может начинаться с recca:. Подпись — HMAC-SHA256 в шестнадцатеричном виде (64 символа), секретом оффера, от строки из значений через двоеточие:

click_id:external_id:status:sum_rub:sub_id[:goal[:timestamp]]

В строку идут значения ровно в том виде, в каком вы их отправили, включая status. Пустые значения остаются пустыми сегментами: если нет суммы и метки, строка заканчивается двумя двоеточиями. Сегмент goal добавляется, если вы передали цель, даже goal=1. Порядок полей в подписываемой строке фиксирован и не зависит от порядка полей в JSON.

Заголовок X-CPA-Timestamp необязателен. Если вы его шлёте, это время Unix в секундах, оно добавляется в конец строки подписи (без цели на её месте остаётся пустой сегмент), а сеть принимает запрос, если метка отличается от её часов не больше чем на 5 минут в любую сторону. Повторяя запрос из очереди, подписывайте его заново с новой меткой. Заголовок X-CPA-Key-Id тоже необязателен: без него сеть сама проверяет текущий секрет и предыдущий (после выпуска нового), допустимые значения current и previous.

GET-ссылка для CRM

https://api.recca.ru/cpa/postback/<offer_id>?clickid={click_id}&action_id={order_id}&goal={goal}&sum={sum}&status=1&sub_id={sub_id}&secure=ВАШ_ТОКЕН_GET

Готовая строка для каждого оффера лежит на странице S2S в поле «Ссылка для CRM (GET)»: замените плейсхолдеры на макросы вашей CRM. Токен secure вида cpag_… выдаётся вместе с секретом и не является секретом подписи. Он выведен из секрета и оффера, поэтому выпуск нового секрета заменяет и токен; старый токен принимается столько же, сколько и прежний секрет (см. конец статьи).

Параметры можно называть по-разному:

ЧтоДопустимые имена
идентификатор переходаclickid, click_id
ваш номер заказаaction_id, external_id, actionid, order_id
сумма заказаsum, sum_rub, amount
метка партнёраsub_id, sub1, sub_id1
цель воронкиgoal

Сумма принимается и с точкой, и с запятой, от 0 до 10 000 000. Если номера заказа нет, номером становится сам переход, и повторный вызов той же ссылки ничего не задваивает.

Проверка живого адреса:

curl -i "https://api.recca.ru/cpa/postback/$OFFER_ID?clickid=clk_test&action_id=order-1&sum=1000&status=1&secure=$GET_TOKEN"

Ответ 201 значит, что конверсия создана, 200 — что это повтор уже принятого заказа. 403 значит, что токен не тот. 400: нет clickid либо неверен адрес оффера.

Статусы

В GET-ссылке статус можно передать числом:

КодЧто означает
1подтверждено: начинается холд
2ожидание: конверсия записана, вознаграждение не начисляется
3отмена: гасит конверсию
5то же, что 1

Словами в GET понимаются те же значения, что и в POST, и ещё несколько: подтверждение — confirmed, approved, hold; ожидание — pending, wait, waiting, on_hold; отмена — declined, cancel, cancelled, reject, rejected, trash. Неизвестное слово считается подтверждением.

Если статуса нет, постбэк считается подтверждением. В POST-запросе числа не понимаются, там шлют слова: pending, wait, waiting или on_hold для ожидания (регистр не важен), cancel или reject строчными для отмены. Любое другое слово в POST считается подтверждением. Значения declined, 3 и Cancel в POST не отменят конверсию, а начнут холд.

Отмена и возврат

Отправьте постбэк с тем же номером заказа и статусом отмены. Если заказ засчитан по цели, отмену нужно слать с той же целью: иначе отмена не найдёт конверсию и сеть ответит ошибкой (400 NOT_CONVERTED, если подтверждения по этой цели не было, либо 404 NOT_FOUND).

Где вознаграждениеЧто произойдёт
на холдеаннулируется, никто ничего не теряет
начислено, но не выплаченосоздаётся обратная проводка
уже выплаченопо политике сети: удержание из будущих выплат или списание за счёт сети

Повторная отмена безопасна.

Цели воронки

Один переход часто приносит цепочку событий: заявка, оплата, продление. Цели позволяют не заводить отдельный оффер на каждое событие. Каждый постбэк передаёт свою цель параметром goal:

...&action_id=order-10421&goal=lead              → заявка
...&action_id=order-10421&goal=deposit&sum=5000   → оплата

Это две разные конверсии: каждая по своей ставке и со своим холдом. Если цель не передана, действует цель по умолчанию 1, основная ставка оффера. Неизвестная цель отклоняется с ошибкой 400 UNKNOWN_GOAL, выключенная оператором — с 409 GOAL_DISABLED. У оффера может быть до 50 целей. Второй заказ той же цели с того же перехода получит 409 ALREADY_CONVERTED, если оператор не включил для цели флаг «Несколько конверсий с одного клика».

Повторы и лимиты

Повтор постбэка безопасен и является правильным способом пережить обрыв связи.

СитуацияОтвет
повтор с тем же заказом и целью, та же сумма200 и idempotent: true, второй раз вознаграждение не начисляется
повтор с другой суммой409 IDEMPOTENT_MISMATCH: другое событие шлите своим номером
номер заказа занят другим оффером той же сети409 EXTERNAL_ID_CONFLICT: добавьте свой префикс к нумерации
превышен лимит429 RATE_LIMITED с заголовком Retry-After

По умолчанию лимит — 2 000 запросов в минуту на оффер, и ещё 30 отказов по праву в минуту с одного адреса (неверная подпись, неверный токен, несуществующий оффер).

Как проверить интеграцию

В блоке «Проверить интеграцию» вставьте секрет ровно так, как он прописан в вашей CRM, с теми же пробелами и кавычками. Сеть подпишет тестовый постбэк им и прогонит через боевой приёмник: несовпадение секрета видно сразу, а не на первом реальном заказе. Тестовая конверсия помечается и не попадает в статистику, выплаты и отчёты.

«Журнал постбеков» хранит каждый запрос за последние 90 дней. Колонки: «Когда», «Оффер», «Дверь» (способ отправки), «Цель», «Заказ», «Статус у вас», «Ответ». Журнал открывается по ссылке «Открыть журнал» на странице «Приём результата (S2S)».

СимптомПричинаЧто делать
строки нетзапрос не дошёл или неверен идентификатор офферапроверьте адрес и что сервер отправляет запрос
ответ 403не совпал секрет или подписьиспользуйте блок «Проверить интеграцию»
200 и «повтор»заказ уже был засчитанэто не ошибка: задвоение исключено
«клик не найден»click_id потерянпроверьте передачу параметра до создания заказа

Если секрет утёк, выпустите новый на странице S2S и обновите его в CRM. Прежний принимается ещё 7 суток, но столько же действует и утёкший, поэтому меняйте сразу. Если оффер ведёт оператор, а своего входа у вас нет, попросите оператора: у него есть кнопка «Новый секрет» в списке офферов.