Авторизация при интеграции по API: различия между версиями

Материал из Касса
Перейти к навигации Перейти к поиску
Строка 1: Строка 1:
== Общие сведения ==
== Общие сведения ==
'''API''' (Application Programming Interface или интерфейс программирования приложений) — это совокупность инструментов и функций в виде интерфейса для создания новых приложений, благодаря которому одна программа будет взаимодействовать с другой.
'''API''' (Application Programming Interface или интерфейс программирования приложений) — совокупность инструментов и функций в виде интерфейса для создания новых приложений и интеграции с ИС. Все запросы к сервису '''БИФИТ Бизнес''' осуществляются при помощи авторотационного токена - '''access_token'''. Для генерации токена, необходимо пройти процедуру авторизации OAuth2. Для этого необходимо использовать логин/пароль зарегистрированной учетной записи.  
 
Для работы с API сервиса БИФИТ Касса, пользователю необходимо получить токен доступа. Генерация токена происходит по правилам авторизации OAuth2.




Информация получаемая по OAuth2:
Информация получаемая по OAuth2:


'''access_token''' — авторотационный ключ (обычно просто набор символов), предъявление которого является пропуском к защищенным ресурсам. Обращение к ним в самом простом случае происходит по HTTPS. Используется при работе по API
* '''access_token''' — авторотационный ключ (обычно просто набор символов), предъявление которого является пропуском к защищенным ресурсам. Обращение к ним в самом простом случае происходит по HTTPS. Используется при работе по API
 
* '''refresh_token''' — ключ, по которому можно получить access token с помощью HTTP-запроса, аналогично авторизации по логину и паролю
'''refresh_token''' — ключ, по которому можно получить access token с помощью HTTP-запроса, аналогично авторизации по логину и паролю
* '''expires_in''' - время работы (протухания) access_token в секундах. В сервисе БИФИТ Бизнес составляет 12 часов или 43 200 секунд - 1 секунда = 43 199 секунд.
 
'''expires_in''' - время работы (протухания) access_token в секундах. В сервисе БИФИТ Бизнес составляет 12 часов или 43 200 секунд - 1 секунда = 43 199 секунд.


