Одна отгрузка с заказами внутри

GET /shipments/{id}

Адрес

GET https://api.perfektpak.ru/v1/shipments/{id}

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

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

То же, что элемент списка GET /shipments, плюс orders — заказы, вошедшие в эту отгрузку.

Авторизация

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

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

id обязательный в пути

строка

Идентификатор отгрузки (id из GET /shipments).

Ответы

200 OK

Схема: 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 (МСК).

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. Присылайте его в поддержку, чтобы нашли конкретный вызов.

404 Ресурса с таким идентификатором нет — в том числе если он существует, но принадлежит не вашему client_id. API намеренно не различает эти два случая (подробнее — в /docs), поэтому чужой объект тоже отвечает 404, а не 403.

Схема: 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/{id}" \
  -H "Authorization: Bearer $PP_KEY"

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

Content-Type: application/json

{
  "id": "s_wb_2026_0825_12",
  "marketplace": "WB",
  "external_id": "WB-1082345671",
  "name": "Поставка 25.08 — кофе и косметика",
  "status": "ACCEPTED",
  "status_label": "Принята складом маркетплейса",
  "orders_count": 2,
  "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",
  "orders": [
    {
      "id": "o_5f6a7b8c9d",
      "marketplace": "WB",
      "external_id": "WB-88213456",
      "status": "COMPLETED",
      "status_label": "Завершён",
      "marketplace_status": {
        "supplier": "complete",
        "buyer": "sold",
        "changed_at": "2026-08-28T09:12:00+03:00"
      },
      "article": "COFFEE-1KG-BRIZ",
      "barcode": "4680012340015",
      "nm_id": 123456789,
      "is_b2b": false,
      "shipment_id": "s_wb_2026_0825_12",
      "shipment_external_id": "WB-1082345671",
      "created_at": "2026-08-25T11:20:00+03:00",
      "packed_at": "2026-08-25T15:40:00+03:00",
      "synced_at": "2026-08-29T14:50:00+03:00"
    },
    {
      "id": "o_5f6a7b8c9e",
      "marketplace": "WB",
      "external_id": "WB-88213457",
      "status": "COMPLETED",
      "status_label": "Завершён",
      "marketplace_status": {
        "supplier": "complete",
        "buyer": "sold",
        "changed_at": "2026-08-28T09:14:00+03:00"
      },
      "article": "CREAM-HAND-SILK-75",
      "barcode": "4680012340022",
      "nm_id": 123456790,
      "is_b2b": false,
      "shipment_id": "s_wb_2026_0825_12",
      "shipment_external_id": "WB-1082345671",
      "created_at": "2026-08-25T11:22:00+03:00",
      "packed_at": "2026-08-25T15:41:00+03:00",
      "synced_at": "2026-08-29T14:50:00+03:00"
    }
  ]
}

Ключ не передан или не существует (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"
  }
}

Ресурса с таким идентификатором нет — в том числе если он существует, но принадлежит не вашему client_id. API намеренно не различает эти два случая (подробнее — в /docs), поэтому чужой объект тоже отвечает 404, а не 403.

{
  "error": {
    "code": "not_found",
    "message": "Запрошенный объект не найден.",
    "request_id": "e5f60718-9203-1234-ef01-345678901234"
  }
}

Превышен лимит запросов — 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"
  }
}

Попробовать

id (path)

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