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

Версия 14:38, 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 секунд.

Внимание Учетная запись от имени которой будут происходить работа по 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"

username: "7xxxxxxxxxx"
password: "asdaldfkhj34o.......kljslkfas"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "password"

Обратите внимание Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма 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 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: "7xxxxxxxxxx" client_id: "cashdesk-rest-client" client_secret: "cashdesk-rest-client" grant_type: "password"

Обратите внимание Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма 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
}

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"

Обратите внимание Значение 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"

Обратите внимание Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма 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

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"

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

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

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

@@ Строка 36: / Строка 36: @@
 <syntaxhighlight lang="JSON">
 username: "7xxxxxxxxxx"
-token: "asdaldfkhj34o.......kljslkfas"
+password: "asdaldfkhj34o.......kljslkfas"
 client_id: "cashdesk-rest-client"
 client_secret: "cashdesk-rest-client"
@@ Строка 71: / Строка 71: @@
 == Авторизацию в OAuth2 по refresh_token ==
-Подготовьте POST запрос следующего вида:
+{{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 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: "7xxxxxxxxxx"
+client_id: "cashdesk-rest-client"
+client_secret: "cashdesk-rest-client"
+grant_type: "password"
+</syntaxhighlight>
+|}}<br>
+{{Note|'''Обратите внимание'''
+Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма '''SHA256''' и затем закодировать полученные данные по стандарту '''Вase64 urlencoded'''.|
+}}<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>
-  URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/token
 body запроса должно передаваться как Content-Type: x-www-form-urlencoded и содержать следующие значений KEY/VALUE:

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

Версия 14:38, 21 апреля 2022

Содержание

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

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

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

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

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

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

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

Навигация

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

Версия 14:38, 21 апреля 2022

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

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

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

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

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

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

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

Навигация

Поиск