Postbacks

Статус: draft

Назначение

Этот раздел нужен, чтобы рекламодатель понял, как вернуть результат целевого действия обратно в платформу: какой postback отправлять, какие параметры обязательны, как передавать clickId, goal и status, и как потом проверить, что конверсия появилась.

Где находится

Кабинет рекламодателя → Postbacks

Для пользовательской интеграции также нужен технический postback endpoint платформы.

Точный путь получения рабочего postback URL в интерфейсе рекламодателя не подтверждён.

TODO: уточнить, где именно рекламодатель получает рабочий postback URL и токен по офферу.

Что такое postback

Postback в этом проекте — это запрос от рекламодателя в платформу после целевого действия пользователя.

Через postback рекламодатель возвращает:

• идентификатор клика;
• цель;
• статус конверсии;
• при необходимости внешний идентификатор транзакции;
• подпись запроса.

Зачем нужен postback

Postback нужен, чтобы платформа смогла:

• связать целевое действие с исходным кликом;
• определить, к какому офферу относится конверсия;
• понять, какая цель была достигнута;
• проставить статус конверсии;
• отразить данные в статистике и финансах.

Без postback платформа видит только клик, но не получает результат.

Что видит рекламодатель

В кабинете рекламодателя раздел Postbacks показывает не настройку, а логи:

• список postback-событий;
• фильтр по датам;
• фильтр по Offer ID;
• фильтр по статусу postback-лога;
• HTTP-статус ответа;
• clickId;
• conversionId, если конверсия была создана;
• код ошибки, если postback завершился неуспешно;
• детальную карточку одной записи журнала.

Когда отправлять postback

Postback нужно отправлять после того, как на стороне рекламодателя произошло целевое действие по офферу.

Типовой сценарий:

1. Пользователь переходит по tracking-ссылке.
2. Рекламодатель получает и сохраняет clickId.
3. Пользователь совершает целевое действие.
4. Рекламодатель отправляет postback в платформу.
5. Платформа создаёт или обновляет конверсию.

Если у вас есть двухэтапная логика, например сначала регистрация, а потом подтверждение, нужно заранее уточнить, какой статус отправлять на каждом этапе.

Куда отправлять postback

Подтверждён технический endpoint платформы:

/track/postback

Поддерживаются:

• GET с query-параметрами;
• POST с JSON body.

Для реальной интеграции нужен полный URL вашей платформы, например:

https://tracking.example.com/track/postback

Если домен и точный URL в вашем окружении отличаются:

TODO: уточнить точный формат postback URL по реализации.

Формат postback URL

Подтверждённый формат требует:

• token оффера;
• clickId или click_id;
• goalId или goal_id;
• signature.

status опционален и по умолчанию становится pending.

externalTransactionId также поддерживается как опциональный параметр.

Обязательные параметры

Опциональные параметры

Важно:

• amount как рабочий пользовательский параметр интерфейсом рекламодателя не подтверждён;
• payoutRub упоминается как legacy-параметр совместимости, но не является авторитетным источником суммы;
• деньги по конверсии рассчитываются платформой по офферу и цели.

Click ID

clickId — это идентификатор клика, который платформа передаёт в tracking-ссылке или редиректе.

Рекламодателю нужно:

1. Получить clickId в момент перехода пользователя.
2. Сохранить его у себя.
3. Вернуть этот же clickId обратно в postback после целевого действия.

Без clickId платформа обычно не сможет:

• найти исходный клик;
• связать конверсию с партнёром;
• корректно отразить статистику.

Если пользователь совершил действие без перехода через tracking-ссылку, корректной связи с кликом может не быть.

Goal

В этом проекте цель передаётся как:

• goalId, либо
• goal_id.

Важно:

• goal обязателен;
• goal должен относиться к тому же офферу, который определяется через token;
• silent fallback на "цель по умолчанию" не подтверждён, наоборот, текущая реализация требует явный goalId.

Что это значит для рекламодателя:

• заранее определите, какой goalId соответствует нужному событию;
• не отправляйте выдуманное текстовое имя цели вместо идентификатора;
• если у оффера несколько целей, у каждой должен быть свой корректный goalId.

Если вам известны только бизнес-названия вроде lead или sale, а не UUID цели:

TODO: уточнить, где рекламодатель получает точный goalId для интеграции.

Status

Параметр status можно передавать явно. Если его не передать, платформа использует pending.

Подтверждённые статусы конверсий:

• pending;
• approved;
• rejected;
• cancelled.

Для базовой интеграции рекламодателю нужно понимать минимум три статуса:

• pending — конверсия создана, но ещё не подтверждена;
• approved — конверсия подтверждена;
• rejected — конверсия отклонена.

Если в вашем процессе есть отмена:

• cancelled — TODO: уточнить, должен ли рекламодатель использовать этот статус в своей интеграции.

Сумма

В интерфейсе и подтверждённой логике проекта деньги по конверсии не должны считаться доверенными значениями со стороны рекламодателя.

Подтверждено:

• revenue и payout вычисляются платформой по офферу и цели;
• переданные извне revenue, payout и profit не считаются авторитетными;
• payoutRub может использоваться только для legacy-совместимости подписи.

