Документация по 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
Сайт компании (advertiser)
name string
Личное имя пользователя
telegram string
Telegram
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
Модель ответа Сайт

Параметры

Ключ Тип Обязательный Описание
dateFrom string
Дата в формате ISO 8601
dateTo string
Дата в формате ISO 8601
status int
Статус
  • 0 - На модерации
  • 1 - Активные
  • 2 - Запрещенные
  • 3 - Неподтвержденные

Пример URI запроса:
`/api/webmaster/sites?dateFrom=2023-01-01&dateTo=2023-01-10&status=1`

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

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

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

Параметры

Ключ Тип Обязательный Описание
dateFrom string
Дата в формате ISO 8601
dateTo string
Дата в формате ISO 8601

Пример URI запроса:
`/api/webmaster/sites/1111?dateFrom=2023-03-01&dateTo=2023-03-02`

Статистика

Получение статистики по сайтам и блокам

Метод GET
Путь https://recreativ.com/api/webmaster/statistic
Модель ответа Статистика

Параметры

Ключ Тип Обязательный Описание
dateFrom string
Дата в формате ISO 8601
dateTo string
Дата в формате ISO 8601
siteIds string
Числовые идентификаторы сайтов через запятую
blockIds string
Числовые идентификаторы блоков через запятую

Пример URI запроса:
`/api/webmaster/statistic?dateFrom=2023-03-01&dateTo=2023-03-026&siteIds=1111,2222&blockIds=3333,4444,5555`

Выплаты

Получение информации о выплатах

Метод GET
Путь https://recreativ.com/api/webmaster/payment
Модель ответа Выплаты

Блок

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

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

Метод 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}
Модель ответа Кампания

Параметры

Ключ Тип Обязательный Описание
dateFrom string
Дата в формате ISO 8601
dateTo string
Дата в формате ISO 8601

Пример URI запроса:
`/api/advertiser/campaigns/1111?dateFrom=2023-03-01&dateTo=2023-03-02`

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

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

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

Параметры

Ключ Тип Обязательный Описание
dateFrom string
Дата в формате ISO 8601
dateTo string
Дата в формате ISO 8601
type int
Тип
  • 1 - Ретаргетинг
  • 2 - Стандартные
archived int
Aрхивные
  • 0 - Да
  • 1 - Нет
targetId int
Конверсия
  • 0 - Все
  • 1 - Покупка
  • 2 - Регистрация
  • 3 - Промежуточная цель

Пример URI запроса:
`/api/advertiser/campaigns?dateFrom=2023-03-01&dateTo=2023-03-026&siteIds=1111&targetId=1&archived=0`

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

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

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

Параметры

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

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

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

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

Параметры

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

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

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

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

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

Параметры

Ключ Тип Обязательный Описание
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` обязателен)
groupDate boolean
Получение статистики рекламных объявлений

Пример 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&groupDate=true`

Коэффициент качества

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

Метод GET
Путь https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}/site/{?id}
Модель ответа Коэффициент

Пример URI запроса:

`/api/advertiser/campaigns/multipliers/1111/site

`/api/advertiser/campaigns/multipliers/1111/site/2222s3333

Изменение коэффициента

Изменение указанного коэффициента.

Метод PUT
Путь https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}/site/{id}
Модель ответа

Пример URI запроса:
`/api/advertiser/campaigns/multipliers/1111/site/2222s3333?coef=1.2

Параметры

Ключ Тип Обязательный Описание
coef float
Число

Минимальное значение 0.1

Максимальное значение 10

Изменение коэффициента устройства

Изменение указанного коэффициента устройства

Метод PUT
Путь https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}/device/{type}
Модель ответа

Пример URI запроса:
`/api/advertiser/campaigns/multipliers/1111/device/{type}?coef=1.2

Параметры

Ключ Тип Обязательный Описание
type string
Устройство
  • desktop
  • mobile
  • tablet
coef float
Число

Минимальное значение 0.1

Максимальное значение 10

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

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

Метод GET
Путь https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}
Модель ответа Статистика по сайтам

Пример URI запроса:
`/api/advertiser/campaigns/multipliers/1111?dateFrom=2023-03-01&dateTo=2023-03-02`

Параметры

Ключ Тип Обязательный Описание
dateFrom string
Дата в формате ISO 8601
dateTo string
Дата в формате ISO 8601
targetId int
Конверсия
  • 0 - Все
  • 1 - Покупка
  • 2 - Регистрация
  • 3 - Промежуточная цель

Статистика по устройствам

Статистика по устройствам

Метод GET
Путь https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}/device
Модель ответа Статистика по устройствам

Пример URI запроса:
`/api/advertiser/campaigns/multipliers/1111/device?dateFrom=2023-03-01&dateTo=2023-03-02`

Параметры

Ключ Тип Обязательный Описание
dateFrom string
Дата в формате ISO 8601
dateTo string
Дата в формате ISO 8601
targetId int
Конверсия
  • 0 - Все
  • 1 - Покупка
  • 2 - Регистрация
  • 3 - Промежуточная цель

Объявление

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

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

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

Параметры

Ключ Тип Обязательный Описание
id int
Идентификатор кампании

