ПерфектПак · API v1.1
openapi.yaml ↗
Справочник методов / Остатки на складе

Остатки по SKU

GET /stock
Адрес
GET https://api.perfektpak.ru/v1/stock

Тот же адрес и в песочнице — режим выбирает ключ: pp_live_… отвечает боевыми данными, pp_test_… — данными песочницы.

Описание метода

Список остатков на складе по всем кабинетам клиента. Без фильтров возвращает все SKU (у типового селлера их 11–106 — укладывается в одну страницу). Самая часто опрашиваемая ручка API: поддерживает условные запросы через ETag/If-None-Match, чтобы не гонять тело ответа, когда остаток не менялся.

Авторизация

Authorization: Bearer <ключ> Ключ выдаёт менеджер (боевой) или песочница (тестовый).

Параметры запроса

barcode в строке запроса
строка
Точное совпадение по штрихкоду.
search в строке запроса
строка
Подстрока в названии или артикуле, без учёта регистра.
limit в строке запроса
целое число1…1000; по умолчанию 100
Размер страницы. Значение вне диапазона молча округляется до ближайшей границы (0 и меньше — до значения по умолчанию, больше максимума — до максимума); ошибка 400 bad_request — только если значение вообще не целое число.
Пример: 100
cursor в строке запроса
строка
Непрозрачный курсор страницы из next_cursor предыдущего ответа. Не передавайте для первой страницы. Курсор, который мы не выдавали сами, — это 400 bad_cursor, а не тихий возврат к первой странице.
If-None-Match заголовок
строка
Значение заголовка ETag из предыдущего ответа на этот же запрос. Если остаток не менялся, отвечаем 304 без тела.

Ответы

200 OK

Схема: StockItemPage

  • items массив обязательно
    поля элемента — StockItem
    • barcode строка обязательно
    • article строка
      Артикул продавца. Поле опущено, если у товара нет артикула.
    • name строка обязательно
    • quantity целое число обязательно
      Остаток по леджеру склада: заморожено на приёмке минус активные отгрузки FBS плюс/минус ручные корректировки — та же цифра, которой живут кладовщик и админка.
    • available целое число обязательно
      quantity минус in_question — сколько реально можно продавать.
    • in_question целое число обязательно
      Единицы под вопросом (расхождение при приёмке, разбор пересорта и т.п.). Уже включены в quantity, вычитать их ещё раз не нужно.
    • reserved целое число обязательно
      Уже заявлено в открытое задание на подбор. Подмножество quantity, а не дополнительное вычитание из него.
    • boxes целое число обязательно
      Число коробов с этим SKU на хранении.
    • pallets целое число обязательно
      Число паллет с этим SKU на хранении.
    • marketplace_stock массив обязательно
      Остаток по данным кабинета продавца на каждом маркетплейсе — другая природа числа, чем quantity выше (см. /docs, «Почему мои остатки не совпадают»). Пустой массив, если ни один кабинет ещё не синхронизировался.
      поля элемента — MarketplaceStock
      • marketplace строка Marketplace обязательно
        Маркетплейс кабинета. WB — Wildberries, OZON — Ozon.
        Значения: WB OZON
      • quantity целое число обязательно
        Остаток, который отдаёт API маркетплейса по этому SKU. Мы его только зеркалим и никогда не пересчитываем и не сверяем автоматически с quantity в StockItem — числа разной природы.
      • warehouse_id целое число
        Идентификатор склада маркетплейса, если маркетплейс различает свои склады в ответе по остаткам. Поле опущено, когда такой разбивки нет.
      • warehouse_name строка
      • synced_at строка или null обязательно
        Когда мы последний раз успешно опросили маркетплейс за этим остатком, или null, если ни разу. RFC 3339, +03:00 (МСК).
    • updated_at строка обязательно
      Момент последнего скана, изменившего остаток. RFC 3339, +03:00 (МСК).
  • total целое число обязательно
    Число позиций, подходящих под фильтр — не число элементов на этой странице.
  • next_cursor строка или null обязательно
    Курсор следующей страницы для параметра cursor, или null, если это последняя страница.
