Документация по 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.
  • customer — метка customer.

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

  • 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.
  • customer — метка customer.

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

  • 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.