Документация по API

API внешних офферов используются в работе постбеков для внешних интеграцией и подключении приложений. С помощью них можно создать лид по клику, поменять его статус, узнать данные оффера и потока, вытащить ID клика в приложении.

Авторизация

За авторизацию в API сайтов отвечает параметр token. Он бывает двух видов:

  • Токен сайта. Состоит из ID сайта и ключа сайта через дефис. Например 123-abcde. Для работы подходит токен любого сайта в рамках оффера - они равнозначны.
  • Глобальный токен. Его можно найти в разделе "Управление - Настройки - Сайты", блок "Технические настройки", параметр "Глобальный ключ API". С его помощью можно работать с любыми сайтами. Полезен при создании глобальных постбеков.

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

Создание лида

Функция предназначена для создания нового лида по ID клика. Может работать с кликами, потоками и внешними ID. Итогом работы будет новый лид. Параметры могут передаваться как в GET, так и в POST-части запроса.

URL: https://domain.com/api/site/click.json?token=123-abcd&click={subid}

Настраиваем ID клика

Функция может использовать эти параметры для понимания источника перехода:

  • click - идентификатор клика внутри AlterCPA.
  • exto - уникальный идентификатор заказа на стороне целевой сети.
  • flow - числовой идентификатор потока в AlterCPA.
  • code - символьный код потока в AlterCPA.

Какие сочетания можно использовать:

  • click - классическое создание лида по ID клика.
  • click + exto - создание лида по клику с защитой от дублей и удобным редактированием.
  • flow - создание лида по ID потока без возможности дальнейшего редактирования.
  • code - создание лида по символьному коду потока, например, из названия рекламной кампании внутри приложения, без возможности дальнейшего редактирования.
  • flow + exto или code + exto - создание лида по потоку с возможностью редактирования после.

При работе с SOI-постбеками вам нужно только создание лида, дальнейшее редактирование не обязательно. В этой ситуации уникальным ID можно пренебречь.

Добавляем статус

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

Функция может принимать следующие переменные для работы со статусами:

  • status - символьное значение статуса, анализируется автоматически.
  • accept=1 - принять лид (псевдоним status=approve).
  • stid - числовой идентификатор статуса AlterCPA.
  • reason - числовой код причины отказа.

При отправке статуса лида через параметр status, его распознавание происходит автоматически. Вы можете передавать ID статуса и причины отказа напрямую в stid и reason. Но удобнее обойти автоматику распознавания, напрямую указав в параметрах запроса, какие именно статусы считать аппрувом, отменой или трешем.

  • sta - статус, распознаваемый как аппрув.
  • stc - статус, распознаваемый как отмена заказа.
  • stt - статус, распознаваемый как треш.
  • sth - статус, распознаваемый как заказ в холде.
  • stw - статус, распознаваемый как заказ в обработке.
  • stn - статус, распознаваемый как новый заказ (создаёт лид вместо изменения статуса).

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

Важно! Очень часто сети используют название hold для обозначения простого ожидания заказа, поэтому необходимо напрямую указывать stw=hold, чтобы лид не улетел в холд и аппрув.

Добавляем отчисления

Отчисления можно получать напрямую через API. За это отвечают параметры:

  • wm - сумма отчисления за лид для вебмастера и рекламодателя.
  • cc - валюта суммы отчисления.
  • pd - комиссия партнёрской сети в валюте отчисления (положительная цифра уменьшит отчисления вебмастера из wm на указанную сумму, отрицательная - увеличит отчисления рекламодателя).
  • pp - комиссия партнерской сети в процентах, работает аналогично pd.
  • pay - сумма отчисления только для рекламодателя.

В реальной работе рекомендуется использовать два сочетания:

  • wm + cc - указание отчисления и валюты для всех сразу. Комиссия при этом настраивается через механизм ручных отчислений внутри оффера.
  • pay + cc - указание отчисления рекламодателя. Отчисление для вебмастера при этом подсчитывается по настройкам внутри оффера.

Использование pd и pp в реальной работе не рекомендуется, поскольку они исключают возможность гибкой настройки различной комиссии для разных вебмастеров.

Добавляем цель

При работе с офферами, у которых созданы расширенные цели, рекомендуется передавать цель через API в момент создания или изменения лида. За работу с целью отвечают два параметра:

  • goal - символьный идентификатор цели.
  • gid - числовой идентификатор цели.

Рекомендуется использовать символьный идентификатор цели. Вы можете настроить цели так, чтобы символьные идентификаторы на стороне AlterCPA совпадали с идентификаторами на стороне целевой сети. Если целевая сеть использует разные символьные идентификаторы для одной и той же цели, вы можете добавить их в список псевдонимов при настройке цели в оффере.

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

