13.2 Возвраты 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

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