Docs

APIPočetak

Konvencije

Format zahtjeva i odgovora, oznake, datumi, valuta, liste i oznaka zahtjeva.

Zahtjevi i odgovori

  • HTTPS i JSON, UTF-8. Tijelo zahtjeva šaljite s Content-Type: application/json.
  • Polja su snake_case, na engleskom; tekstovi za korisnika (nazivi faktora, signali) su na bosanskom.
  • Nepoznata polja u zahtjevu se odbijaju (400 invalid_request), da se greška u nazivu polja ne izgubi tiho.
  • Svaki objekt ima object (npr. valuation, list) i, gdje postoji, id s prefiksom: val_, wv_, alr_, whe_, evt_.

Brojevi, valuta, datumi

  • Cijene su cijeli KM (BAM), zaokružene na 10 KM. Polja s cijenom završavaju na _bam ili su u objektu s currency: "BAM".
  • Postoci su brojevi u procentima (change_pct: -3.97 = −3,97%), a omjeri u dijelovima jedinice (ratio: 0.88, range_probability: 0.8).
  • Dani su YYYY-MM-DD, trenuci ISO 8601 u UTC (2026-10-18T21:57:02.773Z). Dan procjene je UTC dan.

Prazno i nepostojeće

null znači da vrijednost postoji kao polje, ali je nepoznata ili isključena (npr. exposure: null). Polje koje se vraća samo uz neki uslov (npr. forecast bez include) tada potpuno izostaje. Kod PATCH zahtjeva null briše vrijednost, a izostavljeno polje ostaje kakvo jeste.

Liste i stranice

Liste vraćaju { "object": "list", "data": [...], "has_more": … }. Sljedeću stranicu tražite s starting_after = id zadnje stavke, a veličinu s limit (1–100, podrazumijevano 50).

let after;
do {
  const url = new URL("https://api.cifra.ba/v1/watchlist");
  url.searchParams.set("limit", "100");
  if (after) url.searchParams.set("starting_after", after);
  const page = await (await fetch(url, { headers })).json();
  for (const vehicle of page.data) handle(vehicle);
  after = page.has_more ? page.data.at(-1).id : undefined;
} while (after);

Oznaka zahtjeva

Svaki odgovor ima zaglavlje x-request-id, a greška i polje request_id. Pošaljite svoju oznaku (x-request-id, 8–64 slova, brojeva, - ili _) i API će je koristiti — tako isti zahtjev pratite kroz svoje logove, log zahtjeva na platformi i podršku.

Promjene API-ja

Unutar /v1 API se mijenja samo dodavanjem: nova polja u odgovoru, nove vrijednosti upozorenja, novi endpointi. Napišite integraciju tako da zanemaruje nepoznata polja i da nepoznatu šifru upozorenja ili signala samo prikaže ili zabilježi. Novi modeli rade bez promjene adrese; odgovor ih imenuje u model_version.