Endpoints API стоков (Stocks)

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

Обзор

Lamoda предоставляет 3 endpoints/methods для управления стоками через 2 API-системы:

B2B Platform API: 2 endpoints (REST) - получение и установка стоков для товаров
Seller JSON-RPC API: 1 method (JSON-RPC) - получение списка стоков с расширенной фильтрацией

API предоставляет полную функциональность для отслеживания и обновления количества товаров на складах Lamoda (для модели FBO) и на складах продавца (для модели FBS).

1. B2B Platform API - Стоки

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

1.1 Получение информации о стоке

Method: GET Path: /api/v1/stock/goods Operation ID: get_v1-stock-goods Tags: Сток

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

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

Query parameters:
- page (integer, optional): Номер страницы (по умолчанию 1, больше 0)
- limit (integer, optional): Количество значений на странице (по умолчанию 25, больше 0)
- withZeroQuantity (string, optional): Включить отображение товаров с нулевым стоком: "0" - не включать, "1" - включить (по умолчанию "1")
- updatedAt (string, optional): Дата и время обновления стока (формат: YYYY-MM-DD+hh:mm:ss, например: 2020-01-01+10:00:00)
- sku[] (array of string, optional): Список номенклатур для фильтрации (от 1 до 100 артикулов, формат: sku[]=2345&sku[]=2333)

Ответы:

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

{
  "page": 1,
  "limit": 25,
  "pages": 1,
  "total": 10,
  "_links": {
    "self": "href",
    "first": "href",
    "last": "href",
    "next": "href",
    "prev": "href"
  },
  "_embedded": {
    "stockStates": [
      {
        "sku": "B7324031-DEEP NAVY-3XL",
        "quantity": 10
      }
    ]
  }
}

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
500 Internal Server Error: Внутренняя ошибка сервера

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

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

Пример запроса с фильтрацией по артикулам:

curl -X GET 'https://api-b2b.lamoda.ru/api/v1/stock/goods?sku[]=B7324031-DEEP NAVY-3XL&sku[]=B7324032-BLACK-L' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Пример запроса с фильтрацией по дате обновления:

curl -X GET 'https://api-b2b.lamoda.ru/api/v1/stock/goods?updatedAt=2025-01-01+10:00:00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Примечания:

Параметр withZeroQuantity позволяет управлять отображением товаров с нулевым остатком
Параметр updatedAt используется для инкрементальной загрузки изменений стока
Фильтрация по sku[] позволяет получать стоки для конкретных товаров
Максимальное количество артикулов в одном запросе - 100

1.2 Установка стока

Method: POST Path: /api/v1/stock/goods Operation ID: post_v1-stock-goods Tags: Сток

Описание: Запись данных о количестве товаров, которые находятся на хранении на складе партнёра (сток). Используется для схемы работы FBS (Fulfillment by Seller), когда продавец самостоятельно хранит и собирает товары.

Тело запроса:

{
  "stockStates": [
    {
      "sku": "B7324031-DEEP NAVY-3XL",
      "quantity": 50
    },
    {
      "sku": "B7324032-BLACK-L",
      "quantity": 25
    }
  ]
}

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

Body (JSON):
- stockStates (array of objects, required): Список стоков для обновления
  - sku (string, required): Артикул номенклатуры
  - quantity (integer, required): Сток номенклатуры (количество товаров)

Ответы:

200 OK: Сток успешно установлен

{
  "stockStates": [
    {
      "sku": "B7324031-DEEP NAVY-3XL",
      "quantity": 50
    },
    {
      "sku": "B7324032-BLACK-L",
      "quantity": 25
    }
  ]
}

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
500 Internal Server Error: Внутренняя ошибка сервера

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

curl -X POST 'https://api-b2b.lamoda.ru/api/v1/stock/goods' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "stockStates": [
      {
        "sku": "B7324031-DEEP NAVY-3XL",
        "quantity": 50
      },
      {
        "sku": "B7324032-BLACK-L",
        "quantity": 25
      }
    ]
  }'

Примечания:

