Авторизация основана на протоколе OAuth 2.0:
- Получаем токен авторизации — ключ доступа.
- Используя полученный токен, обращаемся к API-методам. При работе с методами API учитываются права доступа пользователя, для которого был выдан токен.
Теперь подробнее об этом.
1. Получение токена авторизации
Используется немного модифицированная и упрощенная версия протокола OAuth 2.0.
Запрос на получение токена отправляет пользователя на специальную страницу авторизации. На этой странице пользователь авторизуется со своими логином и паролем, которые используются для входа на сайт https://bstats.ru.
Пройдя авторизацию, пользователь разрешает или запрещает доступ к API от своего имени. Если доступ разрешается, то выдается токен. Пример токена: b936356100e3883cabf59abed221d03d.
Время жизни токена не ограничено.
Токен выдается только в случае разрешения доступа к API. Схема запроса на доступ от приложения следующая:
Перенаправлять пользователей для подтверждения прав доступа на
https://bstats.ru/api.php/auth?client_id=bstats.ru&client_name=dossier&response_type=code&scope=dossier&format=FORMAT&redirect_uri=REDIRECT_URL
Если пользователь подтверждает доступ, перенаправлять обратно на адрес
REDIRECT_URL?code=CODE
в противном случае — на
REDIRECT_URL?error=access_denied
Сервер выполняет POST-запрос с полями
—code
: CODE,
—client_id
: CLIENT_ID,
—grant_type
: 'authorization_code'
по адресуhttps://bstats.ru/api.php/token?redirect_uri=REDIRECT_URI&format=FORMAT
Ответ может быть в формате JSON (по умолчанию) или XML (&format=XML
).
{ "access_token": ACCESS_TOKEN }или
<response> <access_token>ACCESS_TOKEN</access_token> </response>
Пояснения к переменным
REDIRECT_URI — URL, на который будет перенаправлен пользователь после принятия или отказа от принятия предоставления доступа к данным приложений
CODE — одноразовый код, необходимый для получения токена; действителен в течение 3 минут
FORMAT — необязательный параметр, указывающий на формат обмен информацией; возможные варианты значений: xml
или json
; если параметр не указан, то по умолчанию используется json
2. Запросы к API
Формат URL
https://bstats.ru/api.php?app=dossier&method=METHOD&PARAMS&access_token=ACCESS_TOKEN&format=FORMAT
Пример
https://bstats.ru/api.php/?app=dossier&method=customer.getcomments&access_token=ACCESS_TOKEN&format=xml
- METHOD
название метода, например, customer.getuuid, customer.update
- PARAMS
набор параметров согласно описанию метода
ACCESS_TOKEN
токен, полученный при авторизации
- RESPONSE
необязательный параметр, указывающий на формат ответа; возможные варианты:
xml
,json
(если не указан, тоjson
)
- FORMAT
необязательный параметр, указывающий на формат обмен информацией; возможные варианты значений:
xml
илиjson
; если параметр не указан, то по умолчанию используетсяjson
В случае ошибки в ответе всегда будет доступно поле error
:
JSON
{ "error": "invalid_request }
XML
<response> <error>invalid_request</error> </response>
Коды ошибок (элемент error
)
- invalid_request
неверно сфомированный запрос; дополнительная информация об ошибке указывается в поле
error_description
- access_denied
для данного токена нет доступа к запрошенному методу
- invalid_method
вызов неизвестного метода API
3. Пример кода авторизации
$request_data = array( 'code' => $code, 'client_id' => 'bstats.ru', 'grant_type' => 'authorization_code', ); $url = "https://bstats.ru/api.php/token/?format=JSON"; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, false); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata); $data = json_decode(curl_exec($ch)); curl_close($ch);