Endpoints API возвратов (Returns)

Дата: 2025-02-10 Подзадача: 2-8 - Document all Returns API endpoints Статус: ✅ ЗАВЕРШЕНО

Обзор

Lamoda предоставляет 8 endpoints для управления возвратами через 1 API-систему:

Seller REST API: 8 endpoints (REST) - полное управление возвратами FBS (коробами и товарами)

Все endpoints поддерживают операции получения списков возвратов, детальной информации, статистики и истории статусов.

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

1. Seller REST API - Возвраты FBS

Base URL: https://public-api-seller.lamoda.ru/api API Format: REST (OpenAPI 3.0.0) Authentication: Bearer Token Total Endpoints: 8

1.1 Список возвратных коробов с аномалиями

Method: GET Path: /v2/fbs/return-boxes-anomalies Operation ID: v2.get.fbs.returnBoxesAnomalies Tags: FBS Return Boxes

Описание: Получение списка возвратных коробов с аномалиями (неопознанными посылками).

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

Query parameters:
- sellerId (string, optional): Идентификатор продавца
- createdFrom (string, optional): Дата создания с (формат ISO 8601)
- createdTo (string, optional): Дата создания по (формат ISO 8601)
- page (integer, optional): Номер страницы (по умолчанию 1)
- limit (integer, optional): Количество элементов на странице (по умолчанию 100)
- sort (string, optional): Сортировка (поля: createdAt, updatedAt)

Ответы:

200 OK: Список коробов с аномалиями получен

{
  "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
  }
}

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
404 Not Found: Ресурс не найден
503 Service Unavailable: Сервис недоступен

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

curl -X GET 'https://public-api-seller.lamoda.ru/api/v2/fbs/return-boxes-anomalies?page=1&limit=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Примечание: Аномалии - это короба с неопознанными посылками (отсутствует или не считывается штрихкод).

1.2 Список возвратных коробов

Method: GET Path: /v2/fbs/return-boxes Operation ID: v2.get.fbs.returnBoxes Tags: FBS Return Boxes

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

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

Query parameters:
- sellerId (string, optional): Идентификатор продавца
- createdFrom (string, optional): Дата создания с (формат ISO 8601)
- createdTo (string, optional): Дата создания по (формат ISO 8601)
- page (integer, optional): Номер страницы (по умолчанию 1)
- limit (integer, optional): Количество элементов на странице (по умолчанию 100)
- sort (string, optional): Сортировка (поля: createdAt, updatedAt)

Ответы:

200 OK: Список возвратных коробов получен

{
  "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
  }
}

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
404 Not Found: Ресурс не найден
503 Service Unavailable: Сервис недоступен

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

curl -X GET 'https://public-api-seller.lamoda.ru/api/v2/fbs/return-boxes?page=1&limit=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'

1.3 Информация о возвратном коробе

Method: GET Path: /v2/fbs/return-boxes/{id} Operation ID: v2.get.fbs.returnBox Tags: FBS Return Boxes

Описание: Получение подробной информации о возвратном коробе по идентификатору.

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

Path parameters:
- id (string, required): Идентификатор возвратного короба
Query parameters:
- sellerId (string, optional): Идентификатор продавца

Ответы:

200 OK: Информация о возвратном коробе получена

{
  "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"
}

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
404 Not Found: Короб не найден
503 Service Unavailable: Сервис недоступен

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

curl -X GET 'https://public-api-seller.lamoda.ru/api/v2/fbs/return-boxes/B-XD043421' \
  -H 'Authorization: Bearer YOUR_TOKEN'

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

Method: GET Path: /v2/fbs/return-boxes-summary Operation ID: v2.get.fbs.returnBoxes.summary Tags: FBS Return Boxes

Описание: Получение сводной информации по возвратным коробам с товарами или коробам с аномалиями. В ответе содержится общая информация по коробам, находящимся в статусах IN_PROGRESS ("В процессе наполнения") и ACCEPTED ("Принят").

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

Query parameters:
- sellerId (string, optional): Идентификатор продавца
- boxType (string, required): Тип возвратных коробов
  - RETURN - короба с товарами
  - ANOMALY - короба с неопознанными посылками

Ответы:

200 OK: Сводная информация получена

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

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
404 Not Found: Ресурс не найден
503 Service Unavailable: Сервис недоступен

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

curl -X GET 'https://public-api-seller.lamoda.ru/api/v2/fbs/return-boxes-summary?boxType=RETURN' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Примечание: Используйте этот endpoint для получения общей статистики по коробам возвратов.

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

