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

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


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


Строка 34: Строка 34:
700}}
700}}


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


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


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


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


Строка 59: Строка 59:
700}}
700}}


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


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


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


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


Строка 88: Строка 88:
Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма '''SHA256''' и затем закодировать полученные данные по стандарту '''Вase64 urlencoded'''.|
Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма '''SHA256''' и затем закодировать полученные данные по стандарту '''Вase64 urlencoded'''.|
700}}
700}}
'''В случае если включена двухфакторная авторизация, сервер вернет ошибку ''401 Unauthorized''' в Response запроса будет содержать следующие данные'''
  "error": "mfa_required",
  "error_description": "Требуется многофакторная аутентификация"
Получив такой ответ подготовьте POST запрос следующего вида:
  URL: https://kassa.bifit.com/cashdesk-api/v1/oauth/mfa?username=7xxxxxxxxxx
{{Note|'''7xxxxxxxxxx''' - авторизованный номер телефона на который будет отправлена SMS с кодом подтверждения.|
700}}
'''Сервер вернет ошибку '''200 OK'''. Response запроса будет содержать значение session_id, запомните его и используйте в следующем запросе'''
Получив такой ответ подготовьте 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|'''Обратите внимание'''
Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма '''SHA256''' и затем закодировать полученные данные по стандарту '''Вase64 urlencoded'''.|
700}}
'''Сервер вернет ошибку '''200 OK'''. Response запроса будет содержать следующие данные'''
  "access_token": <Токен доступа>,
  "expires_in": 43199,
  "refresh_token": <Рефреш токен>,
  "scope": "read write",
  "token_type": "bearer",
  "user_id": <id пользователя>

Версия 12:40, 3 февраля 2022

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

API (Application Programming Interface или интерфейс программирования приложений) — это совокупность инструментов и функций в виде интерфейса для создания новых приложений, благодаря которому одна программа будет взаимодействовать с другой.

Для работы с API сервиса БИФИТ Касса, пользователю необходимо получить токен доступа. Генерация токена происходит по правилам авторизации 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

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.

Сервер вернет ошибку 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 при двухфакторной авторизации

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


Подготовьте 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": "Требуется многофакторная аутентификация"

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

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

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

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

Получив такой ответ подготовьте 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 пользователя>