Общие правила API

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

Первый запрос за две минуты#

Чтобы убедиться, что доступ работает, не нужны ни программа, ни скрипт: достаточно браузера.

1. Найдите токен Откройте в кабинете профиль и найдите заголовок API-интерфейс. В поле API токен лежит ваш токен: номер вашей учётной записи и ключ через дефис, вида {user}-{key}.

2. Составьте адрес запроса Для первого раза возьмите список офферов: функция offer/names не требует параметров. Адрес — это адрес API сети, имя раздела offer, имя функции names, формат ответа json и ваш токен в параметре id:

   https://lk.dalead.pro/api/offer/names.json?id={token}

3. Откройте адрес в браузере Вставьте адрес в строку браузера. Вместо страницы вы увидите ответ в формате JSON: список ваших офферов, где число слева — номер оффера, а справа — его название. Номера пригодятся, когда вы начнёте отправлять лиды.

   JSON

   {
     "status": "ok",
     "data": {
       "24": "Hevital BabyBOOM",
       "31": "Meow Nutra",
       "2": "Waist Trainer"
     }
   }

   Ответ сокращён: в настоящем будут все офферы, доступные вам. То же самое можно сделать из командной строки:

   BASH

   curl 'https://lk.dalead.pro/api/offer/names.json?id={token}'

Если вместо списка пришла ошибка, смотрите поле error:

• key — токен не передан или не подошёл. Проверьте, что скопировали его целиком и без пробелов, и что не сбрасывали ключ в профиле после этого.
• access-denied — сеть скрыла от вебмастеров каталог офферов. Работу токена можно проверить другим запросом, wm/flows (см. Потоки): он ответит списком ваших потоков или, если потоков ещё нет, пустым [].
• func, request — в адресе опечатка, см. Ошибки.

Адрес запроса#

Запрос состоит из адреса API вашей сети и трёх частей: приложения, функции и формата ответа. Приложение — раздел API, функция — действие внутри раздела, формат — расширение, дописанное к имени функции через точку. Токен всегда идёт в параметре id.

https://lk.dalead.pro/api/{app}/{func}.{format}?id={token}

Приложения API, описанные в этой справке.

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

Регистр в именах приложения, функции и формата не важен: /api/OFFER/Names.JSON работает так же, как /api/offer/names.json. Имена параметров регистр учитывают, поэтому пишите их так, как они указаны в описании функции. Исключение — добавление лида: там имена полей приводятся к нижнему регистру, потому что данные приходят из чужих форм.

Токен#

Доступ к API есть у любой учётной записи, включать его отдельно не нужно. Кроме отправки лидов — её запросите у своего менеджера. Токен состоит из номера вашей учётной записи ({user}) и ключа API: 32 знака, цифры и латинские буквы a–f. Они пишутся через дефис. Ваш токен целиком — {token}.

Токен передаётся в параметре id строки запроса, в каждом запросе: ?id={token}. Без токена или с неверным токеном платформа отвечает ошибкой key. Если учётная запись заблокирована или отключена, ответ — ошибка ban.

Ключ лежит в профиле, в поле API токен под заголовком API-интерфейс. Там же находится ссылка Сгенерировать новый API-токен: после подтверждения старый ключ сразу перестаёт работать, а номер учётной записи остаётся прежним. Обновите токен во всех своих скриптах и на всех сайтах, где он вписан. Подробнее — на странице Аккаунт и ключ API.

Как отправлять запрос#

Большинство функций можно вызвать и методом GET, и методом POST. Читающие функции удобно вызывать запросом GET, а отправляющие данные лучше слать методом POST: длина адреса ограничена.

Параметры можно передать тремя способами:

• в строке запроса — прямо в адресе: ?offer=31&phone=79001234567;
• формой — телом POST-запроса в формате application/x-www-form-urlencoded;
• JSON — телом запроса в формате JSON с заголовком Content-Type: application/json. Платформа разберёт его и разложит по тем же полям, что и форму. Токен при этом по-прежнему передаётся в строке запроса.

Если один и тот же параметр пришёл и в адресе, и в теле запроса, побеждает тело.

Метка запроса

К любому запросу можно добавить метку: параметр z в строке запроса, например ...&z=meow-landing. Платформа записывает её в журнал API-запросов вместе с самим запросом (журнал включён по умолчанию). Журнал ведёт сеть, вы его не видите, но метка выручает, когда с одним токеном работает несколько лендингов или скриптов: назовите в поддержке метку и время запроса, и администратору проще найти запрос, о котором речь.

В метке остаются латинские буквы (в нижнем регистре), цифры, дефис, подчёркивание и точка. Пробелы превращаются в дефисы, русские буквы заменяются латиницей, остальные знаки отбрасываются: метка Meow Привет! будет записана как meow-privet.

Лимиты и хорошие манеры#

В платформе нет ограничения на частоту и число API-запросов: ни в минуту, ни в сутки. Версий у API тоже нет, в адресе функции нет номера версии. Но каждый запрос — это нагрузка на сеть, которую делят все вебмастера, поэтому:

