Возвраты FBS

Полное описание работы с возвратами в модели FBS (Fulfillment by Seller). В модели FBS обработка возвратов и возврат денежных средств клиенту полностью лежат на стороне партнёра.

Обзор API для возвратов FBS

Мониторинг возвратов: REST API v2

Авторизация

Все методы требуют OAuth-токен в заголовке:

Authorization: Bearer {access_token}

Во всех запросах обязателен query-параметр sellerId.

Методы для работы с возвратными коробами

1. Получение списка возвратных коробов

GET /api/v2/fbs/return-boxes

Возвращает список возвратных коробов с товарами.

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

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

GET /api/v2/fbs/return-boxes?sellerId=242541217&createdFrom=2025-05-01T00:00:00Z&createdTo=2025-06-01T00:00:00Z&page=1&limit=100&sort=-createdAt

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

{
  "data": [
    {
      "id": "B-XD043421",
      "dimensionSymbol": "L",
      "createdAt": "2025-05-12T22:01:02.000Z",
      "status": "ACCEPTED",
      "updatedAt": "2025-05-16T22:01:02.000Z"
    }
  ],
  "meta": {
    "total": 87,
    "page": 1,
    "limit": 100,
    "totalPages": 1
  }
}

2. Получение информации по конкретному коробу

GET /api/v2/fbs/return-boxes/{id}

Возвращает детальную информацию о возвратном коробе по идентификатору, включая размеры.

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

GET /api/v2/fbs/return-boxes/B-XD043421?sellerId=242541217

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

{
  "id": "B-XD043421",
  "dimensionSymbol": "L",
  "boxDimensions": {
    "length": 600,
    "height": 400,
    "width": 400
  },
  "status": "ACCEPTED",
  "createdAt": "2025-05-12T22:01:02.000Z",
  "updatedAt": "2025-05-16T22:01:02.000Z"
}

3. История статусов возвратного короба

GET /api/v2/fbs/return-boxes/{id}/status-history

Возвращает историю смены статусов по возвратному коробу.

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

GET /api/v2/fbs/return-boxes/B-XD043421/status-history?sellerId=242541217

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

{
  "data": [
    {"createdAt": "2024-12-20T09:37:40.000Z", "status": "IN_PROGRESS"},
    {"createdAt": "2024-12-21T10:00:00.000Z", "status": "ACCEPTED"}
  ]
}

4. Сводная информация по возвратным коробам

GET /api/v2/fbs/return-boxes-summary

Возвращает агрегированную информацию по возвратным коробам или коробам с аномалиями.

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

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

GET /api/v2/fbs/return-boxes-summary?sellerId=242541217&boxType=RETURN

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

{
  "totalCount": 100,
  "totalVolume": 0.672,
  "totalItems": 1000,
  "totalPacks": 1000,
  "maxBoxDimensions": {
    "height": 400,
    "length": 600,
    "width": 400
  },
  "hasExpiredBoxes": true
}

Сводка включает короба в статусах IN_PROGRESS и ACCEPTED. Короба в статусах CREATED и SHIPPED в сводку не входят.

5. Список коробов с аномалиями

GET /api/v2/fbs/return-boxes-anomalies

Возвращает список коробов с аномалиями — неопознанные или незаявленные посылки, проблемы с маркировкой.

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

GET /api/v2/fbs/return-boxes-anomalies?sellerId=242541217&createdFrom=2025-05-01T00:00:00Z&createdTo=2025-06-01T00:00:00Z&page=1&limit=100&sort=-createdAt

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

{
  "data": [
    {
      "id": "AN123456",
      "dimensionSymbol": "L",
      "packs": [
        {"type": "BARCODE_MISSING", "count": 2}
      ],
      "createdAt": "2025-05-12T22:01:02.000Z",
      "status": "ACCEPTED",
      "updatedAt": "2025-05-16T22:01:02.000Z"
    }
  ],
  "meta": {
    "total": 50,
    "page": 1,
    "limit": 100,
    "totalPages": 1
  }
}

Методы для работы с возвратными товарами

6. Получение списка возвратных товаров

GET /api/v2/fbs/return-items

Возвращает список товаров на возврат. Поддерживает фильтрацию и пагинацию (параметры аналогичны методу списка коробов).

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

GET /api/v2/fbs/return-items?sellerId=242541217&createdFrom=2025-05-01T00:00:00Z&createdTo=2025-06-01T00:00:00Z&page=1&limit=100&sort=-createdAt

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

