IVA ДОКУМЕНТАЦИЯ
ОБНОВЛЕНИЯ

API-документация

Для документирования API используется Swagger.

Swagger-описание — это файл формата YAML или JSON, содержащий API-спецификацию.

Для доступа к Swagger необходимо перейти по адресу:

  • для формирования json-файла: https://<IP_address>/api/v1/swagger.json

  • для формирования yaml-файла: https://<IP_address>/api/v1/swagger.yaml

где <IP_address> — IP-адрес сервера телефонии IVA CS

Требования для работы с API

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

Взаимодействие с API IVA CS будет рассмотрено на примере работы с коллекцией запросов в Postman

Процесс работы с Postman

С помощью Postman можно протестировать корректность работы серверной части IVA CS.

Возможности Postman

  • сохранять запросы в папки и коллекции

  • изменять параметры запросов

  • изменять окружения: dev, test, production

  • выполнять автотесты

  • импортировать и экспортировать коллекции запросов и наборы тестов, чтобы обмениваться данными

Преимущества Postman

  • поддержка различных API: REST, SOAP, GraphQL

  • возможность легкой интеграции в CI/CD с помощью Newman

  • запуск на любых ОС

  • поддержка ручного и автоматизированного тестирования

Создание коллекции запросов

Для работы с запросами в секции Collections необходимо создать коллекцию, в которой они будут храниться.

В коллекцию необходимо импортировать yaml-файл, полученный с сервера IVA CS:

  1. открыть Collections → нажать кнопку Import

    Импорт API

  2. вставить ссылку на yaml-файл в строку Paste cURL, Raw text or URL...

    Ссылка на API

  3. дождаться окончания подготовки данных для импорта

    Подготовка данных

  4. в окне Choose how to import your Specification выбрать Postman Collection и нажать кнопку Import

    Импорт данных

В Collections будет создана новая коллекция с названием Some title here (название по умолчанию).

Для изменения названия: Нажать на название коллекции → Нажать Ctrl+E → Ввести новое название коллекции → Нажать Enter

Для отображения всей документации API в рабочей области необходимо нажать View complete documentation
Новая коллекция

Работа с запросами

При работе с API можно использовать cURL — командную строку для HTTP-запросов

Настройка постоянных переменных

Для удобства работы с API рекомендуется настроить постоянные переменные, которые будут использоваться для авторизации при совершении запросов.

Для создания окружения в секции Environments необходимо:

  1. открыть секцию Environments и выбрать Globals

    Окружение

  2. добавить переменные окружения:

    • создать переменную в столбце Variable

    • задать значение переменной в столбце Value

      Variable Value

      url

      https://<IP_address>

      где <IP_address> — IP-адрес сервера телефонии IVA CS

      login

      логин для входа (например, admin@example.ru)

      password

      пароль для входа (например, admin)

      bearerToken

      указать токен доступа
      Значение bearerToken

Получение токена доступа bearerToken

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

  1. нажать кнопку New → нажать HTTP. В рабочей области будет создан новый запрос Untitled Request

    Новый запрос

  2. в окне запроса:

    Новое окно запроса

    • выбрать метод запроса: POST

    • в строке запроса Enter URL or paste text ввести URL-запроса: {{url}}/auth/login

    • открыть вкладку Body, нажать raw, выбрать JSON и в теле запроса указать следующие данные:

      {
    "email": "{{login}}",
    "password": "{{password}}"
}

      где:

      • url — переменная url

      • login — переменная login

      • password — переменная password

        В качестве переменных используются названия переменных, указанные в столбце Variable

        Пример запроса:

        Пример запроса

  3. нажать кнопку Send

Если запрос был завершен успешно, то в области ответа отобразится статус 200 OK, а на вкладке Body — тело ответа в формате JSON.

Пример вывода:

Тело запроса

Для получения значения токена bearerToken необходимо скопировать значение поля "access" без символов " и вставить его в столбец Value в качестве значения переменной окружения bearerToken.

Переменную окружения bearerToken необходимо указывать во вкладке Authorization при совершении запросов:

Authorization → В выпадающем списке Auth Type выбрать Bearer Token → В поле Token вставить {{bearerToken}}

Авторизация с токеном

Выполнение запроса

Для выполнения запроса необходимо:

  1. перейти в Collections → открыть созданную коллекцию

    Созданная коллекция

  2. выбрать необходимый тип запроса и метод запроса

    Выбранный запрос

  3. в окне запроса:

    • выбрать метод запроса (по умолчанию устанавливается при выборе типа запроса)

    • в строке запроса ввести URL-запроса: {{url}}{{baseUrl}}/<NAME_REQUEST>, где <NAME_REQUEST> — название типа запроса

      Строка запроса

    • открыть вкладку Authorization и убедиться, что в качестве типа авторизации установлен Bearer Token

      Выбор токена запроса

  4. нажать кнопку Send

Если запрос был успешно завершен, то в теле запроса Body отобразится статус 200 OK.

Пример выполнения запроса из коллекции Subscriber для получения списка абонентов:

Пример выполнения запроса

Управление заданиями обратного вызова

Операция /api/v1/ServiceCallbackTask предназначена для запуска и остановки заданий сервиса Обратный вызов. Через REST API можно инициировать звонок из внешней системы, например CRM, ERP или адресной книги.

Последовательность дозвона определяется параметрами задания: сначала система звонит участнику, заданному через dest_number или dest_subscriber_id, затем — участнику, заданному через from_number или from_subscriber_id. Это позволяет сначала позвонить инициатору, затем вызываемому абоненту или наоборот.

Для каждого участника необходимо указать либо номер, либо ID абонента. По умолчанию хотя бы один участник должен быть задан через dest_subscriber_id или from_subscriber_id. Чтобы задать обоих участников по номерам, необходимо включить системную настройку allow_scb_task_number2number.

В задании API голосовое приветствие необязательно. При создании сервиса в веб-интерфейсе Файл приветствия и Файл приветствия обратного вызова обязательны.

Тело запроса содержит следующие параметры:

Параметр Описание

command

Команда управления заданием: run — запустить, stop — остановить

call_attempt_period

Период между попытками дозвона до первого участника, в секундах

call_attempt_timeout

Общее время выполнения попыток дозвона до первого участника, в секундах

callback_attempt_timeout

Время, в течение которого система пытается дозвониться до второго участника, в секундах

dest_number

Номер участника, которому система звонит первым

dest_subscriber_id

ID абонента, которому система звонит первым

from_number

Номер участника, которому система звонит вторым

from_subscriber_id

ID абонента, которому система звонит вторым

greeting_called_audio_id

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

id

UUID задания. Значение записывается в поле CDR callback_task_id