Перейти к основному содержимому

Endpoints API отгрузок (Shipments)

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

Обзор​

Lamoda предоставляет 8 endpoints для управления отгрузками через B2B Platform API:

  • B2B Platform API: 8 endpoints (REST) - полное управление отгрузками (входящие и исходящие)

API отгрузок поддерживает две основные модели работы:

  1. Входящие поставки (Fulfilment/Incoming) - FBO модель, товары на склад Lamoda
  2. Исходящие поставки (Outgoing) - FBS/DBS модели, товары со склада продавца

1. B2B Platform API - Отгрузки​

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

Категории endpoints:​

1.1 Входящие поставки (Fulfilment Shipments) - 5 endpoints​

  • GET /api/v1/shipments/fulfilment - Список входящих поставок
  • POST /api/v1/shipments/fulfilment - Создание входящей поставки
  • GET /api/v1/shipments/fulfilment/{id} - Детали поставки
  • GET /api/v1/shipments/fulfilment/{id}/items - Товары в поставке
  • POST /api/v1/brand-packing/pack-shipment - Упаковочные материалы

1.2 Исходящие поставки (Outgoing Shipments) - 3 endpoints​

  • GET /api/v1/shipments - Список всех поставок
  • POST /api/v1/shipments/out - Создание исходящей поставки
  • POST /api/v1/shipments/out/{id}/events - События поставки

2. Входящие поставки (Fulfilment Shipments)​

2.1 Список входящих поставок​

Method: GET Path: /api/v1/shipments/fulfilment Operation ID: get_v1-shipments-fulfilment Tags: Входящие поставки

Описание: Получение списка всех входящих поставок с постраничной навигацией. Используется для FBO модели - товаров, которые продавец отправляет на склад Lamoda.

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

  • Query parameters:
    • limit (integer, optional): Количество элементов на странице (по умолчанию 25)
    • page (integer, optional): Номер запрашиваемой страницы (по умолчанию 1)

Ответы:

  • 200 OK: Список поставок получен 
    {
      "page": 1,
      "limit": 25,
      "pages": 10,
      "total": 250,
      "_links": {
        "self": "href",
        "first": "href",
        "last": "href",
        "next": "href",
        "prev": "href"
      },
      "_embedded": {
        "fulfilment_shipments": [
          {
            "date": "2024-04-17 10:00:00",
            "shipmentId": "FF123",
            "itemsQuantity": 10
          }
        ]
      }
    }
  • 400 Bad Request: Неверный параметр
  • 401 Unauthorized: Отказ в доступе
  • 403 Forbidden: Доступ запрещен
  • 500 Internal Server Error: Внутренняя ошибка сервера

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

curl -X GET 'https://api-b2b.lamoda.ru/api/v1/shipments/fulfilment?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'

2.2 Создание входящей поставки​

Method: POST Path: /api/v1/shipments/fulfilment Operation ID: post_v1-shipments-fulfilment Tags: Входящие поставки

Описание: Создание новой входящей поставки на склад Lamoda. Используется для FBO модели - когда продавец отправляет товары на склад Lamoda для последующей продажи.

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

  • Body: Схема поставки (Shipments.Fulfilment)

    {
      "date": "10.09.2017",
      "id": "187-000-157",
      "documentNumber": "1aa2706f-cacd-4040-b094-c5f9fd844b2b",
      "items": [
        {
          "sku": "SELLERSK157",
          "quantity": 25,
          "price": 999.99,
          "ean": "EANK157",
          "weight": 500.5,
          "uit": "0104670039709513211nQLE3OjFqRC6Oi0nUXY98aI8a7gNkEDQv8NKNBPH4NJv31fK==",
          "uitn": "030467003970951321@QLE3OjFqRC6Oi0nUXY98aI8a7gNkEDQv8NKNBPH4NJv31fK==",
          "attributes": {
            "color": "BLACK",
            "size": "M"
          }
        }
      ]
    }

    Поля запроса:

    • date (string, required): Дата поставки в формате DD.MM.YYYY
    • id (string, required): Уникальный номер поставки (max 20 символов)
    • documentNumber (string, optional): GUID документа (обязателен если есть UIT/UITN)
    • items (array, required): Массив товаров
      • sku (string, required): SKU товара (max 50 символов)
      • quantity (integer, required): Количество единиц
      • price (number, required): Цена в рублях (float, не более 2 знаков после запятой)
      • ean (string, optional): EAN код (max 80 символов)
      • weight (number, optional): Вес в граммах (float)
      • uit (string, optional): Код маркировки (грачные товары)
      • uitn (string, optional): Код маркировки (упаковка)
      • attributes (object, optional): Атрибуты товара (цвет, размер и т.д.)