Эти параметры применяются достаточно редко. Их применение зависит от задачи.

  • name - имя покупателя.
  • phone - телефон покупателя.
  • email - адрес электронной почты.
  • country - двухбуквенный ISO-код страны.
  • base - цена единицы товара или цена конверсии (не отчисление!).
  • curr - числовой идентификатор валюты в рамках платформы.
  • currency - трёхсимвольный ISO-код валюты.
  • count - количество товара в заказе.
  • comment - комментарий к заказу.
  • mobile - тип трафика (мобильный или десктоп).
  • bad - если установлено в 1, трафик помечается некачественным.
  • time - время создания лида в формате UNIX timestamp.

В параметре mobile можно передавать значения:

  • Десктоп: 0, dsk, desk, desktop, pc, laptop.
  • Мобильный: 1, mob, mobile, tablet, любое не пустое значение.

Планшеты считаются мобильным трафиком. Отдельной категории "Планшет" не существует. При необходимости работы с таким типом трафика, используйте цели.

Ответ функции

Функция выдаёт ответ в виде JSON-объекта со следующими полями:

  • status - ok в случае успеха и error в случае ошибки.
  • id - идентификатор лида в AlterCPA.
  • error - код ошибки.

При работе функции могут возникать такие ошибки:

  • auth - проблема с авторизацией, проверьте токен.
  • no-id или bad-id - не удалось найти ID клика или потока.
  • traffic - трафик на оффер запрещён настройками приватности.
  • duplicate - дублированный лид.
  • db - системная ошибка при работе с базой.

Вы можете сохранить ID лида в приложении для дальнейшего редактирования. Не используйте наличие поля id для определения успеха, проверяйте именно по status=ok. Ошибка дубликата также выдаёт ID лида, но это будет идентификатор оригинала.

Пример успешного ответа функции:

{ "status": "ok", "id": 1234 }

Пример ошибки:

{ "status": "error", "error": "duplicate", "id": 1234 }

Изменение статуса лида

Функция предназначена для изменения статуса ранее созданного лида. Может работать с кликами, заказами, потоками и внешними ID. Итогом работы будет лид в указанном статусе. Параметры могут передаваться как в GET, так и в POST-части запроса.

URL: https://domain.com/api/site/status.json?token=123-abcd&click={subid}&status={status}

Настраиваем ID клика

Функция может использовать эти параметры для понимания источника перехода:

  • click - идентификатор клика внутри AlterCPA.
  • exto - уникальный идентификатор заказа на стороне целевой сети.
  • order - идентификатор лида внутри AlterCPA.
  • flow - числовой идентификатор потока в AlterCPA.
  • code - символьный код потока в AlterCPA.

Какие сочетания можно использовать:

  • click - классическое изменение лида по ID клика, работает только с одним лидом.
  • click + exto - изменение лида по клику с возможностью работы с несколькими лидами с одинаковым ID клика.
  • order - изменение лида по его ID, полученному при создании.
  • flow + exto или code + exto - изменение лида по потоку (ID или коду).

Обязательно используйте идентичное сочетание параметров при создании и редактировании лида. Если вы создаёте лид без указания exto, а редактируете его уже с указанием exto, вы получите ошибку.

Если лид не нашёлся

Иногда постбек на создание лида теряется. В такой ситуации функция не сможет найти нужный лид и завершится с ошибкой. Существуют два пути обхода этой проблемы.

  • Добавьте auto=1 в запрос. В этой ситуации потерянный лид будет создан автоматически и переведён в нужный статус.
  • Используйте в запросе stn=new с указанием статуса, который считать новым заказом. Это позволит использовать единый постбек и для создания, и для изменения лида.

В чём отличие stn=new от auto=1? При использовании параметра stn лид создаётся только в том случае, если статус совпадает с указанным в stn и попадает в статус "Новый". При использовании auto лид будет создан сразу в нужном статусе, если не был найден другой лид с тем же ID клика.

Статусы, отчисления, цели и другие поля

Функция использует те же поля для работы со статусами, отчислениям, целями и дополнительными полями, что и создание лида. Обратитесь к документации выше.

Ответ функции

Функция выдаёт ответ в виде JSON-объекта со следующими полями:

  • status - ok в случае успеха и error в случае ошибки.
  • id - идентификатор лида в AlterCPA.
  • error - код ошибки.

При работе функции могут возникать такие ошибки:

  • auth - проблема с авторизацией, проверьте токен.
  • no-id или bad-id - не удалось найти лид по указанным ID.
  • db - системная ошибка при работе с базой.
  • edit - лид уже прибывает в нужном состоянии, изменять нечего.

Пример успешного ответа функции:

{ "status": "ok", "id": 1234 }

Пример ошибки:

{ "status": "error", "error": "edit" }

Получение клика

