Приём конверсий (postback)¶

Постбэк — запрос от партнёрки, которым она сообщает: «по клику X пришёл лид». Это основной способ получить конверсии в трекер.

Адрес¶

В пути постбэк-URL стоит ключ воркспейса — он и аутентифицирует запрос:

https://tr.example.com/<postback_key>/postback?subid={click_id}&status=lead&payout=1.5&currency=USD

Готовый URL со своим ключом возьмите в Настройки → Интеграции → Postback URL (входящий), там же кнопка «Копировать». Ключ выдаётся воркспейсу автоматически, это 32 шестнадцатеричных символа.

Отдайте этот шаблон партнёрке, подставив её собственный макрос click_id — у всех он называется по-своему: {subid}, {sub1}, {aff_sub}, {s1}.

Ключ — это пароль

Кто знает ключ, тот может записать в ваш воркспейс любую конверсию с любой суммой. Не публикуйте его на лендинге и в задачах; отдавайте только партнёрке. В журнале Постбэки ключ маскируется: /***/postback.

Запрос без ключа — по старому адресу /postback — отклоняется с ответом 401 Incorrect postback key. Если после обновления конверсии перестали приходить, первым делом обновите URL в кабинете партнёрки.

Работают и GET, и POST (application/x-www-form-urlencoded); параметры берутся и из строки запроса, и из тела, тело читается до 8 КБ. JSON-тело не разбирается — параметры должны быть в query или в form-urlencoded теле.

Параметры¶

Параметр	Обяз.	Значение
`subid`	да	ID клика. Синоним: `clickid`
`status`	да	`lead` · `sale` · `rejected` · `trash` или ваш кастомный код
`payout`	нет	сумма выплаты, числом
`currency`	нет	ISO-код, по умолчанию `USD`
`txid`	нет	ID транзакции на стороне партнёрки — по нему работает дедупликация
`em` / `email`, `ph` / `phone`	нет	контакты для CAPI — хешируются перед отправкой

Других имён для click_id нет: click_id, cid и прочие трекер не читает — макрос партнёрки должен подставляться именно в subid (или clickid).

Без subid или status постбэк отклоняется с 400 — это защита от «тихих» конверсий без привязки к клику.

Статусы и жизненный цикл¶

Канонические статусы трекера — lead, sale, rejected, trash. Свои коды заводятся в Настройки → Статусы, где у каждого указано, чем он считается в отчётах (counts_as).

Если партнёрка говорит на своём языке (approved, pending, reversed), трекер переводит её статусы в свои по карте партнёрской сети. Готовая карта приходит с шаблоном из Сети → Каталог: например, у MaxBounty approved → sale, pending → lead, reversed → rejected. Карта берётся по офферу клика и применяется до записи конверсии — в отчётах и исходящем S2S статус уже канонический.

Своя карта статусов

В форме сети поля маппинга нет: у сети, созданной вручную, статусы записываются как есть. Задать свою карту можно через API: PUT /admin_api/v1/affiliate-networks/{id}, поле status_mapping.

Конверсия по одному txid может меняться: lead → sale при апруве, sale → rejected при отмене. Трекер принимает такие обновления, и в отчётах остаётся последнее состояние.

Дедупликация¶

Ключ дубля — txid вместе со статусом, суммой и валютой, окно 24 часа.

Точный повтор того же постбэка отвечает 200 ok, но второй конверсии не создаёт и повторно не дёргает вебхуки, CAPI и исходящий S2S — партнёрки часто ретраят.
Изменился статус или сумма — постбэк проходит и заменяет прежнее состояние.
Пустой txid отключает дедупликацию: идемпотентность в этом случае целиком на стороне партнёрки.

Сумма и валюта¶

Payout должен быть числом. 10.50 — принимается, европейская запятая 10,50 тоже. $10.50, 10.50 USD, 1,000.50 (запятая неоднозначна) — отклоняются с 400, конверсия не записывается. Так сумма не теряется незаметно: партнёрка видит ошибку и может починить формат у себя.

