Список отгрузок

GET /shipments

Адрес

GET https://api.perfektpak.ru/v1/shipments

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

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

Отгрузки — то, что мы собрали и передали в маркетплейс (у WB это называется «поставка»; не путать с ресурсом receipt — привозом товара селлером к нам, см. глоссарий в /docs).

Авторизация

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

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

marketplace в строке запроса

строка

Фильтр по маркетплейсу. Без фильтра — отгрузки во все маркетплейсы.

Значения: WB OZON

Пример: WB

status в строке запроса

строка

Фильтр по статусу отгрузки. Без фильтра — отгрузки во всех статусах.

Значения: ASSEMBLING HANDED_OVER ACCEPTED

Пример: HANDED_OVER

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…200; по умолчанию 50

Размер страницы. Значение вне диапазона молча округляется до ближайшей границы (0 и меньше — до значения по умолчанию, больше максимума — до максимума); ошибка 400 bad_request — только если значение вообще не целое число.

Пример: 50

cursor в строке запроса

строка

Непрозрачный курсор страницы из next_cursor предыдущего ответа. Не передавайте для первой страницы. Курсор, который мы не выдавали сами, — это 400 bad_cursor, а не тихий возврат к первой странице.

Ответы

200 OK

Схема: ShipmentPage

items массив обязательно
поля элемента — Shipment
- id строка обязательно
- marketplace строка Marketplace обязательно
  
  Маркетплейс кабинета. WB — Wildberries, OZON — Ozon.
  
  Значения: WB OZON
- external_id строка обязательно
  
  Номер отгрузки в кабинете маркетплейса (у WB это и есть «поставка WB №…»).
- name строка
  
  Название отгрузки, если ему его давали. Поле опущено, если названия нет.
- status строка ShipmentStatus обязательно
  
  Статус отгрузки — партии заказов, которую мы передаём маркетплейсу (у WB в кабинете она называется «поставка»). ASSEMBLING — отгрузка открыта, мы ещё докладываем в неё заказы; HANDED_OVER — закрыта с нашей стороны и передана маркетплейсу; ACCEPTED — маркетплейс отсканировал отгрузку на своём складе или сортировочном центре.
  
  Значения: ASSEMBLING HANDED_OVER ACCEPTED
- status_label строка обязательно
- orders_count целое число обязательно
  
  Число заказов в отгрузке.
- created_at строка обязательно
  
  Когда отгрузку открыли. RFC 3339, +03:00 (МСК).
- closed_at строка или null обязательно
  
  Когда отгрузку закрыли с нашей стороны, или null, пока она ещё собирается. RFC 3339, +03:00 (МСК).
- accepted_at строка или null обязательно
  
  Момент, когда маркетплейс отсканировал отгрузку на своём складе или сортировочном центре — юридически значимый факт приёма, или null, пока этого не произошло. RFC 3339, +03:00 (МСК).
- orders массив
  
  Заказы внутри отгрузки. Поле присутствует только в ответе GET /shipments/{id} — в списке GET /shipments его нет.
  поля элемента — 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. Присылайте его в поддержку, чтобы нашли конкретный вызов.

Пример запроса

curl "https://api.perfektpak.ru/v1/shipments?marketplace=WB&status=HANDED_OVER&limit=50" \
  -H "Authorization: Bearer $PP_KEY"

Примеры ответа

Content-Type: application/json

{
  "items": [
    {
      "id": "s_wb_2026_0825_12",
      "marketplace": "WB",
      "external_id": "WB-1082345671",
      "name": "Поставка 25.08 — кофе и косметика",
      "status": "ACCEPTED",
      "status_label": "Принята складом маркетплейса",
      "orders_count": 180,
      "created_at": "2026-08-25T09:00:00+03:00",
      "closed_at": "2026-08-25T18:30:00+03:00",
      "accepted_at": "2026-08-26T07:15:00+03:00"
    },
    {
      "id": "s_wb_2026_0827_13",
      "marketplace": "WB",
      "external_id": "WB-1082345699",
      "status": "ASSEMBLING",
      "status_label": "Собирается",
      "orders_count": 64,
      "created_at": "2026-08-27T10:00:00+03:00",
      "closed_at": null,
      "accepted_at": null
    }
  ],
  "total": 41,
  "next_cursor": null
}

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

Недопустимое значение параметра-перечисления

{
  "error": {
    "code": "bad_request",
    "message": "Некорректное значение параметра \"status\": \"SHIPPED\". Допустимые значения: NEW, ASSEMBLING, IN_DELIVERY, COMPLETED, CANCELLED, OTHER.",
    "request_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890"
  }
}

Некорректный формат даты

{
  "error": {
    "code": "bad_request",
    "message": "Некорректное значение параметра \"created_from\": используйте RFC 3339 (например, 2026-08-29T00:00:00+03:00) или дату в формате ГГГГ-ММ-ДД.",
    "request_id": "a7b8c9d0-1e2f-3405-abcd-ef1234567891"
  }
}

Курсор пагинации не наш или испорчен

{
  "error": {
    "code": "bad_cursor",
    "message": "Курсор недействителен. Запросите первую страницу заново, без параметра \"cursor\".",
    "request_id": "b2c3d4e5-6f70-8901-bcde-f12345678901"
  }
}

Ключ не передан или не существует (unauthorized), либо существует, но отозван (key_revoked). Этот ответ единственный, где нет заголовков X-RateLimit-* — они появляются только после того, как ключ прошёл проверку.

Ключ не передан

{
  "error": {
    "code": "unauthorized",
    "message": "Ключ API не передан. Передайте его в заголовке \"Authorization: Bearer \u003cключ\u003e\" или \"X-Api-Key\".",
    "request_id": "c3d4e5f6-7081-9012-cdef-123456789012"
  }
}

Ключ отозван

{
  "error": {
    "code": "key_revoked",
    "message": "Ключ отозван 14.08.2026.",
    "request_id": "d4e5f607-8192-0123-def0-234567890123"
  }
}

Превышен лимит запросов — 60 в минуту на ключ, с всплеском до 20.

{
  "error": {
    "code": "rate_limited",
    "message": "Превышен лимит запросов: 60 в минуту на ключ. Повторите попытку позже.",
    "request_id": "f6071829-0314-2345-f012-456789012345"
  }
}

Ошибка на нашей стороне. request_id стоит передать в поддержку.

{
  "error": {
    "code": "internal",
    "message": "Внутренняя ошибка сервиса. Мы её видим — повторите попытку или обратитесь в поддержку.",
    "request_id": "07182930-4152-3456-0123-567890123456"
  }
}

Попробовать

marketplace (query) status (query) created_from (query) created_to (query) limit (query) cursor (query)

Запрос уходит с тестовым ключом песочницы, сохранённым в этом браузере; боевые данные так не получить.