LogoAPI Documentation

Базовая информация


Примеры выполнения запросов к Alloka API при помощи различных технологий

Ниже приведены примеры запросов к Alloka API при помощи утилиты cURL, а также языков PHP, Ruby и Python. Если у вас появились затруднения или вы используете технологию, не описанную в данной документации — напишите нам на электронный адрес support@alloka.ru

Пример запроса через утилиту cURL

curl -X GET "https://api.alloka.ru/v1/geo" -u gnLZYz0FexchC6RFPyP0PBb9n26cecQh: -v

HTTP авторизация в утилите cURL происходит указанием следующего аргумента:

curl -u username:password

В примере запроса выше username — это API-ключ, а password параметр должен быть пуст:

curl -u <ВАШ_API_КЛЮЧ>:

Пример запроса на языке PHP

 <?php 
// URL запроса
$ch = curl_init("https://api.alloka.ru/v1/geo");

// Ваш API-ключ авторизации
$api_key = "gnLZYz0FexchC6RFPyP0PBb9n26cecQh";

// Авторизация
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":");

// Заголовки запроса
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json"
));

// Выполняем запрос
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);

// Закрываем соедиениние
curl_close($ch);

/* Обработка ответа */
echo $result;
?>

Пример запроса на языке Ruby

require 'uri'
require 'net/https'

# Ваш API-ключ авторизации
api_key = "gnLZYz0FexchC6RFPyP0PBb9n26cecQh"

# URL запроса
uri = URI.parse("https://api.alloka.ru/v1/geo")

# Создаём объекты запроса
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_PEER
request = Net::HTTP::Get.new(uri.request_uri)

# Авторизация
request.basic_auth(api_key, "")

# Заголовки запроса
request.headers["Content-Type"] = "application/json"

# Выполняем запрос
response = http.request(request)

# Ваша обработка ответа
puts response.body

Пример запроса на языке Python

import httplib2

# Ваш API-ключ авторизации
api_key = "gnLZYz0FexchC6RFPyP0PBb9n26cecQh"

# URL запроса
url = "https://api.alloka.ru/v1/geo"

# Создаём объект запроса
http = httplib2.Http()

# Авторизация
http.add_credentials(api_key, '')

# Заголовки запроса
headers = {'Content-type': 'application/json'}

# Выполняем запрос
response, content = http.request(url, 'GET', headers=headers)

# Обработка ответа
print(content)

Примеры ответов API

GET запрос по адресу https://api.alloka.ru/v1/payment/plans/pro_15k выдаст следующий ответ с кодом статуса HTTP “200 ОК”:

200 OK

Строка Тип Значение
name string pro_15k
title string Про 15k
price string $59.00
sessions number 15000
numbers number 7

GET запрос по адресу https://api.alloka.ru/v1/payment/plans/pro_1k выдаст следующий ответ с кодом статуса HTTP “404 Not Found”:

404 Not Found

Строка Значение
error not_found

Коды статуса HTTP

Успешность выполнения запроса к Alloka API определяется HTTP-кодом ответа.

Таблица 1. Основные коды статуса HTTP, используемые в Alloka API.

Код статуса HTTP Описания значения в Alloka API
200 OK

Неправильные входные данные.

Причины:

— Некорректный JSON.

— Неправильные или отсутствующие параметры запроса.

Рекомендации:

— Проверьте валидность вашего JSON — http://jsonlint.com.

— Внимательно проверьте соответствие вашего запроса данной документации.

401 Unauthorized

Неавторизованный доступ.

Причины:

— Отсутствует API-ключ.

— Передан неправильный или пустой API-ключ.

Рекомендации:

— Удостоверьтесь, что вы правильно передаёте API-ключ авторизации (см. выше).

— Проверьте, что вы используете актуальный API-ключ в вашем профиле в личном кабинете Аллока Аналитика.

403 Forbidden

Доступ к запрашиваемому ресурсу запрещён.

Причины:

— Запросы к разделам API, предназначенных для агентств при авторизации от обычного пользователя.

Рекомендации:

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

— В случае, если вы исполняете запросы от обычного пользователя, разделы для агентств не будут вам доступны.

404 Not Found

Запрашиваемый ресурс не найден.

Причины:

— Неправильный URL запроса.

— Ресурс с запрашиваемым ID не найден.

Рекомендации:

— Проверьте, что URL запроса соответствует тому, что приведён в данной документации.

— Возможно, запрашиваемый ресурс удалён или принадлежит другом пользователю. Выполните запрос списка ресурсов, посмотрите есть ли требуемый ресурс в ответе.

500 Internal Server Error

502 Bad Gateway

503 Service Unavailable

504 Gateway Timeout

Внутренняя ошибка.

Причины:

Внутренний сбой работы системы.

Рекомендация:

При возникновение получении таких кодов статуса — напишите нам на support@alloka.ru, указав в письме детали запроса к API (точное время, URL, параметры запроса).