{
  "data": [
    {
      "id": "RU250512-718260-001",
      "itemId": "RU250512-718260-001",
      "boxId": "B-XD043421",
      "orderId": "RU250512-718260",
      "sku": "LM-SKU-12345",
      "externalSku": "SELLER-ART-001",
      "itemName": "Кроссовки Nike Air Max",
      "dimensionSymbol": "42",
      "returnType": "CLAIM",
      "returnDate": "2025-05-15",
      "status": "ARRIVED_TO_WH",
      "updatedAt": "2025-05-18T05:04:44.000Z",
      "price": {
        "amount": 1299400,
        "currency": "RUB"
      },
      "imageUrl": "https://a.lmcdn.ru/product/12345.jpg"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 100,
    "totalPages": 1
  }
}

7. История статусов возвратного товара

GET /api/v2/fbs/return-items/{itemId}/status-history

Возвращает историю смены статусов по возвратному товару.

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

GET /api/v2/fbs/return-items/RU250512-718260-001/status-history?sellerId=242541217

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

{
  "data": [
    {"createdAt": "2025-05-18T05:04:44.000Z", "status": "ARRIVED_TO_WH"},
    {"createdAt": "2025-05-19T06:00:00.000Z", "status": "READY_TO_RETURN"}
  ]
}

8. Количество возвратных товаров по статусам

GET /api/v2/fbs/return-items-summary

Возвращает агрегированные количества товаров по статусам. Ответ — динамическая map, ключи — статусы, значения — количество.

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

GET /api/v2/fbs/return-items-summary?sellerId=242541217

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

{
  "CREATED": 3,
  "LEFT_TO_WH": 2,
  "ARRIVED_TO_WH": 1,
  "READY_TO_RETURN": 3,
  "SHIPPED": 10
}

Статусы в REST API v2

Справочник статусов и типов возвратов

Подтверждение возврата: Lamoda B2B Platform Partner API v1

Изменение статуса заказа

GET /api/v1/orders/{orderNr}/change_status_request

Изменение статуса всех товаров в заказе.

curl -X POST "https://api-b2b.lamoda.ru/api/v1/orders/CZ123456789/change_status_request" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "returned"
}'

Изменение статуса отдельного товара

GET /api/v1/orders/{orderNr}/items/{itemNr}/change_status_request

Изменение статуса одного товара в заказе.

curl -X POST "https://api-b2b.lamoda.ru/api/v1/orders/CZ123456789/items/7602/change_status_request" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "returned"
}'

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

Допустимые статусы

Процесс обработки возврата FBS

1. Получить информацию о возврате

Отслеживайте возвраты через REST API v2:

GET https://public-api-seller.lamoda.ru/api/v2/fbs/return-items?sellerId=242541217&sort=-createdAt

2. Проверить товар

Проверка качества на стороне партнёра или на ПВЗ Lamoda (для маркетплейс-доставки).

3. Подтвердить возврат через Lamoda B2B Platform Partner API v1

POST https://api-b2b.lamoda.ru/api/v1/orders/{orderNr}/items/{itemNr}/change_status_request
{"status": "returned"}

4. Вернуть деньги клиенту

После перехода товара в статус Refund by partner — вернуть деньги клиенту самостоятельно.

Возврат в магазин партнёра

DataMatrix при возврате

Если товар маркирован — при продаже DataMatrix выводится из оборота на стороне партнёра (FBS). При возврате необходимо:

• Вернуть DataMatrix в оборот (если товар пригоден к продаже)
• Или списать код (если товар признан браком)

Миграция на новые методы

Порядок действий:

1. Реализуйте получение возвратных товаров и коробов через новые эндпоинты /api/v2/fbs/return-*
2. Протестируйте обработку новых статусов (CREATED, LEFT_TO_WH, ARRIVED_TO_WH, READY_TO_RETURN, SHIPPED) и типов возвратов (CLAIM, REJECT, CANCEL, NO_SHOW)
3. Настройте периодический polling новых методов вместо нотификаций itemStatusChanged
4. Убедитесь, что подтверждение возврата (change_status_request) по-прежнему вызывается через Lamoda B2B Platform Partner API v1
5. Отключите обработку возвратных статусов из GET /api/v1/orders и нотификаций

Затронутые методы API (перестанут возвращать возвратные статусы с 3 марта)

• GET /api/v1/orders
• GET /api/v1/orders/{orderNr}
• GET /api/v1/orders/count-by-statuses
• GET /api/v1/orders/{orderNr}/statuses
• GET /api/v1/shipments
• GET /api/v1/shipments/{shipmentId}
• GET /api/v1/container/{barcode}
• GET /api/v1/goods
• Нотификация itemStatusChanged (для возвратных статусов)

См. также

• Типы возвратов и статусы — общее описание, маппинг статусов v1 → v2
• Статусы заказов и товаров
• Типы нотификаций