Перейти к содержимому
AISARAISAR

OpenAPI и Postman

Спецификация OpenAPI 3.1 и коллекция Postman для AISAR API: где скачать, как импортировать, куда положить токен и как читать расширения x-aisar-*.

Кроме страниц справочника AISAR публикует то же описание API в машиночитаемом виде: спецификацию OpenAPI 3.1 и коллекцию Postman. Оба файла собираются из справочника REST и каталога событий вебхуков при каждой публикации документации, поэтому описывают ровно те эндпоинты и события, что есть на сайте. Их удобно импортировать в Postman или Insomnia, отдать генератору SDK или подключить к внутренним инструментам команды.

Файлы и адреса

ФайлАдрес
OpenAPI 3.1, описания на английскомhttps://docs.aisar.app/openapi.json
OpenAPI 3.1, описания на русскомhttps://docs.aisar.app/openapi.ru.json
Коллекция Postman, английскийhttps://docs.aisar.app/postman/aisar.postman_collection.json
Коллекция Postman, русскийhttps://docs.aisar.app/postman/aisar.ru.postman_collection.json
Окружение Postmanhttps://docs.aisar.app/postman/aisar.postman_environment.json

Русская и английская версии отличаются только текстами: пути, operationId, теги и схемы у них общие. В спецификации есть раздел webhooks с телом каждого события и заголовками доставки, в коллекции Postman по папке на каждую группу эндпоинтов.

Импорт в Postman

  1. В Postman откройте File → Import, перейдите на вкладку ссылки и вставьте адрес коллекции, например https://docs.aisar.app/postman/aisar.ru.postman_collection.json.
  2. Тем же способом импортируйте окружение https://docs.aisar.app/postman/aisar.postman_environment.json и выберите его в правом верхнем углу.
  3. В окружении впишите токен в переменную apiToken и сохраните. Запросы коллекции уже подставляют Authorization: Bearer {{apiToken}} и адрес {{baseUrl}}.

Спецификацию OpenAPI в Postman можно импортировать так же, по ссылке на openapi.json или openapi.ru.json: Postman сам построит из неё коллекцию. Готовая коллекция AISAR удобнее тем, что в ней уже есть примеры ответов и переменные.

Переменные и токен

ПеременнаяГде объявленаЗначение
baseUrlколлекция и окружениеhttps://api.aisar.app; пути запросов начинаются с /v1
apiTokenтолько окружение, тип secretваш API-токен целиком, в формате {id}|{plaintext}
Токен храните только в окружении, в переменной apiToken. В коллекции такой переменной нет намеренно: коллекцию часто экспортируют и пересылают коллегам, и токен не должен уехать вместе с ней. Не вписывайте токен во вкладку Authorization отдельных запросов и не делитесь окружением с заполненным apiToken.

Токен создаётся в кабинете в разделе Настройки → Системы → API или запросом POST /v1/api-tokens, см. группу API-токены. Он показывается один раз. Что даёт токен и как его отозвать, описано в разделе «Аутентификация».

Расширения x-aisar-*

То, чего нет в стандартных полях OpenAPI, вынесено в расширения с префиксом x-aisar-. Генераторы SDK их пропускают, а читать их полезно, когда вы разбираетесь, почему запрос вернул 403.

РасширениеЧто значит
x-aisar-token-full: trueОперация требует токен с полным доступом; токен только для чтения получит 403.
x-aisar-featureФункция тарифа, без которой операция недоступна, например api.
x-aisar-subscription-required: trueНужна активная подписка компании.
x-aisar-business-only: trueОперация есть только у бизнес-компаний.
x-aisar-permissionПраво, которое проверяется у пользователя токена, например conversation.view. Указано не у всех операций.
x-aisar-signed-url: trueАдрес подписан сервером и открывается без токена; такие ссылки приходят внутри других ответов, самим их собирать не нужно.
x-aisar-source-commitКоммит документации, из которого собран файл. По нему видно, обновился ли файл с прошлого импорта.

Схемы, выведенные из примеров

Схема ответа с пометкой x-aisar-schema-origin: example построена по примеру из справочника, а не по описанию валидации на сервере. Типы полей в ней верные, но схема намеренно разрешающая: поля не помечены обязательными, допускаются дополнительные свойства (additionalProperties: true), а поле, которое в примере равно null, может иметь и другое значение. Генерируя клиент по такой схеме, не делайте его строгим к лишним полям: ответы со временем дополняются.

Совместимость

В пределах /v1 ответы и тела событий вебхуков только расширяются: новые поля добавляются, существующие ключи не удаляются и не переименовываются. Поэтому парсер, который пропускает незнакомые поля, переживает обновления спецификации без правок. Версия в info.version остаётся 1.0, пока действует это правило.

Почему нет кнопки «попробовать»

На сайте документации нет консоли, которая отправляет запросы прямо со страницы. Токен AISAR даёт доступ ко всей рабочей области компании, и вводить его в форму на чужом для вашей системы сайте незачем. Запросы удобнее и безопаснее выполнять из Postman или из своего кода, где токен лежит в окружении.

Вебхуки в спецификации

Раздел webhooks описывает тело каждого события и заголовки X-AISAR-Event, X-AISAR-Delivery-Id, X-AISAR-Signature. Как проверить подпись доставки и как работают повторы, описано в разделе «Вебхуки».