Liste, paginare și fields

O colecție vine în data ca listă, iar în meta.pagination primești de unde se continuă:

{
  "data": [
    { "id": "cli_4f1c9b2e7a3d4c6b8e5f0a1d2c3b4a59", "denumire": "Client Exemplu SRL", "cod_unic": "12345674" }
  ],
  "meta": {
    "timestamp": "2026-09-03T12:00:00+03:00",
    "pagination": {
      "next_cursor": "eyJ2IjoxLCJvZmZzZXQiOjEwMH0.7f1d9e3a",
      "prev_cursor": null
    }
  }
}

Cursorul

Prima pagină o ceri fără cursor. Pentru următoarea, trimiți next_cursor neschimbat:

GET /v2/clienti?fields=denumire,cod_unic&cursor=eyJ2IjoxLCJvZmZzZXQiOjEwMH0.7f1d9e3a

next_cursor: null înseamnă ultima pagină. prev_cursor: null înseamnă prima pagină.

Cursorul e opac. Nu îl construi, nu îl decodezi și nu îl compari cu altul; îl iei din răspuns și îl dai înapoi. E legat de firmă și de filtrele cererii în care l-ai primit: dacă schimbi un filtru, pornește din nou fără cursor, altfel primești 400 invalid-cursor.

limit stabilește numărul maxim de elemente din răspuns. Fără el, operația întoarce până la numărul ei implicit de elemente; peste plafonul ei, cererea e servită la plafon. Răspunsul poate conține mai puține elemente, dar niciodată mai multe. limit nu e în cursor — îl poți schimba de la o pagină la alta.

fields

Multe listări cer parametrul fields: spui ce câmpuri vrei în fiecare element, iar răspunsul conține identitatea resursei plus exact acelea.

GET /v2/clienti?fields=denumire,email

Separă numele câmpurilor prin virgulă. Identitatea resursei, când există — de exemplu id la clienți sau serie și numar la facturi — vine întotdeauna. La nomenclatoare, câmpurile disponibile și cele returnate automat sunt precizate în referința fiecărei operații.

Pentru obiecte imbricate ceri subcâmpurile prin grupare: fields=luni(luna,valoare). Un obiect cerut fără subcâmpuri e 400.

Descrierea parametrului, la fiecare operație din referință, enumeră câmpurile pe care le poți cere. Un nume necunoscut răspunde 400 validation cu numele greșite în mesaj. Fără fields, sau cu listă goală, tot 400: cere explicit ce ai nevoie.

Într-un răspuns proiectat, null înseamnă „valoarea e null", nu „nu ai cerut câmpul" — câmpurile necerute lipsesc cu totul.

Filtre

Fiecare listare are filtrele ei, documentate la operație. Filtrele de interval sunt inclusive la ambele capete și poartă sufixele _de_la și _pana_la:

GET /v2/facturi?data_emitere_de_la=2026-09-01&data_emitere_pana_la=2026-09-30&fields=serie,numar,valoare_totala

Numele parametrilor sunt exact cele din documentație. Data_Emitere_De_La sau dataEmitereDeLa nu sunt variante acceptate, sunt parametri necunoscuți, și răspund 400.