Top.Mail.Ru

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

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

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

API InSales работает через HTTP протокол с использованием (GET/POST/PUT/DELETE) запросов. Данные при обмене передаются в XML-формате или JSON-формате.

Для корректной работы необходимо указывать Content-Type в запросе (Content-Typeapplication/xml или Content-Typeapplication/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

Авторизация

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

Оставить оценку

Оценка успешно отправлена.
Она будет проверена администратором перед публикацией.
Перед публикацией все оценки проходят модерацию

Оценки: 0

Остались вопросы?
Отправь тикет в техподдержку!
Еще нет своего магазина?
Создайте интернет-магазин на платформе InSales
Всё для продаж уже внутри!
Недавно просмотренные статьи