Paginacija in kurzorji

Seznami vrnejo ovojnico list:

{
  "object": "list",
  "data": [ { "object": "entity", "…": "…" } ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJzb3J0Ijoi…",
  "data_as_of": "2026-10-19"
}

Naslednjo stran dobite tako, da iste parametre pošljete znova z cursor=<next_cursor>:

curl "https://api.maticna.si/v1/entities?q=cebelica&cursor=eyJ2IjoxLCJzb3J0Ijoi…" \
  -H "Authorization: Bearer $MATICNA_KEY"

Pravila

• Kurzor je neprozoren in podpisan s HMAC. Ne razčlenjujte ga in ne spreminjajte; spremenjen kurzor vrne 400 bad_request.
• Kurzor je vezan na poizvedbo. Če spremenite q ali filtre, začnite brez kurzorja.
• Kurzor je vezan na podatkovno različico. Ko se podatki dnevno osvežijo (X-Data-Version se spremeni), stari kurzor vrne 409 cursor_expired. Začnite znova od prve strani.
• Filtriran seznam je urejen po davčni številki (keyset), iskanje po relevantnosti po (score, id).

Globinska omejitev

Ena poizvedba vrne največ 1.000 zadetkov (20 strani po 50) za pravne osebe in 50 za fizične osebe. Ko je omejitev dosežena, je has_more false. Zožite filtre (npr. postal_code, activity_code).

Za celoten nabor pravnih oseb so namenjeni dnevni izvozi na paketu Custom, ne paginacija. Fizičnih oseb ne izvažamo.

Vzorec

async function* all(params) {
  let cursor;
  for (;;) {
    const qs = new URLSearchParams({ ...params, ...(cursor ? { cursor } : {}) });
    const r = await fetch(`https://api.maticna.si/v1/entities?${qs}`, { headers });
    if (r.status === 409) { cursor = undefined; continue; } // podatki osveženi: znova od prve strani (že prejete zadetke po potrebi odstranite po tax_number)
    if (!r.ok) throw new Error(`maticna.si ${r.status}`);
    const page = await r.json();
    yield* page.data;
    if (!page.has_more) return;
    cursor = page.next_cursor;
  }
}