Постбэк рекламодателя: как передавать конверсии в сеть
Адрес постбэка, подпись, статусы и цели: как рекламодателю передавать сети Recca результаты заказов из CRM и проверить приём.
Чтобы настроить постбэк, ваш сервер должен сообщать сети о каждом подтверждённом заказе: постбэк — это запрос на адрес оффера («URL для постбека» в кабинете), «заказ такой-то состоялся». Сеть не видит вашу CRM и ничего не знает о продаже, пока вы о ней не сообщите. Статья собирает всё об S2S-интеграции: как это работает, как настроить, какие бывают статусы и как проверить.
Как считается конверсия
| Шаг | Кто | Что происходит |
|---|---|---|
| 1. Переход | партнёр | человек приходит по ссылке; сеть создаёт клик и передаёт его идентификатор click_id параметром в адресе вашего сайта |
| 2. Сохранение | вы | click_id сохраняется в заказе рядом с его номером: это единственная нить между переходом и продажей |
| 3. Постбэк | ваш сервер | заказ подтверждён: вы вызываете адрес постбэка оффера с click_id, номером заказа и статусом |
| 4. Холд | сеть | вознаграждение считается по условиям оффера и резервируется на срок холда |
| 5. Выплата | сеть | холд закончился: деньги доступны партнёру |
Постбэк без click_id сеть отклонит с ошибкой 400 INVALID_INPUT. Если click_id пришёл, но такого перехода нет, продажа запишется как конверсия без найденного перехода (в кабинете статус «клик не найден»): привязки к партнёру нет, и денег никто не получает. Чаще всего параметр теряется между лендингом и формой оплаты, поэтому проверьте, что он доживает до создания заказа.
Быстрый старт
Всё нужное находится на странице «Приём результата (S2S)» в кабинете рекламодателя.
- В карточке оффера скопируйте «URL для постбека» вида
https://api.recca.ru/cpa/postback/<offer_id>. - Нажмите «Выпустить секрет» (если секрет уже есть, кнопка называется «Выпустить новый секрет») и сохраните его сразу: он показывается один раз.
- Научите сайт сохранять
click_idиз адреса в заказ, как utm-метки. - Отправляйте постбэк при подтверждении заказа: подписанным POST или GET-ссылкой (ниже).
- Проверьте: блок «Проверить интеграцию», затем «Журнал постбеков».
Два способа отправки
| 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 суток, но столько же действует и утёкший, поэтому меняйте сразу. Если оффер ведёт оператор, а своего входа у вас нет, попросите оператора: у него есть кнопка «Новый секрет» в списке офферов.