Данный endpoint используется только для модели работы FBS
Можно обновлять стоки для нескольких товаров в одном запросе
Отрицательные значения quantity не допускаются
При установке стока в 0 товар перестает быть доступен для продажи

2. Seller JSON-RPC API - Стоки

Base URL: https://public-api-seller.lamoda.ru API Format: JSON-RPC 2.0 Authentication: Bearer Token Total Methods: 1

2.1 Получение списка стоков

Method: POST (JSON-RPC) Path: /v1/stock.list Operation ID: v1.stock.getList Tags: seller-stock

Описание: Получение списка стоков с возможностью фильтрации по складу, артикулам Lamoda или артикулам продавца. Поддерживает постраничную навигацию. Возвращает расширенную информацию о стоках включая временные метки создания и обновления.

Тело запроса (JSON-RPC):

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "method": "v1.stock.getList",
  "params": {
    "seller_id": 123,
    "warehouse_code": "BYKOVO",
    "lamoda_sku_list": ["LAMODA_SKU1", "LAMODA_SKU2"],
    "seller_sku_list": ["SELLER_SKU1", "SELLER_SKU2"],
    "limit": 100,
    "page": 1
  }
}

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

JSON-RPC envelope:
- jsonrpc (string, required): Версия протокола (всегда "2.0")
- id (string, required): Уникальный идентификатор запроса (UUID)
- method (string, required): Имя метода (всегда "v1.stock.getList")
- params (object, required): Параметры метода
  - seller_id (integer, required): Идентификатор продавца
  - warehouse_code (string, optional): Код склада для фильтрации (например: "BYKOVO", "SOFINO")
  - lamoda_sku_list (array of string, optional): Список артикулов Lamoda для фильтрации
  - seller_sku_list (array of string, optional): Список артикулов продавца для фильтрации
  - limit (integer, optional): Количество элементов на странице (по умолчанию 100)
  - page (integer, optional): Номер страницы (по умолчанию 1)

Ответы:

200 OK: Список стоков получен

{
  "jsonrpc": "2.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "data": [
      {
        "lamoda_sku": "LAMODA_SKU1",
        "seller_sku": "SELLER_SKU1",
        "seller_id": 123,
        "quantity": 100,
        "warehouse_code": "BYKOVO",
        "created_at": "2025-04-14 06:52:28",
        "updated_at": "2025-04-14 06:52:28"
      },
      {
        "lamoda_sku": "LAMODA_SKU2",
        "seller_sku": "SELLER_SKU2",
        "seller_id": 123,
        "quantity": 50,
        "warehouse_code": "BYKOVO",
        "created_at": "2025-04-14 06:52:28",
        "updated_at": "2025-04-14 06:52:28"
      }
    ],
    "pagination": {
      "limit": 100,
      "page": 1,
      "total": 250
    }
  }
}

400 Bad Request: Неверный параметр
401 Unauthorized: Отказ в доступе
403 Forbidden: Доступ запрещен
500 Internal Server Error: Внутренняя ошибка сервера

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

curl -X POST 'https://public-api-seller.lamoda.ru/v1/stock.list' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "method": "v1.stock.getList",
    "params": {
      "seller_id": 123,
      "limit": 100,
      "page": 1
    }
  }'

Пример запроса с фильтрацией по складу:

curl -X POST 'https://public-api-seller.lamoda.ru/v1/stock.list' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "method": "v1.stock.getList",
    "params": {
      "seller_id": 123,
      "warehouse_code": "BYKOVO",
      "limit": 100,
      "page": 1
    }
  }'

Пример запроса с фильтрацией по артикулам Lamoda:

curl -X POST 'https://public-api-seller.lamoda.ru/v1/stock.list' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "method": "v1.stock.getList",
    "params": {
      "seller_id": 123,
      "lamoda_sku_list": ["LAMODA_SKU1", "LAMODA_SKU2"],
      "limit": 100,
      "page": 1
    }
  }'

Примечания:

