Обращение к API Webasyst и установленных в нем приложений выполняется через файл /api.php
. Авторизация работает на основе протокола OAuth 2.0.
Порядок работы:
- Получить токен авторизации — ключ доступа. В запросе получения токена нужно перечислить идентификаторы приложений, к API которых нужно получить доступ.
- Обращаться к API-методам этих приложений, используя полученный токен. При работе с методами API учитываются права доступа пользователя, для которого был выдан токен.
1. Получение токена авторизации
Используется немного модифицированная и упрощённая версия протокола OAuth 2.0.
Запрос на получение токена отправляет пользователя на специальную страницу авторизации Webasyst. На этой странице пользователь авторизуется со своими логином и паролем, которые используются для входа в аккаунт Webasyst.
Логин и пароль пользователь вводит на сайте с установленным фреймворком, а не в приложении-клиенте, которое пытается получить токен.
После авторизации пользователь должен разрешить или запретить доступ к API от своего имени. Если доступ разрешается, то выдается токен в виде строки символов. Пример токена: b936356100e3883cabf59abed991d03d.
Время жизни токена не ограничено.
Далее описаны схемы отправки запросов на доступ от разных типов приложений:
Серверные приложения
Порядок работы:
- Перенаправить пользователя на 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
для подтверждения прав доступа. - В зависимости от подтверждения доступа:
- Если пользователь подтверждает доступ, он перенаправляется его на URL вида
REDIRECT_URI?code=CODE. - В противном случае пользователь перенаправляется на URL вида
REDIRECT_URI?error=access_denied.
- Если пользователь подтверждает доступ, он перенаправляется его на URL вида
- Выполнить 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>
Клиентские приложения
Порядок работы:
- Перенаправить пользователя на 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
для подтверждения прав доступа. - В зависимости от подтверждения доступа:
- Если пользователь подтверждает доступ, он перенаправляется его на URL вида
REDIRECT_URI#access_token=ACCESS_TOKEN. - В противном случае пользователь перенаправляется на URL вида
REDIRECT_URI#error=access_denied.
- Если пользователь подтверждает доступ, он перенаправляется его на URL вида
Описания переменных
- ACCOUNT_URL: URL корневой директории аккаунта Webasyst.
- CLIENT_ID: уникальный идентификатор приложения, например, XYZCompanyShopImportApp. Для веб-приложений рекомендуется указывать домен, чтобы избежать возможных конфликтов. Идентификатор приложения разработчик формирует на своё усмотрение.
- CLIENT_NAME: название приложения, которое будет показано пользователю на странице запроса доступа.
- SCOPE: идентификаторы приложений, к которым запрашивается доступ, перечисленные через запятую. Пример:
shop,photos,blog
. - REDIRECT_URI: URL, на который будет перенаправлен пользователь после подтверждения или отказа от предоставления доступа к перечисленным приложениям.
- CODE: одноразовый код, необходимый для получения токена; действителен в течение 3 минут.
- FORMAT: необязательный параметр для обозначения формата обмена информацией. Допустимые значения:
- xml
- json: используется по умолчанию, даже если обозначение формата не указано.
2. Запросы к API
В составе запросов нужно указывать значение заголовка Content-Type
равным application/x-www-form-urlencoded
или multipart/form-data
(для случаев, когда нужно выполнять отправку файлов).
Формат URL
https://ACCOUNT_URL/api.php/APP_ID.METHOD?PARAMS
Пример
https://mydomain.ru/api.php/shop.product.getInfo?id=4
Альтернативный формат URL
https://ACCOUNT_URL/api.php?app=APP_ID
Пример
https://mydomain.ru/api.php?app=shop
Безопасный способ передачи токена авторизации
Для того чтобы исключить отслеживание токена по 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.