Общие концепции

Идентификация товара: offer_id и product_id

• offer_id – ваш артикул (строка). Задаётся продавцом.
• product_id – внутренний идентификатор маркетплейса.

Правило приоритета: если в запросе передан offer_id, используется он; product_id игнорируется.

Важные особенности: Правило не учитывается в курсорной пагинации.

Пример:

{
  "offer_id": "SKU-12345",
  "product_id": "market-67890"
}
// Будет обработан offer_id = "SKU-12345"

Курсорная пагинация

Методы, возвращающие списки, используют курсорную пагинацию. Это позволяет эффективно работать с большими объёмами данных без скачков производительности.

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

• cursor (string) – маркер позиции, полученный из предыдущего ответа. Для первого запроса не передаётся.
• limit (int) – максимальное количество записей в ответе. Рекомендуется 100–300, максимум – 500.

Параметры ответа:

• next_cursor (string) – маркер для следующего запроса. Если null или пустая строка – данных больше нет.
• total (int) – точное общее количество записей, соответствующих фильтру (может отсутствовать в будущих версиях).

Важные особенности:

• Курсор можно использовать без фильтра – для последовательного обхода всех записей.
• Если после запроса с фильтром вы передадите тот же курсор, но без фильтра, вы продолжите чтение с той же позиции (фильтр не запоминается).
• Если передать курсор с другим фильтром, чтение продолжится, но результат будет по новому фильтру.
• Фильтры offer_id и product_id объединяются по «И» – возвращаются записи, удовлетворяющие обоим условиям.
• При изменении данных (добавление/удаление записей) курсорная пагинация остаётся стабильной, если сортировка идёт по неизменяемому полю (id, created_at). Сортировка по updated_at может приводить к дубликатам или пропускам, поэтому не рекомендуется для полной выгрузки.

Пример последовательности запросов:

// 1. Первая страница
{ "limit": 100 }
// Ответ: { "items": [...], "next_cursor": "abc123", "total": 350 }

// 2. Вторая страница
{ "cursor": "abc123", "limit": 100 }
// ... и так далее

Форматы дат и времени

Все даты передаются в формате RFC3339 (ISO 8601):

"created_at": "2026-05-14T12:05:00Z"

Валюты и цены

• Коды валют: RUB, BYN, KZT, EUR, USD, CNY.
• Цены передаются в копейках (умноженные на 100).
  Пример: 49990 = 499.90 руб.

Схемы работы: DBS и FBS

• DBS (Delivery by Seller) – продавец управляет логистикой (свои склады, полигоны доставки). Подробнее в руководстве по DBS.
• FBS (Fulfillment by Seller) – продавец использует склады маркетплейса для приёмки и обработки заказов. Подробнее в руководстве по FBS.

Методы по схемам разделены в справочнике API.