Для того, чтобы интегрироваться с InSales, необходимо использовать API. Оно позволяет создавать, читать и удалять объекты бэк-офиса. Также доступен механизм для оповещения внешних систем о событиях.
Кроме того, реализован механизм, позволяющий другим пользователям подключить написанную интеграцию нажатием одной кнопки. Данный механизм называется приложением.
API InSales работает через HTTP протокол с использованием (GET/POST/PUT/DELETE) запросов. Данные при обмене передаются в XML-формате или JSON-формате.
Для корректной работы необходимо указывать Content-Type в запросе (Content-Type: application/xml или Content-Type: application/json ).
Для каждой группы объектов (заказов, товаров, категорий и т.д.) есть свой URL, при помощи которого можно управлять соответствующими объектами. Другими словами большаяя часть API организована в соответствии с принципами REST.
Если возникли вопросы, то напишите на почту partners@insales.ru.
Создание приложения
Добавление приложения
Для начала необходимо создать партнерский реферальный аккаунт, далее в разделе Приложения → Разработчикам можно будет создать приложение, заполнив поля:
- название приложения (будет отображаться в списке приложений);
- идентификатор приложения (должен состоять из латинских букв и цифр, используется в качестве логина для basic авторизации при отправке запросов);
- секрет (секретный ключ приложения, он не должен быть кому-либо известен, используется для установки приложения. При создании приложения он сформируется автоматически, но с возможностью отредактировать в будущем);
- текст краткого описания приложения (в html формате, будет отображаться в списке приложений);
- URL для установки приложения (без параметров, например http://myapp.ru/install);
- URL страницы приложения, куда попадает пользователь после нажатия кнопки установки приложения;
- URL страницы приложения, куда отправляется запрос для удаления приложения;
- логотип приложения, размером 250x100;
- название компании разработчика;
- контакты для пользователей.
Процедура установки
После того, как пользователь нажал кнопку "Установить приложение", InSales генерирует token (одноразовая строка, хранить у себя не нужно) и устанавливает пароль для подключения password = MD5(token + secret_key), где seсret_key - секрет (секретный ключ приложения). Этот пароль нужно сохранить на своей стороне и использовать в дальнейшем при запросах. Пароль для каждого магазина свой.
После этого отправляется GET запрос на URL для установки приложений с параметрами token , shop и insales_id,
где shop - адрес магазина на домене myinsales.ru, например myshop.myinsales.ru ,
insales_id - внутренний уникальный иденитификатор магазина, который не меняется и по нему однозначно идентифицируется магазин.
Если приложение отвечает 200 OK, то InSales считает, что приложение успешно установлено. Теперь можно отправлять запросы к InSales через API, используя сгенерированный пароль и идентификатор приложения в качестве логина.
Поле того как приложение ответило 200 OK, приложение может установить свои обработчики для событий, создать в InSales необходимые данные или загрузить данные в приложение из InSales.
Важно: до тех пор пока InSales не получил ответ 200 OK в ответ на запрос установки приложение считается не установленным, и оно не может совершать запросы к InSales через API.
Рассмотрим на конкретном примере:
-
Вы создали приложение со следующими настройками:
- идентификатор приложения - myapplogin;
- секретный ключ приложения - mysecret;
- URL установки - http://myapp.ru/install.
-
Пользователь магазина test.myinsales.ru (insales_id = 123) нажимает на установку приложения, генерируется случайный token (например, token123) и идет запрос:
http://myapp.ru/install?shop=test.myinsales.ru&token=token123&insales_id=123
При обработке этого запроса у себя вам нужно по токену вычислить пароль и записать его в своей базе для этого магазина, чтобы в дальнейшем отправлять запросы по API к нему. В данном случае получается такой пароль: password = MD5(token + secret_key) = MD5("token123mysecret") = 4c3f4c197336eb97475506e71c839c71
-
Теперь можно отправить запрос по API в магазин:
http://myapplogin:4c3f4c197336eb97475506e71c839c71@test.myinsales.ru/admin/account.xml
Авторизация
Для авторизации используется Basic Authorization. Логин задается в настройках приложения (идентификатор приложения) и является общим при запросах в разные магазины, пароль же формируется в момент установки, процедура описана выше.
Оповещение о событии
Для оповещения о событиях в InSales есть webhook-и: для определенных событий по заданному HTTP адресу отправляется POST запрос. В теле запроса в XML формате передается объект, с которым связано событие. Для того, чтобы оповещение заработало, необходимо через API установить обработчик для событий соответствующего типа. Пока доступны три типа событий: создание, изменение и удаление заказа.
Процедура автологина пользователя
Для того, чтобы пользователь не утруждал себя запоминанием логина и пароля, для каждого есть процедура, позволяющая авторизовать пользователя по адресу его магазина - shop_host. Для этого необходимо отправить GET запрос на адрес.
http://shop_host/admin/applications/api_key/login?token=token&login=api_autologin_url,
где shop_host - адрес интернет магазина на под-домене myinsales.ru,
api_key - идентификатора приложения,
token - одноразовый токен (формируете сами, никак не связан с token из установки приложения),
api_autologin_url - URL, на который будет выполнено перенаправление в приложение.
Важно: домен из урла api_autologin_url должен совпадать с доменом из урла входа в приложение из настроек, такая проверка сделана для безопасности.
Если пользователь уже вошел в бэк-офис магазина, и у него установлено приложение, его перенаправляют на URL:
api_autologin_url?token=MD5(token + password),
где password - пароль приложения в конкретном магазине (не путать с секретным ключем приложения).
Если пользователь еще не вошел в приложение, то ему предложат войти в бэк-офис, а потом перенаправят на указанный URL.
В частности так может работать механизм автологина при нажатии на кнопку "Войти" в приложение из бэкофиса:
-
Пользователя кидает урл входа в приложение, который указан его настройках. В GET-параметрах передаются название и id магазина, например: http://myapp.ru/login?shop=test.myinsales.ru&insales_id=123&user_id=1
-
Приложение смотрит сессию в cookies пользователя и, если он уже логинился, то все в порядке, показывает ему бэкофис приложения.
-
Если пользователь не залогинен в приложение, то редиректим его на урл автологина в InSales: http://test.myinsales.ru/admin/applications/my_app_key/login?token=3ad376b668c48c15d4beed467a567ef7&login=http://myapp.ru/autologin test.myinsales.ru - имя магазина, которое пришло в пункте 1. my_app_key - идентификатор приложения, который был указан в настройках при его создании; token - случайная одноразовая фраза; login - урл, где мы ждем пользователя назад для логина после редиректа с InSales
-
На стороне InSales идет проверка по сессии, что пользователь залогинен в этот магазин и, если все нормально, редирект его назад в приложение: http://myapp.ru/autologin?token3=c7a19acbbd574b0391233bf946f653fd&user_email=user@myshop.ru&user_name=igor&user_id=1&email_сonfirmed=true token3 - MD5(token + user_email + user_name + user_id
+email_сonfirmed + password) - md5-сумма от токена, которыл был передан в пункте 3, параметров user_email, user_name, user_id, email_сonfirmed (флаг, отображающий то, что e-mail был подтвержден по почте пользователем) и пароля приложения, который был сформирован при его установке, по этому token можно убедиться, чтобы пользователь действительно логинен в магазин на InSales, а не подделал этот урл.
Процедура удаления аккаунта
Если пользователь решил удалить приложение, то после нажатия на соответствующую кнопку cистема InSales отправляет приложению запрос вида:
uninstall_url?shop=shop&token=password&insales_id=insales_id,
где pasword - пароль приложения,
shop - адрес магазина на поддомене myinsales.ru,
insales_id - внутренний уникальный иденитификатор магазина.
Если приложение отвечает 200 ОК, то приложение считается удаленным.
Ограничения
Частота запросов к API
На приложение накладывается ограничение в 500 запросов к API одного магазина за 5 минут. Время расчитывается с момента первого запроса в серии. Количество выполненых запросов в текущем промежутке времени передается в HTTP заголовке API-Usage-Limit (пример: API-Usage-Limit: 1/500).
При превышении лимита доступ к API становится недоступным до окончания текущих 5 минут. В таком случае код ответа сервера - 503 и при этом в HTTP заголовке Retry-After передается время до начала предоставления доступа в секундах.
Возможные варианты http кодов в ответах
- 200 - штатный ответ на операцию, никаких ошибок не возникло
- 201 - в некоторых случаях при создании объектов может вернуться этот код, по сути тоже самое, что и 200-й ответ
- 400 - пришел некорректный http-запрос, http-сервер не смог его обработать, возможно слишком большой заголовок
- 401 - не прошла авторизация, необходимо проверить логин и пароль для basic-авторизации приложения
- 403 - нет прав для данной операции, необходимо проверить настройки прав для приложения
- 404 - запрашиваемый объект не найден, видимо его уже удалили или подставлен ошибочный id объекта
- 500 - внутренняя ошибка на нашей стороне, возможно вы некорректно сформировали данные для запроса или что-то еще случилось, необходимо обратиться в поддержку, чтобы разобраться
- 503 - вы привысили лимиты в API, если вам не хватает лимитов, то напишите в поддержку, чтобы разобраться в ситуации
- 504 - мы не смогли обработать ваш запрос за 50 секунд и прервали его выполнение, возможно вы пробуете получить слишком много данных за раз или еще какая-то проблема, можно так же обратиться в поддержку