Получение остатков через сервис API

Инструкция для клиентов B2B-портала остатков Компании Варум.

1. Что понадобится и безопасность

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

Ключ можно получить у вашего менеджера или запросить по почте zapros@warum.ru.

Только HTTPS — адрес должен начинаться с https://.

2. Что вы получите

По защищённому запросу сервер отдаёт список позиций со склада: артикулы, названия, количества, цену для вашего портала и время обновления. Формат ответа на выбор — XML (удобно для 1С и учётных систем) или JSON (удобно для сайтов и скриптов).

3. Два адреса: таблица в браузере и API для программ

Один и тот же ключ (client_secret) работает в двух местах, но пути разные:

• Портал — обычная страница с таблицей. Откройте https://warum.ru/stock и добавьте ключ: https://warum.ru/stock?client_secret=ВАШ_КЛЮЧ (подставьте свой ключ client_secret). Это не API: здесь нет параметра method, ответ — HTML.
• API для выгрузки — машиночитаемый ответ. Базовый адрес: https://warum.ru/stock/api. Параметры перечисляют после ?: обязательно method и client_secret, остальное — по задаче (см. разделы ниже).

Если ключ на портале не указан или неверен, страница сообщит об ограничении доступа. При неверном ключе к API придёт ответ с кодом 401.

4. Быстрая проверка работы API в браузере

Чтобы убедиться, что ключ подходит к API, один раз откройте ссылку (подставьте свой ключ):

# Вместо ВАШ_КЛЮЧ — подставьте в параметр свой ключ client_secret
https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ&format=json

• При верном ключе (и при наличии открытых для вас категорий и товаров на стороне Компании Варум) отобразится текст ответа в JSON.
• При неверном или пустом ключе — сообщение об ошибке (обычно код 401).

5. Как устроен запрос к API

• Разрешён только GET (как переход по ссылке или скачивание по URL).
• В строке запроса задают имя метода и ключ:
  • GetStock — остатки по всем открытым вам категориям (с опциональными фильтрами).
  • GetStockByCategory — остатки только одной категории; обязателен параметр category= (ID или точное имя).
  • GetCategories — список категорий, доступных ключу (чтобы подставлять category в другие методы).
• Для GetStock и GetStockByCategory можно задавать формат, наличие, артикул, валюту, пагинацию. Для GetCategories обычно достаточно ключа и при необходимости format=json.

6. Метод GetStock

7. Метод GetStockByCategory

Те же поля, что у GetStock, но выборка только из одной категории, если она разрешена вашему ключу. Без category сервер вернёт 400.

# Остатки только категории с id 133, JSON
https://warum.ru/stock/api?method=GetStockByCategory&client_secret=ВАШ_КЛЮЧ&category=133&format=json
# Или
https://warum.ru/stock/api?method=GetStockByCategory&client_secret=ВАШ_КЛЮЧ&category=Ноутбуки&format=json

8. Метод GetCategories

Возвращает категории, открытые вашему порталу, с category_id и category_name. Удобно для подстановки category=… в GetStock или GetStockByCategory.

Ответ. В XML — узел categories с элементами item (category_id, category_name). В JSON — массив categories. Если ни одна категория не включена в настройках портала, список пустой, возможен hint.

# Пример одного элемента categories в XML (не строка остатков)
<item>
  <category_id>133</category_id>
  <category_name>Ноутбуки</category_name>
</item>

9. Что приходит в ответе

В успешном ответе (XML или JSON) обычно есть:

• generated_at — время формирования ответа (московское).
• meta — имя и e-mail портала. Для GetStock и GetStockByCategory дополнительно: currency и при RUB — usd_rub_rate. Для GetCategories в meta только контакты.
• hint — необязательная текстовая подсказка; в JSON поле выводится только если есть текст (при отсутствии подсказки ключа нет, в отличие от null).
• stock (GetStock, GetStockByCategory) — позиции: product_id, category_id, category_name, sku, product_name, vendor, quantity, in_reserve, price, updated.
• categories (GetCategories только) — список категорий с category_id и category_name.

10. Примеры готовых ссылок

В блоках ниже первая строка в рамке — комментарий, вторая — адрес. Подставьте свой ключ вместо ВАШ_КЛЮЧ.

Пример A. Все доступные позиции (GetStock)

# Все доступные позиции (формат XML по умолчанию)
https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ

При необходимости добавьте limit и offset — сколько строк за один ответ и сколько пропустить с начала списка (см. таблицу параметров GetStock).

# Пагинация: по 100 позиций на запрос (первая страница)
https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ&limit=100&offset=0

• limit=100 — не больше 100 строк в этом ответе.
• offset=0 — начать с первой записи; для следующей «страницы» по 100 позиций укажите offset=100, затем 200, 300 и т.д. при том же limit=100.
• Можно задать другой размер порции, например limit=500: тогда вторая порция — offset=500, третья — offset=1000 (максимум строк за запрос по правилам API — 5000).

Пример B. Только в наличии (quantity > 0), JSON

# available=1 и формат json
https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ&available=1&format=json

Пример C. Поиск по артикулу (sku / sku_exact)

# Подстрока в артикуле (LIKE - по части артикула)
https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ&sku=MW1&format=json

# Точное совпадение артикула
https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ&sku_exact=BE400-RS&format=json

К поиску по части артикула (sku) можно добавить цены в рублях — currency=RUB (см. пример E):

https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ&sku=MW1&currency=RUB&format=json

Пример D. Фильтр GetStock по категории (числовой id)

# Подставьте реальный category_id из выдачи
https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ&category=123&format=json

Пример E. Цены в рублях (весь список, без фильтра sku)

# price в RUB; курс в meta (usd_rub_rate)
https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ&currency=RUB&format=json

Пример F. Список категорий в JSON

# Для подстановки в GetStock / GetStockByCategory
https://warum.ru/stock/api?method=GetCategories&client_secret=ВАШ_КЛЮЧ&format=json

11. Коды HTTP при ошибках

12. Для специалиста: curl и Postman

Отдельная «проверка» здесь не обязательна: ключ и ответ API уже можно проверить в браузере (раздел 4). curl и Postman удобны, когда нужен терминал (сервер без браузера, SSH), скрипт или повторяемый запрос с разными параметрами, а также когда важно сразу увидеть код ответа HTTP и заголовки.

curl (часто уже есть в Linux, macOS; в Windows — в PowerShell как алиас или через WSL):

# Кавычки вокруг URL — чтобы & в адресе не восприняла оболочка как свой оператор
curl -sS "https://warum.ru/stock/api?method=GetStock&client_secret=ВАШ_КЛЮЧ&format=json"

В консоль выведется тело ответа (JSON или XML).

Postman (или аналог — Insomnia, Bruno): API и т.д. Создайте запрос GET, вставьте полный URL, как в разделах 4 и 10, либо укажите базовый адрес https://warum.ru/stock/api и во вкладке параметров добавьте method, client_secret и при необходимости format=json. В ответе будут тело, статус (например 200 или 401) и заголовки.

13. Частые вопросы

Документ подготовлен для клиентов портала остатков Компании Варум.