Paginación y sincronización

Cada listado de la API es también un feed de cambios: leelo hasta el final una vez y después volvé con el cursor de sincronización por lo que cambió desde entonces.

Cargando el índice de búsqueda…

Paginación y sincronización

Listados

Cada listado responde con los mismos campos:

CampoQué es
dataLos registros de la página.
next_cursorCursor de la página siguiente; null en la última.
has_moretrue cuando hay una página siguiente.
sync_cursorSolo en la última página: el cursor para seguir más tarde.
deletedRegistros borrados de la base, como {id, deleted_at}; solo al seguir con include_deleted=true.

limit fija el tamaño de la página, hasta 250 registros. Un cursor es opaco: devolvelo tal como llegó.

Mandá Accept-Encoding: gzip y la página llega comprimida, varias veces más liviana; la mayoría de los clientes HTTP lo hace solo. Un registro que responde con ETag llega sin comprimir: la compresión cambiaría la etiqueta que compara If-Match.

Mantené una copia sincronizada

  1. Primera sincronización: leé el listado sin cursor, página por página con next_cursor, hasta que has_more sea false.
  2. Guardá el sync_cursor de la última página.
  3. Siguiente sincronización: enviá el cursor guardado. El listado devuelve solo lo que cambió después y termina con un sync_cursor nuevo.
Solicitud
curl "https://api.saleya.app/v1/orders?include_deleted=true&limit=250" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"

El listado va en el orden en que se confirmaron los cambios, no por updated_at. Un cambio que todavía se estaba escribiendo mientras leías llega con la siguiente sincronización, y ninguno se saltea — algo que un filtro por tiempo no puede prometer.

Filtros y cursor

Un cursor pertenece a los filtros con los que se emitió: updated_since, include_deleted y los filtros del listado. Enviá los mismos filtros con cada página y cada sincronización posterior; un cursor con otros filtros recibe 422.

updated_since empieza la primera sincronización desde un momento en lugar del principio — por ejemplo, los pedidos del último mes. Seguí enviándolo con el cursor: el cursor continúa desde donde se detuvo la sincronización.

Registros eliminados

Con include_deleted=true el listado devuelve también lo eliminado:

  • un registro archivado llega en data con deleted_at completo;
  • un registro borrado de la base llega en deleted como {id, deleted_at} — solo al seguir con un cursor, así que la primera sincronización no los devuelve.
Solicitud
curl "https://api.saleya.app/v1/products?include_deleted=true&limit=250&cursor=eyJmIjoiOWQ0ZjJhIiwicyI6IjQwMjE3OjQwMjE3OiJ9" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Respuesta
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"
}

Cursores vencidos

Los registros borrados se recuerdan durante 30 días, así que un cursor más viejo podría perder alguno y recibe 410 cursor_expired. Lo mismo pasa después de restaurar los datos de la tienda desde una copia de seguridad. Empezá la sincronización de nuevo sin cursor; sincronizar al menos una vez por semana lo evita.

Ejemplo

Una sincronización de productos en Node.js: los mismos filtros en cada solicitud, los eliminados aplicados, una pausa ante 429 y un nuevo comienzo ante 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))
}

Los webhooks avisan enseguida que algo cambió, y el listado sigue siendo la fuente de verdad: corré la sincronización con una frecuencia fija y cuando llega un webhook — mirá webhooks.

Siguiente guíaOperaciones masivas