Зачем нужна пагинация

В реальном магазине могут быть тысячи товаров, сотни тысяч заказов и миллионы строк в отчётах. API не может вернуть все данные за один запрос — это привело бы к таймаутам и перегрузкам. Поэтому данные возвращаются порциями (страницами), а вы последовательно запрашиваете следующую порцию.

В WB API используются три подхода к пагинации. Конкретный подход зависит от категории API и метода — он указан в документации каждого метода.

---

Подход 1: Курсор (cursor)

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

Как работает

Вы передаёте объект cursor в теле POST-запроса. В ответе API возвращает данные и обновлённый cursor — его нужно подставить в следующий запрос.

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

Первый запрос — передайте cursor с limit (количество элементов на странице):

{
  "settings": {
    "cursor": {
      "limit": 100
    },
    "filter": {
      "withPhoto": -1
    }
  }
}

Ответ — API вернёт данные и обновлённый cursor:

{
  "cards": [ ... ],
  "cursor": {
    "updatedAt": "2026-04-03T10:00:00Z",
    "nmID": 370870300,
    "total": 100
  }
}

Следующий запрос — скопируйте updatedAt и nmID из ответа в запрос:

{
  "settings": {
    "cursor": {
      "updatedAt": "2026-04-03T10:00:00Z",
      "nmID": 370870300,
      "limit": 100
    },
    "filter": {
      "withPhoto": -1
    }
  }
}

Когда остановиться

Повторяйте запросы, пока значение total в ответе не станет меньше limit. Если total < limit — это последняя страница, все данные получены.

---

Подход 2: Смещение (limit + offset)

Используется в категориях Аналитика, Продвижение, Отчёты и некоторых методах Общего API.

Как работает

Вы передаёте два query-параметра:

• limit — сколько элементов вернуть (размер страницы)
• offset — сколько элементов пропустить с начала

Пример

Первая страница (элементы 1–100):

GET /api/v1/analytics/search-data?limit=100&offset=0

Вторая страница (элементы 101–200):

GET /api/v1/analytics/search-data?limit=100&offset=100

Третья страница (элементы 201–300):

GET /api/v1/analytics/search-data?limit=100&offset=200

Когда остановиться

Повторяйте, увеличивая offset на limit, пока количество возвращённых элементов не станет меньше limit. Некоторые методы также возвращают поле total с общим количеством элементов.

Ограничения

• Максимальное значение limit различается по методам (от 30 до 1000) — проверяйте в документации
• При больших значениях offset запросы могут работать медленнее
• Если данные изменяются между запросами, возможны пропуски или дубли

---

Подход 3: Токен продолжения (next)

Используется в категориях Маркетплейс (заказы FBS, DBS, DBW), Вопросы и отзывы, Самовывоз и Финансы.

Как работает

API возвращает в ответе параметр next — идентификатор, с которого нужно начать следующий запрос. Для первого запроса используйте next=0.

Пример: получение заказов

Первый запрос:

GET /api/v3/orders?next=0&limit=1000&dateFrom=1698045576

Ответ:

{
  "next": 1698045590000,
  "orders": [ ... ]
}

Следующий запрос — подставьте next из ответа:

GET /api/v3/orders?next=1698045590000&limit=1000&dateFrom=1698045576

Вариант: rrdid для финансовых отчётов

В категории «Финансы» (детализированный отчёт) используется аналогичный механизм, но параметр называется rrdid:

1. Первый запрос: rrdid=0
2. В ответе — массив строк, в последней строке есть поле rrd_id
3. Следующий запрос: подставьте rrd_id из последней строки как rrdid
4. Повторяйте, пока не получите ответ с кодом 204 No Content — все данные получены

Когда остановиться

Зависит от метода:

• Заказы: next равен 0 или массив заказов пуст
• Чат/события: totalEvents равен 0
• Финансы: HTTP-код ответа 204

---

Фильтрация по дате

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

Фильтрация по дате часто комбинируется с одним из подходов выше. Например:

GET /api/v3/orders?next=0&limit=1000&dateFrom=1698045576&dateTo=1698131976

Формат даты зависит от метода — это может быть Unix-timestamp (секунды или миллисекунды), ISO 8601 (2026-04-01T00:00:00Z) или дата в формате YYYY-MM-DD. Проверяйте формат в документации конкретного метода.

---

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

Учитывайте лимиты запросов. Каждый запрос пагинации — это отдельный запрос к API, который учитывается в лимитах. Делайте паузы между запросами, чтобы не получить ошибку 429. Подробнее — в статье «Лимиты запросов WB API».

Используйте максимальный limit. Чем больше limit, тем меньше запросов нужно для получения всех данных. Проверяйте максимально допустимое значение в документации метода.

Обрабатывайте ошибки между страницами. Если запрос одной страницы вернул ошибку (5XX, 429) — повторите именно этот запрос, а не начинайте сначала. Курсор и next позволяют продолжить с того места, где остановились.

Логируйте прогресс. При обработке больших объёмов данных (например, выгрузка всех заказов за год) сохраняйте текущий cursor или next, чтобы продолжить в случае сбоя.

Не храните offset в долгоживущих процессах. Если данные изменяются — используйте курсорную пагинацию или токен продолжения. Offset-подход надёжен только для стабильных данных (справочники, аналитика за прошлый период).

---

Какой подход в каком API

Конкретные параметры и максимальные значения limit указаны в документации каждого метода на портале разработчиков.

---

Что дальше

• Отправьте первый запрос — если ещё не работали с API, начните с пошагового гайда в статье «Первый запрос к WB API»
• Настройте обработку ошибок — в статье «Расшифровка кодов ошибок WB API»
• Учитывайте лимиты — в статье «Лимиты запросов WB API»