• каталог офферов (offer/list, offer/names, offer/show) сохраняйте у себя и обновляйте по расписанию, а не перед каждой операцией, offer/show запрашивайте по одному офферу;
• о смене статуса лидов узнавайте из постбеков потока (см. Постбеки), а leads/list используйте для выборочной сверки и сужайте датами;
• добавляйте к запросам метку z, чтобы при разборе ошибок было видно, какой скрипт их прислал.

Отдельно от API действуют правила приёма лидов: защита от дублей и массовой отправки с одного IP-адреса, фильтры трафика. Они срабатывают при добавлении лида и описаны на странице Лиды.

Формат ответа#

Формат ответа задаётся расширением в адресе функции. Во всех примерах справки используется json: его и берите для работы.

Форматы ответа.

Незнакомое расширение ошибкой не считается: ответ придёт в красивом JSON с отступами и переносами строк, чтобы его было удобно читать глазами.

Конверт ответа

Почти все функции отвечают объектом, который начинается с поля status: его значение ok или error. Это «конверт» ответа. При успехе остальные поля зависят от функции. При ошибке в поле error приходит её код, а иногда и уточнения: info — причина, bad — список проблемных полей, message — текст ошибки стороннего сервиса.

{
  "status": "error",
  "error": "key"
}

Некоторые функции отдают данные без конверта: сводная статистика и статистика с группировкой (wm/stats, wm/click) и список потоков (wm/flows) возвращают сразу данные, поля status в них нет, а пустой результат выглядит как []. Ошибки этих функций приходят в обычном конверте. Есть ли конверт у функции, сказано на странице функции.

Результат дублируется в заголовках ответа, и это надёжнее всего для функций без конверта: X-API-Status содержит ok или error, X-API-Error — код ошибки, если она была, а X-Status — код HTTP, которым платформа ответила бы на ошибку (200 или 400).

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Status: 400
X-API-Status: error
X-API-Error: key

Сам HTTP-код при этом всегда 200, чтобы ответ дошёл до клиентов, которые не читают тело ошибочного ответа. Если вам удобнее ловить ошибки по коду HTTP, добавьте в строку запроса параметр statuscode=1: тогда ошибка придёт с кодом 400, а успех по-прежнему с 200.

Ошибки#

Прежде чем дело дойдёт до функции, запрос проходит через вход в API. Его ошибки одинаковы для всех функций.

Ошибки входа в API.

Коды ошибок самих функций описаны на страницах функций. Два кода встречаются почти везде и означают «нельзя»: access — у вас нет права на действие или поток чужой, access-denied — функция или данные для вас закрыты (например, сеть скрыла каталог офферов, оффер вам недоступен или функция предназначена другой роли).

Справочники значений#

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

Фазы заказа

Фаза — состояние заказа с точки зрения вебмастера, от неё зависят ваши деньги. Она есть в любой сети и приходит числом в поле phase и символьным кодом в поле stage. Те же значения подставляются в макросы постбеков {phase} и {stage}.

Фазы заказа.

Статусы заказа

Статус — шаг обработки заказа в CRM сети: от создания до выкупа или отказа. Фаза и статус описывают одно состояние заказа: фаза — для вебмастера и денег, статус — подробнее. Какую фазу даёт статус, зависит от модели оплаты оффера, см. ниже.

Статусов двенадцать, их коды — от 1 до 12. Основные есть в любом оффере. Дополнительные, подробные шаги обзвона и доставки, характерны только для товарных сетей.

Коды статусов.

Код статуса приходит в поле crm ответа leads/list: это статус заказа в CRM, код из справочника выше. Функция wm/stats считает заказы по статусам в полях c1–c12.

В моделях cps, cod, cor заказ в статусе 5 попадает в «Треш», если его причина отказа входит в набор треш-причин, и в «Отмену» в остальных случаях: см. Причины отказа. В моделях cpl, cpv, cpa статус 5 с обычной причиной даёт фазу «Принят»: см. таблицу ниже.

Как статус становится фазой

Фазу заказа определяет его статус и модель оплаты оффера. Модель — поле model в каталоге офферов: cps, cpl, cpv, cpa, cod или cor; модель cpx работает как cps. Сеть может назначить другую модель отдельной цели, вебмастеру или команде. В таблице — коды статусов, которые модель переводит в каждую фазу.

Модели оплаты: из какого статуса какая фаза. Статус 5 разобран по причине отказа.

Если у оффера задан срок холда, заказ, который по модели должен стать «Принят», сначала попадает в «Холд» на этот срок и затем подтверждается автоматически.

Причины отказа

Причина отказа приходит в поле reason и нужна только отменённым заказам, то есть заказам в статусе 5. Значение 0 — причина не указана. Причина из набора треш-причин переводит отмену в фазу «Треш» (кроме модели cpa), и такой заказ не считается в проценте аппрува среди валидных лидов.

Набор треш-причин задаёт сеть. В таблице отмечен стандартный набор, с которым система устанавливается: сеть могла его изменить. Поэтому ориентируйтесь на фазу заказа: заказ с причиной из набора сети приходит в фазе 5 (trash).

Причины отказа и стандартный набор треш-причин.

Куда дальше#

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

Как устроены ключ и профиль в кабинете — в разделе Аккаунт и ключ API, а когда платформа сама сообщает о смене статуса лида — в разделе Постбеки.