Заказы, FBS и этикетки

Часть руководства «Переход на Lamoda Seller API v2».

Эта глава описывает переход заказных и FBS-сценариев с B2B REST v1 и Seller JSON-RPC на Seller API v2.

Новый порядок работы с FBS-заказом

1. Получить заказы: GET /v2/orders?sellerId=....
2. Получить детали заказа: GET /v2/orders/{orderId}?sellerId=.... ⚠️ В path идёт поле id из списка заказов, а не групповой orderId — по orderId будет 404.
3. Получить историю заказа и позиций: GET /v2/orders/{orderId}/status-history, GET /v2/orders/{orderId}/item-statuses.
4. Создать сборку: POST /v2/orders/{orderId}/assembly.
5. Сгенерировать паковые штрихкоды: POST /v2/orders/{orderId}/packs?sellerId=....
6. Сформировать этикетки.
7. Создать или получить FBS-отгрузку.
8. Менять статус заказа/позиции только если это разрешено сценарием обработки конкретного заказа.

Получение заказов

Методы чтения и изменения customer и shipping address относятся к устаревшей модели сотрудничества. Они станут deprecated и позже будут выключены.

Изменение статусов заказа и позиции

Методы:

• POST /v2/orders/{orderId}/status;
• POST /v2/orders/{orderId}/items/{itemId}/status.

{
  "sellerId": "242541217",
  "status": "CANCELED",
  "reason": "Нет остатка для отгрузки"
}

Важные правила:

• reason обязателен для CANCELED и NOT_DELIVERED;
• для остальных статусов reason передавать нельзя;
• по схеме тела запроса reason — строка; допустимость значения и причины проверяется на стороне Lamoda в рамках сценария обработки заказа;
• допустимость перехода проверяется на стороне Lamoda и зависит от сценария обработки заказа;
• не используйте полный список статусов из ответа заказа как список статусов, которые можно отправить в запросе изменения.

По спецификации v2:

Паковые коды и сборка заказа

Сгенерировать паковые коды

POST /api/v2/orders/{orderId}/packs?sellerId=242541217
Content-Type: application/json

{
  "count": 2
}

Метод заменяет старый POST /api/v1/orders/{sellerOrderNr}/pack-numbers.

Ответ содержит массив data[].packNumber. Это штрихкоды упаковок. Они используются в методах этикеток упаковок и при получении PDF-этикетки конкретного пака.

{
  "data": [
    {"packNumber": "FBS3NA3KF8C3"},
    {"packNumber": "FBS9XK2QW8L4"}
  ]
}

Создать сборку

POST /api/v2/orders/{orderId}/assembly
Content-Type: application/json

{
  "sellerId": "242541217",
  "packs": [
    {
      "itemIds": ["ITEM-001", "ITEM-002"]
    }
  ]
}

Сборка сохраняет состав товаров в паках и переводит заказ в состояние ожидания отгрузки. В теле запроса сборки передаются только packs[].itemIds; packNumber в схеме assembly не передается. Если интеграции нужно связать packNumber с конкретным набором позиций, храните эту связь у себя в момент сборки заказа или получайте ее из последующих контейнерных/отгрузочных данных, где она доступна.

Важно различать поля:

• itemIds — идентификаторы позиций из деталей заказа GET /v2/orders/{orderId};
• packNumber — штрихкод упаковки из POST /v2/orders/{orderId}/packs, используется в labels/order-packs и GET /v2/orders/{orderId}/packs/{packNumber}/label;
• packId — поле упаковки в запросе/ответе FBS-отгрузки. Если ваш процесс использует сгенерированный packNumber как код упаковки для отгрузки, сохраните это соответствие явно; не подставляйте старый sellerOrderNr или произвольный WMS id без сверки с операционным потоком.

Старый общий POST /api/v1/orders/collect нужно заменить операцией конкретного заказа.

Сквозной порядок для FBS:

