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

offer_id, product_id, пагинация курсором, форматы дат и валют.

Идентификация товара: 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 и FBO

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

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