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

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

Популярные статьи

Введение

Программные интерфейсы 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/

Методы /api/vendor/v1/ и /api/vendor/v2/ устарели. Рекомендуется использовать соответствующие методы API v3 /api/v3/resellers/ (см. Реселлеры). Если в API v3 нет подходящего метода, рекомендуется использовать полностью совместимые методы /api/v1/reseller/ и /api/v2/reseller/.

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

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

Переменная {base_url} в описании методов — это URL ActivePlatform (например, https://test.activeplatform.com).

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-кодов состояния совместно с телом ответа. Код ответа показывает, был ли успешно выполнен запрос. Подробнее см. Список кодов.

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

Возможные типы передаваемых параметров в 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.

Ответы в случае ошибки

В случае ошибки выполнения запроса метод возвращает ответ с кодом статуса ошибки и текстом сообщения об ошибке.