Method: GET Path: /v2/fbs/return-boxes/{id}/status-history Operation ID: v2.get.fbs.returnBox.statusHistory Tags: FBS Return Boxes

Описание: Получение истории изменений статусов возвратного короба по идентификатору.

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

Path parameters:
- id (string, required): Идентификатор возвратного короба
Query parameters:
- sellerId (string, optional): Идентификатор продавца

Ответы:

200 OK: История статусов получена

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

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
404 Not Found: Короб не найден
503 Service Unavailable: Сервис недоступен

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

curl -X GET 'https://public-api-seller.lamoda.ru/api/v2/fbs/return-boxes/B-XD043421/status-history' \
  -H 'Authorization: Bearer YOUR_TOKEN'

1.6 Список возвратных товаров

Method: GET Path: /v2/fbs/return-items Operation ID: v2.get.fbs.returnItems Tags: FBS Return Items

Описание: Получение списка товаров на возврат с постраничной навигацией и фильтрацией.

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

Query parameters:
- sellerId (string, optional): Идентификатор продавца
- status (string, optional): Статус возвратного товара
- returnDateFrom (string, optional): Дата возврата с (формат ISO 8601)
- returnDateTo (string, optional): Дата возврата по (формат ISO 8601)
- boxId (string, optional): Идентификатор короба
- page (integer, optional): Номер страницы (по умолчанию 1)
- limit (integer, optional): Количество элементов на странице (по умолчанию 100)
- sort (string, optional): Сортировка (поля: returnDate, updatedAt)

Ответы:

200 OK: Список возвратных товаров получен

{
  "data": [
    {
      "id": "RU250512-718260-001",
      "boxId": "B-XD043421",
      "dimensionSymbol": "M",
      "itemName": "Item Name",
      "itemId": "RU250512-718260-001",
      "orderId": "RU250512-718260",
      "returnDate": "2025-05-15",
      "returnType": "REJECT",
      "status": "READY_TO_RETURN",
      "updatedAt": "2025-05-16T22:01:02.000Z",
      "externalSku": "HT-0214_DBEIGE",
      "sku": "MP002XM23QJ2R123",
      "price": {
        "amount": 129944,
        "currency": "RUB"
      },
      "imageUrl": "https://example.com/image.jpg"
    }
  ],
  "meta": {
    "total": 87,
    "page": 1,
    "limit": 100,
    "totalPages": 1
  }
}

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
404 Not Found: Ресурс не найден
503 Service Unavailable: Сервис недоступен

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

curl -X GET 'https://public-api-seller.lamoda.ru/api/v2/fbs/return-items?page=1&limit=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Примечание: Используйте параметры фильтрации для поиска конкретных возвратов.

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

Method: GET Path: /v2/fbs/return-items/{itemId}/status-history Operation ID: v2.get.fbs.returnItem.statusHistory Tags: FBS Return Items

Описание: Получение истории изменений статусов возвратного товара по идентификатору.

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

Path parameters:
- itemId (string, required): Идентификатор товара
Query parameters:
- sellerId (string, optional): Идентификатор продавца

Ответы:

200 OK: История статусов получена

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

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
404 Not Found: Товар не найден
503 Service Unavailable: Сервис недоступен

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

curl -X GET 'https://public-api-seller.lamoda.ru/api/v2/fbs/return-items/RU250512-718260-001/status-history' \
  -H 'Authorization: Bearer YOUR_TOKEN'

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

Method: GET Path: /v2/fbs/return-items-summary Operation ID: v2.get.fbs.returnItems.summary Tags: FBS Return Items

Описание: Получение количества возвратных товаров по каждому статусу для мониторинга состояния возвратов.

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

Query parameters:
- sellerId (string, optional): Идентификатор продавца

Ответы:

200 OK: Количество товаров по статусам получено

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

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
404 Not Found: Ресурс не найден
503 Service Unavailable: Сервис недоступен

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

curl -X GET 'https://public-api-seller.lamoda.ru/api/v2/fbs/return-items-summary' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Примечание: Используйте этот endpoint для получения сводной статистики по всем статусам возвратов.

Сводная таблица всех endpoints

API System	Endpoint/Method	Method	Description	Используется для
Seller REST API	`/v2/fbs/return-boxes-anomalies`	GET	Список коробов с аномалиями	FBS
Seller REST API	`/v2/fbs/return-boxes`	GET	Список возвратных коробов	FBS
Seller REST API	`/v2/fbs/return-boxes/{id}`	GET	Информация о возвратном коробе	FBS
Seller REST API	`/v2/fbs/return-boxes-summary`	GET	Сводка по возвратным коробам	FBS
Seller REST API	`/v2/fbs/return-boxes/{id}/status-history`	GET	История статусов короба	FBS
Seller REST API	`/v2/fbs/return-items`	GET	Список возвратных товаров	FBS
Seller REST API	`/v2/fbs/return-items/{itemId}/status-history`	GET	История статусов товара	FBS
Seller REST API	`/v2/fbs/return-items-summary`	GET	Количество товаров по статусам	FBS