Поэтому рекламодателю не стоит строить интеграцию на предположении, что платформа возьмёт сумму из postback как основное финансовое значение.

Если в вашем конкретном сценарии нужно передавать сумму:

TODO: уточнить, используется ли amount в продакшн-интеграции вашего окружения.

Примеры postback URL

Ниже примеры с безопасным доменом и подтверждёнными именами параметров проекта.

Пример GET для approved

https://tracking.example.com/track/postback?token={offer_token}&click_id={click_id}&goal_id={goal_id}&status=approved&signature={signature}

Пример GET для pending

https://tracking.example.com/track/postback?token={offer_token}&click_id={click_id}&goal_id={goal_id}&status=pending&signature={signature}

Пример GET для rejected

https://tracking.example.com/track/postback?token={offer_token}&click_id={click_id}&goal_id={goal_id}&status=rejected&signature={signature}

Пример GET с внешним ID транзакции

https://tracking.example.com/track/postback?token={offer_token}&click_id={click_id}&goal_id={goal_id}&externalTransactionId=order-123&status=approved&signature={signature}

Пример POST

{
  "token": "offer_conversion_token",
  "clickId": "click-id-or-tracking-token",
  "goalId": "goal-uuid",
  "externalTransactionId": "order-123",
  "status": "approved",
  "signature": "signed-value"
}

Пример c amount

Ниже пример только как формат передачи параметра, без утверждения, что сумма будет принята как финансовое значение:

https://tracking.example.com/track/postback?token={offer_token}&click_id={click_id}&goal_id={goal_id}&status=approved&amount=1500&signature={signature}

Как подключить postback

Подготовить данные интеграции

1. Получите рабочий postback URL платформы.
2. Получите token оффера.
3. Получите точные goalId для нужных целей.
4. Уточните правило расчёта signature.

Результат: у вас есть все технические данные для отправки postback.

Настроить сохранение click ID

1. Убедитесь, что при переходе пользователя вы получаете clickId.
2. Сохраните clickId в своей системе вместе с пользователем, заказом или событием.
3. Проверьте, что clickId можно достать в момент целевого действия.

Результат: платформа сможет связать конверсию с исходным кликом.

Отправить postback при целевом действии

1. Дождитесь целевого действия в вашей системе.
2. Соберите token, clickId, goalId, status и signature.
3. Отправьте GET или POST на /track/postback.

Результат: платформа получит postback и попробует создать или обновить конверсию.

Проверить результат в кабинете

1. Откройте раздел Postbacks.
2. Найдите запись по дате, Offer ID или clickId.
3. Проверьте статус, HTTP-код и наличие conversionId.

Результат: вы видите, был ли postback принят и создалась ли конверсия.

Как проверить postback

Простой сценарий проверки:

1. Возьмите тестовую tracking-ссылку.
2. Перейдите по ней как пользователь.
3. Убедитесь, что клик появился в платформе.
4. Сохраните полученный clickId.
5. Отправьте тестовый postback с этим clickId, правильным goalId, status и signature.
6. Откройте раздел Postbacks и проверьте, что запись появилась.
7. Проверьте conversionId, статус postback и отсутствие ошибки.
8. Сверьте, что конверсия отражается в Статистика и Финансы.

Отдельный тестовый режим postback в интерфейсе рекламодателя не подтверждён.

TODO: уточнить, есть ли отдельный тестовый режим postback в вашем окружении.

Основные поля

Фильтры и поиск

В разделе логов postback подтверждены:

• Дата от;
• Дата до;
• Offer ID;
• фильтр по статусу;
• пагинация;
• переход в детальную запись лога.

Отдельного текстового поиска по clickId в этом экране не подтверждено.

Статусы

Ниже важно различать два уровня статусов.

Статусы конверсии

Статусы записи postback-лога

Почему postback не засчитался

Ниже перечислены практические причины, которые нужно проверить в первую очередь:

• не передан clickId;
• передан неверный clickId;
• clickId не найден в платформе;
• рекламодатель не сохранил clickId у себя;
• пользователь совершил действие без исходного клика через tracking-ссылку;
• не передан goalId или goal_id;
• goalId не существует у этого оффера;
• status передан в некорректном значении;
• postback отправлен на неправильный URL;
• не передан token;
• передан неправильный token;
• не передана signature;
• signature не прошла проверку;
• postback отправлен повторно;
• конверсия уже создана;
• внешний ID транзакции конфликтует с уже существующей конверсией;
• оффер выключен или недоступен;
• postback не прошёл валидацию параметров.

Если нужна точная карта ошибок по кодам:

TODO: уточнить полный список errorCode, который может увидеть рекламодатель в логе postback.

Частые ошибки и ситуации

Ожидаемый результат

После работы с этим разделом рекламодатель должен:

• понимать, какой endpoint использовать для postback;
• знать обязательные параметры token, clickId, goalId и signature;
• понимать, как передавать status;
• сохранять и возвращать clickId;
• уметь отправить тестовый postback;
• уметь проверить результат в логах;
• понимать, почему postback может не засчитаться.

Связанные разделы

• Карточка оффера
• Статистика
• Финансы