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

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


* Для работы с API сервиса БИФИТ Касса, пользователю необходимо получить токен доступа ('''access_token''').
* Генерация токена происходит по правилам авторизации Oauth2.


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


Токены предоставляют собой средство авторизации для каждого запроса от клиента к серверу. Токены (и соответственно сигнатура токена) генерируются на сервере основываясь на секретном ключе(который хранится на сервере) и payload'e. Токен хранится на клиенте и используется при необходимости авторизации какого-либо запроса.


Основные функции:
{{Note|'''Внимание''' <br>
* Аутентифицировать пользователей, используя внутреннее хранилище пользователей или внешний источник (например, Active Directory)
Учетная запись от имени которой будет происходить работа по API должна иметь максимальное кол-во прав, для создания, редактирования или удаления документов и справочников БИФИТ Касса|
* Управлять клиентами (хранить) и аутентифицировать их
700}}
* Предоставлять управление сессией и возможность реализации Single sing-on
* Выдавать identity-токены и access-токены клиентам
* Проверять ранее выданные токены


== Авторизацию в OAuth2 по паролю ==
{{ProductTable-2
|title-left='''Запрос'''
|title-right='''POST'''
|content-left= URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token
|content-right=
<syntaxhighlight>
https://kassa.bifit.com/cashdesk-api/v1/oauth/token
</syntaxhighlight>
|}}<br>


Информация получаемая по OAuth2:
{{ProductTable-2
  |title-left= Request HEADERS
  |title-right='''HEADERS'''
  |content-left= отключение компрессии
  |content-right=
<syntaxhighlight lang="JSON">
Accept-Encoding: "deflate"
</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">
username: "7xxxxxxxxxx"
password: "asdaldfkhj34o.......kljslkfas"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "password"
</syntaxhighlight>
|}}<br>
 