Параметр seller_id является обязательным
Параметры warehouse_code, lamoda_sku_list и seller_sku_list являются взаимоисключающими для фильтрации
Метод возвращает более детальную информацию по сравнению с B2B Platform API, включая временные метки
Список кодов складов можно получить через метод v1.fbo.warehouse.list
Формат даты и времени в полях created_at и updated_at: "YYYY-MM-DD HH:MM:SS"

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

API System	Method	Path	Operation ID	Описание
B2B Platform API	GET	`/api/v1/stock/goods`	`get_v1-stock-goods`	Получение информации о стоке
B2B Platform API	POST	`/api/v1/stock/goods`	`post_v1-stock-goods`	Установка стока (для FBS)
JSON-RPC API	POST	`/v1/stock.list`	`v1.stock.getList`	Получение списка стоков с фильтрацией

Ключевые особенности

B2B Platform API vs JSON-RPC API

Характеристика	B2B Platform API	JSON-RPC API
Формат	REST	JSON-RPC 2.0
Аутентификация	OAuth2 Bearer Token	Bearer Token
Получение стоков	GET `/api/v1/stock/goods`	POST `/v1/stock.list`
Установка стоков	POST `/api/v1/stock/goods`	Не поддерживается
Фильтрация по складу	Не поддерживается	Поддерживается
Временные метки	Не возвращаются	Возвращаются
Формат даты	`YYYY-MM-DD+hh:mm:ss`	`YYYY-MM-DD HH:MM:SS`
Использование	FBO и FBS	В основном для FBS

Особенности использования

Для модели FBO (Fulfillment by Operator/Lamoda):
- Используйте B2B Platform API GET /api/v1/stock/goods для получения информации о стоках на складах Lamoda
- Установка стоков не требуется (Lamoda управляет стоками автоматически)
Для модели FBS (Fulfillment by Seller):
- Используйте B2B Platform API POST /api/v1/stock/goods для установки стоков на своем складе
- Используйте JSON-RPC API /v1/stock.list для получения детализированной информации о стоках
- Обязательно обновляйте стоки после каждого изменения остатков
Инкрементальная загрузка:
- Используйте параметр updatedAt в B2B Platform API для загрузки только измененных стоков
- Рекомендуется выполнять периодическую синхронизацию (например, каждый час)
Массовые операции:
- B2B Platform API: можно фильтровать до 100 артикулов в одном запросе
- JSON-RPC API: можно фильтровать по списку артикулов Lamoda или продавца
- Используйте постраничную навигацию для обработки больших объемов данных

Сценарии интеграции

Сценарий 1: Первичная загрузка всех стоков

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

B2B Platform API:

curl -X GET 'https://api-b2b.lamoda.ru/api/v1/stock/goods?page=1&limit=100&withZeroQuantity=0' \
  -H 'Authorization: Bearer YOUR_TOKEN'

JSON-RPC API:

curl -X POST 'https://public-api-seller.lamoda.ru/v1/stock.list' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "uuid-1",
    "method": "v1.stock.getList",
    "params": {
      "seller_id": 123,
      "limit": 1000,
      "page": 1
    }
  }'

Сценарий 2: Инкрементальная синхронизация стоков

Используется для периодического обновления только измененных стоков.

B2B Platform API:

curl -X GET 'https://api-b2b.lamoda.ru/api/v1/stock/goods?updatedAt=2025-02-10+10:00:00' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Сценарий 3: Получение стоков для конкретных товаров

Используется для проверки остатков по списку артикулов.

B2B Platform API:

curl -X GET 'https://api-b2b.lamoda.ru/api/v1/stock/goods?sku[]=SKU1&sku[]=SKU2&sku[]=SKU3' \
  -H 'Authorization: Bearer YOUR_TOKEN'

JSON-RPC API:

curl -X POST 'https://public-api-seller.lamoda.ru/v1/stock.list' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "uuid-1",
    "method": "v1.stock.getList",
    "params": {
      "seller_id": 123,
      "seller_sku_list": ["SKU1", "SKU2", "SKU3"]
    }
  }'

Сценарий 4: Обновление стоков для FBS

Используется продавцом для обновления остатков на своем складе.

B2B Platform API:

