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

Материал из Insales Wiki
Перейти к: навигация, поиск
(Процедура авто-логина пользователя)
 
(не показаны 43 промежуточные версии 8 участников)
Строка 1: Строка 1:
 
=Введение=
 
=Введение=
  
Для того чтобы интегрироваться с InSales есть [[Команды API|API]] позволяющее создавать, читать и удалять объекты бек-офиса. Также есть механизм для оповещения внешних систем о событиях.  
+
Для того чтобы интегрироваться с InSales есть [[Команды API|API]] позволяющее создавать, читать и удалять объекты бэк-офиса. Также есть механизм для оповещения внешних систем о событиях.  
  
Кроме того, есть механизм позволяющий другим пользователям подключить написанную вами интеграцию нажатием одной кнопки.
+
Кроме того, есть механизм позволяющий другим пользователям подключить написанную Вами интеграцию нажатием одной кнопки.
Это механизм называется приложениями.
+
Это механизм называется [[Расширение системы с помощью приложений|приложениями]].
  
 +
Так же рекомендуем посмотреть презентацию http://www.slideshare.net/insales/in-sales-32846771 , чтобы в целом составить представление о принципах работы и возможностях API .
  
 
=Протокол обмена данными=
 
=Протокол обмена данными=
  
Обмен данными происходит по протоколу HTTP, данные передаются в формате xml. [[Команды API|Более подробно о командах API]]
+
Обмен данными происходит по протоколу HTTP, данные передаются в формате xml или json. [[Команды API|Более подробно о командах API]]
  
 +
=Создание приложения для AppStore=
  
=Авторизация=
+
==Добавление приложения==
 +
 
 +
