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

API позволит в динамике подгружать необходимые данные, используя их в своих системах статистики

Общая информация

Обзор

API Recreativ предоставляет доступ к инфраструктуре Recreativ через стандартизированный программный интерфейс. Через API Recreativ Вы можете сделать все то же самое, что доступно при использовании кабинета Recreativ.com, но при помощи выбранного Вами языка программирования.

API Recreativ это RESTful API, базирующееся на HTTP запросах и ответах в формате XML или JSON(P). Если Вы знакомы с API Twitter, Amazon S3, del.icio.us, или другим web-сервисом, Вам не составит труда начать работу с нашим API.

Эта версия API для авторизации использует механизм токенов. Это значит, что все запросы должны быть зашифрованы и посланы через SSL/TLS на https://. Это также значит, что каждый запрос должен сопровождать специально сформированный заголовок HTTP, в котором будет ключ авторизации. Этот ключ Вы можете узнать в своем личном кабинете на странице профиля.

Пример кода

user@localhost:~$ curl 'https://recreativ.com/api/advertiser/campaigns?filter[id]=111,222' \ -H 'Content-Type: application/json; charset=UTF-8' \ -H 'Accept: application/json' \ -H 'Auth-Token: eNldKDZHFuemaotqp6166WhZ0nximcHz' -v
> GET /api/advertiser/campaigns?filter[id]=111,222 HTTP/1.1
> User-Agent: curl/7.35.0
> Host: recreativ.com
> Content-Type: application/json; charset=UTF-8
> Accept: application/json
> Auth-Token: eNldKDZHFuemaotqp6166WhZ0nximcHz
> < HTTP/1.1 200 OK< Server: nginx< Date: Wed, 18 Feb 2015 15:34:24 GMT< Content-Type: application/json; charset=UTF-8< Transfer-Encoding: chunked< Connection: keep-alive<
[ { "id":111, "title":"Первая кампания", "active":1, "maxclicks":0, "maxmoney":"0.0000", "isRetarget":0 }, { "id":222, "title":"Вторая кампания", "active":1, "maxclicks":1000, "maxmoney":"25.0000", "isRetarget":0 }
]

Нужна помощь?

Если у Вас возникли вопросы, задавайте их нашей службе поддержки на почту, cкайп или через форму на сайте.

Точка входа

API доступно через осуществление HTTP запросов на определенный URL, в котором в GET и POST переменных содержится информация о том, что именно Вы хотите сделать. Все точки входа доступны только через зашифрованное HTTPS соединение.

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

Для передачи данных используются XML и JSON. Выбор конкретного формата зависит от заголовка Accept в запросе к серверу. Для получения ответа в JSON значение этого заголовка должно содержать MIME тип JSON - application/json, для XML - application/xml. Все общение с сервером происходит по протоколу HTTPS.

Стабильная корневая точка входа последней версии:

https://recreativ.com/api/

Ответ может быть сформирован как в формате JSON, так и в XML. Это поведение зависит от переданного заголовка Accept, который должен содержать тип желаемого ответа.

Авторизация

Авторизация происходит с помощью специального ключа, т.н. access token, который должен сопровождать каждый запрос к серверу в заголовке запроса Auth-Token.

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

Ограничение запросов

Число запросов к API в секунду ограничено 5 запросами. При превышении этого числа, вы получите ответ сервера c кодом 429.

Точки входа

На этой странице описаны адреса точек входа с параметрами, которые используются при создании запроса.

Пользователь

Текущий пользователь

Запрос информации о текущем пользователе.

Метод GET
Путь https://recreativ.com/api/me
Модель ответа Пользователь

Список клиентов

Получение списка рефералов текущего аккаунта.

Метод GET
Путь https://recreativ.com/api/advertiser/users
Модель ответа Пользователь

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

Получение информации об аккаунте из числа своих рефералов.

Метод GET
Путь https://recreativ.com/api/advertiser/users/{id}
Модель ответа Пользователь

Список кампаний клиента

Получение списка кампаний, принадлежащих клиенту.

Метод GET
Путь https://recreativ.com/api/advertiser/users/{id}?expand=campaigns
Модель ответа Пользователь, Кампания

Добавление клиента

Создание аккаунта рекламодателя. В случае успеха, вернет код 201.

ОБРАТИТЕ ВНИМАНИЕ! Созданный пользователя автоматически будет обозначен, как реферал владельца ключа API, с которого пришел запрос о создании.
Метод POST
Путь https://recreativ.com/api/advertiser/users
Модель ответа Пользователь

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

