Страницы и синхронизация

Каждый список API — ещё и лента изменений: один раз прочитайте его до конца, а потом возвращайтесь с курсором синхронизации за тем, что изменилось с тех пор.

Загружаем поисковый индекс…

Страницы и синхронизация

Списки

Каждый список отвечает одними и теми же полями:

ПолеЧто это
dataЗаписи страницы.
next_cursorКурсор следующей страницы; null на последней.
has_moretrue, когда есть следующая страница.
sync_cursorТолько на последней странице: курсор, чтобы продолжить позже.
deletedЗаписи, стёртые из базы, в виде {id, deleted_at}; только в продолжении с include_deleted=true.

limit задаёт размер страницы, до 250 записей. Курсор непрозрачен: отправляйте его обратно ровно таким, каким он пришёл.

Отправьте Accept-Encoding: gzip — страница придёт сжатой, в разы меньше; большинство HTTP-клиентов делает это само. Запись с ETag приходит несжатой: сжатие изменило бы тег, который сверяет If-Match.

Синхронизация копии

  1. Первая синхронизация: прочитайте список без курсора, страница за страницей по next_cursor, пока has_more не станет false.
  2. Сохраните sync_cursor последней страницы.
  3. Следующая синхронизация: отправьте сохранённый курсор. Список вернёт только изменённое после него и закончится новым sync_cursor.
Запрос
curl "https://api.saleya.app/v1/orders?include_deleted=true&limit=250" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"

Список идёт в порядке, в котором изменения были закоммичены, а не по updated_at. Изменение, которое ещё записывалось, пока вы читали, придёт со следующей синхронизацией, и ни одно не пропадёт — этого фильтр по времени обещать не может.

Фильтры и курсор

Курсор принадлежит фильтрам, с которыми выдан: updated_since, include_deleted и фильтрам списка. Отправляйте те же фильтры с каждой страницей и каждой следующей синхронизацией; курсор с другими фильтрами получает 422.

updated_since начинает первую синхронизацию с момента, а не с начала — например, заказы за последний месяц. Продолжайте отправлять его вместе с курсором: курсор продолжает с того места, где синхронизация остановилась.

Удалённые записи

С include_deleted=true список отдаёт и удалённое:

  • запись в архиве приходит в data с заполненным deleted_at;
  • запись, стёртая из базы, приходит в deleted как {id, deleted_at} — только в продолжении по курсору, поэтому первая синхронизация их не отдаёт.
Запрос
curl "https://api.saleya.app/v1/products?include_deleted=true&limit=250&cursor=eyJmIjoiOWQ0ZjJhIiwicyI6IjQwMjE3OjQwMjE3OiJ9" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ответ
HTTP/1.1 200 OK

{
  "data": [],
  "deleted": [
    {
      "id": 318,
      "deleted_at": "2026-11-10T18:02:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "sync_cursor": "eyJmIjoiOWQ0ZjJhIiwicyI6IjQwNTUxOjQwNTUxOiJ9"
}

Устаревший курсор

Стёртые записи помнятся 30 дней, поэтому более старый курсор мог бы пропустить одну из них и получает 410 cursor_expired. То же бывает после восстановления данных магазина из резервной копии. Начните синхронизацию заново без курсора; синхронизация хотя бы раз в неделю этого не допускает.

Пример

Синхронизация товаров на Node.js: одни и те же фильтры в каждом запросе, удалённые записи применяются, пауза на 429 и новый старт на 410.

Node.js
const API = 'https://api.saleya.app/v1'

/*
 * The cursor is bound to the filters it was issued with, so every request of the feed sends
 * the same ones — the first sync, each next page and every later sync.
 */
const FILTERS = 'include_deleted=true&limit=250'

/**
 * Brings the local copy of the products up to date and returns the cursor for the next run.
 *
 * cursor — the cursor returned by the previous run, null on the first run.
 * save, remove — write and delete a product on your side; they must accept the same product twice.
 */
export async function syncProducts({ token, cursor, save, remove, fetch = globalThis.fetch }) {
  let next = cursor
  for (;;) {
    const url = `${API}/products?${FILTERS}${next === null ? '' : `&cursor=${encodeURIComponent(next)}`}`
    const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } })

    if (response.status === 429) {
      await sleep(Number(response.headers.get('Retry-After') ?? '1') * 1000)
      continue
    }
    if (response.status === 410) {
      // cursor_expired: the cursor is older than 30 days — sync the whole feed again.
      next = null
      continue
    }
    if (!response.ok) {
      const problem = await response.json()
      throw new Error(`Saleya API ${response.status} ${problem.type}: ${problem.detail ?? problem.title}`)
    }

    const page = await response.json()
    for (const product of page.data) {
      await (product.deleted_at === null ? save(product) : remove(product.id))
    }
    for (const tombstone of page.deleted) {
      await remove(tombstone.id)
    }
    if (!page.has_more) {
      return page.sync_cursor
    }
    next = page.next_cursor
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms))
}

Вебхуки сразу сообщают, что что-то изменилось, а источником правды остаётся список: запускайте синхронизацию по расписанию и по приходу вебхука — см. вебхуки.

Следующий гайдМассовые операции