Документація по 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
Архів
  • 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 860
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 860
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
Архів
  • 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 Тип акаунта (advertiser, webmaster)
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

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