Параметры

Ключ Тип Обязательный Описание
user string
Логин пользователя
email string
E-mail пользователя
url string
Сайт компании
name string
Личное имя пользователя
icq numeric
ICQ
skype string
Skype
phone string
Телефон пользователя

Изменение клиента

Изменение баланса пользователя {id} на указанную в параметрах запроса сумму. Ответом на запрос будет структура пользователя в указанном формате.

Метод PUT
Путь https://recreativ.com/api/advertiser/users/{id}
Модель ответа Пользователь

Параметры

Ключ Тип Обязательный Описание
balance float
Сумма, на которую изменится баланс
аккаунта (может быть отрицательной)

Сайт

Список категорий

Позволяет получить список категорий сайтов.

Метод GET
Путь https://recreativ.com/api/webmaster/categories
Модель ответа Категория

Список сайтов

Позволяет получить список сайтов пользователя.

Метод GET
Путь https://recreativ.com/api/webmaster/sites
Модель ответа Сайт

Получение сайта

Получение информации об указанном сайте.

Метод GET
Путь https://recreativ.com/api/webmaster/sites/{id}
Модель ответа Сайт

Блок

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

Получение информации об указанном блоке.

Метод GET
Путь https://recreativ.com/api/webmaster/blocks/{id}
Модель ответа Блок

Список блоков

Позволяет получить список блоков для указанного сайта.

Метод GET
Путь https://recreativ.com/api/webmaster/sites/{id}?expand=blocks
Модель ответа Блок, Сайт

Кампания

Список категорий

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

Метод GET
Путь https://recreativ.com/api/advertiser/categories
Модель ответа Категория

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

Получение информации об указанной кампании.

Метод GET
Путь https://recreativ.com/api/advertiser/campaigns/{id}
Модель ответа Кампания

Список кампаний

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

Метод GET
Путь https://recreativ.com/api/advertiser/campaigns
Модель ответа Кампания

Изменение кампании

Изменение указанной кампании.

Метод PUT
Путь https://recreativ.com/api/advertiser/campaigns/{id}
Модель ответа Кампания

Параметры

Ключ Тип Обязательный Описание
active boolean
Флаг активности кампании

Статистика кампаний

Статистика кампаний.

Метод GET
Путь https://recreativ.com/api/advertiser/statistics
Модель ответа Статистика кампаний

Параметры

Ключ Тип Обязательный Описание
scope string
Область получения статистических
данных, для кампаний равна `campaigns`
filter[dateFrom] string
Дата начала среза в формате ISO 8601
filter[dateTo] string
Дата конца среза в формате ISO 8601
filter[id] string
Числовые идентификаторы кампаний через
запятую

Пример URI запроса:
`/api/advertiser/statistics?filter[dateFrom]=2015-05-13&filter[id]=123,234,345`

Статистика объявлений

Статистика объявлений.

Метод GET
Путь https://recreativ.com/api/advertiser/statisticss
Модель ответа Статистика объявлений

Параметры

Ключ Тип Обязательный Описание
scope string
Область получения статистических
данных, для объявлений равна `offers`
filter[dateFrom] string
Дата начала среза в формате ISO 8601
filter[dateTo] string
Дата конца среза в формате ISO 8601
filter[date] string
Точная дата в формате ISO 8601
filter[id] int
Числовой идентификатор объявления
filter[campaignId] int
Числовой идентификатор кампании
(при использовании этого фильтра,
фильтр `date` обязателен)

Пример URI запроса:
`/api/advertiser/statistics?scope=offers&filter[dateFrom]=2015-05-13&filter[id]=123`
`/api/advertiser/statistics?scope=offers&filter[date]=2015-05-13&filter[campaignId]=321`

Объявление

Получение объявления

Получение информации об указанном объявлении.

Метод GET
Путь https://recreativ.com/api/advertiser/offers/{id}
Модель ответа Объявление

Список объявлений

Получение списка объявлений, принадлежащих кампании.

Метод GET
Путь https://recreativ.com/api/advertiser/campaigns/{id}?expand=offers
Модель ответа Объявление, Кампания

Удаление объявления

Удаление объявления. В случае успеха, вернет код `204`.

Метод DELETE
Путь https://recreativ.com/api/advertiser/offers/{id}
Модель ответа -

Модели данных

На этой странице перечислены все структуры данных, которые используются в ответах API.

Пользователь

Модель, представляющая данные пользователя.

