-
Notifications
You must be signed in to change notification settings - Fork 47
Api
API (Application Programming Interface) предоставляет удобный интерфейс для взаимодействия вашего приложения с L-Shop. Вы можете работать с L-Shop по средствам отправки http - запросов, следуя определенным правилам. Например, вы сможете авторизовывать пользователя, для того, чтобы ему не приходилось авторизовываться в магазине, если он уже вошёл в свой аккаунт на вашем ресурсе.
Для взаимодействия с API вам необходимо отправить HTTP - запрос (GET или POST, не важно) по определенному адресу. Каждый адрес соответствует опредленной функции, которая выполняется после успешной проверки подлинности данных. В зпросе необходимо передать какие-либо параметры, а также, контрольную сумму (hash) этих параметров.
Пример GET - запроса на авторизацию пользователя: http://example.ru/api/signin?username=d3lph1&hash=2080e2809b6ace6f6be9a1a22dba89aee2669ee1bb44e60476cfb9cf3d15c6a8
Здесь:
api - Эта часть url говорит о том, что запрос осуществяется к API, а не к другому компоненту магазина.
signin - Свидетельствует о том, что мы хоти авторизовать пользователя.
username - Имя пользователя.
hash - Контрольная сумма параметров запроса.
Хэш (hash) или контрольная сумма - это строка фиксированной длины, полученная в результате
выполнения определенного, необратимого алгоритма (алгоритмы бывают разные, md5 - один из них)
над исходной строкой. Например, в результате хэширования строки test1234567890 алгоритмом sha256, мы получим
вот такой хэш: 7afecb08fb6b7bab4bb45c755d857ae71d90ed2b37899f29b8bbc6ae758a5175.
Мы получили что-то вроде сигнатуры, однозначно идентифицирующей исходную строку,
при этом, вычислить саму исходную строку, зная хэш, крайне затруднительно или
невозможно вовсе.
Контрольная сумма берется от строки, построенной из параметров запроса
и секретного API - ключа, который хранится у вас на сайте, а также здесь, в магазине. Изменить
его вы можете в разделе Администрирование > Управление > API. Там же имеется возможность
выбрать алгоритм расчета контрольной суммы, а также, установить разделитель параметров.
И так, представьте, что пользователь уже вошел в свой аккаунтам на вашем сайте. И вам необходимо
выдать пользователю ссылку на магазин, работающей на L-Shop, да так, чтобы этот пользователь,
перейдя по ссылке, автоматически вошел в свой акаунт магазина и был готов совершать покупки.
Давайте составим запрос для этого дела.
Начало ссылки для API авторизации выглядит так: http://example.ru/api/signin?
Далее, следует передать параметр username, начением которого является имя пользователя
(логин), которого требуется авторизовать.
Теперь составим контрольнуя сумму нашего запроса, для этого, возьмем API - ключ, припишем к нему
разделитель, и в конце концов, припишем к этому имя пользователя.
Например, если моим секреным ключем является строка kR6rrpgUO2Hn3*aI?1vHwvdKcVUFIB,
разделителем - символ двоеточия (:), а имя пользователя - d3lph1,
то в результате, мы получим вот такую строку: kR6rrpgUO2Hn3*aI?1vHwvdKcVUFIB:d3lph1.
Возьмем хэш от этой строки тем алгоритмом, который вы указали в настройках API.
Например, если я использую алгоритм sha256, то результат будет таким:
22cc462bda02453b1bc7661a2045445756a9bffeb479d7668c3e03e7e4764da0.
Припишем этот хэш, значением параметра hash нашего запроса.
В конце концов, получаем вот такой url:
http://example.ru/api/signin?username=d3lph1&hash=22cc462bda02453b1bc7661a2045445756a9bffeb479d7668c3e03e7e4764da0
Конечно же, потребуется, так сказать, воплотить этот алгоритм в жизнь. Я написал для этого PHP - код, который составляет ссылку для авторизации пользователя.
/**
* Разумеется, все эти данные вы будете вытаскивать из БД, конфига и тд.
*/
$key = 'kR6rrpgUO2Hn3*aI?1~vHwvd~KcVUFIB:d3lph1'; // Секретный ключ. Должен соответствовать секретному ключу в магазине.
$delimiter = ':'; // Разделитель параметров
$algo = 'sha256'; // Алгоритм расчета контрольной суммы
$url = 'http://example.ru/api/signin?'; // Адрес API-авторизации
$username = 'D3lph1'; // Имя пользователя, которого необходимо авторизовать
$str = sprintf('%s%s%s', $key, $delimiter, $username);
$hash = hash($algo, $str);
$paramsStr = http_build_query([
'username' => $username,
'hash' => $hash
]);
$link = $url . $paramsStr; // Ссылка по переходу по которой, пользователь будет авторизованВ качетсве ответа, сервер отдаст JSON строку. Распарсив JSON, получим массив. Он содержит 2 обязательных элемента: status - краткое описание результата запроса на английском и code - число, однозначно идентифицирующее результат запроса. Запрос на аутентификацию пользователя не отдает ответ, так как выполняется непосредственно самим пользователем. У разных запросов имеются разные вариации ответа, но некоторые из них схожи:
| Status | Code | Описание |
|---|---|---|
| option disabled | -1 | Данная функция отключена или недоступна |
| invalid hash | -2 | Неверный хэш |
Для вашего удобства, я добавил возможность API-регистрации. Что это значит? Вы отправляете запрос к L-Shop'у, и в магазине создается пользователь с теми данными, которые вы передали в запросе. Делать это удобно, когда, пользователь регистрируется на вашем сайте. Таким образом, вы зарегистрируете его и в магазине тоже.
Запрос на регистрацию должен содержать следующие параметры: имя пользователя (username),
адрес электронной почты (email), пароль (password), баланс (balance),
нужно ли активировать пользователя мгновенно (force_activate) и, наконец, является ли он
администратором (admin).
В итоге, получаем вот такую схему строки, от которой необходимо взять хэш (разделителями, в данном случае
являются символы двоеточия (:)): key:username:email:password:balance:force_activate:admin.
Предположим, что мы хотим зарегистрировать пользователя GeraltOfRivia с адресом электронной почты
[email protected], паролем LambertLambert, выдать ему 100 рублей на счет и
мгновенно активировать. В этом случае строка будет такой (Секретный ключ - kR6rrpgUO2Hn3aI?1vHwvdKcVUFIB*,
разделитель - :): kR6rrpgUO2Hn3aI?1vHwvdKcVUFIB:GeraltOfRivia:[email protected]:LambertLambert: 100:1:0*.
Так как значения таких параметром, как force_activate и admin являются логическими, то мы передаем в них либо ноль(0),
либо - единицу(1). Если взять хэш от этой строки алгоритмом sha256, то получим нечто следующее:
592c19f8b889e33b9693f14957b341502728e5d3d281a53c3f032e93449bd154.
| Status | Code | Описание |
|---|---|---|
| username already exists | 1 | Пользователь с таким логином уже существует |
| email already exists | 2 | Пользователь с таким адресом электронной почты уже существует |
| unable to create user | 3 | Не удалось создать пользователя по техническим причинам |
| invalid username | 4 | Имя пользователя невалидно |
| success | 0 | Пользователь успешно зарегистрирован |
↑ Понравился магазин? Вырази благодарность разработчикам "звездочкой" ★.