Ответы:

  • 201 Created: Поставка успешно создана 
    {
      "id": "FF123",
      "date": "2020-01-01",
      "shipmentId": "187-000-157"
    }
    • id: Номер поставки Lamoda
    • date: Дата создания поставки
    • shipmentId: Номер поставки поставщика
  • 400 Bad Request: Неверный параметр
  • 401 Unauthorized: Отказ в доступе
  • 403 Forbidden: Доступ запрещен
  • 500 Internal Server Error: Внутренняя ошибка сервера

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

curl -X POST 'https://api-b2b.lamoda.ru/api/v1/shipments/fulfilment' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "date": "10.09.2017",
    "id": "187-000-157",
    "items": [
      {
        "sku": "SELLERSK157",
        "quantity": 25,
        "price": 999.99
      }
    ]
  }'

Важные замечания:

  • Используется только для FBO модели (товары на складе Lamoda)
  • Для маркированных товаров обязателен documentNumber (GUID)
  • uit и uitn обязательны для маркированных товаров (табак, обувь, одежда и т.д.)
  • Цена указывается в рублях с точностью до 2 знаков после запятой
  • Вес указывается в граммах

2.3 Получение деталей поставки​

Method: GET Path: /api/v1/shipments/fulfilment/{id} Operation ID: get_v1-shipments-fulfilment-id Tags: Входящие поставки

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

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

  • Path parameters:
    • id (string, required): Номер поставки Lamoda

Ответы:

  • 200 OK: Данные о поставке получены 
    {
      "id": "FF123",
      "date": "2024-04-17 10:00:00",
      "shipmentId": "187-000-157",
      "status": "ACCEPTED",
      "items": [...]
    }
  • 400 Bad Request: Неверный параметр
  • 401 Unauthorized: Отказ в доступе
  • 403 Forbidden: Доступ запрещен
  • 500 Internal Server Error: Внутренняя ошибка сервера

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

curl -X GET 'https://api-b2b.lamoda.ru/api/v1/shipments/fulfilment/FF123' \
  -H 'Authorization: Bearer YOUR_TOKEN'

2.4 Товары в поставке​

Method: GET Path: /api/v1/shipments/fulfilment/{id}/items Operation ID: get_v1-shipments-fulfilment-items Tags: Входящие поставки

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

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

  • Path parameters:
    • id (string, required): Номер поставки Lamoda

Ответы:

  • 200 OK: Массив товаров в поставке 
    {
      "items": [
        {
          "sku": "SELLERSK157",
          "quantity": 25,
          "accepted": 20,
          "rejected": 5,
          "price": 999.99,
          "attributes": {
            "color": "BLACK",
            "size": "M"
          }
        }
      ],
      "total": 25
    }
  • 400 Bad Request: Неверный параметр
  • 401 Unauthorized: Отказ в доступе
  • 403 Forbidden: Доступ запрещен
  • 500 Internal Server Error: Внутренняя ошибка сервера

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

curl -X GET 'https://api-b2b.lamoda.ru/api/v1/shipments/fulfilment/FF123/items' \
  -H 'Authorization: Bearer YOUR_TOKEN'

2.5 Создание поставки упаковочных материалов​