Поле Тип Описание
id int Идентификатор пользователя
username string Логин пользователя
email string E-mail пользователя
type string Тип аккаунта (advertiser, webmaster)
url string Сайт компании
date date Дата регистрации в формате ISO 8601
maxmoney float Дневной бюджет
name string Личное имя пользователя
icq numeric ICQ
skype string Skype
phone string Телефон пользователя
balance float Текущий баланс аккаунта
parentId int Идентификатор модели Пользователь, рефералом которого является аккаунт

Статистика кампаний

Модель, представляющая статистические данные кампаний.

Поле Тип Описание
campaignId int Идентификатор кампании
date string Дата в формате ISO 8601
views int Количество показов
clicks int Количество переходов
money float Количество расходов

Кампания

Модель, представляющая данные кампании.

Поле Тип Описание
id int Идентификатор кампании
title string Заголовок кампании
active bool Флаг активности кампании
maxclicks int Лимит переходов
maxmoney float Лимит расходов
isRetarget bool Является ли кампания кампанией ретаргетинга

Статистика объявлений

Модель, представляющая статистические данные объявлений.

Поле Тип Описание
offerId int Идентификатор объявления
date string Дата в формате ISO 8601
views int Количество показов
clicks int Количество переходов
money float Количество расходов

Объявление

Модель, представляющая данные объявления.

Поле Тип Описание
id int Идентификатор объявления
title string Заголовок товара
campaignId int Идентификатор модели Кампании
img Изображение Структура со списком изображений товара
opis string Описание товара
cost string Цена товара
url string Адрес перехода
url_mobile string Адрес перехода для мобильных платформ
stavka float Текущая цена перехода
active bool Флаг активности объявления
clicks int Переходы за весь период
views int Просмотры за весь период
money float Расходы за весь период
todayclicks int Переходы за сегодняшний день
todayviews int Показы за сегодняшний день
todaymoney float Расходы за сегодняшний день

Категория

Модель, представляющая данные категории.

Поле Тип Описание
id int Идентификатор категории
parent_id int Идентификатор родительской модели Категория
title string Заголовок категории

Изображение

Модель, представляющая данные изображения.

Поле Тип Описание
url string Изображение по-умолчанию
allowedSizes string Разрешенные размеры изображения
pattern string Шаблон для формирования пользовательского размера

Сайт

Модель, представляющая данные сайта.

Поле Тип Описание
id int Идентификатор сайта
url string Адрес сайта
category_id string Идентификатор модели Категория

Блок

Модель, представляющая данные блока.

Поле Тип Описание
id int Идентификатор блока
bn string Код блока
title string Заголовок блока

Обработка ошибок

Общая информация

О статусе выполнения запроса свидетельствует код ответа сервера с соответствующим статусом. В случае, если ошибка требует более детального описания, в теле ответа может находится список с параметром `message`. значение которого будет расширенным описанием ошибки.

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

Попытка запроса ресурса без соответствующих прав приведет к следующей ошибке:

XML

 <response> <name>Unauthorized</name> <message>You are requesting with an invalid credential.</message> <code>0</code> <status>401</status>
</response>  

JSON

 { "name": "Unauthorized", "message": "You are requesting with an invalid credential.", "code": 0, "status": 401
} 

Статус 200

Запрос был успешно обработан сервером и не произошло никаких ошибок.

Статус 201

Ресурс был успешно создан в ответ на `POST`-запрос. Заголовок `Location` содержит URL, указывающий на только что созданный ресурс.

Статус 204

Запрос обработан успешно, и в ответе нет содержимого (для запроса `DELETE`, например).

Статус 304

Ресурс не изменялся. Можно использовать закэшированную версию.

Статус 400

Неверный запрос. Может быть связано с разнообразными проблемами на стороне пользователя, такими как неверные JSON-данные в теле запроса, неправильные параметры действия, и т.д.

Статус 401

Аутентификация завершилась неудачно.

Статус 403

Аутентифицированному пользователю не разрешен доступ к указанной точке входа API.

Статус 404

Запрошенный ресурс не существует.

Статус 405

Метод не поддерживается. Сверьтесь со списком поддерживаемых HTTP-методов в заголовке `Allow`.

Статус 415

Неподдерживаемый тип данных. Запрашивается неправильный тип данных или номер версии.

Статус 422

Проверка данных завершилась неудачно (в ответе на `POST`-запрос, например). Подробные сообщения об ошибках смотрите в теле ответа.

Статус 429

Слишком много запросов. Запрос отклонен из-за превышения ограничения частоты запросов.

Статус 500

Внутренняя ошибка сервера. Возможная причина — ошибки в самой программе.