Отказ не «сжигает» txid: после исправления на её стороне повторный постбэк с тем же txid запишет реальную сумму.

Пустой payout — это законный лид без выплаты, он записывается как 0. Сумма пересчитывается в базовую валюту воркспейса по курсу на дату клика (Настройки → Валюты), поэтому исторические отчёты не переписываются задним числом.

Подпись (HMAC)¶

Подпись — необязательный слой поверх обязательного ключа воркспейса. Нужен, если партнёрка умеет подписывать запросы и вы хотите застраховаться на случай утечки URL.

Задайте секрет в карточке источника трафика: Источники → Postback secret (HMAC) (хранится зашифрованным). После этого трекер требует подпись на каждом постбэке, чей клик пришёл с этого источника, — сам, по цепочке клик → кампания → источник. Никакого параметра source_id в запросе не нужно: сеть не может выбрать, проверять её или нет.

Заголовок:

X-Signature: sha256=<hex>

где hex — HMAC-SHA256 на секрете источника от:

строки запроса — для GET;
тела запроса — для POST без query-параметров;
строка запроса + \n + тело — если есть и то, и другое.

Постбэк без подписи или с некорректной подписью отклоняется с 401.

QS="subid=$CLICK_ID&status=sale&payout=10.50&currency=USD&txid=T-1"
SIG=$(printf '%s' "$QS" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')
curl -i -H "X-Signature: sha256=$SIG" "https://tr.example.com/$KEY/postback?$QS"

Коды ответов¶

Код	Когда	Что делать партнёрке
`200 ok`	конверсия записана либо подавлена как точный дубль	ничего
`400`	нет `subid`/`status` или `payout` не разобран	починить запрос и повторить
`401 Incorrect postback key`	ключа нет, ключ неверен или клик принадлежит другому воркспейсу	исправить URL
`401 invalid signature`	у источника задан секрет, подпись отсутствует или не сошлась	исправить подпись
`429`	превышен лимит частоты	повторить позже (`Retry-After`)
`503`	click_id трекеру неизвестен либо база/очередь недоступны	повторить

Лимит частоты — 100 запросов в секунду с одного IP, всплеск до 500.

Почему неизвестный click_id — это 503, а не «ok»

Клик мог ещё не долететь до базы, а мог и вовсе не существовать. Трекер не подтверждает то, что не сохранил: партнёрка видит ошибку и повторяет доставку, и повтор с тем же txid уже запишется нормально — заявка на дедупликацию при отказе снимается.

Как проверить, что работает¶

Возьмите click_id живого клика из Журнала кликов.

Дёрните постбэк вручную:

curl -i "https://tr.example.com/ВАШ_КЛЮЧ/postback?subid=ВАШ_CLICK_ID&status=lead&payout=1.5"

Конверсия появится в разделе Конверсии за пару секунд.

Принятые постбэки — входящие и исходящие — видны в разделе Постбэки: время, направление, код ответа, click_id, URL и ошибка. Если партнёрка уверяет, что «мы отправили», начинайте с него.

Чего в журнале не будет

Журнал строится по кампаниям воркспейса, поэтому постбэк, отклонённый до привязки к клику (неверный ключ, нет subid/status, битый payout), в него не попадает. Такой отказ виден только по HTTP-коду, который получила партнёрка.

Частые причины «конверсии не приходят»¶

Симптом	Причина
В журнале постбэков пусто	партнёрка не шлёт вообще или её запросы отклоняются на входе — попросите у неё код ответа
`401 Incorrect postback key`	у партнёрки сохранён старый URL без ключа или ключ чужого воркспейса
`400 missing required parameter: subid/clickid`	в ссылке оффера не передан `{click_id}` — конверсию не к чему привязать
`400 unparseable payout`	партнёрка шлёт сумму с валютой или знаком доллара
`503` на каждый постбэк	click_id не резолвится: клик старше срока хранения (90 дней) или subid придуман партнёркой
`200 ok`, а новой конверсии нет	тот же `txid` с тем же статусом и суммой — подавлен как дубль

Дальше — отдать конверсию источнику.