Method: POST Path: /api/v1/brand-packing/pack-shipment Operation ID: post_v1-brand_packing-pack_shipment Tags: Входящие поставки

Описание: Метод для создания поставки с упаковочными материалами (УМ). Используется для учета упаковки, которую продавец поставляет на склад Lamoda.

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

  • Body: Схема поставки упаковочных материалов (ShipmentBP) 
    {
      "date": "2020-01-01",
      "items": [
        {
          "sku": "PACK_001",
          "quantity": 100
        }
      ]
    }

Ответы:

  • 201 Created: Поставка создана 
    {
      "lamodaShipmentId": "FF1440",
      "date": "2020-01-01",
      "shipmentId": "ZAPH-821468"
    }
    • lamodaShipmentId: Номер поставки Lamoda
    • date: Ожидаемая дата поставки
    • shipmentId: Номер поставки поставщика
  • 400 Bad Request: Неверный параметр
  • 401 Unauthorized: Отказ в доступе
  • 403 Forbidden: Доступ запрещен
  • 500 Internal Server Error: Внутренняя ошибка сервера

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

curl -X POST 'https://api-b2b.lamoda.ru/api/v1/brand-packing/pack-shipment' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "date": "2020-01-01",
    "items": [
      {
        "sku": "PACK_001",
        "quantity": 100
      }
    ]
  }'

3. Исходящие поставки (Outgoing Shipments)​

3.1 Список всех поставок​

Method: GET Path: /api/v1/shipments Operation ID: get_v1-shipments Tags: Управление поставками

Описание: Получение списка всех поставок (как входящих, так и исходящих) с возможностью фильтрации по направлению.

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

  • Query parameters:
    • limit (integer, optional): Количество элементов на странице (по умолчанию 25)
    • page (integer, optional): Номер запрашиваемой страницы (по умолчанию 1)
    • filter (string, optional): Фильтр по направлению
      • direction=in: Входящие поставки
      • direction=out: Исходящие поставки

Ответы:

  • 200 OK: Список поставок получен 
    {
      "page": 1,
      "limit": 25,
      "pages": 5,
      "total": 125,
      "_links": {
        "self": "href",
        "first": "href",
        "last": "href",
        "next": "href",
        "prev": "href"
      },
      "_embedded": {
        "shipments": [
          {
            "id": "OUT123",
            "direction": "out",
            "status": "SHIPPED",
            "date": "2024-04-17 10:00:00"
          }
        ]
      }
    }
  • 400 Bad Request: Неверный параметр
  • 401 Unauthorized: Отказ в доступе
  • 500 Internal Server Error: Внутренняя ошибка сервера

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

# Все поставки
curl -X GET 'https://api-b2b.lamoda.ru/api/v1/shipments?page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'

# Только исходящие поставки
curl -X GET 'https://api-b2b.lamoda.ru/api/v1/shipments?filter=direction%3Dout&page=1&limit=25' \
  -H 'Authorization: Bearer YOUR_TOKEN'

3.2 Создание исходящей поставки​

Method: POST Path: /api/v1/shipments/out Operation ID: post_v1-shipments-out Tags: Управление поставками

Описание: Создание новой исходящей поставки для FBS/DBS моделей - когда продавец отгружает товары со своего склада. Если информация о поставке успешно принята и обработана, возвращается уникальный идентификатор поставки.

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

  • Body: Схема исходящей поставки (Shipment.Out)

    {
      "shipmentId": "OUT-2024-001",
      "orderNr": "123456789",
      "items": [
        {
          "sku": "SELLERSK157",
          "quantity": 1
        }
      ],
      "deliveryMethod": "COURIER",
      "trackingNumber": "TRACK123456",
      "shipmentDate": "2024-04-17"
    }

    Основные поля:

    • shipmentId: Уникальный номер поставки
    • orderNr: Номер заказа
    • items: Массив товаров в поставке
    • deliveryMethod: Метод доставки
    • trackingNumber: Трекинг-номер отгрузки
    • shipmentDate: Дата отгрузки

