API приложений Webasyst

Содержание...

Обращение к API Webasyst и установленных в нем приложений выполняется через файл api.php.

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

  1. Получаем токен авторизации — ключ доступа. В запросе получения токена перечисляем идентификаторы приложений, к API которых нужно получить доступ.
  2. Используя полученный токен, обращаемся к API-методам этих приложений. При работе с методами API учитываются права доступа пользователя, для которого был выдан токен.

Теперь подробнее об этом.

1. Получение токена авторизации

Используется немного модифицированная и упрощенная версия протокола OAuth 2.0.

Запрос на получение токена отправляет пользователя на специальную страницу авторизации Webasyst. На этой странице пользователь авторизуется со своими логином и паролем, которые используются для входа в бекенд Webasyst. Логин и пароль пользователь вводит именно на сайте с установленным фреймворком, а не в приложении-клиенте, которое пытается получить токен.

Пройдя авторизацию, пользователь разрешает или запрещает доступ к API от своего имени. Если доступ разрешается, то выдается токен. Пример токена: b936356100e3883cabf59abed991d03d.

Время жизни токена не ограничено.

Токен выдается только в случае разрешения доступа к API. Схема запроса на доступ от приложения следующая:

А. Серверные приложения

Перенаправлять пользователей для подтверждения прав доступа на
http://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=code&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT

Если пользователь подтверждает доступ, перенаправлять обратно на адрес
REDIRECT_URL?code=CODE

в противном случае — на
REDIRECT_URL?error=access_denied

Сервер выполняет POST-запрос с полями

code: CODE,
client_id: CLIENT_ID,
grant_type: 'authorization_code'

по адресу http://ACCOUNT_URL/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>

Б. Клиентские приложения

Перенаправлять пользователей для подтверждения прав доступа на
http://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=token&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT

Если пользователь подтверждает доступ, перенаправлять обратно на
REDIRECT_URL#access_token=ACCESS_TOKEN
в противном случае на
REDIRECT_URL#error=access_denied

Пояснения к переменным

ACCOUNT_URL — URL корневой папки установки фреймворка Webasyst

CLIENT_ID — уникальный идентификатор приложения, например, XYZCompanyShopImportApp; для веб-приложений рекомендуется указывать домен, чтобы избежать возможных конфликтов; идентификатор приложения разработчик придумывает на свое усмотрение

CLIENT_NAME — название приложения, которое будет показано на странице запроса доступа

SCOPE — приложения, к которым нужен доступ, перечисленные через запятую, например, scope=shop,photos,blog

REDIRECT_URI — URL, на который будет перенаправлен пользователь после принятия или отказа от принятия предоставления доступа к данным приложений

CODE — одноразовый код, необходимый для получения токена; действителен в течение 3 минут

FORMAT — необязательный параметр, указывающий на формат обмен информацией; возможные варианты значений: xml или json; если параметр не указан, то по умолчанию используется json

2. Запросы к API

Формат URL

http://ACCOUNT_URL/api.php/APP_ID.METHOD?PARAMS&access_token=ACCESS_TOKEN&format=FORMAT

Пример

Например, https://mydomain.ru/api.php/shop.product.getInfo?id=4&access_token=ACCESS_TOKEN&format=xml

Альтернативный формат

http://ACCOUNT_URL/api.php?app=APP_ID&method=METHOD&PARAMS&access_token=ACCESS_TOKEN&format=FORMAT

Пример

https://mydomain.ru/api.php?app=shop&method=product.getInfo&id=4&access_token=ACCESS_TOKEN&format=xml

Безопасный способ передачи токена авторизации

Для того чтобы исключить отслеживание токена по URL запросов, передавайте его одним из следующих способов в зависимости от используемого метода API:

  • в составе POST-запроса в поле access_token; в этом случае формируйте URL запроса без использования этого значения, например: https://mydomain.ru/api.php/shop.product.getInfo?id=4;
  • в HTTP-заголовке AUTHORIZATION в формате «Bearer ACCESS_TOKEN».

    Примеры

        /**
        * waNet
        */
        
        $net = new waNet([
            'authorization' => true,
            'auth_type' => 'Bearer',
            'auth_key' => '1d1863e4afd0fd818a74adbb56e9c2a6',
            'format' => waNet::FORMAT_JSON,
        ]);
        $response = $net->query('https://mydomain.ru/api.php/shop.product.getInfo', [
            'id' => 4,
        ], waNet::METHOD_GET);
        
        /**
        * PHP curl
        */
        
        $curl_h = curl_init('https://mydomain.ru/api.php/shop.product.getInfo/?id=4');
        
        curl_setopt($curl_h, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer 1d1863e4afd0fd818a74adbb56e9c2a6',
        ]);
        
        # do not output, but store to variable
        curl_setopt($curl_h, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($curl_h);
        $response = json_decode($response, true);
        
        /**
        * jQuery
        */
        
        $.ajax({
            url: 'https://mydomain.ru/api.php/shop.product.getInfo/?id=4',
            headers: {
                'Authorization': 'Bearer 1d1863e4afd0fd818a74adbb56e9c2a6'
            }
        }).then(function(response) {
            console.log(response);
        });
  • METHOD

    название метода, например, shop.category.getTree, stickies.sheet.getList

  • PARAMS

    набор параметров согласно описанию метода, например, parent_id=0&max_level=3

  • ACCESS_TOKEN

    токен, полученный при авторизации

  • RESPONSE

    необязательный параметр, указывающий на формат ответа; возможные варианты: xml, json (если не указан, то json)

  • APP_ID (в альтернативном способе вызова)

    идентификатор приложения, например, shop, stickies, photos, blog

  • 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