304 Данные не менялись с прошлого запроса (сверка по ETag/ If-None-Match). Тело ответа пустое.

Тело ответа не возвращается.

400 Параметры запроса не прошли валидацию, либо курсор пагинации не наш или испорчен.

Схема: ErrorResponse

  • error объект Error обязательно
    поля Error
    • code строка ErrorCode обязательно
      Машинный, стабильный код ошибки — ветвитесь в коде по нему, а не по тексту message (он на русском и может измениться). unauthorized — ключ не передан или не существует; key_revoked — ключ существует, но отозван; bad_request — параметры запроса не прошли валидацию; bad_cursor — курсор не наш или испорчен (в отличие от обычного bad_request, здесь нужно перезапросить страницу заново, а не повторять тот же курсор); not_found — ресурса нет либо он принадлежит не вашему client_id (специально неразличимо); rate_limited — превышен лимит запросов; internal — ошибка на нашей стороне. С v1.1: validation_error — поле тела запроса не прошло проверку (поле названо в message); cabinet_required — у вас несколько кабинетов, укажите cabinet_id; mixed_marking — в одной заявке позиции и с маркировкой, и без, разделите на две; write_disabled — заявки через API ещё не включены для вашего ключа; warehouse_unavailable — склад временно не принял заявку, повторите через минуту (заявка не создана); webhook_url_unverified — адрес не ответил 2xx на проверочное событие; webhook_limit — больше 10 подписок; webhooks_unavailable — вебхуки временно выключены; sandbox_only — операция только для тестового ключа.
      Значения: unauthorized key_revoked rate_limited not_found bad_request bad_cursor internal validation_error cabinet_required mixed_marking write_disabled warehouse_unavailable webhook_url_unverified webhook_limit webhooks_unavailable sandbox_only
    • message строка обязательно
      Текст ошибки на русском для лога и для человека — не для ветвления в коде.
    • request_id строка обязательно
      Тот же идентификатор, что и в заголовке X-Request-Id. Присылайте его в поддержку, чтобы нашли конкретный вызов.
401 Ключ не передан или не существует (unauthorized), либо существует, но отозван (key_revoked). Этот ответ единственный, где нет заголовков X-RateLimit-* — они появляются только после того, как ключ прошёл проверку.

Схема: ErrorResponse

  • error объект Error обязательно
    поля Error
    • code строка ErrorCode обязательно
      Машинный, стабильный код ошибки — ветвитесь в коде по нему, а не по тексту message (он на русском и может измениться). unauthorized — ключ не передан или не существует; key_revoked — ключ существует, но отозван; bad_request — параметры запроса не прошли валидацию; bad_cursor — курсор не наш или испорчен (в отличие от обычного bad_request, здесь нужно перезапросить страницу заново, а не повторять тот же курсор); not_found — ресурса нет либо он принадлежит не вашему client_id (специально неразличимо); rate_limited — превышен лимит запросов; internal — ошибка на нашей стороне. С v1.1: validation_error — поле тела запроса не прошло проверку (поле названо в message); cabinet_required — у вас несколько кабинетов, укажите cabinet_id; mixed_marking — в одной заявке позиции и с маркировкой, и без, разделите на две; write_disabled — заявки через API ещё не включены для вашего ключа; warehouse_unavailable — склад временно не принял заявку, повторите через минуту (заявка не создана); webhook_url_unverified — адрес не ответил 2xx на проверочное событие; webhook_limit — больше 10 подписок; webhooks_unavailable — вебхуки временно выключены; sandbox_only — операция только для тестового ключа.
      Значения: unauthorized key_revoked rate_limited not_found bad_request bad_cursor internal validation_error cabinet_required mixed_marking write_disabled warehouse_unavailable webhook_url_unverified webhook_limit webhooks_unavailable sandbox_only
    • message строка обязательно
      Текст ошибки на русском для лога и для человека — не для ветвления в коде.
    • request_id строка обязательно
      Тот же идентификатор, что и в заголовке X-Request-Id. Присылайте его в поддержку, чтобы нашли конкретный вызов.