Ответы:

  • 200 OK: Поставка создана 
    {
      "id": "12345",
      "shipmentId": "OUT-2024-001",
      "status": "CREATED",
      "message": "Shipment created successfully"
    }
  • 400 Bad Request: Ошибка валидации
  • 401 Unauthorized: Ошибка авторизации
  • 500 Internal Server Error: Внутренняя ошибка сервера

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

curl -X POST 'https://api-b2b.lamoda.ru/api/v1/shipments/out' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipmentId": "OUT-2024-001",
    "orderNr": "123456789",
    "items": [
      {
        "sku": "SELLERSK157",
        "quantity": 1
      }
    ],
    "deliveryMethod": "COURIER",
    "trackingNumber": "TRACK123456",
    "shipmentDate": "2024-04-17"
  }'

Важные замечания:

  • Используется для FBS и DBS моделей
  • Трекинг-номер обязателен для отслеживания доставки
  • Метод доставки должен соответствовать доступным методам

3.3 События поставки​

Method: POST Path: /api/v1/shipments/out/{id}/events Operation ID: post_v1-shipments-out-events Tags: Управление поставками

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

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

  • Path parameters:

    • id (string, required): Номер поставки

  • Body: Схема события поставки (Shipment.Out.EventType)

    {
      "eventType": "CONFIRMED",
      "comment": "Товары отправлены",
      "eventDate": "2024-04-17T10:00:00"
    }

    Типы событий:

    • CONFIRMED: Подтверждение поставки
    • CANCELED: Отмена поставки

Ответы:

  • 201 Created: Событие успешно создано 
    {
      "id": "EVT123",
      "shipmentId": "12345",
      "eventType": "CONFIRMED",
      "eventDate": "2024-04-17T10:00:00",
      "status": "PROCESSED"
    }
  • 400 Bad Request: Ошибка валидации
  • 401 Unauthorized: Ошибка авторизации
  • 500 Internal Server Error: Внутренняя ошибка сервера

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

# Подтверждение поставки
curl -X POST 'https://api-b2b.lamoda.ru/api/v1/shipments/out/12345/events' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "eventType": "CONFIRMED",
    "comment": "Товары отправлены",
    "eventDate": "2024-04-17T10:00:00"
  }'

# Отмена поставки
curl -X POST 'https://api-b2b.lamoda.ru/api/v1/shipments/out/12345/events' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "eventType": "CANCELED",
    "comment": "Товары недоступны",
    "eventDate": "2024-04-17T10:00:00"
  }'

Важные замечания:

  • Подтверждение используется только если отключена автоподтверждение
  • Отмена возможна только до подтверждения поставки
  • Комментарий рекомендуется для отмены поставки

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

MethodPathOperation IDОписаниеКатегория
GET/api/v1/shipments/fulfilmentget_v1-shipments-fulfilmentСписок входящих поставокFulfilment
POST/api/v1/shipments/fulfilmentpost_v1-shipments-fulfilmentСоздание входящей поставкиFulfilment
GET/api/v1/shipments/fulfilment/{id}get_v1-shipments-fulfilment-idДетали поставкиFulfilment
GET/api/v1/shipments/fulfilment/{id}/itemsget_v1-shipments-fulfilment-itemsТовары в поставкеFulfilment
POST/api/v1/brand-packing/pack-shipmentpost_v1-brand_packing-pack_shipmentУпаковочные материалыFulfilment
GET/api/v1/shipmentsget_v1-shipmentsСписок всех поставокGeneral
POST/api/v1/shipments/outpost_v1-shipments-outСоздание исходящей поставкиOutgoing
POST/api/v1/shipments/out/{id}/eventspost_v1-shipments-out-eventsСобытия поставкиOutgoing

5. Статусы поставок​

