Как интегрироваться с InSales — различия между версиями
(→Добавление приложения) |
|||
| Строка 140: | Строка 140: | ||
При превышении лимита доступ к API становится недоступным до окончания текущих 5 минут. В таком случае код ответа сервера - 503 и при этом в 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 секунд и прервали его выполнение, возможно вы пробуете получить слишком много данных за раз или еще какая-то проблема, можно так же обратиться в поддержку | ||
Версия 07:47, 19 февраля 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:
test.myinsales.ru - имя магазина, которое пришло в пункте 1.
my_app_key - идентификатор приложения, который был указан в настройках при его создании
token - случайная одноразовая фраза
login - урл, где мы ждем пользователя назад для логина после редиректа с InSales
4. На стороне InSales идет проверка по сессии, что пользователь залогинен в этот магазин и если все нормально редирект его назад в приложение:
token2 - MD5(token + user_email + user_name + user_id +password) - md5-сумма от токена, которыл был передан в пункте 3, параметров user_email, user_name, user_id и пароля приложения, который был сформирован при его установке, по этому 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 секунд и прервали его выполнение, возможно вы пробуете получить слишком много данных за раз или еще какая-то проблема, можно так же обратиться в поддержку
