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

Для того, чтобы интегрироваться с 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.

Заготовки под разные языки

1. Создание приложения
2. Процедура автологина пользователя
3. Процедура удаления аккаунта
4. Ограничения

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

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

Для начала необходимо создать партнерский реферальный аккаунт, далее в разделе Приложения → Разработчикам можно будет создать приложение, заполнив поля:

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

   - URL установки - 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 ,
   
   где test.myinsales.ru - это магазин, в котором происходит установка приложения.

Авторизация

Для авторизации используется 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 должен совпадать с доменом из урла входа в приложение из настроек, такая проверка сделана для безопасности.

Если пользователь уже вошел в бэк-офис магазина, и у него установлено приложение, его перенаправляют на 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?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 минут. В таком случае код ответа сервера - 429 и при этом в HTTP заголовке Retry-After передается время до начала предоставления доступа в секундах.

Возможные варианты http кодов в ответах

• 200 - штатный ответ на операцию, никаких ошибок не возникло
• 201 - в некоторых случаях при создании объектов может вернуться этот код, по сути тоже самое, что и 200-й ответ
• 400 - пришел некорректный http-запрос, http-сервер не смог его обработать, возможно слишком большой заголовок
• 401 - не прошла авторизация, необходимо проверить логин и пароль для basic-авторизации приложения
• 403 - нет прав для данной операции, необходимо проверить настройки прав для приложения
• 404 - запрашиваемый объект не найден, видимо его уже удалили или подставлен ошибочный id объекта
• 429 - превышены лимиты в API, если вам не хватает лимитов, то напишите в поддержку, чтобы разобраться в ситуации
• 500 - внутренняя ошибка на нашей стороне, возможно вы некорректно сформировали данные для запроса или что-то еще случилось, необходимо обратиться в поддержку, чтобы разобраться
• 504 - мы не смогли обработать ваш запрос за 50 секунд и прервали его выполнение, возможно вы пробуете получить слишком много данных за раз или еще какая-то проблема, можно так же обратиться в поддержку

Диапазоны per_page

Большинство admin эндпоинтов имеют ограничения per_page около 100, с фиксированными значениями для некоторых и сессией для других.

Если явно не указано иное, применяется глобальное ограничение для публичных API — до 1000, с минимумом 25 и дефолтом 25.

При определении значения параметра пагинации per_page сначала проверяется параметр query limit. Если он отсутствует, то используется параметр query per_page. Если оба параметра отсутствуют, значение берется из сессии session[:per_page_bo2] по ключу controller_name/action_name. При отсутствии всех значений используется значение по умолчанию.

Глобальные правила пагинации

• min_per_page: - 25
• max_per_page: - 1000 (максимум для публичных API)
• default_per_page: - 25