Авторизация при интеграции по API
Общие сведения
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 HEADERS | HEADERS |
| отключение компрессии | Accept-Encoding, "deflate"
|
| Request Body | type: x-www-form-urlencoded |
|
username: "7xxxxxxxxxx"
password: "asdaldfkhj34o.......kljslkfas"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "password"
|
Обратите внимание
Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма SHA256 и затем закодировать полученные данные по стандарту Вase64 urlencoded.
| Response | |
|
{
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: "dfowYbGcdiJSUzxs67.._782S_MQ"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "refresh_token"
|
Обратите внимание
Значение refresh_token передается в том же виде, в каком оно было получено в ответе на предыдущий запрос авторизации. Без изменений и дополнительного кодирования.
| Response | |
|
{
access_token: "eyJhbGciOiJSUzI1NiI...YQqpk7w",
token_type: "bearer",
refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ",
expires_in: 43199,
scope: "read write",
user_id: 4567
}
|
Авторизацию в OAuth2 при двухфакторной авторизации
Двухфакторная авторизация это дополнительная защита пользователем своего аккаунта. Требует от пользователя дополнительного ввода кода подтверждения, отправленного в SMS на номер учетной записи, после стандартной процедуры авторизации. Включение двухфакторной авторизации производится пользователем самостоятельно в настройках организации (учетной записи). При авторизации клиентское приложение не знает включена ли в учетной записи возможность двухфакторной авторизации. Ниже описан механизм авторизации пользователя по паролю и порядок действий, в случае если в учетной записи задана двухфакторная авторизация.
Внимание На момент написания статьи 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: "asdaldfkhj34o.......kljslkfas"
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "password"
|
Обратите внимание
Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма SHA256 и затем закодировать полученные данные по стандарту Вase64 urlencoded.
| Response | |
|
{
"error": "mfa_required",
"error_description": "Требуется многофакторная аутентификация"
}
|
Обратите внимание
В случае если включена двухфакторная авторизация, сервер вернет ошибку 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: "asdaldfkhj34o.......kljslkfas"
session_id: 590809155
code: 3021
client_id: "cashdesk-rest-client"
client_secret: "cashdesk-rest-client"
grant_type: "mfa"
|
Обратите внимание
Пароль передается в виде хэш суммы. Необходимо зашифровать пароль при помощи алгоритма SHA256 и затем закодировать полученные данные по стандарту Вase64 urlencoded.
| Response | |
|
{
access_token: "eyJhbGciOiJSUzI1NiI...YQqpk7w",
token_type: "bearer",
refresh_token: "dfowYbGcdiJSUzxs67.._782S_MQ",
expires_in: 43199,
scope: "read write",
user_id: 4567
}
|