Общие изменения контракта API

Часть руководства «Переход на Lamoda Seller API v2».

Эти изменения нужно внести один раз в общий API-клиент до переноса отдельных бизнес-сценариев.

Base URL и версия API

Методы Seller API v2 вызываются с base path /api/v2/....

baseUrl = https://public-api-seller.lamoda.ru/api
path    = /v2/orders

Храните host/base path отдельно от пути метода. Это упростит переключение окружений и позволит использовать один клиент для всех v2-ресурсов.

Авторизация

Вместо старых методов авторизации используйте единый метод:

POST /api/v2/auth-token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>"
}

Успешный ответ содержит access_token, expires_in, token_type, scope. Все бизнес-запросы отправляются с заголовком:

Authorization: Bearer <access_token>

Рекомендации:

• обновляйте токен заранее, не в момент первого 401 в бизнес-процессе;
• не передавайте токен в параметрах URL;
• не логируйте client_secret и полный токен;
• при 401 обновите токен и повторите запрос один раз, затем отдайте ошибку наверх.

JSON-RPC → REST

Если вы мигрируете с Seller Partner JSON-RPC, меняется не только URL, но и форма вызова.

Было:

POST /v1/nomenclature.set-price
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "nomenclature.set-price",
  "params": {
    "sellerId": "242541217",
    "country": "RU",
    "sku": "MP002XW0J7E6R",
    "price": 199900
  }
}

Стало:

POST /api/v2/nomenclature-price
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "sellerId": "242541217",
  "country": "RU",
  "parentSku": "MP002XW0J7E6R",
  "price": {
    "amount": 199900,
    "currency": "RUB"
  },
  "force": false
}

sellerId

sellerId остается явной частью запроса и должен соответствовать токену.

Исключение в текущей спецификации — изменение статуса FBS pickup request: POST /v2/fbs/pickup-requests/{requestId}/status принимает seller_id в теле запроса как integer. Для таких методов ориентируйтесь на конкретную схему запроса, а не на общее правило.

Не подставляйте sellerId из произвольного заказа или SKU. Источник должен быть один: конфигурация интеграции или результат авторизованного выбора продавца.

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

Деньги, даты и страны

• Деньги передаются объектом Price/PriceAmount: amount в минорных единицах валюты и currency.
• Для RUB и BYN минорная единица — копейка, для KZT — тиын.
• Поддерживаемые страны: RU, BY, KZ.
• Timestamp поля передаются в ISO 8601, обычно UTC с Z: 2025-06-01T00:00:00.000Z.
• Даты поставок могут быть датой без времени: 2024-05-30.

Пагинация, фильтры и сортировка

Большинство списков используют page и limit. Не копируйте старый лимит автоматически: у разных методов разные ограничения.

Сортировку передавайте по схеме конкретного метода: имя поля или -field для убывания. Массивные query-параметры передавайте повторением параметра, если это указано в спецификации метода:

GET /api/v2/fbo/stocks?sellerId=12345&sku=SKU1&sku=SKU2&withZeroQuantity=false

Ошибки и повторы

Типовая ошибка v2:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Проверьте переданные данные",
    "details": [
      {"field": "prices[0].price.amount", "issue": "must be greater than 0"}
    ]
  }
}

Это формат HTTP-ошибки ApiError. Не смешивайте его с доменными ошибками внутри успешных бизнес-ответов. Например, при массовом обновлении цен ошибка конкретного товара может вернуться в errors[] с кодом VALIDATION_ERROR, даже если сам HTTP-запрос обработан.

Для массовых интеграций ведите лимиты и очереди отдельно по sellerId. Если в ответе есть Retry-After, используйте его; если нет — применяйте увеличивающуюся паузу со случайным разбросом, чтобы проблемы одного продавца не блокировали остальных.

Статусы

В v2 важно различать:

• статусы, которые приходят в ответах (OrderResponseStatusEnum, OrderItemResponseStatusEnum, FBOShipmentStatusEnum);
• статусы, которые разрешено отправлять в методах изменения данных.

Например, POST /v2/orders/{orderId}/status принимает ограниченный набор статусов, а фактический переход зависит от сценария обработки заказа. Не используйте полный список статусов из ответа как список допустимых значений для изменения.

См. также

• Переход на Lamoda Seller API v2
• Каталог, цены и остатки
• Заказы, FBS и этикетки
• FBO, возвраты, вопросы, акции и сертификаты
• Справочник соответствия методов