429 Превышен лимит запросов — 60 в минуту на ключ, с всплеском до 20.

Схема: ErrorResponse

  • error объект Error обязательно
    поля Error
    • code строка ErrorCode обязательно
      Машинный, стабильный код ошибки — ветвитесь в коде по нему, а не по тексту message (он на русском и может измениться). unauthorized — ключ не передан или не существует; key_revoked — ключ существует, но отозван; bad_request — параметры запроса не прошли валидацию; bad_cursor — курсор не наш или испорчен (в отличие от обычного bad_request, здесь нужно перезапросить страницу заново, а не повторять тот же курсор); not_found — ресурса нет либо он принадлежит не вашему client_id (специально неразличимо); rate_limited — превышен лимит запросов; internal — ошибка на нашей стороне. С v1.1: validation_error — поле тела запроса не прошло проверку (поле названо в message); cabinet_required — у вас несколько кабинетов, укажите cabinet_id; mixed_marking — в одной заявке позиции и с маркировкой, и без, разделите на две; write_disabled — заявки через API ещё не включены для вашего ключа; warehouse_unavailable — склад временно не принял заявку, повторите через минуту (заявка не создана); webhook_url_unverified — адрес не ответил 2xx на проверочное событие; webhook_limit — больше 10 подписок; webhooks_unavailable — вебхуки временно выключены; sandbox_only — операция только для тестового ключа.
      Значения: unauthorized key_revoked rate_limited not_found bad_request bad_cursor internal validation_error cabinet_required mixed_marking write_disabled warehouse_unavailable webhook_url_unverified webhook_limit webhooks_unavailable sandbox_only
    • message строка обязательно
      Текст ошибки на русском для лога и для человека — не для ветвления в коде.
    • request_id строка обязательно
      Тот же идентификатор, что и в заголовке X-Request-Id. Присылайте его в поддержку, чтобы нашли конкретный вызов.
500 Ошибка на нашей стороне. request_id стоит передать в поддержку.

Схема: ErrorResponse

  • error объект Error обязательно
    поля Error
    • code строка ErrorCode обязательно
      Машинный, стабильный код ошибки — ветвитесь в коде по нему, а не по тексту message (он на русском и может измениться). unauthorized — ключ не передан или не существует; key_revoked — ключ существует, но отозван; bad_request — параметры запроса не прошли валидацию; bad_cursor — курсор не наш или испорчен (в отличие от обычного bad_request, здесь нужно перезапросить страницу заново, а не повторять тот же курсор); not_found — ресурса нет либо он принадлежит не вашему client_id (специально неразличимо); rate_limited — превышен лимит запросов; internal — ошибка на нашей стороне. С v1.1: validation_error — поле тела запроса не прошло проверку (поле названо в message); cabinet_required — у вас несколько кабинетов, укажите cabinet_id; mixed_marking — в одной заявке позиции и с маркировкой, и без, разделите на две; write_disabled — заявки через API ещё не включены для вашего ключа; warehouse_unavailable — склад временно не принял заявку, повторите через минуту (заявка не создана); webhook_url_unverified — адрес не ответил 2xx на проверочное событие; webhook_limit — больше 10 подписок; webhooks_unavailable — вебхуки временно выключены; sandbox_only — операция только для тестового ключа.
      Значения: unauthorized key_revoked rate_limited not_found bad_request bad_cursor internal validation_error cabinet_required mixed_marking write_disabled warehouse_unavailable webhook_url_unverified webhook_limit webhooks_unavailable sandbox_only
    • message строка обязательно
      Текст ошибки на русском для лога и для человека — не для ветвления в коде.
    • request_id строка обязательно
      Тот же идентификатор, что и в заголовке X-Request-Id. Присылайте его в поддержку, чтобы нашли конкретный вызов.