curl -X POST 'https://api-b2b.lamoda.ru/api/v1/stock/goods' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "stockStates": [
      {"sku": "SKU1", "quantity": 100},
      {"sku": "SKU2", "quantity": 50},
      {"sku": "SKU3", "quantity": 0}
    ]
  }'

Python пример:

import requests
import json

def update_stocks(token, stock_updates):
    """
    Обновление стоков для модели FBS.

    Args:
        token: OAuth2 токен
        stock_updates: Список словарей [{'sku': 'SKU1', 'quantity': 100}, ...]
    """
    url = "https://api-b2b.lamoda.ru/api/v1/stock/goods"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    data = {"stockStates": stock_updates}

    response = requests.post(url, headers=headers, data=json.dumps(data))
    response.raise_for_status()
    return response.json()

# Пример использования
stock_updates = [
    {"sku": "B7324031-DEEP NAVY-3XL", "quantity": 100},
    {"sku": "B7324032-BLACK-L", "quantity": 50},
    {"sku": "B7324033-RED-M", "quantity": 0}
]

result = update_stocks("YOUR_TOKEN", stock_updates)
print(f"Обновлено стоков: {len(result['stockStates'])}")

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

Products API: Управление номенклатурами и товарами (стоки привязаны к артикулам)
Orders API: Заказы используют информацию о стоках для проверки доступности
Warehouses API: Управление складами (через JSON-RPC метод v1.fbo.warehouse.list)
Business Models: FBO (стоки на складах Lamoda) vs FBS (стоки у продавца)

Дополнительные сведения

Часто задаваемые вопросы

Q: Как часто нужно обновлять стоки для FBS? A: Рекомендуется обновлять стоки в реальном времени при каждом изменении остатков, либо выполнять периодическую синхронизацию каждые 15-30 минут.

Q: Что произойдет если установить сток в 0? A: Товар перестанет быть доступен для продажи на платформе Lamoda.

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

Q: В чем разница между seller_sku и lamoda_sku? A: seller_sku - это артикул товара в системе продавца, lamoda_sku - это артикул, присвоенный Lamoda. Они могут отличаться.

Q: Как узнать код склада для фильтрации? A: Используйте метод v1.fbo.warehouse.list в JSON-RPC API для получения списка всех складов.

Q: Поддерживается ли пакетная загрузка стоков? A: Да, вы можете обновлять стоки для нескольких товаров в одном запросе (до 100 артикулов для фильтрации в B2B API).

Статистика

Total endpoints/methods: 3
B2B Platform API endpoints: 2
JSON-RPC API methods: 1
Поддерживаемые бизнес-модели: FBO, FBS
Постраничная навигация: Поддерживается
Фильтрация по складам: Поддерживается (только JSON-RPC)
Инкрементальная загрузка: Поддерживается (только B2B Platform API)

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

Обзор​

1. B2B Platform API - Стоки​

1.1 Получение информации о стоке​

1.2 Установка стока​

2. Seller JSON-RPC API - Стоки​

2.1 Получение списка стоков​

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

Ключевые особенности​

B2B Platform API vs JSON-RPC API​

Особенности использования​

Сценарии интеграции​

Сценарий 1: Первичная загрузка всех стоков​

Сценарий 2: Инкрементальная синхронизация стоков​

Сценарий 3: Получение стоков для конкретных товаров​

Сценарий 4: Обновление стоков для FBS​

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

Дополнительные сведения​

Часто задаваемые вопросы​

Статистика​

Обзор

1. B2B Platform API - Стоки

1.1 Получение информации о стоке

1.2 Установка стока

2. Seller JSON-RPC API - Стоки

2.1 Получение списка стоков

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

Ключевые особенности

B2B Platform API vs JSON-RPC API

Особенности использования

Сценарии интеграции

Сценарий 1: Первичная загрузка всех стоков

Сценарий 2: Инкрементальная синхронизация стоков

Сценарий 3: Получение стоков для конкретных товаров

Сценарий 4: Обновление стоков для FBS

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

Дополнительные сведения

Часто задаваемые вопросы

Статистика