Входящий постбек: приём конверсий от партнёрской сети

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

Где взять адрес

Адрес показан в двух местах панели. Оба адреса рабочие: первый ведёт на домен трекинга, второй — на домен панели, часть параметров названа по-разному.

Раздел «Сети»

Раздел видят все роли, кроме финансиста. Добавлять и удалять сети могут владелец и администратор.

1. Откройте Сети.
2. В блоке URL постбэка приёма конверсий нажмите Копировать.
3. Вставьте адрес в настройки постбека партнёрской сети.
4. Замените {click_id}, {status}, {payout} и {txid} на макросы сети.

Адрес выглядит так:

https://track.example.com/api/v1/postback?subid={click_id}&status={status}&payout={payout}&txid={txid}

Если партнёрская сеть добавлена в список, в колонке URL постбэка показан её адрес с дополнительными параметрами. Скопируйте его кнопкой копировать в строке сети.

Мастер во вкладке «Postback»

Вкладку видят владелец и администратор.

1. Откройте Настройки → Postback. Блок называется Входящий S2S postback.
2. Выберите Источник.
3. Выберите Статус: lead, sale, rejected или hold. По умолчанию выбран lead.
4. Если у источника задан секрет, введите его в поле Секрет источника. Сохранённый секрет панель не показывает.
5. Нажмите Копировать шаблон. Появится сообщение «Скопировано».
6. В партнёрской сети замените {subid}, {payout} и {transaction_id} на её макросы.
7. Если сеть платит не в долларах, замените USD на код валюты выплаты.

Шаблон мастера:

https://panel.example.com/api/v1/postback?subid={subid}&status=lead&payout={payout}&currency=USD&tid={transaction_id}

Значение status в шаблоне постоянное. Если сеть передаёт статус макросом, подставьте макрос вместо значения.

Кнопка Копировать шаблон недоступна, пока не выбран источник, а для источника с секретом — пока не введён секрет.

Параметры запроса

Чтобы сеть вернула ID клика, передайте его в ссылке оффера макросом {subid}, например sub1={subid}. Имя параметра задаёт сеть. Список макросов — на странице Макросы в ссылках и страницах.

GET, POST и домены

Трекер принимает постбек методами GET и POST. В теле POST параметры передаются как application/x-www-form-urlencoded или JSON-объектом с заголовком Content-Type: application/json. Размер тела — до 1 МиБ. Если параметр есть и в адресе, и в теле, берётся значение из адреса.

Путь /api/v1/postback работает на домене панели, на основном домене трекинга и на доменах кампаний, добавленных в панели. Авторизация не нужна.

Как определяется статус

Трекер проверяет значение status по порядку:

1. Списки в самом постбеке. Значение из lead_status записывается как lead, из sale_status — как sale, из rejected_status — как rejected. При значении из ignore_status конверсия не записывается.
2. Типы конверсий во вкладке Настройки → Конверсии. Берётся первый по порядку создания тип, в чьих значениях есть этот статус.
3. Если совпадений нет, статус записывается как пришёл, строчными буквами.

Пример: сеть шлёт approved, declined и pending, и ожидающие конверсии учитывать не нужно. Допишите к адресу:

&sale_status=approved&rejected_status=declined&ignore_status=pending

Статус hold через списки в адресе не задаётся — для него создайте тип конверсии.

Выплата и валюта

Откуда берётся сумма, зависит от настроек оффера:

• У оффера включён флажок Выплата из параметра постбэка — сумма берётся из параметра payout. Другое имя параметра задаётся через API полем payout_param, см. Admin API: офферы.
• У оффера указана выплата больше нуля — записывается выплата оффера, значение из постбека не используется. Для статусов lead и rejected записывается 0. Если status в постбеке пустой, записывается выплата оффера.
• В остальных случаях, а также когда клик пришёл без оффера, сумма берётся из параметра payout.

Сумма пересчитывается в USD по курсу на дату приёма постбека. Курсы настраиваются во вкладке Настройки → Валюты, см. Валюты и курсы. Если курса для валюты нет, трекер отвечает кодом 422 и конверсию не записывает.

Сумма, которую не удалось разобрать, отрицательная или больше предела записывается как 0. В журнале Логи → Postbacks появляется строка «Выплата в postback не распознана или недопустима — записан 0».

ID транзакции

По txid трекер отличает повтор постбека от новой конверсии по тому же клику:

• Тот же txid, тот же статус и та же выплата — повтор пропускается, дубль не создаётся.
• Тот же txid, тот же статус, в постбеке другая выплата — выплата конверсии исправляется.
• Тот же txid, новый статус — конверсия обновляется.
• После sale приходит lead или hold с тем же txid — постбек пропускается, продажа остаётся.
• txid не передан — постбек не сравнивается с прежними: по клику остаётся одна конверсия с последним статусом и суммой, а событие каждый раз уходит получателям.

Незаменённый макрос вида {txid} трекер считает пустым значением. Подробные правила — на странице ID транзакции, дубли и корректировки конверсий.

Секрет источника

Если у источника задан секрет, трекер принимает постбек только с верным параметром secret. Секрет задаётся у источника трафика, а не у сети: трекер проверяет секрет источника, с которого пришёл клик. Клик без источника секрета не требует. Задать секрет могут владелец и администратор.

1. В разделе Источники выберите источник.
2. Введите значение в поле Секрет постбэка/лида.
3. Нажмите Сохранить.
4. Добавьте к адресу постбека в партнёрской сети параметр &secret=значение. Мастер Настройки → Postback дописывает его сам, в адрес из раздела Сети добавьте его вручную.

Сохранённый секрет показан в поле как ***. Чтобы сменить секрет, введите новое значение и сохраните. Пустое поле и *** оставляют прежний секрет. Чтобы убрать секрет, нажмите Удалить рядом с полем, затем Сохранить.

Ответы трекера

Ошибки приходят в JSON с полями code и message, в таблице приведено значение message. Ответ на время обслуживания приходит обычным текстом. При ответах 429 и 503 сеть должна повторить запрос позже.

Клик попадает в статистику с небольшой задержкой, поэтому трекер ищет его около 1,5 секунды, прежде чем ответить 404.

Приём постбеков не зависит от лицензии: при истёкшей лицензии конверсии продолжают записываться. Что происходит с исходящими событиями, описано на странице Истечение лицензии: что закрыто и что работает.

Проверка

Для проверки отправьте постбек вручную. Раздел Логи доступен владельцу и администратору. Пример адреса, где SUBID — ID тестового клика:

https://track.example.com/api/v1/postback?subid=SUBID&status=lead&payout=1&txid=test-1

Если у источника клика задан секрет, добавьте к адресу &secret=значение.

1. Перейдите по ссылке кампании.
2. В Логи → Клики и лиды скопируйте значение из колонки Subid у своего клика. Поиск описан на странице Поиск кликов и лидов.
3. Откройте в браузере адрес постбека с этим subid.
4. Убедитесь, что трекер ответил ok.
5. В Логи → Postbacks введите subid в поле поиска. Когда клик найден, в журнале есть строка «Processing subid …» с ID кампании и статусом. Отказ по секрету, ненайденный клик и дубль тоже пишутся в этот журнал.
6. В кампании нажмите Статистика.
7. Найдите конверсию во вкладке Лог конверсий, см. Лог конверсий кампании.

Если конверсия не появилась, откройте страницу Постбек не приходит: что проверить.