Пагінація та синхронізація

Списки (GET /proposals/search, GET /proposals/my) повертають однакову обгортку:

{
  "data": [ /* … заявки … */ ],
  "nextCursor": "eyJvIjoyMH0",
  "total": 137
}

• data — сторінка результатів.
• nextCursor — непрозорий рядок для наступної сторінки або null, якщо сторінок більше немає.
• total — скільки всього записів під фільтр.

Розмір сторінки

Параметр limit: за замовчуванням 20, максимум 100. Більше значення не є помилкою — воно мовчки зменшується до 100. Тобто limit=500 поверне 100 записів, а не 400.

Перехід сторінками

Передайте отриманий nextCursor у параметрі cursor:

# перша сторінка
curl "https://api.samo-trans.com/api/public/v1/proposals/search?type=CARGO&limit=50" \
  -H "Authorization: Bearer $SAMO_KEY"

# наступна
curl "https://api.samo-trans.com/api/public/v1/proposals/search?type=CARGO&limit=50&cursor=eyJvIjo1MH0" \
  -H "Authorization: Bearer $SAMO_KEY"

Курсор непрозорий: не розбирайте й не конструюйте його самостійно, передавайте рівно те значення, яке повернув сервер. Його формат може змінитися без зміни версії API.

Важливо: курсор не є «keyset»

Курсор наразі кодує зміщення, а не позицію в стабільному порядку. З цього випливають два практичні наслідки:

1. Глибокі сторінки дорожчають. Проходити тисячі сторінок, щоб вивантажити всю біржу, — поганий сценарій: він повільний і навантажує обидві сторони.
2. Між сторінками стрічка змінюється. Поки ви читаєте сторінку 3, на біржу додають нові заявки — запис може повторитися на іншій сторінці або, навпаки, зникнути.

Тому завжди дедуплікуйте за id і не покладайтеся на те, що об'єднання всіх сторінок дає рівно total унікальних записів. Додатковий чинник: повторна активація заявки оновлює її createdAt, тобто піднімає її в сортуванні.

Правильний спосіб синхронізації

Для підтримання власної копії даних використовуйте не повний обхід, а дельту — параметр updatedSince:

curl "https://api.samo-trans.com/api/public/v1/proposals/search?updatedSince=2026-08-05T09:00:00.000Z&limit=100" \
  -H "Authorization: Bearer $SAMO_KEY"

Повернуться лише заявки, змінені з цього моменту. Робочий цикл:

1. Збережіть час початку синхронізації (за годинником сервера у відповіді, не за локальним).
2. Запросіть сторінки з updatedSince = час попередньої успішної синхронізації.
3. Застосуйте зміни у себе, зіставляючи за id (вставка або оновлення).
4. Запам'ятайте новий час і повторіть за розкладом.

Беріть невелике перекриття (наприклад, мінус хвилина від попереднього часу) — це безпечно саме тому, що ви дедуплікуєте за id, і рятує від крайових ефектів на межі секунди.

Якщо потрібна реакція в реальному часі, а не за розкладом — дивіться вебхуки: подія proposal.matched приходить сама, щойно на біржі з'являється заявка під ваші критерії.