Документація по 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

Внутрішня помилка сервера. Можлива причина - помилки в самій програмі.