Listados
Cada listado responde con los mismos campos:
| Campo | Qué es |
|---|---|
data | Los registros de la página. |
next_cursor | Cursor de la página siguiente; null en la última. |
has_more | true cuando hay una página siguiente. |
sync_cursor | Solo en la última página: el cursor para seguir más tarde. |
deleted | Registros 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
- Primera sincronización: leé el listado sin cursor, página por página con
next_cursor, hasta quehas_moreseafalse. - Guardá el
sync_cursorde la última página. - Siguiente sincronización: enviá el cursor guardado. El listado devuelve solo lo que cambió después y termina con un
sync_cursornuevo.
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
datacondeleted_atcompleto; - un registro borrado de la base llega en
deletedcomo{id, deleted_at}— solo al seguir con un cursor, así que la primera sincronización no los devuelve.
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"
}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.
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.