Общая информация

В этой статье:

Введение

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

Аудитория

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

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

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

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

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

Авторизация и аутентификация

Для авторизации требуется API-токен менеджера (сотрудника). API-токен можно получить через Панель управления Оператора (см. Просмотр и обновление информации о сотруднике).

По указанному в запросе API-токену определяются:

• Роль и уровень доступа менеджера, от которых зависит доступность метода.
• Текущий реселлер и его нижестоящие реселлеры, доступные в рамках метода.

API-токен менеджера должен быть указан в заголовке X-Api-Token.

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

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

• Path — параметр используется как часть URL. Например, /items/{item_id}, где {item_id} — значение path-параметра.
• Query — параметр добавляется в конце URL через ?, например, /items?id={item_id}, где id — ключ query-параметра, {item_id} — значение query-параметра. Несколько query-параметров указываются через &, например: /items?page[size]={page_size}&page[number]={page_number}.
• Form — параметр используется в JSON-теле запроса для добавления или обновления данных с помощью методов PUT, POST и PATCH.
• Header — параметр используется как заголовок запроса. Например, в API v3 API-токен должен быть указан в header-параметре (заголовке) X-Api-Token.

Выбор языка

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

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

Ответ может содержать один из HTTP-кодов состояния совместно с телом ответа. Код ответа показывает, был ли успешно выполнен запрос. Подробнее см. Список кодов.

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

В случае ошибки выполнения запроса метод возвращает ответ с кодом статуса ошибки и текстом сообщения об ошибке. Некоторые методы API v3 поддерживают единую модель ответа для случаев, когда выполнение запроса завершилось ошибкой.