Как интегрироваться с InSales — различия между версиями

Материал из Insales Wiki
Перейти к: навигация, поиск
(Процедура установки)
(Введение)
Строка 5: Строка 5:
 
Кроме того, есть механизм позволяющий другим пользователям подключить написанную Вами интеграцию нажатием одной кнопки.
 
Кроме того, есть механизм позволяющий другим пользователям подключить написанную Вами интеграцию нажатием одной кнопки.
 
Это механизм называется [[Расширение системы с помощью приложений|приложениями]].
 
Это механизм называется [[Расширение системы с помощью приложений|приложениями]].
 +
 +
Так же рекомендуем посмотреть презентацию http://www.slideshare.net/insales/in-sales-32846771 , чтобы в целом составить представление о принципах работы и возможностях API .
  
 
=Протокол обмена данными=
 
=Протокол обмена данными=

Версия 11:20, 28 марта 2014

Введение

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

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

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

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

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

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

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

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

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

Если пользователь уже вошел в бэк-офис магазина, и у него установлено приложение, его перенаправляют на URL

api_autologin_url?token=MD5(token + password)

где password - пароль приложения.

Если пользователь еще не вошел в приложение, то ему предложат войти в бэк-офис, а потом перенаправят на указанный URL.


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

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

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

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?token=c7a19acbbd574b0391233bf946f653fd

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