# 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](#api-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` |

```bash title="Pagina a doua de tranzacții, câte 50"
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) |
| `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) |

```bash title="Notificările, pagină cu pagină"
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ă.

> [!NOTE]
> 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ă | — |

> [!WARNING]
> 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.