Авторизация приложения и запуск интеграции

Схема взаимодействия

Для предоставления возможности интеграции из интерфейса CRM-системы предусмотрен механизм серверной авторизации на базе протокола OAuth 2.0, позволяющий реализовать безопасную аутентификацию пользователей АТС через API виртуальной АТС и получить доступ к функциям АТС с сервера CRM-системы.

Процесс авторизации состоит из следующих шагов:

Открытие диалогового окна для аутентификации пользователя на API-сервере АТС.
Разрешение пользователем АТС доступа к своим данным.
Передача API-серверу АТС значения code для получения токена доступа с временем жизни.
Получение сервером CRM-системы токена доступа с временем жизни access_token для доступа к API АТС.
Создание постоянного доверенного приложения пользователю АТС.

Схематически данный процесс происходит следующим образом:

1 Схема взаимодействия
2 Аутентификация пользователя АТС на API-сервере АТС
3 Получение токена доступа
4 Создание постоянного доверенного приложения
5 Получение токена доступа доверенным приложением
6 Передача запросов с использованием токена доступа

Аутентификация пользователя АТС на API-сервере АТС

Провайдер IP-телефонии по запросу интегратора создает приложение уровня дилера/администратора типа public (получение токена доступа возможно после авторизации пользователя на сервере АТС и получения кода авторизации), указывает URI перенаправления и передает интегратору App ID (идентификатор приложения) и App Secret (пароль приложения) этого приложения.

Для авторизации пользователя АТС необходимо перенаправить его во всплывающем окне в CRM-системе (или на отдельной страничке) на URI авторизации https://<hostname>/oauth/authorize, где hostname — hostname API-сервера провайдера IP-телефонии, передавая данные авторизации в качестве параметров GET-запроса в формате URL-encoded:

Параметр	Описание
response_type	Тип ответа, всегда должен иметь значение code
redirect_uri	URI, по которому API-сервер АТС будет посылать ответ. Должен совпадать с указанным при создании приложения типа public
client_id	App ID, сгенерированный при создании приложения типа public
scope	Сфера разрешений для приложения типа public, должен иметь значение all

Пример:
App ID a80f1e618ddd4d4584e2bd48fd404194
App Secret a2423941f5be408c998d5f7207570990
В качестве redirect_url использован https://your_site.com

Пользователь АТС нажимает в появившемся всплывающем окне на ссылку: https://<hostname>/oauth/authorize?response_type=code&client_id=a80f1e618ddd4d4584e2bd48fd404194&redirect_uri=https%3A%2F%2Fyour_site.com&scope=all

После нажатия на данную ссылку должно появиться всплывающее окно с запросом подтверждения доступа к данным пользователя АТС. Пользователь нажимает "Разрешить".

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

Передача API-сервером АТС значения code для получения токена доступа с временем жизни

Если пользователь АТС разрешает доступ, API-сервер АТС перенаправляет его на redirect_uri приложения (your_site.com), передавая в качестве параметра запроса значение code (код для получения токена доступа) в виде https://your_site.com/cont/url?code=aIlsm1bCglDGvQKShmJAhHrBhDyshn .

Получение данного значения code (aIlsm1bCglDGvQKShmJAhHrBhDyshn) означает, что разрешен доступ к АТС и теперь возможно получить токен доступа с временем жизни и обновлять его.

Получение сервером CRM-системы токена доступа с временем жизни access_token для доступа к API АТС

Для получения токена доступа необходимо сделать POST-запрос с сервера CRM-системы на адрес https://<hostname>/oauth/token, используя полученный код. Параметры передаются в теле запроса в формате application/x-www-form-urlencoded:

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

Параметр	Описание
grant_type	Всегда должен иметь значение authorization_code
code	Параметр code, полученный приложением типа public на предыдущем шаге
redirect_uri	URI перенаправления. Должен совпадать с одним из указанных при создании приложения типа public
client_id	App ID, сгенерированный при создании приложения типа public
client_secret	App Secret, сгенерированный при создании приложения типа public

Пример:

{
  "grant_type": "authorization_code",
  "code": "aIlsm1bCglDGvQKShmJAhHrBhDyshn",
  "client_id": "a80f1e618ddd4d4584e2bd48fd404194",
  "client_secret": "a2423941f5be408c998d5f7207570990",
  "redirect_uri": "https://your_site.com"
}

API-сервер АТС отвечает приложению типа public. Параметры ответа:

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

Параметр	Описание
access_token	Токен доступа. Используется приложением типа public для API-запросов
expires_in	Период времени в секундах, в течение которого токен действителен. Если в процессе использования токена возникла ошибка авторизации, рекомендуется запросить токен заново, даже если заявленное в поле expires_in время до истечения токена еще не прошло
token_type	Тип токена. Всегда имеет значение Bearer
refresh_token	Refresh token, который может быть использован для регенерации токена доступа, когда он стал недействителен

В ответ на этот запрос сервер CRM-системы получит токен доступа, с которым можно создать на API-сервере АТС постоянное доверенное приложение типа trusted. Это приложение нужно, чтобы не приходилось повторно запрашивать доступ к аккаунту пользователя АТС, как это было описано выше. Приложение типа trusted получает токен доступа без авторизации пользователя на сервере АТС.

Создание постоянного доверенного приложения

Постоянное доверенное приложение типа trusted создается следующим образом. Например, ранее был получен токен доступа pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes . Необходимо отправить запрос POST на адрес https://<hostname>/api/ver1.0/application/ c заголовками:
'Content-type': 'application/json',
'Authorization': 'Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes'
и телом запроса в формате JSON:

{
  "name" : 'App_name',
  "type": "trusted"
}

Получение токена доступа доверенным приложением

Для получения токена приложение должно сделать POST-запрос на URL https://<hostname>/oauth/token. Параметры передаются в теле запроса в формате application/x-www-form-urlencoded:

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

Параметр	Описание
grant_type	Всегда должен иметь значение client_credentials
client_id	App ID, сгенерированный при создании приложения типа public
client_secret	App Secret, сгенерированный при создании приложения типа public

API-сервер АТС отвечает приложению. Параметры ответа:

Параметр	Описание
access_token	Токен доступа. Используется приложением для API-запросов
expires_in	Период времени в секундах, в течение которого токен действителен
token_type	Тип токена всегда имеет значение Bearer

Передача запросов с использованием токена доступа

Полученный токен доступа необходимо передавать в заголовке Authorization в формате "Bearer <access_token>" в каждом запроса к API. Пример заголовка:
Authorization: Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes

Запросы к API будут выполняться от имени и с разрешениями пользователя АТС, предоставившего доступ приложению. Если в процессе использования токена возникла ошибка авторизации, рекомендуется запросить токен заново, даже если заявленное в поле expires_in время до истечения токена еще не прошло.

Пример запроса на получение информации об авторизованном пользователе АТС:

Ответ системы:

{
  "admin": false,
  "client_id": 12,
  "dealer_id": null,
  "extension_group_id": null,
  "extension_id": null,
  "id": 20,
  "login": "client1"
}

← Интеграция с CRM-системой События на внутренних номерах →