1. Из GET /v2/orders/{orderId} возьмите items[].id.
2. Отправьте POST /v2/orders/{orderId}/assembly с packs[].itemIds — распределение позиций по упаковкам.
3. Сгенерируйте нужное количество packNumber через POST /v2/orders/{orderId}/packs.
4. Сохраните у себя связь между выбранным packNumber и набором itemIds, если она нужна WMS или печати.
5. Для этикетки упаковки передайте packNumber в POST /v2/labels/order-packs или в GET /v2/orders/{orderId}/packs/{packNumber}/label.
6. Для FBS-отгрузки передайте packId в POST /v2/fbs/shipments; если в вашем процессе packId равен сгенерированному packNumber, используйте сохраненную связь явно.

Этикетки

Пример товарных этикеток:

{
  "sellerId": "12345",
  "labelFormat": "M",
  "items": [
    "RU250216-884060-001-1",
    "RU250216-884061-002-1"
  ]
}

Ответ содержит fileUrl и список исключенных сущностей (excludedItems, excludedPacks, excludedPallets). Если часть этикеток не сформирована, интеграция должна показать это пользователю или отправить на повторную обработку.

FBS-отгрузки

Пример создания FBS-отгрузки:

{
  "sellerId": "123",
  "pallets": [
    {
      "packs": [
        {
          "packId": "PACK-123",
          "items": [
            {"unitload": "UNITLOAD-123"}
          ]
        }
      ]
    }
  ]
}

Обязательные поля обычной FBS-отгрузки:

• sellerId — из конфигурации интеграции;
• pallets[].packs[] — упаковки внутри паллеты;
• packs[].packId — код упаковки для отгрузки; чаще всего это сохраненный код упаковки из процесса сборки/WMS, а при использовании паковых кодов Lamoda — сохраненный packNumber;
• packs[].items[].unitload — идентификатор единицы товара: значение items[].id из деталей заказа (GET /v2/orders/{orderId}; в v1 поле называлось itemNr).

Для подготовленной вручную отгрузки используйте POST /v2/fbs/prepared-shipments. В этом сценарии обязательно передаются shipmentId, shippedAt, sellerId и pallets; внутри паков можно передать вес, габариты и состав позиций.

{
  "sellerId": "123",
  "shipmentId": "JLX0000000200",
  "shippedAt": "2026-04-20",
  "docNumber": "DOC-001",
  "pallets": [
    {
      "palletId": "PALLET-001",
      "packs": [
        {
          "packId": "PACK-001",
          "weight": "1.5",
          "length": "30",
          "width": "20",
          "height": "10",
          "items": [
            {
              "orderId": "ORDER-001",
              "sku": "SKU-001",
              "unitload": "UNITLOAD-001"
            }
          ]
        }
      ]
    }
  ]
}

POST /api/v1/shipments/out/{code}/events относится к старому FBS-контракту. Метод станет deprecated и позже будет выключен.

FBS-заявки на доставку и возврат

Новые методы:

• GET /v2/fbs/pickup-requests;
• POST /v2/fbs/pickup-requests/{requestId}/status.

Они работают с заявками на доставку/возврат (DELIVERY, RETURN) и статусами ACTIVE, CANCELLED, PAID_CANCELLED, RECOVERED, PAID_RECOVERED. Это не замена CRUD партнерских ПВЗ из B2B REST v1.

Через API можно получить список заявок и отменить заявку. Для отмены используется отдельная схема тела запроса:

{
  "seller_id": 12345,
  "status": "CANCELLED"
}

seller_id здесь отличается от общего sellerId: это поле описано в спецификации как integer. Другие статусы из списка являются статусами чтения и фильтрации, а не допустимыми целями для POST /v2/fbs/pickup-requests/{requestId}/status.

Методы v1, которые станут deprecated

Эти методы заказов и доставки станут deprecated и позже будут выключены:

• создание заказа продавцом;
• изменение номера заказа партнера;
• добавление товара в заказ;
• чтение и изменение customer;
• чтение и изменение shipping address;
• подбор и установка delivery methods;
• адресные справочники city/street/building;
• pickup points;
• отдельный метод shipment events для подтверждения или отмены FBS-отгрузки.

См. также

• Переход на Lamoda Seller API v2
• Общие изменения контракта
• Справочник соответствия методов
• Продажа со своего склада (FBS)