Обращение к API Webasyst и установленных в нем приложений выполняется через файл api.php
.
Авторизация основана на протоколе OAuth 2.0:
- Получаем токен авторизации — ключ доступа. В запросе получения токена перечисляем идентификаторы приложений, к API которых нужно получить доступ.
- Используя полученный токен, обращаемся к 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