В случае, если вы уверены, что ваш запрос корректен, но вам выдаётся ошибка, напишите нам на support@alloka.ru, указав в письме детали запроса к API (точное время, URL, параметры запроса).

Основные коды ошибок

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

Таблица 2. Основные коды ошибки запросов, используемые в Alloka API.

Код ошибки Описание
invalid_json

Неправильный JSON.

Причины:

— Ошибка парсинга JSON, переданного в теле запроса.

Рекомендации:

— Проверьте валидность вашего JSON — http://jsonlint.com

invalid_request

Неправильный URL запроса.

Причины:

— Запрашиваемый запрос в Alloka API не существует.

Рекомендации:

— Проверьте, что URL запроса соответствует тому, что приведён в данной документации.

unauthorized

Неавторизованный доступ.

Причины:

— Отсутствует API-ключ.

— Передан неправильный или пустой API-ключ.

Рекомендации:

— Удостоверьтесь, что вы правильно передаёте API-ключ авторизации (см. выше).

— Проверьте, что вы используете актуальный API-ключ в вашем профиле в личном кабинете Аллока Аналитика.

access_denied

Доступ к запрашиваемому ресурсу запрещён.

Причины:

— Запросы к разделам API, предназначенных для агентств при авторизации от обычного пользователя.

Рекомендации:

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

— В случае, если вы исполняете запросы от обычного пользователя, разделы для агентств не будут вам доступны.

not_found

Не найдено.

Причины:

— Запрашиваемый ресурс не найден

Рекомендации:

— Возможно, запрашиваемый ресурс удалён или принадлежит другом пользователю. Выполните запрос списка ресурсов, посмотрите есть ли требуемый ресурс в ответе.

unknown_error

Внутренняя ошибка.

Причины:

Внутренний сбой работы системы.

Рекомендация:

При возникновение получении таких кодов статуса — напишите нам на support@alloka.ru, указав в письме детали запроса к API (точное время, URL, параметры запроса).

В случае, если вы уверены, что ваш запрос корректен, но вам выдаётся ошибка, напишите нам на support@alloka.ru, указав в письме детали запроса к API (точное время, URL, параметры запроса).

Кроме того, каждый запрос может обладать своими кодами ошибок, о чём указано в описании запросов к Alloka API.

Пагинация — разбиение списка ресурсов по страницам

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

limit — ограничение на количество ресурсов в ответе. По умолчанию limit равен 20. Может принимать целочисленное значение от 1 до 100 включительно.

offset — смещение на указанное количество ресурсов от начала. Допустим, вы указали limit = 5. Чтобы отобразить первые 5 элементов, offset должен быть равен 0. Если вы желаете отобразить вторые 5 элементов, offset должен быть равен 5. Чтобы отобразить третьи 5 элементов, offset должен быть равен 10. И так далее. По умолчанию offset равен 0. Может принимать любое положительное целочисленное значение.

Также каждый ответ на запрос списка ресурсов содержит два поля, помогающие узнать суммарное количество элементов по запросу, общее количество страниц, а также количество элементов в данном ответе:

count — количество элементов в данном ответе.

total — общее количество элементов, соответствующее запросу.

Методы HTTP в Alloka API

Alloka API использует 4 HTTP метода в различных случаях:

GET — для получения каких-либо данных. Это может быть список ресурсов, единичный ресурс и т.п.

POST — для создания нового ресурса, переключения состояния ресурса или вызова специфичных запросов.

PUT — обновление ресурса.

DELETE — удаление ресурса.

В подробном описание каждого запроса указан необходимый метод HTTP.

Версии Alloka API

Используемая версия API должна содержаться в URL каждого запроса сразу после домена:

https://api.alloka.ru/v1/

Текущая наиболее актуальная версия - v1. В будущем, при наличии серьёзных изменений в работе, будут создаваться новые версии. Тем не менее, текущая версия также будет функционировать. Поэтому вы можете не беспокоиться за то, что ваша интеграция с Аллока Аналитика внезапно перестанет работать из-за изменений в API.

Alloka API для агентств

Агентский интерфейс Аллока Аналитика позволяет создавать расширенные аккаунты в системе, наделённые возможностью создавать других пользователей — клиентов агентства.

Функционал агентского интерфейса в системе Аллока Аналитика представлен разделами Alloka API “Agency” и “Clients”. Данные разделы предоставляют возможности получения информации по агентству и его клиентам, а также управления аккаунтами клиентов агентства.

Агентский аккаунт не имеет возможности создавать свои объекты и управлять ими. Все запросы напрямую к разделам Alloka API “Objects”, “Payment” и “Calls” будут возращать код статуса HTTP 403 Forbidden.

Для того, чтобы обращаться к разделам API “Objects”, “Payment” и “Calls” от клиента агентства — необходимо в URL каждого запроса добавить префикс /clients/<ID_КЛИЕНТА> сразу после указания версии Alloka API.

Например URL запроса на список объектов клиента с ID 9999 будет иметь вид:

https://api.alloka.ru/v1/clients/9999/objects