Pagination

Shumica e listave lexohen me limit dhe offset, dhe numëruesit kthehen në një objekt pagination. Jo të gjitha listat sillen njësoj, dhe dallimet kanë rëndësi kur shkruani një cikël që lexon gjithçka.

Tabela e shkurtër#

Pa limit merret 20 dhe pa offset merret 0, me përjashtim të produkteve. Numëruesit vijnë në objektin pagination: records (sa erdhën në këtë faqe), total (sa ekzistojnë, ku llogaritet), limit dhe offset. Kur nuk ka total, ndaloni kur një faqe vjen më e shkurtër se limit. Te faturat e blerjes përsëritni me page + 1 sa kohë pagination.hasMore është true.

Listat me total#

Klientët dhe llogaritë bankare kthejnë total, pra që në faqen e parë e dini sa faqe ju presin:

curl 'https://demo.fature.al/api/v1/clients?limit=100&offset=0' \
  -H 'Authorization: Bearer TOKEN_I_JUAJ'

{
  "status": true,
  "data": {
    "items": [ ... ],
    "pagination": { "records": 100, "total": 842, "limit": 100, "offset": 0 }
  }
}

Vazhdoni me offset += limit derisa offset të kalojë total.

Listat pa total#

Lista e faturave, ajo e fletëve shoqëruese dhe veprimet e arkës nuk e llogaritin totalin. pagination i tyre ka vetëm numëruesit e faqes:

{
  "items": [ ... ],
  "pagination": { "records": 20, "limit": 20, "offset": 0, "type": "EINVOICE", "query": null }
}

Ndaloni kur faqja vjen më e shkurtër se limit:

offset=0
while :; do
  n=$(curl -s "https://demo.fature.al/api/v1/invoice?limit=100&offset=$offset" \
        -H "Authorization: Bearer $TOKEN" | jq '.data.pagination.records')
  [ "$n" -lt 100 ] && break
  offset=$((offset + 100))
done

Lista e faturave nuk e kufizon limit, por një faqe shumë e madhe ngadalëson përgjigjen dhe rrit mundësinë që kërkesa të dalë në timeout. Faqe nga 100 deri në 500 punojnë mirë.

pagination e faturave kthen edhe type dhe query, pra filtrat që zbatoi.

Produktet e mbajnë pagination krahas data#

Lista e produkteve e mban pagination krahas data, jo brenda, dhe data mbetet një listë e thjeshtë: data[0] është produkt, ndërsa te listat e tjera elementët janë te data.items.

{
  "status": true,
  "data": [ { "id": 1, "code": "SRV-01", "name": "Shërbim" } ],
  "pagination": { "records": 1, "total": 340, "limit": 20, "offset": 0 }
}

Pa limit kthehet i gjithë katalogu dhe limit mbetet null në përgjigje. Sapo e dërgoni, ai kufizohet në 500.

Kjo listë pranon një kërkesë në proces njëkohësisht për token: sa kohë një thirrje nuk ka mbaruar, e dyta refuzohet, dhe refuzimi vjen me kodin 200 dhe status: false, jo me 429. Kontrolloni fushën status, jo vetëm kodin. Thirrjet njëra pas tjetrës nuk kanë kufi tjetër.

Faturat e blerjes numërohen me faqe#

GET /purchase-invoices lexon nga CIS-i, jo nga baza e fature.al, dhe lexohet me numër faqeje që fillon nga 1:

curl 'https://demo.fature.al/api/v1/purchase-invoices?fromDate=2026-09-01&toDate=2026-09-30&page=1' \
  -H 'Authorization: Bearer TOKEN_I_JUAJ'

pagination kthen records, page dhe hasMore. records është numri i faturave të gjithë periudhës, jo i faqes. Përsëritni me page + 1 sa kohë hasMore është true, dhe mos u ndalni te një items bosh: një faturë që nuk arrihet për detaje hiqet pa gabim, prandaj një faqe mund të vijë bosh edhe kur ka të tjera pas saj. CIS-i nuk e tregon madhësinë e faqes, prandaj faqja e fundit mund të thotë true dhe ajo pas saj të vijë bosh me false.

Pa fromDate dhe toDate merret dita e sotme, jo e gjithë historia. Për një periudhë të kaluar dërgoni të dyja datat, edhe kur kërkoni me fic.

Renditja#

Listat kthehen nga më e reja te më e vjetra, sipas id zbritës. Një faturë e re e lëshuar gjatë kohës që ju lexoni faqet i zhvendos rreshtat një pozicion më poshtë, dhe një rresht mund ta shihni dy herë.

Kur lexoni një periudhë të mbyllur, kufizojeni me fromDate dhe toDate, që faqet të mos zhvendosen nga faturat e reja.