Всего: 8 endpoints

Статусы возвратных коробов (Return Box Status)

Статус	Описание
`IN_PROGRESS`	В процессе наполнения
`ACCEPTED`	Принят

Статусы возвратных товаров (Return Item Status)

Статус	Описание
`CREATED`	Возврат создан
`LEFT_TO_WH`	Едет на склад Lamoda
`ARRIVED_TO_WH`	На складе Lamoda
`READY_TO_RETURN`	Готов к возврату продавцу
`SHIPPED`	Отгружен продавцу

Типы возврата (Return Type)

Тип	Описание
`REJECT`	Возврат товара (отказ покупателя)
`CLAIM`	Претензия (брак, несоответствие и т.д.)

Размеры коробов (Dimension Symbol)

Символ	Описание
`S`	Малый
`M`	Средний
`L`	Большой
`XL`	Очень большой

Типы аномалий коробов (Anomaly Pack Type)

Тип	Описание
`BARCODE_MISSING`	Штрихкод отсутствует
`BARCODE_UNREADABLE`	Штрихкод не читается
`MULTIPLE_BARCODES`	Несколько штрихкодов

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

Для возвратных коробов:

createdAt - Дата создания
updatedAt - Дата обновления

Для возвратных товаров:

returnDate - Дата возврата
updatedAt - Дата обновления

Направление сортировки: Добавьте - перед именем поля для сортировки по убыванию (например, -createdAt).

Примечания по использованию

Аутентификация

Seller REST API: Bearer токен (15 минут), получить через v1.tokens.create (JSON-RPC API)

Пагинация

Параметры page и limit, по умолчанию limit=100
Максимальное количество элементов на странице: 100

Фильтрация

Используйте параметр status для фильтрации по статусу товара
Используйте параметры createdFrom/createdTo для фильтрации по диапазону дат
Используйте параметр boxId для фильтрации товаров по конкретному коробу

Rate Limiting

Лимиты официально не задокументированы
Рекомендуется не более 10 запросов в секунду

Особенности для модели FBS

Endpoints возвратов доступны только для FBS (Fulfillment by Seller)
Для моделей FBO и B2B FF возвры обрабатываются автоматически Lamoda

Идентификаторы

ID короба: Формат B-XXXXXXXX (например, B-XD043421)
ID товара: Формат XXXXXXXXXXX-NNN (например, RU250512-718260-001)

Лучшие практики

1. Мониторинг возвратов

Используйте /v2/fbs/return-items-summary для получения общей статистики
Отслеживайте товары в статусе READY_TO_RETURN для своевременной обработки
Обратите внимание на коробы с аномалиями через /v2/fbs/return-boxes-anomalies

2. Обработка коробов возвратов

Получайте список коробов через /v2/fbs/return-boxes
Проверяйте детали каждого короба через /v2/fbs/return-boxes/{id}
Отслеживайте историю статусов для мониторинга проблемных коробов

3. Обработка товаров возвратов

Получайте список товаров через /v2/fbs/return-items
Фильтруйте по статусу READY_TO_RETURN для товаров, готовых к возврату
Проверяйте историю статусов для understanding жизненного цикла возврата

4. Оптимизация запросов

Используйте пагинацию для больших списков
Применяйте фильтры по датам для получения свежих данных
Кэшируйте результаты сводных запросов (*-summary endpoints)

5. Интеграция с бизнес-процессами

Настраивайте периодические опросы для отслеживания новых возвратов
Создавайте уведомления для товаров в статусе READY_TO_RETURN
Анализируйте аномалии для улучшения упаковки товаров

Примеры интеграционных сценариев

Сценарий 1: Ежедневный мониторинг возвратов

Получить сводку по товарам: GET /v2/fbs/return-items-summary
Проверить количество товаров в статусе READY_TO_RETURN
Получить список готовых к возврату товаров: GET /v2/fbs/return-items?status=READY_TO_RETURN
Сформировать заявку на отгрузку

Сценарий 2: Обработка коробов с аномалиями

Получить список аномальных коробов: GET /v2/fbs/return-boxes-anomalies
Получить детали короба: GET /v2/fbs/return-boxes/{id}
Проверить историю статусов: GET /v2/fbs/return-boxes/{id}/status-history
Принять решение о дальнейших действиях

