Версия 10:20, 8 октября 2012

Введение

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

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

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

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

Авторизация

Для авторизации используется Basic Authorization. Для получения логина и пароля зайдите в бэк-офисе в раздел Настройки -> Приложения.

Внизу раздела будет ссылка на подраздел для разработчиков.

В разделе для разработчиков вам надо нажать кнопку создать приложение

и вам сгенерируют реквизиты для доступа к API

Оповещение о событии

Для оповещения о событиях, в InSales есть webhook-и: для определенных событий по заданному HTTP адресу отправляется POST запрос. В теле запроса в xml формате передается объект, с которым связанно событие. Для того чтобы оповещение заработало, надо через API установить обработчик, для событий соответствующего типа. Пока доступны два типа событий: создание и изменение заказа.

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

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

Для того чтобы разместить кнопку для установки приложения надо получить согласие от администрации и сообщить ей:

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

Процедура авто-логина пользователя

Для того чтобы пользователь не утруждал себя запоминанием логина и пароля, для каждого есть процедура, позволяющая авторизовать пользователя по адресу его магазина - shop_host. Для этого надо отправить GET запрос на адрес

http://shop_host/admin/applications/api_key/login?token=token&login=api_autologin_url

где shop_host - адрес интернет магазина на под-домене myinsales.ru, api_key - идентификатора приложения, token - одноразовый токен, api_autologin_url - URL, на который будет выполнено перенаправление в приложение.

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

api_autologin_url?token=MD5(token + password)

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

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

Процедура удаления аккаунта

Если пользователь решил удалить приложение. То после нажатия на соответствующую кнопку cистема InSales отправляет приложению запрос вида:

uninstall_url?shop=shop&token=password

где pasword - пароль приложения, а shop - адрес магазина на поддомене myinsales.ru. Если приложение отвечает 200 ОК, то приложение считается удаленным.