Авторизация

На главную / API

Авторизация основана на протоколе OAuth 2.0:

  1. Получаем токен авторизации — ключ доступа.
  2. Используя полученный токен, обращаемся к 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);