Для начала вам необходимо создать партнерский аккаунт ( https://www.insales.ru/partnership  ) , после в разделе Приложения -> Разработчикам вы сможете создать приложение, указав поля:
 +
* Название приложения (будет показываться в списке приложений)
 +
* Идентификатор приложения (должен состоять из латинских букв и цифр, используется в качестве логина для 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.
  
Для авторизации используется Basic Authorization. Для получения логина и пароля зайдите в бек-офисе в раздел Настройки -> Приложения.
 
  
Внизу раздела будет ссылка на подраздел для разработчиков.
+
Рассмотрим на конкретном примере:
  
  
[[Изображение:App1.png]]
+
1. Вы создали приложение со следующими настройками:
  
  
В разделе для разработчиков вам надо нажать кнопку создать приложение
+
идентификатор приложения - myapplogin
  
 +
секретный ключ приложения - mysecret
  
[[Изображение:App2.png]]
+
урл установки - http://myapp.ru/install
  
  
и вам сгенерируют реквизиты для доступа к API
+
2. Пользователь магазина test.myinsales.ru (insales_id = 123) нажимает на установку вашего приложения, генерируется случайный token (для примера token123) и идет запрос:
  
  
[[Изображение:App3.png]]
+
http://myapp.ru/install?shop=test.myinsales.ru&token=token123&insales_id=123
  
  
=Оповещение о событии=
+
При обработке этого запроса у себя вам нужно по токену вычислить пароль и записать его в своей базе для этого магазина, чтобы в дальнейшем слать запросы по API к нему.
 +
В данном случае получается такой пароль:
  
Для оповещения о событиях, InSales умеет отправлять по заданному HTTP адресу POST запрос. В теле запроса в xml формате передается объект, с которым связанно событие. Для того чтобы оповещение заработало, надо [[Команды API|через API установить обработчик]], для событий соответствующего типа. Пока доступны два типа событий: создание и изменение заказа.
 
  
 +
password = MD5(token + secret_key) = MD5("token123mysecret") = 4c3f4c197336eb97475506e71c839c71
  
=Создание приложения=
 
  
==Добавление приложения==
+
3. Теперь можно послать запрос по API в магазин:
  
Для того чтобы разместить кнопку для установки приложения надо получить согласие от администрации и сообщить ей:
 
* Название приложения (будет показываться в списке приложений)
 
* Идентификатор приложения (должен состоять из латинских букв и цифр, используется для авторизации)
 
* Секретный ключ приложения (он не должен быть никому известен, используется для установки приложения)
 
* Текст краткого описания приложения (в html формате, будет показываться в списке приложений)
 
* URL для установки приложения (без параметров)
 
* URL станицы приложения, куда попадает пользователь после нажатия кнопки установки приложения
 
  
==Процедура установки==
+
http://myapplogin:4c3f4c197336eb97475506e71c839c71@test.myinsales.ru/admin/account.xml
  
После того как пользователь нажал кнопку установить приложение InSales генерирует '''token''' и устанавливает пароль для подключения '''password = MD5(token + secret_key)''', где '''seсret_key''' - секретный ключ приложения.
+
=Авторизация=
  
После этого отправляется GET запрос на URL для установки приложений с параметрами '''token''' и '''shop''', где '''shop''' - адрес магазина на домене myinsales.ru, например myshop.myinsales.ru.  
+
Для авторизации используется Basic Authorization. Логин задается в настройках приложения (идентификатор приложения) и он общий при запросах в разные магазины, пароль же формируется в момент установки, процедура описана выше.
  
Если приложение отвечает 200 OK, то InSales считает, что приложение успешно установлено. Теперь можно слать запросы к insales через API, используя сгенерированный пароль и идентификатор, приложения в качестве.
+
=Оповещение о событии=
  
Поле того как приложение ответило 200 OK, приложение может установить свои обработчики для событий, создать в InSales необходимые данные или загрузить данные в приложение из InSales.
+
Для оповещения о событиях, в InSales есть webhook-и: для определенных событий по заданному HTTP адресу отправляется POST запрос. В теле запроса в xml формате передается объект, с которым связанно событие. Для того чтобы оповещение заработало, надо [[InSales API - Webhooks|через API установить обработчик]], для событий соответствующего типа. Пока доступны три типа событий: создание, изменение и удаление заказа.
  
 
==Процедура авто-логина пользователя==
 
==Процедура авто-логина пользователя==
  
Для того чтобы пользователь не утруждал себя запоминанием логина и пароля для каждого есть процедура позволяющая авторизовать пользователя по адресу его магазина - shop_host. Для этого надо отправить GET запрос на адрес  
+
Для того чтобы пользователь не утруждал себя запоминанием логина и пароля, для каждого есть процедура, позволяющая авторизовать пользователя по адресу его магазина - shop_host. Для этого надо отправить GET запрос на адрес  
  
 
http://'''shop_host'''/admin/applications/'''api_key'''/login?token='''token'''&login='''api_autologin_url'''
 
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, на который будет выполнено перенаправление в приложение.
+
где '''shop_host''' - адрес интернет магазина на под-домене myinsales.ru, '''api_key''' - идентификатора приложения, '''token''' - одноразовый токен (формируете сами, никак не связан с token из установки приложения), '''api_autologin_url''' - URL, на который будет выполнено перенаправление в приложение. Важно(!), чтобы домен из урла api_autologin_url совпадал с доменом из урла входа в приложение из настроек, такая проверка сделана для безопасности.
  
Если пользователь уже вошел в бек-офис магазиа, и у него установлено приложение, его перенаправляют на URL
+
Если пользователь уже вошел в бэк-офис магазина, и у него установлено приложение, его перенаправляют на URL
  
 
'''api_autologin_url'''?token='''MD5(token + password)'''
 
'''api_autologin_url'''?token='''MD5(token + password)'''
  
где '''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 заголовке <code>API-Usage-Limit</code> (пример: <code>API-Usage-Limit: 1/500</code>).
 +
 
 +
При превышении лимита доступ к API становится недоступным до окончания текущих 5 минут. В таком случае код ответа сервера - 503 и при этом в HTTP заголовке <code>Retry-After</code> передается время до начала предоставления доступа в секундах.
 +
 
 +
 
 +
=Возможные варианты http кодов в ответах=
  
Если пользователь еще не вошел в приложение, то ему предложат войти в бек-офис, а потом перенаправят на указанный URL.
+
* 200  - штатный ответ на операцию, означает что никаких ошибок не возникло
 +
* 201 - в некоторых случаях при создании объектов может вернуться этот код, по сути тоже самое, что и 200-й ответ
 +
* 400 - пришел некорректный http-запрос, http-сервер не смог его обработать, возможно слишком большой заголовок или еще какая-то проблема
 +
* 401 - не прошла авторизация, необходимо проверить логин и пароль для basic-авторизации приложения
 +
* 403 - нет прав для данной операции, необходимо проверить настройки прав для приложения
 +
* 404 - запрашиваемый объект не найден, видимо его уже удалили или подставлен ошибочный id объекта
 +
* 500 - внутренняя ошибка на нашей стороне, возможно вы некорректно передали сформировали данные для запроса или что-то еще случилось, необходимо обратиться в поддержку, чтобы разобраться
 +
* 503 - вы привысили лимиты в API,  если вам не хватает лимитов напишите в поддержку, чтобы разобраться в ситуации
 +
* 504 - мы не смогли обработать ваш запрос за 50 секунд и прервали его выполнение, возможно вы пробуете получить слишком много данных за раз или еще какая-то проблема, можно так же обратиться в поддержку

Текущая версия на 12:13, 12 декабря 2018

Введение

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

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

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

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

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

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

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

Для начала вам необходимо создать партнерский аккаунт ( https://www.insales.ru/partnership ) , после в разделе Приложения -> Разработчикам вы сможете создать приложение, указав поля:

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