Общее описание

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

Аудитория

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

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

Методы

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

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

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

• Header — параметр используется как заголовок запроса. Например, для авторизации, указания формата запроса и ответа, а также для выбора языка ответа.

• 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.

Типы данных

Запросы и ответы всех методов поддерживают только один тип данных. При вызове любого метода указывайте значение application/vnd.api+json в следующих двух заголовках:

• Content-Type — тип данных, передаваемых в запросе.

• Accept — формат ответа.

Авторизация

Для вызова большинства методов требуется авторизация. Для авторизации укажите в заголовке Authorization действующий access token пользователя. Формат: Bearer <access token>.

Платформа создает access token для пользователя при входе (аутентификации с использованием email и пароля) и ограничивает срок его действия. Refresh token, который также выдается пользователю при входе, используется для получения нового access token после истечения его срока действия. Срок действия access token устанавливается на выбор 1 день или 1 месяц при входе пользователя.

Для выполнения действий в рамках аккаунта у текущего пользователя должен быть к нему доступ, то есть:

1. Текущий пользователь присоединен к аккаунту.

2. Статус текущего пользователя в этом аккаунте Активный.

3. Уровень доступа пользователя позволяет выполнять запрошенное действие (см. ).

Выбор языка

Чтобы выбрать язык, на котором метод должен вернуть ответ, укажите его двухбуквенный код в заголовке X-Api-Locale. Если значение не указано, используется английский язык (en).

Пагинация

Для большинства методов, которые возвращают список сущностей, используется пагинация — автоматическое деление ответа на страницы. По умолчанию каждая страница содержит до 50 элементов списка, а метод возвращает первую страницу. Метод также возвращает в ответе объект links — ссылки для постраничной навигации:

• self — текущая страница списка.

• first — первая страница списка.

• prev — предыдущая страница списка (при наличии).

• next — следующая страница списка (при наличии).

• last — последняя страница списка.

Пример:

"links": {
        "self": "https://{reseller_domain}/internal_api/accounts/{account_id}/subscriptions?page%5Bnumber%5D=1&page%5Bsize%5D=50",
        "first": "https://{reseller_domain}/internal_api/accounts/{account_id}/subscriptions?page%5Bnumber%5D=1&page%5Bsize%5D=50",
        "prev": null,
        "next": "https://{reseller_domain}/internal_api/accounts/{account_id}/subscriptions?page%5Bnumber%5D=2&page%5Bsize%5D=50",
        "last": "https://{reseller_domain}/internal_api/accounts/{account_id}/subscriptions?page%5Bnumber%5D=5&page%5Bsize%5D=50"
    }

Чтобы запросить определенную страницу, используйте следующие query-параметры:

• page[size] — количество элементов на странице.

• page[number] — порядковый номер страницы.

Пример: 

GET {reseller_domain}/internal_api/accounts/{account_id}/subscriptions?page[size]=2&page[number]=10

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

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

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

В случае ошибки запроса метод возвращает ответ с текстом сообщения об ошибке. Код ответа не включается в тело ответа. Если произошло несколько ошибок с разными кодами, метод возвращает информацию только о первой из них в следующем порядке:

1. 401.

2. 403.

3. 422.

Структура ответа в случае ошибки

Пример ответа в случае ошибки

{
    "errors": [
        {
            "source": {
                "pointer": "/data/attributes/email"
            },
            "detail": "Вы должны подтвердить вашу электронную почту.",
            "status": "email_not_confirmed"
        }
    ]
}

Типичные ошибки

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