Пример URI запроса:
`/api/advertiser/subCategories?id=1111`

Список типов скидок

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

Метод GET
Путь https://recreativ.com/api/advertiser/discountType/{campaign}
Ответ

json

Параметры

Ключ Тип Обязательный Описание
campaign int
Идентификатор кампании

Пример URI запроса:
`/api/advertiser/discountType/1111`

Добавление объявления

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

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

Параметры

Ключ Тип Обязательный Описание
campaignId int
Идентификатор кампании
description string
Текст не более 60 символов. ГЕО Тайланд, 100 символов
url string
URL
price int
Цена
discount int
  • Скидка id: 1
  • от id: 2
  • до id: 3
discountType string
Тип скидки
oldPrice int
Старая цена
subCategory int
Идентификатор подкатегории
clickPrice float
Цена клика
rectangle string

Прямоугольное изображение (Основное)

Пример формата:

data:image/{type};base64,.... где type - jpeg, png
square string

Квадратное изображение

Пример формата:

data:image/{type};base64,.... где type - jpeg, png

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

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

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

Параметры

Ключ Тип Обязательный Описание
dateFrom string
Дата в формате ISO 8601
dateTo string
Дата в формате ISO 8601
targetId int
Конверсия
  • 0 - Все
  • 1 - Покупка
  • 2 - Регистрация
  • 3 - Промежуточная цель

Пример URI запроса:
`/api/advertiser/offers/1111?dateFrom=2023-03-01&dateTo=2023-03-02`

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

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

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

Параметры

Ключ Тип Обязательный Описание
dateFrom string
Дата в формате ISO 8601
dateTo string
Дата в формате ISO 8601
archived int
Aрхивные
  • 0 - Да
  • 1 - Нет
targetId int
Конверсия
  • 0 - Все
  • 1 - Покупка
  • 2 - Регистрация
  • 3 - Промежуточная цель
type int
Тип
  • 1 - Ретаргетинг
  • 2 - Стандартные

Пример URI запроса:
`/api/advertiser/campaigns/1111?dateFrom=2023-03-01&dateTo=2023-03-02&type=1`

Вкл./выкл. объявление

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

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

Параметры

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

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

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

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

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

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

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

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

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

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

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

Поле Тип Описание
date string Дата в формате ISO 8601
views int Количество показов
clicks int Количество переходов
money float Количество расходов
orders int Конверсии
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC

Кампания

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

Поле Тип Описание
id int Идентификатор кампании
title string Заголовок кампании
active bool Флаг активности кампании
maxclicks int Лимит переходов
maxmoney float Лимит расходов
isRetarget bool Является ли кампания кампанией ретаргетинга
category_id int Идентификатор категории
items int Товары
status int Статус
views int Количество показов
clicks int Количество переходов
money float Количество расходов
orders int Конверсии
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC

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

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

Поле Тип Описание
date string Дата в формате ISO 8601
views int Количество показов
clicks int Количество переходов
money float Количество расходов
orders int Конверсии
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC

Объявление

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

Поле Тип Описание
id int Идентификатор объявления
title string Заголовок товара
campaignId int Идентификатор модели Кампании
img Изображение Структура со списком изображений товара
img_wide Изображение Структура со списком изображений товара
isRetarget bool Является ли кампания кампанией ретаргетинга
opis string Описание товара
cost string Цена товара
url string Адрес перехода
url_mobile string Адрес перехода для мобильных платформ
stavka float Текущая цена перехода
active bool Флаг активности объявления
views int Количество показов
clicks int Количество переходов
money float Количество расходов
orders int Конверсии
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC

Категория

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

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

Изображение

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

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

Сайт

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

Поле Тип Описание
id int Идентификатор сайта
status string Статус
url string Адрес сайта
category_id string Идентификатор модели Категория
monthly_uniq_users string Уникальные посетители ежемесячно
blocks_count int Блоки
views int Показов
clicks int Переходов
ctr float CTR
cpm float CPM
money int Доход

Блок

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

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

Статистика

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

Поле Тип Описание
date string Дата в формате ISO 8601
views int Показов
clicks int Переходов
ctr float CTR
cpm float CPM
money int Доход

Выплаты

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

Поле Тип Описание
date string Дата в формате ISO 8601
wallet string Метод оплаты
amount float Доход
status string Статус

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

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

Поле Тип Описание
site_id string Идентификатор сайта
views int Количество показов
clicks int Количество переходов
money float Количество расходов
orders int Конверсии
ctr float CTR
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC
coef float Коэффициент

Статистика по устройствам

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

Поле Тип Описание
device string Устройство
views int Количество показов
clicks int Количество переходов
money float Количество расходов
orders int Конверсии
ctr float CTR
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC
coef float Коэффициент

Коэффициент

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

Поле Тип Описание
coef float Коэффициент
campaignId int Идентификатор кампании
siteId int Идентификатор сайта
deviceId int Идентификатор устройства
informerId int SSP informer ID

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

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

О статусе выполнения запроса свидетельствует код ответа сервера с соответствующим статусом. В случае, если ошибка требует более детального описания, в теле ответа может находится список с параметром `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

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