Входящие поставки (Fulfilment)​

  • CREATED: Поставка создана
  • IN_TRANSIT: В пути
  • ACCEPTED: Принята на складе
  • PARTIALLY_ACCEPTED: Принята частично
  • REJECTED: Отклонена

Исходящие поставки (Outgoing)​

  • CREATED: Создана
  • CONFIRMED: Подтверждена
  • SHIPPED: Отгружена
  • DELIVERED: Доставлена
  • CANCELED: Отменена
  • RETURNED: Возвращена

6. Особенности использования по бизнес-моделям​

FBO (Fulfillment by Operator/Lamoda)​

Используемые endpoints:

  • POST /api/v1/shipments/fulfilment - Создание поставки на склад
  • GET /api/v1/shipments/fulfilment - Список поставок
  • GET /api/v1/shipments/fulfilment/{id} - Детали поставки
  • GET /api/v1/shipments/fulfilment/{id}/items - Товары в поставке

Рабочий процесс:

  1. Создать поставку через POST /api/v1/shipments/fulfilment
  2. Получить ID поставки Lamoda
  3. Отследить статус поставки
  4. Проверить принятые товары

FBS (Fulfillment by Seller)​

Используемые endpoints:

  • POST /api/v1/shipments/out - Сообщить об отгрузке
  • POST /api/v1/shipments/out/{id}/events - Подтвердить/отменить поставку
  • GET /api/v1/shipments - Список поставок

Рабочий процесс:

  1. Получить заказ через Orders API
  2. Собрать заказ на своем складе
  3. Создать исходящую поставку через POST /api/v1/shipments/out
  4. Подтвердить отправку (если не автоподтверждение)
  5. Отследить доставку

DBS (Delivery by Seller)​

Используемые endpoints:

  • POST /api/v1/shipments/out - Сообщить о доставке своим курьером
  • GET /api/v1/shipments - История поставок

Рабочий процесс:

  1. Получить заказ через Orders API
  2. Доставить своим курьером
  3. Сообщить о доставке через POST /api/v1/shipments/out

7. Маркировка товаров (Честный ЗНАК)​

Для маркированных товаров обязательно указание:

  • documentNumber: GUID документа (для поставок с маркировкой)
  • uit: Код маркировки DataMatrix (для единицы товара)
  • uitn: Код маркировки (для групповой упаковки)

Категории маркируемых товаров:

  • Табачные изделия
  • Обувь
  • Одежда
  • Парфюмерия
  • Фотоаппараты и вспышки
  • Шины и покрышки

Пример запроса с маркировкой:

{
  "date": "10.09.2017",
  "id": "187-000-157",
  "documentNumber": "1aa2706f-cacd-4040-b094-c5f9fd844b2b",
  "items": [
    {
      "sku": "SELLERSK157",
      "quantity": 25,
      "price": 999.99,
      "uit": "0104670039709513211nQLE3OjFqRC6Oi0nUXY98aI8a7gNkEDQv8NKNBPH4NJv31fK=="
    }
  ]
}

8. Примеры интеграции​

Пример 1: Создание FBO поставки​

import requests
import json

url = "https://api-b2b.lamoda.ru/api/v1/shipments/fulfilment"
token = "YOUR_OAUTH_TOKEN"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

shipment_data = {
    "date": "10.09.2024",
    "id": "SHIP-2024-001",
    "items": [
        {
            "sku": "PRODUCT001",
            "quantity": 50,
            "price": 1999.99,
            "weight": 500.0,
            "attributes": {
                "color": "BLACK",
                "size": "L"
            }
        }
    ]
}

response = requests.post(url, headers=headers, json=shipment_data)
print(f"Shipment ID: {response.json()['id']}")

Пример 2: Создание FBS отгрузки​

import requests
import json

url = "https://api-b2b.lamoda.ru/api/v1/shipments/out"
token = "YOUR_OAUTH_TOKEN"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

