Wildberries Seller API
Локальный снимок OpenAPI-спецификаций в swagger/*.yaml — единственный источник истины по этому API. Отвечай по нему, а не по памяти: WB меняет эндпоинты часто, и то, что ты помнишь, скорее всего устарело.
Порядок работы
Помощник требует PyYAML. Если его нет: python -m pip install -r requirements.txt.
- Начинай с компактных запросов к снимку:
- обзор разделов:
python scripts/wb.py map
- поиск:
python scripts/wb.py search "<запрос>" --limit 15
- конкретный эндпоинт:
python scripts/wb.py detail <METHOD> <PATH>
- со схемами тела и ответов:
python scripts/wb.py detail <METHOD> <PATH> --schemas
- авторизация, хосты, токены, коды:
python scripts/wb.py protocol
- Сырой
swagger/*.yaml открывай только когда вывода скрипта не хватает: нужны вложенные примеры, значения enum или длинное описание целиком. Целиком файлы не читай — они по 100–350 КБ.
- Целостность снимка:
python scripts/wb.py validate.
Свежесть
Перед содержательным ответом по API сверься с python scripts/wb.py stale.
Снимок старше 30 дней — скажи об этом пользователю прямо: назови дату снимка и предложи git pull (снимок в репозитории обновляет мейнтейнер). Если и там несвежо — предложи собрать свой снимок: python scripts/update.py. Не делай вид, что данные свежие.
Если пользователь ждёт эндпоинт, которого в снимке нет, — так и скажи: «в снимке от такой-то даты этого нет». Не выдумывай путь и не подгоняй похожий. Предложи обновить снимок.
Правила ответа
- Указывай метод, путь, хост, файл-источник (
swagger/NN-name.yaml), схему авторизации, тип токена и релевантные коды ответов.
- Хост бери с самой операции: у WB он разный для разных доменов (
content-api, marketplace-api, advert-api, statistics-api, seller-analytics-api, common-api и другие). Общего хоста нет.
- Лимиты запросов WB в машиночитаемом виде не публикует — они описаны текстом внутри
description конкретной операции. Приводи их оттуда дословно, не выдумывай числа.
- Не сочиняй общие правила протокола. Всё, что говоришь про авторизацию, песочницу или статус-коды, должно опираться на
securitySchemes, servers, x-token-types и responses из снимка.
- Эндпоинт с
deprecated: true предлагай только если замены нет, и обязательно предупреждай.
Генерация кода
- Токен читай из переменной окружения или конфига, никогда не зашивай в код.
- Передавай токен в заголовке
Authorization по схеме HeaderApiKey — как есть, без префикса Bearer.
- Базовый URL бери с той операции, которую вызываешь.
- Пагинацию, поллинг задач, ретраи и валидацию полей добавляй только там, где этого требует схема или описание эндпоинта.
Обновление снимка
Обычный путь — git pull: снимок сверяется с порталом WB примерно раз в месяц, изменения описаны в релизах и CHANGELOG.md.
python scripts/update.py — собрать свежий снимок самому: качает спеки напрямую с dev.wildberries.ru, проверяет результат до записи и дописывает в CHANGELOG.md, что изменилось в API. Нужен браузер и requirements-update.txt. Подробности в README.md.