ПерфектПак · API v1.1
openapi.yaml ↗
Справочник методов / Заказы FBS

Список заказов FBS

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

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

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

Заказы покупателей по FBS с нормализованным статусом (единым для WB и Ozon) и сырой парой статусов маркетплейса. Объём растёт быстро (у крупного селлера — до ~900 заказов в сутки), поэтому для регулярной выгрузки обязательно задавайте created_from/created_to и идите по cursor, а не пытайтесь получить всё одним запросом без окна по датам.

Авторизация

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

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

marketplace в строке запроса
строка
Фильтр по маркетплейсу. Без фильтра — заказы со всех маркетплейсов.
Значения: WB OZON
Пример: WB
status в строке запроса
строка
Фильтр по нормализованному статусу. Без фильтра — заказы во всех статусах.
Значения: NEW ASSEMBLING IN_DELIVERY COMPLETED CANCELLED OTHER
Пример: ASSEMBLING
shipment_id в строке запроса
строка
Фильтр по отгрузке — значение id (не external_id) из GET /shipments. Возвращает заказы этой отгрузки.
barcode в строке запроса
строка
Точное совпадение по штрихкоду.
created_from в строке запроса
строка
Нижняя граница created_at, включительно. RFC 3339 со смещением +03:00 (МСК), например 2026-08-01T00:00:00+03:00; также принимается короткая дата ГГГГ-ММ-ДД — она читается как полночь по Москве.
created_to в строке запроса
строка
Верхняя граница created_at, исключительно. RFC 3339 со смещением +03:00 (МСК), например 2026-08-29T00:00:00+03:00; также принимается короткая дата ГГГГ-ММ-ДД — она читается как полночь по Москве.
limit в строке запроса
целое число1…1000; по умолчанию 100
Размер страницы. Значение вне диапазона молча округляется до ближайшей границы (0 и меньше — до значения по умолчанию, больше максимума — до максимума); ошибка 400 bad_request — только если значение вообще не целое число.
Пример: 100
cursor в строке запроса
строка
Непрозрачный курсор страницы из next_cursor предыдущего ответа. Не передавайте для первой страницы. Курсор, который мы не выдавали сами, — это 400 bad_cursor, а не тихий возврат к первой странице.

Ответы

200 OK

Схема: OrderPage

  • items массив обязательно
    поля элемента — Order
    • id строка обязательно
    • marketplace строка Marketplace обязательно
      Маркетплейс кабинета. WB — Wildberries, OZON — Ozon.
      Значения: WB OZON
    • external_id строка обязательно
      Номер, под которым заказ виден в вашем кабинете маркетплейса (сборочное задание WB, отправление Ozon) — сверяйте с ним глазами.
    • status строка OrderStatus обязательно
      Нормализованный статус заказа, единый для WB и Ozon. Набор закрытый и исчерпывающий: любой заказ попадает ровно в одно значение, OTHER — предохранитель на случай статуса маркетплейса, которого ещё нет в нашей нормализации (заказ не теряется, а виден с этим статусом). NEW — маркетплейс завёл заказ, в наши отгрузки он ещё не попал; ASSEMBLING — уже в отгрузке, отгрузка не закрыта; IN_DELIVERY — отгрузка передана маркетплейсу; COMPLETED — заказ доехал до покупателя; CANCELLED — отменён любой из сторон.
      Значения: NEW ASSEMBLING IN_DELIVERY COMPLETED CANCELLED OTHER
    • status_label строка обязательно
      Человекочитаемая подпись статуса на русском. Формулировка может меняться без анонса — ветвитесь в коде по status, не по этой строке.
    • marketplace_status объект MarketplaceStatus обязательно
      Сырая пара статусов маркетплейса, как есть, без нормализации — по ней служба поддержки селлера спорит с маркетплейсом. Для логики используйте нормализованный Order.status, а не эти значения: набор сырых статусов не закрыт и различается между WB и Ozon.
      поля MarketplaceStatus
      • supplier строка
        Статус поставщика как есть у маркетплейса (WB — supplier_status, Ozon — status). Поле опущено, если маркетплейс его не прислал.
      • buyer строка
        Статус покупателя как есть у маркетплейса (WB — wb_status, Ozon — substatus). Поле опущено, если маркетплейс его не прислал.
      • changed_at строка
        Когда эта пара статусов последний раз менялась, по нашим наблюдениям. Поле опущено, если неизвестно. RFC 3339, +03:00 (МСК).
    • article строка
      Артикул продавца. Поле опущено, если у товара нет артикула.
    • barcode строка
      Штрихкод товара в заказе. Поле опущено, если неизвестен.
    • nm_id целое число
      Артикул WB (nmId). Поле опущено для заказов Ozon и когда номенклатура WB неизвестна.
    • is_b2b логическое обязательно
      Заказ из B2B-поставки (опт для сетей), а не обычный розничный FBS-заказ.
    • shipment_id строка или null обязательно
      Идентификатор нашей отгрузки (id из GET /shipments), в которую попал заказ, или null, пока заказ ни в одну отгрузку не добавлен.
    • shipment_external_id строка или null обязательно
      Номер той же отгрузки в кабинете маркетплейса, или null по той же причине, что и shipment_id.
    • created_at строка обязательно
      Когда маркетплейс создал заказ. RFC 3339, +03:00 (МСК).
    • packed_at строка или null обязательно
      Когда мы закончили собирать заказ, или null, пока сборка не завершена. RFC 3339, +03:00 (МСК).
    • synced_at строка или null обязательно
      Когда мы последний раз обновили состояние заказа из маркетплейса, или null, если ни разу. RFC 3339, +03:00 (МСК).
  • total целое число обязательно
  • next_cursor строка или null обязательно
    Курсор следующей страницы для параметра cursor, или null, если это последняя страница.
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. Присылайте его в поддержку, чтобы нашли конкретный вызов.