ActivePlatform. Руководство по использованию API

Основные изменения в версии 4.5

Новые методы API v3 для работы с файлами Реселлера с открытым доступом (см. Документы Реселлера с открытым доступом)
Расширенная информация о Тарифных планах Реселлера (см. Получение списка Тарифных планов Реселлера, Получение информации о Тарифном плане Реселлера)

Введение

Программные интерфейсы ActivePlatform (API) базируются на архитектуре REST протокола HTTP 1.1 [RFC2616] и предоставляют доступ к ресурсам по путям URI. Каждый запрос работает через протокол передачи гипертекста (HTTP) и позволяет легко взаимодействовать с любым языком программирования.

Аудитория

Документ предназначен для инженеров-разработчиков, которые хотят интегрировать ActivePlatform с внешними сервисами (интернет-магазинами, сервисами предоставления услуг и другими внешними системами).
Читатель должен быть знаком с основными понятиями ActivePlatform, такими как Подписка, Тарифный план и т.д.

Условные обозначения

Форматирование

Условие

Пример

Bold

Для обозначения названий разделов, подразделов и блоков, названий методов, кнопок, пунктов меню и т.д.

Для создания аккаунта необходимо использовать метод Create an Account.

Italic

Для выделения терминов

Доступ к текущему Реселлеру, относительно которого формируется список нижестоящих Реселлеров, определяется по токену Сотрудника, указанному в заголовке запроса.

Courier

Для описания методов и конфигураций

Для создания аккаунта необходимо использовать следующий метод

POST/api/vendor/v1/accounts.json

Версионность

Данное руководство содержит описание методов для следующих версий API:

API v1 — в пути методов указывается /v1/
API v2 — в пути методов указывается /v2/
API v3 — в пути методов указывается /v3/

Основные понятия

REST API позволяет использовать такие стандартные методы HTTP запросов как: GET, PUT, POST и DELETE. Формат тела сообщения запроса и ответа - JavaScript Object Notation (JSON). Для тела ответа используется кодировка UTF-8.

API Token аутентификации

Некоторые вызовы REST API, которые обычно требуют учетных данных администратора, могут быть также аутентифицированы с использованием API token. REST API Token привязан к конкретному пользователю (сотруднику Оператора) и может быть получен в Панели Управления Оператора на странице Сотрудника (см. Добавление сотрудника в ActivePlatform. Панель управления Оператора).

API v1 поддерживает аутентификацию по токену с использованием query-параметра в конце URL, например, ?api_token={api_token}, где api_token — полученный API Token.

API v3 поддерживает аутентификацию по токену с использованием заголовка X-Api-Token Header.

Коды состояния HTTP

Ответ может содержать один из следующих HTTP-кодов состояния совместно с телом ответа. Дополнительное текстовое описание статус-кода не следует использовать, так как для ответов используются стандартные описания статус-кодов.
См. Hypertext Transfer Protocol — HTTP/1.1, Status Code Definitions стандарт для получения полного списка кодов состояния и их значения.

Типы параметров

Возможные типы передаваемых параметров в API запросе:

Path — параметр используется как часть запроса URL. Для выделения данного типа параметров в URL запросе используются фигурные скобки {}. Например, /items/{itemId}, где path — параметр itemId.
Query — параметр добавляется в конце URL, например, /items?id=###, где query — параметр id.
Form — параметр используется для описания полезных данных в HTTP запросе при использовании application/x-www-form-urlencoded и/или multipart/form-data в содержимом запроса (подробнее http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4).

Выбор языка

По умолчанию сообщения об ошибках API v3 возвращаются на английском языке, что эквивалентно использованию значение заголовка X-Api-Locale: en. Некоторые методы API v3 поддерживают как английский, так и русский язык в сообщениях об ошибках. Для выбора русского языка необходимо указать значение заголовка X-Api-Locale: ru.