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

Материал из Insales Wiki
Перейти к: навигация, поиск
(Процедура удаления аккаунта)
(Процедура авто-логина пользователя)
 
(не показана 21 промежуточная версия 2 участников)
Строка 5: Строка 5:
 
Кроме того, есть механизм позволяющий другим пользователям подключить написанную Вами интеграцию нажатием одной кнопки.
 
Кроме того, есть механизм позволяющий другим пользователям подключить написанную Вами интеграцию нажатием одной кнопки.
 
Это механизм называется [[Расширение системы с помощью приложений|приложениями]].
 
Это механизм называется [[Расширение системы с помощью приложений|приложениями]].
 +
 +
Так же рекомендуем посмотреть презентацию 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 есть webhook-и: для определенных событий по заданному HTTP адресу отправляется POST запрос. В теле запроса в xml формате передается объект, с которым связанно событие. Для того чтобы оповещение заработало, надо [[InSales API - Webhooks|через API установить обработчик]], для событий соответствующего типа. Пока доступны три типа событий: создание, изменение и удаление заказа.
 
  
=Создание приложения=
+
password = MD5(token + secret_key) = MD5("token123mysecret") = 4c3f4c197336eb97475506e71c839c71
  
==Добавление приложения==
 
  
Для того чтобы разместить кнопку для установки приложения надо получить согласие от администрации и создать тестовое приложение в разделе Приложения -> Разработчикам, указав поля:
+
3. Теперь можно послать запрос по API в магазин:
* Название приложения (будет показываться в списке приложений)
 
* Идентификатор приложения (должен состоять из латинских букв и цифр, используется для авторизации)
 
* Секретный ключ приложения (он не должен быть никому известен, используется для установки приложения)
 
* Текст краткого описания приложения (в html формате, будет показываться в списке приложений)
 
* URL для установки приложения (без параметров)
 
* URL страницы приложения, куда попадает пользователь после нажатия кнопки установки приложения
 
* URL страницы приложения, куда попадает шлется запрос для удаления приложения
 
* Картинку приложения, размером 250x100
 
* Название компании разработчика
 
* Контакты для пользователей
 
  
==Процедура установки==
 
  
После того как пользователь нажал кнопку установить приложение InSales генерирует '''token''' (одноразовая строка, хранить у себя не нужно) и устанавливает пароль для подключения '''password = MD5(token + secret_key)''', где '''seсret_key''' - секретный ключ приложения.  
+
http://myapplogin:4c3f4c197336eb97475506e71c839c71@test.myinsales.ru/admin/account.xml
  
После этого отправляется GET запрос на URL для установки приложений с параметрами '''token''' , '''shop''' и '''insales_id''', где '''shop''' - адрес магазина на домене myinsales.ru, например myshop.myinsales.ru ,  '''insales_id''' - внутренний уникальный иденитификатор магазина,  который не меняется и по нему однозначно идентифицируется магазин.
+
=Авторизация=
  
Если приложение отвечает 200 OK, то InSales считает, что приложение успешно установлено. Теперь можно слать запросы к insales через API используя сгенерированный пароль и идентификатор приложения в качестве логина.
+
Для авторизации используется Basic Authorization. Логин задается в настройках приложения (идентификатор приложения) и он общий при запросах в разные магазины, пароль же формируется в момент установки, процедура описана выше.
  
Поле того как приложение ответило 200 OK, приложение может установить свои обработчики для событий, создать в InSales необходимые данные или загрузить данные в приложение из InSales.
+
=Оповещение о событии=
  
Особое внимание надо обратить на то, что до тех пор пока InSales не получили ответ 200 OK  в ответ на запрос установки приложение считается не установленным, и оно не может совершать запросы к InSales через API.
+
Для оповещения о событиях, в InSales есть webhook-и: для определенных событий по заданному HTTP адресу отправляется POST запрос. В теле запроса в xml формате передается объект, с которым связанно событие. Для того чтобы оповещение заработало, надо [[InSales API - Webhooks|через API установить обработчик]], для событий соответствующего типа. Пока доступны три типа событий: создание, изменение и удаление заказа.
  
 
==Процедура авто-логина пользователя==
 
