Внимание: API находится на стадии активной разработки. В скором времени он будет дополнен множеством новых методов, однако возможны изменения в существующих методах. О важных изменения мы обязательно уведомим вас, оставайтесь на связи.

Начало работы

В документе описан программный интерфейс сервиса ad1 (далее — «API»). Через API внешние приложения добавляют и редактируют офферы, цели, промоматериалы, получают списки офферов, лидов, а также всевозможную статистику.

Предполагается, что читатель владеет терминологией и понимает принципы работы CPA сетей. Эта информация содержится в справке сервиса.

Варианты использования

API предусматривает различные уровни доступа к объектам системы, эти уровни соответствуют типам аккаунтов. Без авторизации доступен уровень "Гость", используя который можно получить информацию, также доступную без регистрации на сайте: список доступных офферов, их целей, новости и т.д. Уровни "Вебмастер" и "Рекламодатель" соответствуют функционалу аналогичных аккаунтов на сайте.

Доступ

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

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

REST

API построено по принципу REST. Для получения доступа к любому ресурсу достаточно сделать обычный HTTP запрос.

В общем случае, url ресурса выглядит так: /api/<resource_name>, всего может быть 5 методов взаимодействия с ресурсом.

Очевидно, что не каждый ресурс поддерживает все 5 методов взаимодействия. Полный список доступных методов для каждого типа аккаунта можно увидеть в меню "Ресурсы и методы" слева.

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

Используется базовый способ передачи данных по HTTP. В случае GET запросов — параметры передаются в виде строки параметров url, в случае POST,PUT,DELETE — в теле запроса.

Дополнительная сериализация запроса не требуется, однако, обратите внимание, в некоторых случаях необходимо использовать кодирование url.

Ответы сервера и ошибки

Формат данных ответа — всегда JSON. В таблице выше можно увидеть, какие поля следует ожидать в ответе в случае успешного запроса. В случае ошибки в ответе сожержится только поле error.

Общее правило такое: если в ответе нет поля error, значит запрос выполнен успешно, и в ответе нужно искать поле, соответствующее запросу (см. таблицу методов).

В поле error сожержится наиболее подробное описание ошибки. В этом поле может передаваться как строка, так и более сложная структура данных, например:

GET /api/geo?api_key=wrongkey

{ "error": "Unauthorized" }

GET /api/goal/?offer_id=-123

{ "error": { "offer_id": ["Offers not found"] } }

Кроме описания ошибки в поле error, общая информация об ответе (в том числе об ошибке) передается в коде статуса HTTP. Список используемых кодов: