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

Система — используемое в вашей организации программное бизнес-приложение, с которым необходимо произвести интеграцию.

АТС — это виртуальная телефонная станция «Телфин.Офис», размещенная на хостинге и предоставляемая как облачный сервис (услуга).

Интегратор — программист или системный администратор вашей организации, реализующий интеграцию используемой системы и АТС «Телфин.Офис».

Пользователь — пользователь АТС.

API (application programming interface) — программный интерфейс приложения, с помощью которого пользователь системы может осуществлять запросы к серверу виртуальной АТС с целью осуществления определённых действий или получения требуемых данных.

Суперприложение — приложение уровня дилера/администратора типа public(получение токена доступа возможно после авторизации пользователя на сервере АТС и получения кода авторизации), создаваемое Телфин для интегратора.

App ID — идентификатор суперприложения, сгенерированный при его создании.

App Secret — пароль суперприложения, сгенерированный при его создании.

Приложение — клиентское приложение типа trusted (получение токена доступа возможно без авторизации пользователя), создаваемое интегратором для данной интеграции.

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

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

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

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

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

Телфин по запросу интегратора создает суперприложение типа public, указывает URI перенаправления и передает интегратору App ID и App Secret этого приложения.

Для авторизации пользователя необходимо перенаправить его во всплывающем окне в системе (или на отдельной страничке) на URI авторизации https://apiproxy.telphin.ru/oauth/authorize, передавая данные авторизации в качестве параметров GET-запроса в формате URL-encoded:

Пример:

App ID a80f1e618ddd4d4584e2bd48fd404194

App Secret a2423941f5be408c998d5f7207570990

В качестве redirect_url использован https://your_site.com

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

Разрешение пользователем доступа к своим данным

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

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

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

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

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

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

Пример:

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

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

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

Постоянное приложение создается следующим образом.

Например, ранее был получен токен доступа pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes . Необходимо отправить запрос POST c заголовками

{
"Content-type": "application/json",
"Authorization": "Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes")
}

и телом запроса в формате json

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

на https://apiproxy.telphin.ru/api/ver1.0/application.

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

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

Запросы к API с токеном доступа

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

Authorization: Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes

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

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

curl -H "Authorization: Bearer pyt4ZUcLWc2FP3t10OJUN2N4Xh2qes" https://apiproxy.telphin.ru/api/ver1.0/user/
{
"admin": false,
"client_id": 12,
"dealer_id": null,
"extension_group_id": null,
"extension_id": null,
"id": 20,
"login": "client1"
}