{{Note|'''Обратите внимание'''
Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма '''SHA256''' и затем закодировать полученные данные по стандарту '''Вase64 urlencoded'''.<br>
Для удобства можно использовать данный <b>[https://caligatio.github.io/jsSHA/ сайт]</b> с шифрованием. |
700}}<br>
 
{{ProductTable-2
|title-left= Response
|title-right=
|content-left=&nbsp;
* '''access_token''': токен доступа. Используется при отправке запросов ФП
* '''token_type''': тип токена
* '''refresh_token''': использовать для обновления токена доступа после истечении срока жизни (либо повторно авторизоваться с токеном коннектора)
* '''expires_in''': срок жизни токена доступа в секундах.
* '''scope''': права работы с токеном
* '''user_id''': ID пользователя
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
{
    access_token: "eyJhbGciOiJSUzI1NiI...YQqpk7w",
    token_type: "bearer",
    refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ",
    expires_in: 43199,
    scope: "read write",
    user_id: 4567
}
</syntaxhighlight>
|}}<br>
 
== Авторизацию в OAuth2 по refresh_token ==
{{ProductTable-2
|title-left='''Запрос'''
|title-right='''POST'''
|content-left= URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token
|content-right=
<syntaxhighlight>
https://kassa.bifit.com/cashdesk-api/v1/oauth/token
</syntaxhighlight>
|}}<br>
 
{{ProductTable-2
  |title-left= Request HEADERS
  |title-right='''HEADERS'''
  |content-left= отключение компрессии
  |content-right=
<syntaxhighlight lang="JSON">
Accept-Encoding: "deflate"
</syntaxhighlight>
|}}<br>
 
{{ProductTable-2
|title-left= Request Body
|title-right= type: '''x-www-form-urlencoded'''
|content-left=&nbsp;
* '''refresh_token''': значение '''refresh_token'''
* '''client_id''': передать значение ''"cashdesk-rest-client"''
* '''client_secret''': передать значение ''"cashdesk-rest-client"''
* '''grant_type''': передать значение ''"refresh_token"''
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "refresh_token"
</syntaxhighlight>
|}}<br>
 
{{Note|'''Обратите внимание'''
Значение '''refresh_token''' передается в том же виде, в каком оно было получено в ответе на предыдущий запрос авторизации. Без изменений и дополнительного кодирования.|
700}}<br>
 
{{ProductTable-2
|title-left= Response
|title-right=
|content-left=&nbsp;
* '''access_token''': токен доступа. Используется при отправке запросов ФП
* '''token_type''': тип токена
* '''refresh_token''': использовать для обновления токена доступа после истечении срока жизни (либо повторно авторизоваться с токеном коннектора)
* '''expires_in''': срок жизни токена доступа в секундах.
* '''scope''': права работы с токеном
* '''user_id''': ID пользователя
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
{
    access_token: "eyJhbGciOiJSUzI1NiI...YQqpk7w",
    token_type: "bearer",
    refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ",
    expires_in: 43199,
    scope: "read write",
    user_id: 4567
}
</syntaxhighlight>
|}}<br>
 
== Авторизацию в OAuth2 при двухфакторной авторизации ==
Двухфакторная авторизация это дополнительная защита пользователем своего аккаунта. Требует от пользователя дополнительного ввода кода подтверждения, отправленного в SMS на номер учетной записи, после стандартной процедуры авторизации. Включение двухфакторной авторизации производится пользователем самостоятельно в настройках организации (учетной записи). При авторизации клиентское приложение не знает включена ли в учетной записи возможность двухфакторной авторизации. Ниже описан механизм авторизации пользователя по паролю и порядок действий, в случае если в учетной записи задана двухфакторная авторизация.<br>
 
 
{{Note|'''Внимание''' На момент написания статьи '''21.04.2022''', включение механизма двухфакторной авторизации доступно только техническому персоналу '''ООО "БИФИТ КАССА"'''. Включение двухфакторной авторизации в набор типовых возможностей ЛК будет доступно позже|
1200}}
 
=== Шаг №1: Стандартная авторизация по паролю ===
 
{{ProductTable-2
|title-left='''Запрос'''
|title-right='''POST'''
|content-left= URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token
|content-right=
<syntaxhighlight>
https://kassa.bifit.com/cashdesk-api/v1/oauth/token
</syntaxhighlight>
|}}<br>
 
{{ProductTable-2
  |title-left= Request HEADERS
  |title-right='''HEADERS'''
  |content-left= отключение компрессии
  |content-right=
<syntaxhighlight lang="JSON">
Accept-Encoding: "deflate"
</syntaxhighlight>
 
|}}<br>


'''access_token''' — авторотационный ключ (обычно просто набор символов), предъявление которого является пропуском к защищенным ресурсам. Обращение к ним в самом простом случае происходит по HTTPS. Используется при работе по API
{{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">
username: "7xxxxxxxxxx"
password: "asdaldfkhj34o.......kljslkfas"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "password"
</syntaxhighlight>
|}}<br>


'''refresh_token''' — ключ, по которому можно получить access token с помощью HTTP-запроса, аналогично авторизации по логину и паролю
{{Note|'''Обратите внимание'''
Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма '''SHA256''' и затем закодировать полученные данные по стандарту '''Вase64 urlencoded'''.<br>
Для удобства можно использовать данный <b>[https://caligatio.github.io/jsSHA/ сайт]</b> с шифрованием.|
700}}<br>


'''expires_in''' - время работы (протухания) access_token в секундах. В сервисе БИФИТ Бизнес составляет 12 часов или 43 200 секунд - 1 секунда = 43 199 секунд.
{{ProductTable-2
|title-left= Response
|title-right=
|content-left=&nbsp;
* '''error''': ошибка
* '''error_description''': описание ошибки
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
{
  "error": "mfa_required",
  "error_description": "Требуется многофакторная аутентификация"
}
</syntaxhighlight>
|}}<br>


{{Note|
{{Note|'''Обратите внимание'''
Учетная запись от имени которой будут происходить работа по API должна иметь максимальное кол-во прав, для создания, редактирования или удаления документов и справочников БИФИТ Касса|
В случае если включена двухфакторная авторизация, сервер вернет ошибку '''401 Unauthorized''' в Response запроса будет содержать следующие данные..|
700}}
700}}


== Авторизацию в OAuth2 по паролю ==
=== Шаг №2: Отправка SMS с кодом подтверждения на привязанный номер телефона ===
Подготовьте POST запрос следующего вида:


  URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token
{{ProductTable-2
|title-left='''Запрос'''
|title-right='''POST'''
|content-left= '''7xxxxxxxxxx''' - авторизованный номер телефона на который будет отправлена SMS с кодом подтверждения
|content-right=
<syntaxhighlight>
https://kassa.bifit.com/cashdesk-api/v1/oauth/mfa?username=7xxxxxxxxxx
</syntaxhighlight>
|}}<br>


body запроса передаваться как Content-Type: form-data и содержать следующие параметры:
{{ProductTable-2
|title-left= Response
|title-right=
|content-left=&nbsp;
'''session_id''': Ответом на запрос будет значение session_id
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
  590809155
</syntaxhighlight>
|}}<br>


"grant_type" : "password"
=== Шаг №3: Отправка запроса на авторизацию с кодом из SMS ===
"username" : номер телефона (вводится как 79999999999)
{{ProductTable-2
"password" : вставить скопированный Access_token
|title-left='''Запрос'''
"client_id" : "cashdesk-rest-client"
|title-right='''POST'''
"client_secret" : "cashdesk-rest-client"
|content-left= URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token
|content-right=
<syntaxhighlight>
https://kassa.bifit.com/cashdesk-api/v1/oauth/token
</syntaxhighlight>
|}}<br>


После этого нажмите кнопку '''''Send'''''.
{{ProductTable-2
|title-left= Request Body
|title-right= type: '''x-www-form-urlencoded'''
|content-left=&nbsp;
* '''username''': логин учетной записи, передается в формате '''7xxxxxxxxxx'''
* '''password''': пароль, передается в виде зашифрованного хэш -> '''SHA-256 -> base64 urlencoded'''
* '''session_id''': id сессии полученный, при отправке кода в SMS
* '''code''': код из полученной SMS
* '''client_id''': передать значение ''"cashdesk-rest-client"''
* '''client_secret''': передать значение ''"cashdesk-rest-client"''
* '''grant_type''': передать значение ''"password"''
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
username: "7xxxxxxxxxx"
password: "asdaldfkhj34o.......kljslkfas"
session_id: 590809155
code: 3021
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "mfa"
</syntaxhighlight>
|}}<br>


== Авторизацию в OAuth2 по refresh_token ==
{{Note|'''Обратите внимание'''
Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма '''SHA256''' и затем закодировать полученные данные по стандарту '''Вase64 urlencoded'''.<br>
Для удобства можно использовать данный <b>[https://caligatio.github.io/jsSHA/ сайт]</b> с шифрованием.|
700}}<br>


== Авторизацию в OAuth2 при двухфакторной авторизации ==
{{ProductTable-2
|title-left= Response
|title-right=  
|content-left=&nbsp;
* '''access_token''': токен доступа. Используется при отправке запросов ФП
* '''token_type''': тип токена
* '''refresh_token''': использовать для обновления токена доступа после истечении срока жизни (либо повторно авторизоваться с токеном коннектора)
* '''expires_in''': срок жизни токена доступа в секундах.
* '''scope''': права работы с токеном
* '''user_id''': ID пользователя
|content-right=&nbsp;
<syntaxhighlight lang="JSON">
{
    access_token: "eyJhbGciOiJSUzI1NiI...YQqpk7w",
    token_type: "bearer",
    refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ",
    expires_in: 43199,
    scope: "read write",
    user_id: 4567
}
</syntaxhighlight>
|}}<br>

Текущая версия на 16:17, 17 июля 2023

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

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 HEADERS HEADERS
отключение компрессии 
Accept-Encoding: "deflate"


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"
   
username: "7xxxxxxxxxx"
password: "asdaldfkhj34o.......kljslkfas"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "password"


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


Response
 
  • access_token: токен доступа. Используется при отправке запросов ФП
  • token_type: тип токена
  • refresh_token: использовать для обновления токена доступа после истечении срока жизни (либо повторно авторизоваться с токеном коннектора)
  • expires_in: срок жизни токена доступа в секундах.
  • scope: права работы с токеном
  • user_id: ID пользователя
   
{
    access_token: "eyJhbGciOiJSUzI1NiI...YQqpk7w",
    token_type: "bearer",
    refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ",
    expires_in: 43199,
    scope: "read write",
    user_id: 4567
}


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

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


Request HEADERS HEADERS
отключение компрессии 
Accept-Encoding: "deflate"


Request Body type: x-www-form-urlencoded
 
  • refresh_token: значение refresh_token
  • client_id: передать значение "cashdesk-rest-client"
  • client_secret: передать значение "cashdesk-rest-client"
  • grant_type: передать значение "refresh_token"
   
refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "refresh_token"


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


Response
 
  • access_token: токен доступа. Используется при отправке запросов ФП
  • token_type: тип токена
  • refresh_token: использовать для обновления токена доступа после истечении срока жизни (либо повторно авторизоваться с токеном коннектора)
  • expires_in: срок жизни токена доступа в секундах.
  • scope: права работы с токеном
  • user_id: ID пользователя
   
{
    access_token: "eyJhbGciOiJSUzI1NiI...YQqpk7w",
    token_type: "bearer",
    refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ",
    expires_in: 43199,
    scope: "read write",
    user_id: 4567
}


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

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


Note.svg Внимание На момент написания статьи 21.04.2022, включение механизма двухфакторной авторизации доступно только техническому персоналу ООО "БИФИТ КАССА". Включение двухфакторной авторизации в набор типовых возможностей ЛК будет доступно позже

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

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


Request HEADERS HEADERS
отключение компрессии 
Accept-Encoding: "deflate"


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"
   
username: "7xxxxxxxxxx"
password: "asdaldfkhj34o.......kljslkfas"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "password"


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


Response
 
  • error: ошибка
  • error_description: описание ошибки
   
{
  "error": "mfa_required",
  "error_description": "Требуется многофакторная аутентификация"
}


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

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

Запрос POST
7xxxxxxxxxx - авторизованный номер телефона на который будет отправлена SMS с кодом подтверждения 
https://kassa.bifit.com/cashdesk-api/v1/oauth/mfa?username=7xxxxxxxxxx


Response
  session_id: Ответом на запрос будет значение session_id   
  590809155


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

Запрос 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
  • session_id: id сессии полученный, при отправке кода в SMS
  • code: код из полученной SMS
  • client_id: передать значение "cashdesk-rest-client"
  • client_secret: передать значение "cashdesk-rest-client"
  • grant_type: передать значение "password"
   
username: "7xxxxxxxxxx"
password: "asdaldfkhj34o.......kljslkfas"
session_id: 590809155
code: 3021
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "mfa"


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


Response
 
  • access_token: токен доступа. Используется при отправке запросов ФП
  • token_type: тип токена
  • refresh_token: использовать для обновления токена доступа после истечении срока жизни (либо повторно авторизоваться с токеном коннектора)
  • expires_in: срок жизни токена доступа в секундах.
  • scope: права работы с токеном
  • user_id: ID пользователя
   
{
    access_token: "eyJhbGciOiJSUzI1NiI...YQqpk7w",
    token_type: "bearer",
    refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ",
    expires_in: 43199,
    scope: "read write",
    user_id: 4567
}


Источник — http://kassa.bifit.com/wiki/index.php?title=Авторизация_при_интеграции_по_API&oldid=51154