{{Note|'''Внимание'''  
{{Note|'''Внимание'''  
Строка 18: Строка 14:


== Авторизацию в OAuth2 по паролю ==
== Авторизацию в OAuth2 по паролю ==
Подготовьте POST запрос следующего вида:
{{ProductTable-2
 
|title-left='''Запрос'''
URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token
|title-right='''POST'''
 
|content-left= URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token
 
|content-right=
body запроса должно передаваться как Content-Type: x-www-form-urlencoded и содержать следующие значений KEY/VALUE:
<syntaxhighlight>
https://kassa.bifit.com/cashdesk-api/v1/oauth/token
</syntaxhighlight>
|}}<br>


{{ProductTable-2
|title-left= Request Body
|title-right= type: '''x-www-form-urlencoded'''
|content-left=&nbsp;
* '''username''': логин учетной записи, передается в формате '''7xxxxxxxxxx'''
* '''password''': пароль, передается в виде зашифрованного хэш -> '''SHA-256 -> base64 urlencoded'''
* '''client_id''': передать значение ''"cashdesk-rest-client"''
* '''client_secret''': передать значение ''"cashdesk-rest-client"''
* '''grant_type''': передать значение ''"password"''
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
<syntaxhighlight lang="JSON">
"grant_type" : "password",
token: "P5cKbUUD9uSSrSlGdzspLblvBnD0GzTAE0cLmAPSEMxJ79DtLE"
"username" : номер телефона (вводится как 7xxxxxxxxxx),
client_id: "processing-connector-token"
"password" : пароль -> SHA-256 -> base64 urlencoded,
client_secret: "processing-connector-token"
"client_id" : "cashdesk-rest-client",
grant_type: "token"
"client_secret" : "cashdesk-rest-client"
</syntaxhighlight>
</syntaxhighlight>
|}}<br>


{{Note|'''Обратите внимание'''
{{Note|'''Обратите внимание'''

Версия 13:48, 21 апреля 2022

Общие сведения

API (Application Programming Interface или интерфейс программирования приложений) — совокупность инструментов и функций в виде интерфейса для создания новых приложений и интеграции с ИС. Все запросы к сервису БИФИТ Бизнес осуществляются при помощи авторотационного токена - access_token. Для генерации токена, необходимо пройти процедуру авторизации OAuth2. Для этого необходимо использовать логин/пароль зарегистрированной учетной записи.


Информация получаемая по OAuth2:

  • access_token — авторотационный ключ (обычно просто набор символов), предъявление которого является пропуском к защищенным ресурсам. Обращение к ним в самом простом случае происходит по HTTPS. Используется при работе по API
  • refresh_token — ключ, по которому можно получить access token с помощью HTTP-запроса, аналогично авторизации по логину и паролю
  • expires_in - время работы (протухания) access_token в секундах. В сервисе БИФИТ Бизнес составляет 12 часов или 43 200 секунд - 1 секунда = 43 199 секунд.

Note.svg Внимание Учетная запись от имени которой будут происходить работа по API должна иметь максимальное кол-во прав, для создания, редактирования или удаления документов и справочников БИФИТ Касса

Авторизацию в OAuth2 по паролю

Запрос POST
URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token 
https://kassa.bifit.com/cashdesk-api/v1/oauth/token


Request Body type: x-www-form-urlencoded
 
  • username: логин учетной записи, передается в формате 7xxxxxxxxxx
  • password: пароль, передается в виде зашифрованного хэш -> SHA-256 -> base64 urlencoded
  • client_id: передать значение "cashdesk-rest-client"
  • client_secret: передать значение "cashdesk-rest-client"
  • grant_type: передать значение "password"
   
token: "P5cKbUUD9uSSrSlGdzspLblvBnD0GzTAE0cLmAPSEMxJ79DtLE"
client_id: "processing-connector-token"
client_secret: "processing-connector-token"
grant_type: "token"


Note.svg Обратите внимание Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма SHA256 и затем закодировать полученные данные по стандарту Вase64 urlencoded.

Сервер вернет ошибку 200 OK. Response запроса будет содержать следующие данные 

  "access_token": <Токен доступа>,
  "expires_in": 43199,
  "refresh_token": <Рефреш токен>,
  "scope": "read write",
  "token_type": "bearer",
  "user_id": <id пользователя>

Авторизацию в OAuth2 по refresh_token

Подготовьте POST запрос следующего вида: 

 URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token

body запроса должно передаваться как Content-Type: x-www-form-urlencoded и содержать следующие значений KEY/VALUE: 

 "grant_type": "refresh_token",
 "refresh_token": <Значение refresh_tokent, полученное при предыдущей авторизации>,
 "client_id": "cashdesk-rest-client",
 "client_secret": "cashdesk-rest-client"

Note.svg Обратите внимание Значение refresh_token передается в том же виде, в каком оно было получено в ответе на предыдущий запрос авторизации. Без изменений и дополнительного кодирования.

Сервер вернет ошибку 200 OK. Response запроса будет содержать следующие данные. 

  "access_token": <Токен доступа>,
  "expires_in": 43199,
  "refresh_token": <Рефреш токен>,
  "scope": "read write",
  "token_type": "bearer",
  "user_id": <id пользователя>

Авторизацию в OAuth2 при двухфакторной авторизации

Двухфакторная авторизация это дополнительная защита пользователем своего аккаунта. Это более защищенный механизм авторизации пользователя по паролю. Возможность такой авторизации задается пользователем самостоятельно в настройках организации (учетной записи). При авторизации клиентское приложение не знает включена ли в учетной записи возможность двухфакторной авторизации. Ниже описан механизм авторизации пользователя по паролю и порядок действий, в случае если в учетной записи задана двухфакторная авторизация.


Шаг №1: Стандартная авторизация по паролю

Подготовьте POST запрос следующего вида: 

 URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token

body запроса должно передаваться как Content-Type: x-www-form-urlencoded и содержать следующие значений KEY/VALUE: 

  "grant_type" : "password",
  "username" : номер телефона (вводится как 7xxxxxxxxxx),
  "password" : пароль -> SHA-256 -> base64 urlencoded,
  "client_id" : "cashdesk-rest-client",
  "client_secret" : "cashdesk-rest-client"

Note.svg Обратите внимание Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма SHA256 и затем закодировать полученные данные по стандарту Вase64 urlencoded.

В случае если включена двухфакторная авторизация, сервер вернет ошибку 401 Unauthorized в Response запроса будет содержать следующие данные. 

  "error": "mfa_required",
  "error_description": "Требуется многофакторная аутентификация"

Шаг №2: Отправка SMS с кодом подтверждения на привязанный номер телефона

Получив такой ответ подготовьте POST запрос следующего вида: 

 URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/mfa?username=7xxxxxxxxxx

Note.svg 7xxxxxxxxxx - авторизованный номер телефона на который будет отправлена SMS с кодом подтверждения.

Сервер вернет ошибку 200 OK. Response запроса будет содержать значение session_id, запомните его и используйте на следующем шаге.

Шаг №3: Отправка запроса на авторизацию с кодом из SMS

Получив такой ответ подготовьте POST запрос следующего вида: 

 URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token

body запроса должно передаваться как Content-Type: x-www-form-urlencoded и содержать следующие значений KEY/VALUE: 

  "grant_type" : "mfa",
  "username" : номер телефона (вводится как 7xxxxxxxxxx),
  "password" : пароль -> SHA-256 -> base64 urlencoded,
  "session_id": <значение полученное на предыдущем шаге>,
  "code": <код из полученной SMS>,
  "client_id" : "cashdesk-rest-client",
  "client_secret" : "cashdesk-rest-client"

Note.svg Обратите внимание Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма SHA256 и затем закодировать полученные данные по стандарту Вase64 urlencoded.

Сервер вернет ошибку 200 OK. Response запроса будет содержать следующие данные. 

  "access_token": <Токен доступа>,
  "expires_in": 43199,
  "refresh_token": <Рефреш токен>,
  "scope": "read write",
  "token_type": "bearer",
  "user_id": <id пользователя>
Источник — http://kassa.bifit.com/wiki/index.php?title=Авторизация_при_интеграции_по_API&oldid=16184