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 |
| Окружение Postman | https://docs.aisar.app/postman/aisar.postman_environment.json |
Русская и английская версии отличаются только текстами: пути, operationId, теги и схемы у них общие. В спецификации есть раздел webhooks с телом каждого события и заголовками доставки, в коллекции Postman по папке на каждую группу эндпоинтов.
Импорт в Postman
- В Postman откройте File → Import, перейдите на вкладку ссылки и вставьте адрес коллекции, например
https://docs.aisar.app/postman/aisar.ru.postman_collection.json. - Тем же способом импортируйте окружение
https://docs.aisar.app/postman/aisar.postman_environment.jsonи выберите его в правом верхнем углу. - В окружении впишите токен в переменную
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. Как проверить подпись доставки и как работают повторы, описано в разделе «Вебхуки».