Авторизация и доступ
Как часто необходимо обновлять токен?
Токен живёт expires_in секунд из ответа метода POST /v2/auth-token .
Обновляйте токен заранее, ориентируясь на актуальное значение expires_in, не сохраняйте это значение в константу; при 401 обновите токен и повторите запрос один раз. Токен выпускается и обновляется с помощью метода POST /v2/auth-token.
Получаю 401 при вызове API-метода, хотя токен свежий.
Токен передаётся только заголовком Authorization: Bearer <access_token> — не query-параметром и обязательно с префиксом Bearer. Передача токена query-параметром — частая причина 401 со свежим токеном.
Верно ли, что одни и те же client_id/client_secret работают для всех версий API?
Да, верно.
Списки и пагинация
При передачи параметра limit=500 в ответе приходит меньшее количество записей или ошибка. Почему?
Лимит страницы валидируется: если он больше максимума, допустимого в методе, приходит 400 VALIDATION_FAILED.
Максимумы у разных методов отличаются:
- у методов GET /v2/nomenclatures, GET /v2/minimal-prices, GET /v2/nomenclatures-sell-values — 25
- у всех остальных методов — 1000
Фактический максимум смотрите в справочнике соответствующего метода. Для полной выгрузки листайте по page; фактический размер страницы смотрите в параметре meta.limit.
GET /v2/nomenclatures возвращает 400
Список номенклатур в v2 требует обязательный query-параметр country (RU / BY / KZ): без него вы получите 400 «query: "country": field required».
Фильтрую заказы ?filter=status=confirmed — приходит всё подряд
В v2 сериализованной строки filter из v1 нет: фильтры — это отдельные явные query-параметры (например, statusGroup, updatedAtFrom/updatedAtTo).
Неизвестный параметр сервер молча игнорирует.
Заказы, отгрузки, возвраты
Перестали приходить возвратные статусы по заказам — куда смотреть?
Возвраты читаются отдельными методами (только модель FBS):
GET /v2/fbs/return-items (плюс их status-history и summary).
Отслеживайте возвраты через них, а не через статусы заказа.
События и нагрузка
Нотификации приходят не все — как получить недостающие?
Источником истины по заказам является поллинг (регулярный опрос GET /v2/orders по updatedAtFrom), а нотификации через webhooks — это "ускоритель" доставки событий без гарантии, поэтому пропуски необходимо закрывать поллингом за выбранный период.
Подробнее читайте в статье «Синхронизация и события».
Какие существуют лимиты по частоте запросов к API?
Конкретные лимиты по частоте запросов в API не декларированы для внешних пользователей. При превышении лимитов в сообщении об ошибке вы получите ответ TOO_MANY_REQUESTS и HTTP-код 429.
Практические рекомендации по управлению лимитами: держите размер батча умеренным (порядка ≤100 элементов), делайте паузу между запросами и повторяйте с увеличивающейся паузой при 429/503.
См. также
Помогла эта информация?
Спасибо за отзыв