==Процедура авто-логина пользователя==
Строка 70: Строка 86:
 
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''' - одноразовый токен (формируете сами, никак не связан с token из установки приложения), '''api_autologin_url''' - URL, на который будет выполнено перенаправление в приложение.
+
где '''shop_host''' - адрес интернет магазина на под-домене myinsales.ru, '''api_key''' - идентификатора приложения, '''token''' - одноразовый токен (формируете сами, никак не связан с token из установки приложения), '''api_autologin_url''' - URL, на который будет выполнено перенаправление в приложение. Важно(!), чтобы домен из урла api_autologin_url совпадал с доменом из урла входа в приложение из настроек, такая проверка сделана для безопасности.
  
 
Если пользователь уже вошел в бэк-офис магазина, и у него установлено приложение, его перенаправляют на URL
 
Если пользователь уже вошел в бэк-офис магазина, и у него установлено приложение, его перенаправляют на URL
Строка 76: Строка 92:
 
'''api_autologin_url'''?token='''MD5(token + password)'''
 
'''api_autologin_url'''?token='''MD5(token + password)'''
  
где '''password''' - пароль приложения.
+
где '''password''' - пароль приложения в конкретном магазине (не путать с секретным ключем приложения).
  
 
Если пользователь еще не вошел в приложение, то ему предложат войти в бэк-офис, а потом перенаправят на указанный URL.
 
Если пользователь еще не вошел в приложение, то ему предложат войти в бэк-офис, а потом перенаправят на указанный URL.
Строка 86: Строка 102:
 
1. Пользователя кидает урл входа в приложение, который указан его настройках. В GET-параметрах передаются название и id магазина, например:  
 
1. Пользователя кидает урл входа в приложение, который указан его настройках. В GET-параметрах передаются название и id магазина, например:  
  
http://myapp.ru/login?shop=test.myinsales.ru&insales_id=123
+
http://myapp.ru/login?shop=test.myinsales.ru&insales_id=123&user_id=1
  
 
2. Приложение смотрит сессию в cookies пользователя и если он уже логинился, то все в порядке, показывает ему бэкофис приложения.
 
2. Приложение смотрит сессию в cookies пользователя и если он уже логинился, то все в порядке, показывает ему бэкофис приложения.
Строка 104: Строка 120:
 
4. На стороне InSales идет проверка по сессии, что пользователь залогинен в этот магазин и если все нормально редирект его назад в приложение:
 
4. На стороне InSales идет проверка по сессии, что пользователь залогинен в этот магазин и если все нормально редирект его назад в приложение:
  
http://myapp.ru/autologin?token=c7a19acbbd574b0391233bf946f653fd
+
http://myapp.ru/autologin?token3=c7a19acbbd574b0391233bf946f653fd&user_email=user@myshop.ru&user_name=igor&user_id=1&email_сonfirmed=true
  
token - MD5(token + password) - md5-сумма от токена, которыл был передан в пункте 3 и пароля приложения, который был сформирован при его установке,
+
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, а не подделал этот урл.
 
по этому token можно убедиться,  чтобы пользователь действительно логинен в магазин на InSales, а не подделал этот урл.
  
Строка 123: Строка 139:
 
На приложение накладываются ограничение в 500 запросов к API одного магазина за 5 минут. Время расчитывается с момента первого запроса в серии. Количество выполненых запросов в текущем промежутке времени передается в HTTP заголовке <code>API-Usage-Limit</code> (пример: <code>API-Usage-Limit: 1/500</code>).
 
На приложение накладываются ограничение в 500 запросов к API одного магазина за 5 минут. Время расчитывается с момента первого запроса в серии. Количество выполненых запросов в текущем промежутке времени передается в HTTP заголовке <code>API-Usage-Limit</code> (пример: <code>API-Usage-Limit: 1/500</code>).
  
При превышении лимита доступ к API становится недоступным до окончания текущих 5 минут. При этом в HTTP заголовке <code>Retry-After</code> передается время до начала предоставления доступа в секундах.
+
При превышении лимита доступ к API становится недоступным до окончания текущих 5 минут. В таком случае код ответа сервера - 503 и при этом в HTTP заголовке <code>Retry-After</code> передается время до начала предоставления доступа в секундах.
 +
 
 +
 
 +
=Возможные варианты http кодов в ответах=
 +
 
 +
* 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 секунд и прервали его выполнение, возможно вы пробуете получить слишком много данных за раз или еще какая-то проблема, можно так же обратиться в поддержку