Функция позволяет получить идентификатор клика посетителя по его IP-адресу, офферу и потоку. Итогом работы будут данные клика. Параметры могут передаваться как в GET, так и в POST-части запроса.

URL: https://domain.com/api/site/fetch.json?token=123-abcd&offer={offer}

Предполагаемый кейс: редирект-сайт перенаправляет на страницу установки приложения в магазине. Сразу после установки и запуска приложение пытается получить ID клика, по которому был сделан переход. ID сохраняется для дальнейших запросов.

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

  • offer - идентификатор оффера, нужен при работе с глобальным токеном.
  • flow - числовой идентификатор потока для уточнения поиска.
  • code - символьный код потока для уточнения поиска.
  • ip - использовать указанный IP-адрес пользователя вместо определяемого автоматически.
  • to - время, раньше которого не выполняется поиска клика, в формате UNIX timestamp. По умолчанию клики ищутся за последние сутки.

Функция выдаёт ответ в виде JSON-объекта со следующими полями:

  • status - ok в случае успеха и error в случае ошибки.
  • error - код ошибки.
  • click - ID найденного клика.
  • offer - ID оффера.
  • site - ID сайта.
  • flow - ID потока.
  • geo - ISO-код страны клика.
  • ip - IP-адрес клика.
  • time - время клика в формате UNIX timestamp.
  • utms - метка utm_source.
  • utmc - метка utm_campaign.
  • utmn - метка utm_content.
  • utmt - метка utm_term.
  • utmm - метка utm_medium.

При работе функции могут возникать такие ошибки:

  • auth - проблема с авторизацией, проверьте токен.
  • no-click - не удалось найти клик по указанным критериям .
  • no-offer - не задан ID оффера.

Пример успешного ответа функции:

{ "status": "ok", "click": 1234, "geo": "us" }

Пример ошибки:

{ "status": "error", "error": "no-click" }

Получение данных потока

Функция позволяет получить поток по его коду, ID или клику. Итогом работы будут данные потока. Параметры могут передаваться как в GET, так и в POST-части запроса.

URL: https://domain.com/api/site/flow.json?token=123-abcd&code={code}

Предполагаемый кейс: приложение после установки извлекает название рекламной кампании и использует его в качестве кода потока. После получения данных по ссылке потока открывается iframe или код потока используется для дальнейших постбеков.

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

  • click - идентификатор клика.
  • flow - числовой идентификатор потока.
  • code - символьный код потока.

Функция выдаёт ответ в виде JSON-объекта со следующими полями:

  • status - ok в случае успеха и error в случае ошибки.
  • id - идентификатор найденного потока.
  • code - символьный код потока.
  • link - ссылка потока для перенаправления.
  • offer - идентификатор оффера.
  • site - идентификатор лендинга.
  • space - идентификатор прелендинга.
  • fb - ID пикселя Facebook.
  • fbe - событие конверсии Facebook.
  • ga - ID счётчика Google Analytics или Tag Manager.
  • gad - символьный код конверсии Google Analytics.
  • tt - ID пикселя Tik-Tok.
  • lki - ID пикселя Likee.
  • vk - ID пикселя VK.
  • mt - ID счётчика MailTarget.
  • mtrk - ID счётчика Yandex.Metrika.
  • utms - метка utm_source.
  • utmc - метка utm_campaign.
  • utmn - метка utm_content.
  • utmt - метка utm_term.
  • utmm - метка utm_medium.

При работе функции могут возникать такие ошибки:

  • auth - проблема с авторизацией, проверьте токен.
  • no-id или bad-id - не удалось найти поток по указанным ID.

Пример успешного ответа функции:

{ "status": "ok", "id": 1234, "link": "https://r.domain.com/go1234" }

Пример ошибки:

{ "status": "error", "error": "no-click" }

Получение данных оффера

Функция позволяет получить оффер по его ID, потоку или клику. Итогом работы будут данные оффера. Параметры могут передаваться как в GET, так и в POST-части запроса.

URL: https://domain.com/api/site/offer.json?token=123-abcd&id={offer}

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

  • offer - идентификатор оффера (рекомендуется).
  • click - идентификатор клика.
  • flow - числовой идентификатор потока.
  • code - символьный код потока.

Функция выдаёт ответ в виде JSON-объекта со следующими полями:

  • status - ok в случае успеха и error в случае ошибки.
  • id - идентификатор найденного оффера.
  • name - название оффера, которое можно показывать посетителю.
  • geo - массив ISO-кодов поддерживаемых стран.
  • param - массив параметров оффера.
  • price - массив ценников по офферу.
  • site - массив сайтов оффера.

При работе функции могут возникать такие ошибки:

  • auth - проблема с авторизацией, проверьте токен.
  • no-id или bad-id - не удалось найти оффер по указанным ID.