Paginare și filtrare

Cele trei feluri în care platforma împarte o listă lungă în pagini, ce rute folosesc fiecare fel și cât poți cere cel mult.

Pe scurt

Nu există o singură regulă de paginare pentru toată platforma: fiecare modul o alege pe a lui. În cod apar trei feluri.

Fel	Parametri	Ce primești înapoi	Exemple
Decalaj	`limita` + `decalaj`	lista și totalul din corp	`GET /v1/evidenta/tranzactii`
Cursor	`limita` + `dupa`	lista și `urmator` (cursorul paginii următoare sau `null`)	`GET /v1/eu/notificari`
Număr de pagină	`pagina` (de la 1)	lista și `urmatoarea` (`true` / `false`)	`GET /v1/finder/joburi`, `GET /v1/finder/case/anunturi`

Parametrii se trimit în query string. O cheie necunoscută sau o valoare în afara limitelor dă 400 (vezi Erori).

Decalaj: `limita` și `decalaj`

Ceri limita rânduri, sărind peste primele decalaj.

Rută	`limita` implicit	`limita` maxim	Totalul
`GET /v1/evidenta/tranzactii`	50	500	câmpul `total` din corp, alături de `limita` și `decalaj`

Pagina a doua de tranzacții, câte 50bash

curl -s "https://app.ilustromania.com/nucleu/v1/evidenta/tranzactii?limita=50&decalaj=50" \
  -H "Cookie: __Host-sesiune=$JETON_SESIUNE"

Filtrele listei de produse

Parametru	Valori
`stare`	starea produsului
`categorie_id`	id-ul categoriei
`q`	text căutat, 1–100 de caractere
`arhivate`	`1` = include și produsele arhivate (implicit nu apar)
`catering`	`1` = doar produsele de catering
`sortare`	`nume` (implicit), `pret`, `creat_la`
`ordine`	`asc` (implicit) sau `desc`

Filtrele tranzacțiilor din evidență

luna (AAAA-LL), entitate, tip, categorie, cauta (cel mult 200 de caractere) și arhivate (true / false). Fără luna primești toate lunile.

Cursor: `limita` și `dupa`

Notificările se citesc de la cele mai noi spre cele vechi. Prima cerere nu are dupa; următoarele trimit valoarea primită în urmator. Când urmator e null, ai ajuns la capăt.

Parametru	Regula
`limita`	implicit 30, cel mult 100
`dupa`	cursorul primit, 1–200 de caractere
`tip`	`mentiune` sau `activitate` (opțional)

Notificările, pagină cu paginăbash

curl -s "https://app.ilustromania.com/nucleu/v1/eu/notificari?limita=30" -H "Cookie: __Host-sesiune=$JETON_SESIUNE"
# {"notificari":[...],"urmator":"MjAyNi0xMS0xMS..."}
curl -s "https://app.ilustromania.com/nucleu/v1/eu/notificari?limita=30&dupa=MjAyNi0xMS0xMS..." -H "Cookie: __Host-sesiune=$JETON_SESIUNE"

Tratează cursorul ca pe un text opac: nu îl construi și nu îl modifica. Un cursor stricat nu dă eroare, ci întoarce prima pagină.

Paginarea cu cursor nu sare și nu dublează rânduri când apar notificări noi între două cereri. Paginarea cu decalaj poate, dacă lista se schimbă între cereri.

Număr de pagină: `pagina`

Listele modulelor Finder primesc pagina (de la 1) și au o mărime fixă de 50 de rânduri pe pagină. Răspunsul spune doar dacă mai există o pagină (urmatoarea: true), nu și câte sunt.

Rută	`pagina` maxim
`GET /v1/finder/joburi`	100 000
`GET /v1/finder/case/anunturi`	10 000

Celelalte liste Finder (de exemplu GET /v1/finder/case/brut) folosesc cursorul: limita implicit 300 și dupa primit în urmator.

Limitele, adunate

Rută	Implicit	Maxim
`GET /v1/evidenta/tranzactii`	50	500
`GET /v1/eu/notificari`	30	100
listele Finder cu cursor	300	500 (`brut`: 2000)
listele Finder cu `pagina`	50 pe pagină	—

Peste maxim, rutele cu schemă (evidență, notificări) răspund 400. Listele Finder cu cursor nu dau eroare: coboară singure limita la maxim. Nu te baza pe numărul de rânduri cerut, ci pe urmator sau pe total.

A fost utilă pagina?