Документация API Webasyst

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

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

Порядок работы:

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

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

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

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

Логин и пароль пользователь вводит на сайте с установленным фреймворком, а не в приложении-клиенте, которое пытается получить токен.

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

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

Далее описаны схемы отправки запросов на доступ от разных типов приложений:

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

Порядок работы:

  1. Перенаправить пользователя на URL вида
    https://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=code&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT
    для подтверждения прав доступа.
  2. В зависимости от подтверждения доступа:
    • Если пользователь подтверждает доступ, он перенаправляется его на URL вида
      REDIRECT_URI?code=CODE.
    • В противном случае пользователь перенаправляется на URL вида
      REDIRECT_URI?error=access_denied.
  3. Выполнить POST-запрос на URL вида
    https://ACCOUNT_URL/api.php/token?redirect_uri=REDIRECT_URI&format=FORMAT
    со следующими значениями:
    • code: CODE;
    • client_id: CLIENT_ID;
    • grant_type: authorization_code.

    Если необходимо получить ответ в формате XML, то нужно также добавить к URL запроса GET-параметр format=XML. В противном случае ответ возвращается в формате JSON (по умолчанию).

Формат ответа (JSON)
{
    "access_token": ACCESS_TOKEN
}
Формат ответа (XML)
<response>
    <access_token>ACCESS_TOKEN</access_token>
</response>

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

Порядок работы:

  1. Перенаправить пользователя на URL вида
    https://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=token&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT
    для подтверждения прав доступа.
  2. В зависимости от подтверждения доступа:
    • Если пользователь подтверждает доступ, он перенаправляется его на URL вида
      REDIRECT_URI#access_token=ACCESS_TOKEN.
    • В противном случае пользователь перенаправляется на URL вида
      REDIRECT_URI#error=access_denied.

Описания переменных

  • ACCOUNT_URL: URL корневой директории аккаунта Webasyst.
  • CLIENT_ID: уникальный идентификатор приложения, например, XYZCompanyShopImportApp. Для веб-приложений рекомендуется указывать домен, чтобы избежать возможных конфликтов. Идентификатор приложения разработчик формирует на своё усмотрение.
  • CLIENT_NAME: название приложения, которое будет показано пользователю на странице запроса доступа.
  • SCOPE: идентиикаторы приложений, к которым запрашивается доступ, перечисленные через запятую. Пример: shop,photos,blog.
  • REDIRECT_URI: URL, на который будет перенаправлен пользователь после подтверждения или отказа от предоставления доступа к перечисленным приложениям.
  • CODE: одноразовый код, необходимый для получения токена; действителен в течение 3 минут.
  • FORMAT: необязательный параметр для обозначения формата обмена информацией. Допустимые значения:
    • xml
    • json: используется по умолчанию, даже если обозначение формата не указано.

2. Запросы к API

Формат URL

https://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

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

https://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: название API-метода, например, shop.category.getTree или stickies.sheet.getList.
  • PARAMS: набор параметров, отправка которых необходима для выполнения метода, например, parent_id=0&max_level=3.
  • ACCESS_TOKEN: токен, полученный после авторизации пользователя.
  • APP_ID: идентификатор приложения, например, shop.
  • FORMAT: необязательный параметр, указывающий на формат обмена информацией: xml или json (значение, используемое по умолчанию).
  • RESPONSE: необязательный параметр, указывающий на ожидаемый формат ответа: xml или json (значение, используемое по умолчанию).

Формат ответа с ошибкой

В случае ошибки в ответе всегда доступно поле error:

Пример (JSON)
{
    "error":"invalid_request"
}
Пример (XML)
<response>
    <error>invalid_request</error>
</response>

Коды ошибок

Значения поля error в ответе сервера:

  • invalid_request

    Неверно сфомированный запрос. Дополнительная информация об ошибке указывается в поле ответа error_description.

  • access_denied

    Для данного токена нет доступа к запрошенному методу.

  • invalid_method

    Вызов неизвестного метода API.