Перейти к содержанию

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

API бэк-офиса создаёт, читает, изменяет и удаляет объекты магазина: товары, заказы, клиентов и остальные ресурсы из справочника InSales API.

Запрос идёт на адрес магазина, параметр shop при установке приложения. Путь ресурса начинается с /admin/, формат задаётся суффиксом .json или .xml.

GET https://SHOP/admin/account.json

Авторизация — HTTP Basic. Логин — идентификатор приложения, пароль — пароль этого приложения в конкретном магазине. Пароли разных магазинов не совпадают.

GET, HEAD и DELETE проходят без Content-Type. У POST, PUT и PATCH заголовок обязателен и должен совпадать с суффиксом адреса: application/json для .json, application/xml для .xml. Если тип другой, ответ 422, в теле {"message":"incorrect Content-Type, should be application/json"} или то же сообщение для application/xml.

Вопросы по приложениям: partners@insales.ru.

Лимит запросов

На одно приложение в одном магазине — 500 запросов за 5 минут. Окно считается от первого запроса серии. В счётчик входит и запрос с неверным паролем. Счётчик приходит в заголовке API-Usage-Limit, например API-Usage-Limit: 1/500.

Запрос сверх лимита получает 429 Too Many Requests. В заголовке Retry-After — число секунд до конца текущего окна. Тело такого ответа пустое.

Коды ответов

  • 200 — операция выполнена.
  • 201 — объект создан.
  • 400 — тело не разобрано, например в .json пришёл невалидный JSON.
  • 401 — не прошла Basic-авторизация.
  • 403 — у приложения нет права на операцию. Тело: {"status":"error","message":"..."}.
  • 404 — объект не найден.
  • 422 — неверный Content-Type или поля не прошли проверку.
  • 429 — исчерпан лимит, см. Retry-After.

Установка приложения

Приложение создаётся в партнёрском кабинете. Для установки задаются идентификатор (он же логин Basic), секрет и URL установки без параметров, например https://myapp.example/install.

Покупатель нажимает «Установить». InSales создаёт одноразовый token и пароль магазина:

password = MD5(token + secret)

Строки склеиваются без разделителя, берётся hex-дайджест в нижнем регистре. Этот пароль нужно сохранить у себя: token повторно не присылают.

Затем на URL установки уходит GET:

https://myapp.example/install?shop=SHOP&token=TOKEN&insales_id=INSALES_ID
  • shop — адрес магазина, на него дальше уходят запросы API.
  • insales_id — постоянный идентификатор магазина.
  • token — одноразовая строка для расчёта пароля.

Пароль уже создан к моменту этого GET, поэтому в обработчике установки можно сразу вызывать API, например создать вебхуки. Ответ обработчика — ровно 200, и он должен прийти в течение 10 секунд. Другой статус или таймаут отменяет установку, и пароль перестаёт действовать.

Вход пользователя в приложение

Кнопка входа открывает URL входа из настроек приложения и добавляет параметры:

https://myapp.example/login?shop=SHOP&insales_id=INSALES_ID&user_id=USER_ID&user_email=USER_EMAIL

Если своей сессии нет, приложение отправляет браузер на автологин магазина:

https://SHOP/admin/applications/API_KEY/login?token=TOKEN&login=https://myapp.example/autologin

API_KEY — идентификатор приложения. token приложение придумывает само, это не token установки. Домен параметра login должен совпадать с доменом URL входа: проверяется домен второго уровня.

Если пользователь уже в бэк-офисе и приложение установлено, магазин возвращает его на login и дописывает параметры:

  • token — MD5(token + password)
  • user_email, user_name, user_id
  • token2 — MD5(token + user_email + user_name + user_id + password)
  • email_confirmed — true или false
  • token3 — MD5(token + user_email + user_name + user_id + email_confirmed + password)

password здесь — пароль приложения в этом магазине. По token3 можно убедиться, что переход пришёл из бэк-офиса.

Удаление приложения

На URL удаления уходит GET:

UNINSTALL_URL?shop=SHOP&token=PASSWORD&insales_id=INSALES_ID

token в этом запросе — пароль приложения в магазине, не секрет и не token установки.

Что читать дальше

Справочник методов — api.insales.ru. Рядом разобраны сценарии, которых в справочнике нет целиком: