Как интегрироваться с InSales

Материал из Insales Wiki
Перейти к: навигация, поиск

Введение

Для того чтобы интегрироваться с InSales есть API позволяющее создавать, читать и удалять объекты бэк-офиса. Также есть механизм для оповещения внешних систем о событиях.

Кроме того, есть механизм позволяющий другим пользователям подключить написанную Вами интеграцию нажатием одной кнопки. Это механизм называется приложениями.

Так же рекомендуем посмотреть презентацию http://www.slideshare.net/insales/in-sales-32846771 , чтобы в целом составить представление о принципах работы и возможностях API .

Протокол обмена данными

Обмен данными происходит по протоколу HTTP, данные передаются в формате xml или json. Более подробно о командах API

Создание приложения для AppStore

Добавление приложения

Для того чтобы разместить кнопку для установки приложения надо получить согласие от администрации и создать тестовое приложение в разделе Приложения -> Разработчикам, указав поля:

  • Название приложения (будет показываться в списке приложений)
  • Идентификатор приложения (должен состоять из латинских букв и цифр, используется в качестве логина для 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.


Рассмотрим на конкретном примере:


1. Вы создали приложение со следующими настройками:


идентификатор приложения - myapplogin

секретный ключ приложения - mysecret

урл установки - http://myapp.ru/install


2. Пользователь магазина 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


3. Теперь можно послать запрос по 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.


В частности так может работать механизм автологина при нажатии на кнопку "Войти" в приложение из бэкофиса:

1. Пользователя кидает урл входа в приложение, который указан его настройках. В GET-параметрах передаются название и id магазина, например:

http://myapp.ru/login?shop=test.myinsales.ru&insales_id=123&user_id=1

2. Приложение смотрит сессию в cookies пользователя и если он уже логинился, то все в порядке, показывает ему бэкофис приложения.

3. Если пользователь не залогинен в приложение, то редиректим его на урл автологина в 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

4. На стороне InSales идет проверка по сессии, что пользователь залогинен в этот магазин и если все нормально редирект его назад в приложение:

http://myapp.ru/autologin?token2=c7a19acbbd574b0391233bf946f653fd&user_email=user@myshop.ru&user_name=igor&user_id=1

token2 - MD5(token + user_email + user_name + user_id +password) - md5-сумма от токена, которыл был передан в пункте 3, параметров user_email, user_name, user_id и пароля приложения, который был сформирован при его установке, по этому 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 передается время до начала предоставления доступа в секундах.