Как сделать запрос к API?

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

Предполагается, что работа с API организована на внешнем сервере (НЕ на сервере платформы), который отправляет к серверу платформы запросы определенного типа. Для удобства в этой статье будет рассмотрена отправка запросов при помощи приложения Postman. В качестве альтернативы можно использовать Advanced REST Client.

Все доступные запросы в форматах XML и JSON описаны на api.insales.ru. Типовые запросы в формате XML с более подробным описанием можно найти на api.insales.ru.

1. Ограничения
2. Авторизация
3. Общие принципы
4. Примеры XML-запросов
5. Примеры JSON-запросов
6. Возможные коды ответов сервера

Ограничения

На платформе присутствует ограничение в 500 запросов к API в течение 5 минут. Время рассчитывается с момента первого запроса в серии. Количество выполненных запросов в текущем промежутке времени передается в HTTP-заголовке API-Usage-Limit (например, API-Usage-Limit: 1/500).

При достижении лимита доступ к API ограничивается до окончания текущих 5 минут. При этом в HTTP-заголовке Retry-After передается время в секундах до восстановления доступа.

Авторизация

Для отправки запросов к API необходимо создать ключ доступа.

Внимание! Не используйте логин-пароль от бэк-офиса для работы с API, иначе ваш аккаунт может быть заблокирован.

Для создания ключа доступа нужно в бэк-офисе перейти в раздел "Приложения" → "Разработчикам" и нажать кнопку "Создать новый ключ доступа". При необходимости можно указать его название.

Далее в статье мы будем использовать созданные логин (идентификатор) и пароль. Их можно указывать как в адресе запроса:

https://логин:пароль@shop-47483-27.myinsales.ru/admin/orders.xml

Так и в виде HTTP-заголовка Authorization:

Authorization: Basic ZGlnaXRhbC1nb29kczpjNTFjOTA3MDdhMTNjZTNmZmYyMTNhZmJiNWNkMTI3MA==

Вместо shop-47483-27.myinsales.ru необходимо использовать технический или обычный домен вашего магазина. Его можно взять, например, из строки "Пример URL" около выданного ключа доступа.

Общие принципы

API InSales принимает POST, GET, PUT и DELETE-запросы в зависимости от выполняемого действия. Тип и адрес запроса для требуемого действия можно найти на api.insales.ru.

Текст самого запроса должен соответствовать формату XML или JSON. В зависимости от формата меняется адрес запроса и значение HTTP-заголовка Content-Type.

Для XML необходим Content-Type: application/xml

А для JSON - Content-Type: application/json

На скриншоте программы Postman показан выбранный тип запроса, адрес и заголовки. После нажатия кнопки Send появится ответ сервера InSales.

Примеры XML-запросов

Рассмотрим GET-запрос к товару с id 143570988. Такой запрос не требует передачи серверу каких-либо параметров. В качестве адреса необходимо указать https://логин:пароль@shop-47483-27.myinsales.ru/admin/products/143570988.xml

В ответ сервер пришлёт всю доступную информацию об этом товаре.

PUT-запрос служит для обновления данных выбранного объекта. Для обновления названия того же товара с id 143570988 потребуется отправить запрос с телом

<?xml version="1.0" encoding="UTF-8"?>
<product>
<title>Новое название</title>
</product>

В ответ сервер пришлёт обновлённую информацию о товаре (в том числе новое название). Соответственно, в бэк-офисе также будет отображаться новое название товара. В ответе виден код 200, что означает успешное выполнение операции.

Примеры JSON-запросов

Запросы в формате JSON отличаются адресом и заголовком Content-Type.

GET-запрос отправляется на адрес https://логин:пароль@shop-47483-27.myinsales.ru/admin/products/143570988.json . Ответ, соответственно, также будет этом формате.

Тело PUT-запроса на обновление названия товара выглядит следующим образом:

Возможные коды ответов сервера

• 200 - штатный ответ на операцию; означает, что никаких ошибок не возникло
• 201 - в некоторых случаях при создании объектов может вернуться этот код; по смыслу не отличается от кода 200
• 400 - некорректный HTTP-запрос, сервер не смог его обработать
• 401 - не удалось авторизоваться (необходимо проверить логин и пароль)
• 403 - нет прав для данной операции (необходимо проверить настройки прав для приложения)
• 404 - запрашиваемый объект не найден (возможно, его уже удалили или указан неверный id объекта)
• 429 - превышен лимит запросов к API
• 500 - внутренняя ошибка сервера (возможно, вы некорректно сформировали запрос или что-то сломалось на нашей стороне; необходимо обратиться в тех поддержку)
• 504 - сервер не смог обработать ваш запрос за 50 секунд и прервал его выполнение (возможно, вы пытаетесь получить слишком много данных за один запрос)