Сценарий 3: Анализ возвратов за период

Получить список коробов за период: GET /v2/fbs/return-boxes?createdFrom=2025-05-01&createdTo=2025-05-31
Получить список товаров за период: GET /v2/fbs/return-items?returnDateFrom=2025-05-01&returnDateTo=2025-05-31
Проанализировать причины возвратов и количество
Сформировать отчет для оптимизации ассортимента

Сценарий 4: Отслеживание конкретного возврата

Найти товар по заказу: GET /v2/fbs/return-items?orderId=RU250512-718260
Получить детали товара
Проверить историю статусов: GET /v2/fbs/return-items/{itemId}/status-history
Получить информацию о коробе: GET /v2/fbs/return-boxes/{boxId}

Связанные разделы API

Заказы (Orders)

Статус заказа returned указывает на возвращенный заказ
Используйте GET /api/v1/orders/{id}/statuses для отслеживания статусов

Товары (Products)

Информация о товарах в sku и externalSku полях
Используйте для обновления остатков после обработки возврата

Полезные советы

Регулярность опроса: Рекомендуется опрашивать API каждые 15-30 минут для своевременного обнаружения новых возвратов
Обработка аномалий: Коробы с аномалиями требуют особого внимания - возможно, проблема с маркировкой товаров
Своевременный возврат: Товары в статусе READY_TO_RETURN должны быть обработаны в кратчайшие сроки
Логирование: Сохраняйте историю статусов для анализа и разрешения спорных ситуаций
Интеграция со складом: Используйте информацию о размерах коробов (dimensionSymbol) для планирования размещения на складе

Дата создания: 2025-02-10 Следующее обновление: После следующих изменений в API

Источник документации:

Seller REST API: /Users/antonnozdrin/Tools/SCRAP/marketplace-api-specs/lamoda/lamoda_seller_rest_api.yaml

Обзор​

1. Seller REST API - Возвраты FBS​

1.1 Список возвратных коробов с аномалиями​

1.2 Список возвратных коробов​

1.3 Информация о возвратном коробе​

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

1.5 История статусов возвратного короба​

1.6 Список возвратных товаров​

1.7 История статусов возвратного товара​

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

Сводная таблица всех endpoints​

Статусы возвратных коробов (Return Box Status)​

Статусы возвратных товаров (Return Item Status)​

Типы возврата (Return Type)​

Размеры коробов (Dimension Symbol)​

Типы аномалий коробов (Anomaly Pack Type)​

Параметры сортировки​

Для возвратных коробов:​

Для возвратных товаров:​

Примечания по использованию​

Аутентификация​

Пагинация​

Фильтрация​

Rate Limiting​

Особенности для модели FBS​

Идентификаторы​

Лучшие практики​

1. Мониторинг возвратов​

2. Обработка коробов возвратов​

3. Обработка товаров возвратов​

4. Оптимизация запросов​

5. Интеграция с бизнес-процессами​

Примеры интеграционных сценариев​

Сценарий 1: Ежедневный мониторинг возвратов​

Сценарий 2: Обработка коробов с аномалиями​

Сценарий 3: Анализ возвратов за период​

Сценарий 4: Отслеживание конкретного возврата​

Связанные разделы API​

Заказы (Orders)​

Товары (Products)​

Полезные советы​

Обзор

1. Seller REST API - Возвраты FBS

1.1 Список возвратных коробов с аномалиями

1.2 Список возвратных коробов

1.3 Информация о возвратном коробе

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

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

1.6 Список возвратных товаров

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

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

Сводная таблица всех endpoints

Статусы возвратных коробов (Return Box Status)

Статусы возвратных товаров (Return Item Status)

Типы возврата (Return Type)

Размеры коробов (Dimension Symbol)

Типы аномалий коробов (Anomaly Pack Type)

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

Для возвратных коробов:

Для возвратных товаров:

Примечания по использованию

Аутентификация

Пагинация

Фильтрация

Rate Limiting

Особенности для модели FBS

Идентификаторы

Лучшие практики

1. Мониторинг возвратов

2. Обработка коробов возвратов

3. Обработка товаров возвратов

4. Оптимизация запросов

5. Интеграция с бизнес-процессами

Примеры интеграционных сценариев

Сценарий 1: Ежедневный мониторинг возвратов

Сценарий 2: Обработка коробов с аномалиями

Сценарий 3: Анализ возвратов за период

Сценарий 4: Отслеживание конкретного возврата

Связанные разделы API

Заказы (Orders)

Товары (Products)

Полезные советы