shipment_data = {
    "shipmentId": "FBS-2024-001",
    "orderNr": "123456789",
    "items": [
        {
            "sku": "PRODUCT001",
            "quantity": 1
        }
    ],
    "deliveryMethod": "COURIER",
    "trackingNumber": "TRACK123456",
    "shipmentDate": "2024-04-17"
}

response = requests.post(url, headers=headers, json=shipment_data)
print(f"Shipment created: {response.json()['id']}")

Пример 3: Получение списка поставок​

import requests

url = "https://api-b2b.lamoda.ru/api/v1/shipments"
token = "YOUR_OAUTH_TOKEN"

headers = {
    "Authorization": f"Bearer {token}"
}

params = {
    "page": 1,
    "limit": 25,
    "filter": "direction=in"  # Только входящие
}

response = requests.get(url, headers=headers, params=params)
shipments = response.json()["_embedded"]["shipments"]

for shipment in shipments:
    print(f"ID: {shipment['id']}, Status: {shipment['status']}")

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

1. Идентификация поставок​

  • Используйте уникальные ID поставок с префиксом вашего магазина
  • Храните соответствие ID продавца и ID Lamoda
  • Используйте дату в ID для удобства сортировки

2. Обработка ошибок​

  • Проверяйте статус ответа
  • Логируйте все ошибки 400 и 500
  • Повторяйте запросы при ошибках 500 с exponential backoff

3. Маркировка товаров​

  • Проверяйте обязательность маркировки для категории товара
  • Храните UIT/UITN коды в вашей системе
  • Используйте правильный формат documentNumber (GUID)

4. Отслеживание статусов​

  • Периодически проверяйте статус поставок
  • Используйте вебхуки для уведомлений о смене статуса
  • Храните историю всех изменений статусов

5. Работа с большим количеством товаров​

  • Разбивайте большие поставки на чанки (до 1000 товаров)
  • Используйте пагинацию при получении списков
  • Кэшируйте данные о поставках для оптимизации

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

Дополнительные endpoints для работы с поставками:​

Управление ставками:

  • GET /api/v1/stock/goods - Остатки на складе
  • POST /api/v1/stock/goods - Обновление остатков

Заказы:

  • GET /api/v1/orders - Список заказов
  • GET /api/v1/orders/{orderNr} - Детали заказа

Уведомления:

  • Webhook shipments notifications - Статус поставки

Товары:

  • GET /api/v1/nomenclatures - Справочник номенклатуры

11. Часто задаваемые вопросы (FAQ)​

Q: Какое максимальное количество товаров в одной поставке? A: Рекомендуется не более 1000 товаров в одной поставке. Для больших объемов разбивайте на несколько поставок.

Q: Можно ли изменить уже созданную поставку? A: Нет, после создания поставку нельзя изменить. Можно только создать новую или отменить (для исходящих).

Q: Что делать если товар пришел с браком? A: Для FBO: свяжитесь с поддержкой Lamoda. Для FBS: укажите это в событии поставки или при возврате.

Q: Как быстро обрабатывается поставка? A: Обычно от нескольких минут до нескольких часов. Зависит от размера поставки и нагрузки на склад.

Q: Обязателен ли documentNumber для всех поставок? A: Только если в поставке есть товары с маркировкой (UIT/UITN).

Q: Можно ли создать поставку задним числом? A: Да, можно указать любую дату в прошлом, но рекомендуется использовать актуальные даты.

12. Контакты и поддержка​

Техническая поддержка:

Документация:

GitHub ресурсы:

13. Статистика​

Общее количество endpoints: 8 Входящие поставки (Fulfilment): 5 endpoints Исходящие поставки (Outgoing): 3 endpoints Поддерживаемые бизнес-модели: FBO, FBS, DBS, B2B FF, B2B FBS Максимальное количество товаров в поставке: 1000 (рекомендовано) Токен: OAuth2 Bearer Token (TTL: 24 часа)

Дата создания: 2025-02-10 Версия спецификации: OpenAPI 3.0.0 Статус документации: Полная