Pagination

Все endpoints, возвращающие коллекции (списки транзакций, заявок, сообщений и т. п.), используют единый формат пагинации по принципу Laravel paginate().

Query-параметры

Name	Type	Required	Description
`page`	`integer`	optional	Номер страницы, начиная с 1. Default: `1`
`per_page`	`integer`	optional	Сколько элементов на странице. Максимум — 100. Передача большего значения вернёт `422`. Default: `20`
`sort`	`string`	optional	Поле сортировки. Префикс `-` для DESC: `sort=-created_at`. Поддерживаемые поля указаны в каждом endpoint отдельно.
`filter[*]`	`mixed`	optional	Фильтрация. Синтаксис: `filter[status]=pending`, `filter[date_from]=2026-05-01`. Поддерживаемые ключи — в каждом endpoint.

Формат ответа

{
  "data": [
    { "id": "...", ... },
    { "id": "...", ... }
  ],
  "links": {
    "first": "https://fin-os.io/api/transactions?page=1",
    "last":  "https://fin-os.io/api/transactions?page=42",
    "prev":  null,
    "next":  "https://fin-os.io/api/transactions?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 20,
    "per_page": 20,
    "total": 837,
    "last_page": 42,
    "path": "https://fin-os.io/api/transactions"
  }
}

Name	Type	Required	Description
`current_page`	`integer`	optional	Текущая страница.
`last_page`	`integer`	optional	Общее число страниц.
`per_page`	`integer`	optional	Размер страницы (эхо параметра запроса).
`total`	`integer`	optional	Общее число элементов в коллекции (с учётом фильтров).
`from`	`integer`	optional	Номер первого элемента на странице (для UI «1–20 из 837»).
`to`	`integer`	optional	Номер последнего элемента на странице.

Cursor-пагинация (планируется в v1.1)

Для high-throughput списков (история сделок, лог событий) page-based быстро деградирует — большой OFFSET сканирует много строк. В v1.1 появится альтернативный режим:

GET /api/transactions?cursor=eyJpZCI6MTAwMCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ&per_page=50

Ответ будет содержать meta.next_cursor вместо page — токен указывает на «куда читать дальше». Преимущество: O(log N) вместо O(N) на больших списках.

Полный обход коллекции

✦

Не качайте всё одной страницей

per_page=10000 вернёт 422. Если нужно выгрузить всю историю — итерируйте по страницам или используйте POST /api/tax-reports/generate для генерации полного PDF/Excel-отчёта.