Списки
Каждый список отвечает одними и теми же полями:
| Поле | Что это |
|---|---|
data | Записи страницы. |
next_cursor | Курсор следующей страницы; null на последней. |
has_more | true, когда есть следующая страница. |
sync_cursor | Только на последней странице: курсор, чтобы продолжить позже. |
deleted | Записи, стёртые из базы, в виде {id, deleted_at}; только в продолжении с include_deleted=true. |
limit задаёт размер страницы, до 250 записей. Курсор непрозрачен: отправляйте его обратно ровно таким, каким он пришёл.
Отправьте Accept-Encoding: gzip — страница придёт сжатой, в разы меньше; большинство HTTP-клиентов делает это само. Запись с ETag приходит несжатой: сжатие изменило бы тег, который сверяет If-Match.
Синхронизация копии
- Первая синхронизация: прочитайте список без курсора, страница за страницей по
next_cursor, покаhas_moreне станетfalse. - Сохраните
sync_cursorпоследней страницы. - Следующая синхронизация: отправьте сохранённый курсор. Список вернёт только изменённое после него и закончится новым
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.
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))
}
Вебхуки сразу сообщают, что что-то изменилось, а источником правды остаётся список: запускайте синхронизацию по расписанию и по приходу вебхука — см. вебхуки.