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