Взаимодействие с API

подсказка

По этой ссылке доступна коллекция API Altcraft для Postman.

Формат запросов

Данные в запросах передаются методом POST по протоколу HTTP/1.1. Метод запроса также указан на странице с описанием каждого запроса. Параметры запроса помещаются в передаваемую структуру. Часть параметров может быть передана в URL (API key, format).

Формат входных данных указывается в HTTP-заголовке Content-Type.

Возможные значения заголовка:

• application/json — формат JSON
• application/xml — формат XML

Кодировка символов — UTF-8

POST https://example.com/api/v1.1/<имя метода>

Если вы работаете в облачном аккаунте Altcraft Platform, используйте URL-адрес панели управления: ru.altkraft.com. При установке платформы на ваше оборудование (on-Premise) — используйте ваш собственный URL.

Описание формата JSON вы найдёте в RFC 8259: https://www.rfc-editor.org/rfc/rfc8259.

Не забывайте кодировать символы, которые не могут быть непосредственно записаны в JSON.

Авторизация

Для авторизации при отправке запроса вам необходимо передать в платформу токен. Для этого существует несколько способов, например, указать его в теле запроса:

{
  "token": "bfc505684d774e52b188fa1f003cd5ed",
  "db_id": 1,
  "resource_id": 1,
  "matching": "email",
  "email": "example@example.com",
  "data": {
    "_status": 0,
    "_fname": "Jim",
    "_lname": "Jones",
    "email": "example@example.com",
    "phones": ["+79000000000"]
  }
}

Также вы можете передать токен в одном из заголовков запроса. Для этого создайте заголовок с ключом Authorization, а в его значении укажите Bearer <token>, где вместо <token> вставьте ваш токен.

Токен может быть создан в панели пользователя платформы, раздел "Настройки" — "Токены". Для создания токена необходимы права мастер-пользователя:

Токен генерируется автоматически после сохранения. Также в данном интерфейсе можно задать имя токена, и настроить права доступа (уточняются в роли) пользователей к данному токену, и группу, в рамках которой токену доступны объекты.

предупреждение

Мы не рекомендуем передавать токен в URL вашего запроса. Этот метод небезопасен и в будущем не будет поддерживаться платформой.

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

Формат ответа может быть передан в заголовке или в параметрах запроса.

Пример ответа (успешное выполнение операции):

{
  "error": 0,
  "error_text": "Successful operation",
  "profile_id": "5f4fa1a5ce9448665fef548e"
}

В ответе возвращаются следующие параметры:

• error — код ошибки
• error_text — описание ошибки
• profile_id — идентификатор профиля, к которому был применены действия согласно запросу. Получается при успешном выполнении операции.

к сведению

Код 200 — это код успеха на HTTP транспорте. Однако, если внутри HTTP-транспорта есть информация об ошибке, то дополнительные детали об ошибке предоставляются в JSON-объекте в поле error с пояснениями в error_text.

Коды ответа

Код	Описание
0	Операция выполнена успешно
400	Некорректный запрос
401	Требуется API токен
402	Достигнуто ограничение тарифа
403	Нет прав на действие
404	Объект не найден в зоне видимости токена
409	Существует другая запись с такими же признаками уникальности
413	База данных недоступна в выбранном ресурсе
415	Запрашиваемый Content-Type не поддерживается
429	Превышено количество запросов, установленное в файле конфигурации (параметр API_MAX_REQUESTS_COUNT)
435	Неоднозначный поиск, есть несколько объектов с заданными характеристиками
441	Объект принадлежит другой группе
450	Ошибка валидации запроса
500	Внутренняя ошибка сервиса
501	Такой метод отсутствует

Атрибуты тегов XML

XML-запросы строятся на основе JSON-запросов, в связи с этим в некоторых ситуациях требуется вписывать дополнительные атрибуты внутри тегов:

• array='true' — атрибут, указывающий на то, что тег является массивом. Используется в случаях, когда внутри массива находится либо 1 элемент, либо элементов нет совсем.
• string='true' — атрибут используется для указания на то, что используемое значение является строкой (тип данных string). Необходим в случаях, когда в строке находится число или слово "true"/"false".
• json='true' — атрибут, необходимый в тех случаях, когда внутри xml-запроса мы должны передать json-запрос (например, параметры отбора при запросе на получение данных по нескольким профилям).

Дедупликация запросов

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