# Cifra dokumentacija
Sve o Cifri na jednom mjestu: kako nastaje procjena, kako koristiti aplikaciju i platformu za kompanije, i kako ugraditi Cifra API u vaš sistem.
## Odaberite put
- [Cifra API](https://www.cifra.ba/docs/api): Procjene, provjera vozila, praćenje portfelja i webhookovi u vašem sistemu. Vodiči, primjeri i referenca.
- [Cifra Enterprise](https://www.cifra.ba/docs/enterprise): Platforma za timove: procjene s logom, masovne liste, provjera rizika, lager, radar i rezidualne vrijednosti.
- [Cifra za pojedince](https://www.cifra.ba/docs/cifra): Procjena vozila za par sekundi, izvještaj s obračunom cijene, planovi i nalog.
## Po mogućnostima
- [Procjena vozila](https://www.cifra.ba/docs/api-reference/valuations/create): Vrijednost, raspon i ocjena za auto, motocikl ili kamion.
- [Masovna procjena](https://www.cifra.ba/docs/api/batch): Stotine vozila u jednom pozivu, greške po stavci.
- [Provjera vozila](https://www.cifra.ba/docs/api/vehicle-history): Historija oglasa i signali rizika za svaki link.
- [Praćenje i alarmi](https://www.cifra.ba/docs/api/watchlist): Portfelj koji se procjenjuje svako jutro, LTV alarmi.
- [Webhookovi](https://www.cifra.ba/docs/api/webhooks): Potpisani događaji u vaš sistem, s ponovnim pokušajima.
- [Tačnost i modeli](https://www.cifra.ba/docs/overview/accuracy): Kako mjerimo grešku i šta znači raspon od 80%.
---
# Kako Cifra radi
Od oglasa do procjene: odakle dolaze podaci, kako se model uči i zašto svaka procjena dolazi s rasponom.
## Podaci
Cifra svaki dan prati oglase vozila u BiH — olx.ba, autobum.ba i autoplac.ba — i pamti svaku promjenu: cijenu, kilometražu, uklanjanje oglasa. Do sada je to više od 250.000 oglasa automobila, motocikala i kamiona.
Prije učenja podaci se čiste: izbacuju se oštećena vozila, nemoguće kilometraže i cijene, oglasi bez marke i, najvažnije, **ponovljeni oglasi istog vozila**. Isti auto oglašen pet puta inače bi se računao kao pet vozila i iskrivio cijenu.
## Model
Za svaku vrstu vozila postoji poseban model (gradient boosting, LightGBM) koji uči odnos između osobina vozila i cijene. Ograničen je da poštuje zdrav razum: vozilo nikad ne vrijedi više zato što ima više kilometara ili godina.
- Novi model se trenira noću iz najnovijih podataka.
- Prije upotrebe se poredi s modelom koji radi, na istim vozilima koja nijedan nije vidio. Prolazi samo ako nije lošiji, a vrijednosti ne pomjera bez razloga.
- API zatim ponovi oko 1.000 kontrolnih procjena i tek kad se sve poklope do na milioniti dio, prebacuje se na novi model. Bez prekida i bez Pythona u produkciji.
## Procjena
Rezultat je **tržišna vrijednost**: cijena po kojoj se uporedivo vozilo oglašava kod privatnog prodavca na dan procjene. Uz nju idu **raspon** u kojem je cijena s vjerovatnoćom od 80% i **ocjena pouzdanosti** od A do C.
Svaka procjena se može objasniti: obračun po faktorima (kilometraža, oprema, region, stanje tržišta) tačno se sabira u vrijednost. Detalji su u [Obračun cijene](https://www.cifra.ba/docs/api/explanation).
> **Napomena:** Cifra ne zna stanje konkretnog vozila — oštećenja, servis, papire — osim onoga što pošaljete. Procjena je polazna tačka za odluku, ne zamjena za pregled vozila.
---
# Tačnost i modeli
Koliko su procjene tačne, kako to mjerimo i šta tačno znači raspon od 80%.
## Kako mjerimo
Tačnost se mjeri na vozilima koja model nikad nije vidio: oglasima objavljenim nakon zadnjeg dana na kojem je učio, bez ponovnih oglasa vozila koja već zna. Mjera je **medijan apsolutne greške** (MdAPE): pola procjena je bliže cijeni od toga, pola dalje.
Oglasna cijena nije prodajna — prodavci traže i previše i premalo — pa je greška naspram oglasa gornja granica. Naspram stvarnih prodajnih cijena salona greška je znatno manja.
## Modeli koji rade danas
| Model | Greška (MdAPE) | Raspon pogađa | Testirano na |
| --- | --- | --- | --- |
| Automobili | 12,6% | 79% | 18.984 novih oglasa |
| Motocikli | 15,7% | 81% | 1.119 novih oglasa |
| Kamioni | 21,9% | 79% | 775 novih oglasa |
| Automobili, prodaje salona | 7,4% | — | 786 stvarnih prodaja |
Prognoza vrijednosti provjerena je na 693 vozila koja su ponovo oglašena nakon 12 ili 24 mjeseca: medijan greške 9,2%. Stanje: oktobar 2026.
## Raspon od 80%
Raspon nije ukras: kalibrisan je tako da u njega padne 8 od 10 stvarnih cijena, i to se provjerava na svakom novom modelu. Širina zavisi od vozila: za čest model s potpunim podacima uzak je, za rijedak ili nepotpun širi.
| Ocjena | Značenje |
| --- | --- |
| A | Najuži trećina raspona: čest model, potpuni podaci. |
| B | Srednja trećina. |
| C | Najširi rasponi: rijedak model, malo podataka ili nepotpun unos. Uzmite raspon ozbiljno. |
### Šta sužava raspon
- Snaga (`power_kw`), zapremina (`engine_cc`), gorivo i mjenjač — bez njih procjena nosi upozorenje `partial_inputs`.
- Tačna generacija modela (`golf_7`, ne `golf`).
- Grad, oprema, broj vlasnika i servisna historija pomažu manje, ali pomažu.
## Verzije modela
Svaki odgovor nosi `model_version` (npr. `car-20261017-1`). Novi model zamijeni stari samo kad je jednako dobar ili bolji; dva modela trenirana na skoro istim podacima ipak se razlikuju za oko 2% po vozilu. Zato pravila alarma ne idu ispod 3% i zato alarm javlja kad je tog dana počeo raditi novi model.
---
# Pojmovnik
Pojmovi koje koristimo u aplikaciji, na platformi i u API-ju.
| Pojam | Značenje |
| --- | --- |
| Tržišna vrijednost | Cijena po kojoj se uporedivo vozilo oglašava kod privatnog prodavca na dan procjene (`market_value.point`). |
| Raspon | Interval u kojem je cijena s vjerovatnoćom od 80% (`low`–`high`). |
| Ocjena pouzdanosti | A, B ili C: koliko je raspon uzak za takvo vozilo. |
| Šifra (slug) | Oznaka marke ili modela u API-ju, npr. `volkswagen` / `golf_7`, iz šifarnika. |
| Procjena na dan | Vrijednost kakva je bila određenog dana (`as_of`), npr. na dan štete. |
| Prognoza | Očekivana vrijednost za 6–36 mjeseci, uz pretpostavljenu kilometražu. |
| Praćeno vozilo | Vozilo koje se procjenjuje svako jutro, s alarmima (`wv_…`). |
| Izloženost | Iznos vezan za vozilo: dug, osigurana suma ili nabavna cijena. |
| LTV | Izloženost ÷ vrijednost vozila. 0,9 znači da dug iznosi 90% vrijednosti. |
| Signal | Razlog da se vozilo pogleda bolje, npr. vraćena kilometraža. Nije presuda. |
| Jedinica | Obračunska jedinica API-ja: jedna procjena, provjera ili novo praćeno vozilo. |
| Sandbox | Testni ključ (`cfr_test_…`): prava provjera zahtjeva, fiksne vrijednosti, bez naplate. |
| Model kompanije | Model naučen na vašim cijenama, nadogradnja standardnog tržišnog modela. |
---
# Cifra za pojedince
Koliko vrijedi vaš automobil, motocikl ili kamion, iz stvarnih oglasa u BiH: tržišna vrijednost, realan raspon i izvještaj koji možete poslati kupcu.
## Pregled
Cifra na [cifra.ba](https://www.cifra.ba/procjena) procjenjuje vozilo za par sekundi. Unesete marku, model, godište i kilometražu, a dobijete **tržišnu vrijednost**: cijenu po kojoj se uporedivo vozilo oglašava u BiH na dan procjene. Uz nju idu **realan raspon** u kojem je cijena s vjerovatnoćom od 80% i ocjena koliko je procjena pouzdana.
Procjena dolazi iz modela koji uči na više od 250.000 oglasa automobila, motocikala i kamiona, i to svaki dan. Ne zavisi od jednog oglasa ni od nečijeg mišljenja. Kako tačno nastaje: [Kako Cifra radi](https://www.cifra.ba/docs/overview/how-it-works).
Svaka procjena postaje **izvještaj**: stranica s vrijednošću, rasponom, preporukom za koliko oglasiti i, u cijelom izvještaju, obračunom cijene, stanjem tržišta i sličnim vozilima u prodaji. Izvještaj ostaje u vašem nalogu, a kupcu ili prodavcu ga šaljete linkom, QR kodom ili kao PDF.
## Prva procjena za minut
### 1. Odaberite vrstu vozila
Otvorite [Procjena](https://www.cifra.ba/procjena) i odaberite **Automobil**, **Motocikl** ili **Kamion**. Svaka vrsta ima svoj model, učen na svom tržištu.
### 2. Opišite vozilo
Marka, model, godište i kilometraža su obavezni. Gorivo, mjenjač, snaga i zapremina motora sužavaju raspon, a **Najčešće izvedbe na tržištu** ih popunjavaju jednim dodirom.
### 3. Napravite besplatan nalog
Ako još nemate nalog, posljednji korak ga pravi za pola minute: ime, email i lozinka, pa kod iz emaila. Kartica nije potrebna.
### 4. Pročitajte izvještaj
Odaberite **Prikaži procjenu**. Izvještaj se otvara za par sekundi i ostaje u **Moje procjene**.
## Šta je u kojem planu
S **Free** planom imate 1 procjenu dnevno i osnovni izvještaj. **Plus** otvara cijeli izvještaj i 10 procjena dnevno, a **Pro** neograničene procjene i izvještaj koji kupac s linkom vidi u cijelosti, s vašim imenom i kontaktom. Detalji su u [Planovi i plaćanje](https://www.cifra.ba/docs/cifra/plans).
## Dalje
- [Procjena vozila](https://www.cifra.ba/docs/cifra/valuation): Svaki korak unosa i šta najviše sužava raspon.
- [Izvještaj](https://www.cifra.ba/docs/cifra/report): Vrijednost, raspon, za koliko oglasiti, tržište i slična vozila.
- [Dijeljenje i provjera](https://www.cifra.ba/docs/cifra/sharing): Link, QR kod, PDF i provjera izvještaja po broju.
- [Planovi i plaćanje](https://www.cifra.ba/docs/cifra/plans): Free, Plus i Pro, dnevni limit, računi i otkazivanje.
> **Napomena:** Za salone, lizing kuće, banke i osiguranja postoji [Cifra Enterprise](https://www.cifra.ba/docs/enterprise): procjene s logom kompanije, tim, masovne liste i API.
---
# Procjena vozila
Kako unijeti automobil, motocikl ili kamion i koji podaci najviše sužavaju raspon cijene.
[Video: Unos vozila u Cifri: Volkswagen, Golf 7, godište 2016, kilometraža 185.000 km, izvedba s jednim dodirom i detalji](https://www.cifra.ba/docs/cifra/procjena-tok.mp4)
## Pregled
Procjena ima tri kratka koraka: **Vozilo**, **Motor** i **Detalji**. Desno je kartica vozila koja raste s unosom i pokazuje **Preciznost procjene**: koliko od onoga što najviše određuje cijenu Cifra već zna.
Unos se čuva u kartici preglednika. Ako odete na prijavu, osvježite stranicu ili se vratite korak nazad, podaci ostaju gdje ste ih ostavili. Svaki korak je i u adresi stranice, pa dugme za nazad na telefonu vraća korak, ne cijelu procjenu.
## Vodič
### 1. Odaberite vrstu vozila
Na [Procjena](https://www.cifra.ba/procjena) odaberite **Automobil**, **Motocikl** ili **Kamion**. Iz koraka **Vozilo** se uvijek možete vratiti preko **Druga vrsta vozila**.
### 2. Marka, model i godište
Upišite marku ili odaberite jednu od najčešćih ispod polja. Isto vrijedi za model: ispod polja su modeli kojih je najviše u oglasima, s brojem oglasa. Godište je godina proizvodnje, kao u saobraćajnoj dozvoli. Kad odaberete godište, Cifra sama prelazi na sljedeći korak.
### 3. Kilometraža i motor
Kilometraža je jedino obavezno polje u ovom koraku. Zatim pogledajte **Najčešće izvedbe na tržištu**: ako prepoznate svoje vozilo, jedan dodir popunjava gorivo, mjenjač, snagu i zapreminu motora.
Kad je motor popunjen, možete odabrati **Preskoči detalje** i odmah vidjeti procjenu.
### 4. Detalji
Sve u ovom koraku je neobavezno: karoserija, pogon, lokacija, broj vlasnika, servisna historija i da li je vozilo ocarinjeno. Svaki odgovor pomaže da Cifra uporedi vaše vozilo s pravim parnjacima. Lokacija je najkorisnija, jer se cijene razlikuju od grada do grada.
### 5. Prikažite procjenu
Odaberite **Prikaži procjenu**. Ako niste prijavljeni, pojavljuje se korak **Nalog**: napravite besplatan nalog ili se prijavite u **Imam nalog**, potvrdite email kodom i izvještaj se otvara odmah, bez ponovnog unosa.
## Šta najviše sužava raspon
Marka, model, godište i kilometraža su dovoljni za procjenu, ali raspon je tada širi. Kartica vozila pokazuje šta još nedostaje, a nivo preciznosti raste od **Osnovna** do **Najviša**.
| Vrsta | Podaci koji najviše pomažu | Gdje ih naći |
| --- | --- | --- |
| Automobil | Gorivo, mjenjač, snaga i zapremina motora | Saobraćajna dozvola: snaga je polje P.2 (kW), zapremina P.1 (cm³) |
| Motocikl | Tip motocikla i zapremina motora | Tip (naked, enduro, touring…) najviše utiče na cijenu, odmah iza modela |
| Kamion | Snaga, gorivo i mjenjač | Saobraćajna dozvola; nadogradnja, nosivost i osovine su neobavezni |
*Kartica vozila prati unos. Kad su gorivo, mjenjač, snaga i zapremina poznati, preciznost je Visoka; lokacija i broj vlasnika je dižu na Najviša.*
### Najčešće izvedbe na tržištu
Rijetko ko zna snagu svog motora napamet. Zato Cifra za odabrani model i godište pokazuje izvedbe kojih je najviše u oglasima, s brojem oglasa. Odaberite onu koja odgovara vašoj saobraćajnoj i polja ispod se popune sama. Ako vaše nema, upišite podatke ručno; snagu možete unijeti u kW ili KS.
### Provjera kilometraže
Najčešća greška je kilometraža u hiljadama, npr. „185” umjesto 185.000. Cifra to primijeti i ponudi ispravku jednim dodirom. Upozori i kad je kilometraža neobično velika za godište; ako je tačna, samo nastavite.
## Motocikli i kamioni
Unos je isti, uz polja koja tim vozilima određuju cijenu. Za motocikl je to **Tip motocikla** i neobavezni **ABS**; gorivo i mjenjač se ne traže. Za kamion korak se zove **Kilometraža i pogon**, a neobavezni su **Nadogradnja**, **Nosivost** i **Broj osovina**.
## Dnevni limit
Svaki plan ima dnevni broj procjena: Free 1, Plus 10, Pro neograničeno. Dan počinje u ponoć po bosanskom vremenu. Besplatna procjena se broji po nalogu i po pregledniku, pa drugi nalog na istom uređaju ne donosi novu.
Kad je današnja procjena iskorištena, Cifra to kaže iznad forme. Podatke i dalje možete unijeti: kad odaberete **Prikaži procjenu**, vidite koliko je ostalo do sljedeće besplatne procjene i planove koji je otvaraju odmah, bez ponovnog unosa.
## Česta pitanja
**Zašto mi treba nalog za procjenu?**
Da procjena ostane vaša: u historiji, s brojem za provjeru, i da je možete ponoviti za mjesec. Email potvrđujete kodom samo jednom. Tako i besplatna procjena ostaje besplatna za sve, jer je ne mogu potrošiti skripte i lažni nalozi.
**Mog modela nema na listi. Šta da radim?**
Upišite dio naziva u polje **Model**: lista se filtrira dok kucate, a generacije su posebno (npr. Golf 6 i Golf 7). Ako modela i dalje nema, odaberite najbliži model iste marke i klase. Procjena rijetkih modela oslanja se na marku i slična vozila, pa je raspon širi; izvještaj to navodi u napomenama. Javite nam koji model nedostaje preko [podrške](https://www.cifra.ba/kontakt).
**Ne znam snagu ni zapreminu motora.**
Pogledajte **Najčešće izvedbe na tržištu** ili saobraćajnu dozvolu: snaga je u polju P.2 (kW), zapremina u P.1 (cm³). Bez njih procjena radi, samo s nešto širim rasponom.
**Da li Cifra zna stanje mog vozila?**
Ne. Oštećenja, kvarove, dodatnu opremu i održavanje Cifra ne vidi, osim onoga što unesete u **Detalji**. Zato procjena dolazi s rasponom: dobro održavano vozilo ide prema gornjoj granici, zapušteno prema donjoj.
**Mogu li procijeniti isto vozilo ponovo?**
Da. U izvještaju odaberite **Procijeni ponovo**: unos se popuni podacima iz izvještaja, promijenite šta treba (npr. kilometražu) i novi izvještaj pokazuje razliku u odnosu na raniji. Više u [Moje procjene](https://www.cifra.ba/docs/cifra/history).
**Šta znači „neograničeno” na Pro planu?**
Bez dnevnog limita za sve što radite ručno. Granica od 150 procjena dnevno postoji samo protiv automatizovanog prometa. Za procjene iz vlastitog softvera tu je [Cifra API](https://www.cifra.ba/docs/api).
---
# Izvještaj
Šta znači svaki dio izvještaja: vrijednost i raspon, za koliko oglasiti, obračun cijene, tržište, kilometraža, vrijednost kroz vrijeme i slična vozila.
[Video: Kretanje kroz cijeli izvještaj preko sadržaja: obračun cijene, tržište, vrijednost kroz vrijeme i slična vozila](https://www.cifra.ba/docs/cifra/izvjestaj-tura.mp4)
## Pregled
Izvještaj je stranica koja nastaje iz procjene i ne mijenja se: vrijednost, tržište i slična vozila su snimak na dan procjene. Ima svoj broj (npr. `CFR-3HQ8-W2DN`) po kojem ga svako može [provjeriti](https://www.cifra.ba/docs/cifra/sharing#provjera).
Na računaru je sadržaj desno, uz tržišnu vrijednost i **Procijeni ponovo**; na telefonu je sadržaj traka ispod naslova. Dijelovi su numerisani i pojavljuju se samo kad za to vozilo ima dovoljno podataka.
| Dio | Šta pokazuje | Plan |
| --- | --- | --- |
| Sažetak | Tržišna vrijednost, raspon, pouzdanost i zaključci | Svi |
| Za koliko oglasiti | Gdje vaša cijena stoji među sličnim oglasima | Svi |
| Šta pomjera cijenu | Obračun od bazne vrijednosti do vaše, u KM | Plus, Pro |
| Tržište | Ponuda, tražene cijene, trend, gradovi, pregovori | Plus, Pro |
| Kilometraža i cijena | Koliko košta 10.000 km | Plus, Pro |
| Vrijednost kroz vrijeme | Procjena za 12, 24 i 36 mjeseci | Plus, Pro |
| Slična vozila u prodaji | Najbliži oglasi, svaki s Cifra procjenom | Plus, Pro |
| Podaci o vozilu, Metodologija | Unos i kako je procjena nastala | Svi |
## Sažetak
**Tržišna vrijednost** je cijena po kojoj se uporedivo vozilo oglašava kod privatnog prodavca na dan procjene. Ispod nje je **Realan raspon**: u njega padne 8 od 10 stvarnih cijena. Konačna prodajna cijena je često nešto niža od tražene; zavisi od stanja, opreme i pregovora.
- **Visoka pouzdanost**, **Dobra pouzdanost** ili **Okvirna procjena** kaže koliko je raspon uzak za takvo vozilo. Okvirna znači malo uporedivih oglasa ili nepotpun unos.
- **Tipična greška modela** je medijan odstupanja na novim oglasima koje model nije vidio. Šta to tačno znači: [Tačnost i modeli](https://www.cifra.ba/docs/overview/accuracy).
- Histogram pokazuje tražene cijene sličnih oglasa; narandžasti stupci su unutar vašeg raspona.
- **Ukratko** su zaključci iz podataka: mjesto na tržištu, kretanje cijena, brzina prodaje, cijena kilometara, snižavanja i vrijednost za godinu dana.
Ispod sažetka su **Napomene o procjeni** kad ih ima, npr. da je model rijedak u oglasima ili da bi gorivo i snaga suzili raspon.
## Za koliko oglasiti
Upišite cijenu ili pomjerite klizač i odmah vidite gdje stoji: koliko sličnih oglasa traži više, a koliko manje, i šta takva cijena znači za prodaju.
[Video: Pomjeranje klizača tražene cijene od 23.400 do 42.600 KM; ocjena se mijenja od Brza prodaja do Iznad tržišta](https://www.cifra.ba/docs/cifra/za-koliko-oglasiti.mp4)
| Ocjena | Kada | Šta znači |
| --- | --- | --- |
| **Brza prodaja** | Ispod donje granice raspona | Oglas privlači kupce brzo, ali vjerovatno ostavljate novac na stolu. |
| **Tržišna cijena** | Od donje granice do 3% iznad tržišne vrijednosti | Realna cijena koja se prodaje bez dugog čekanja. |
| **Iznad prosjeka** | Do gornje granice raspona | Opravdano za očuvano vozilo s dobrom opremom i servisnom historijom. |
| **Iznad tržišta** | Iznad gornje granice raspona | Oglas će vjerovatno stajati duže i završiti sniženjem. |
Ispod su dva savjeta, **Ako prodaješ** i **Ako kupuješ**, s granicama raspona za to vozilo.
## Šta pomjera cijenu
Obračun počinje od **Bazne vrijednosti modela**, tj. šta taj model tog godišta tipično vrijedi, i faktor po faktor dolazi do vaše vrijednosti. Iznosi se sabiraju tačno: zeleni podižu cijenu, narandžasti je spuštaju.
| Faktor | Šta obuhvata |
| --- | --- |
| Kilometraža | Kilometraža u odnosu na uobičajenu za to godište |
| Oprema i motorizacija | Motor, snaga, mjenjač, gorivo i pogon |
| Stanje i historija vozila | Broj vlasnika, servisna historija, carina |
| Regionalna potražnja | Potražnja i cijene u vašem kraju |
| Stanje tržišta | Kretanje cijena na tržištu do danas |
## Tržište
Isti model u oglasima širom BiH na dan procjene (godište ±1): koliko ih je u prodaji, medijana tražene cijene, koliko dana prođe do prodaje i kako se cijene kreću zadnjih 12 mjeseci. Ispod su cijene po gradovima i koliko oglasa je spuštalo cijenu, što govori koliko prostora ima za pregovore. Prodavce i linkove oglasa ne prikazujemo.
## Kilometraža i cijena
Isto vozilo s drugom kilometražom: koliko vrijednost pada na svakih 10.000 km i šta bi vrijedilo s manje ili više kilometara. Tačke su oglasi istog modela, pa se vidi gdje vaše vozilo stoji.
## Vrijednost kroz vrijeme
Koliko će vozilo vrijediti za 12, 24 i 36 mjeseci ako ga zadržite, uz uobičajenu godišnju kilometražu i današnje stanje tržišta. Prognoza je u beta fazi i dolazi s rasponom; provjerena je na vozilima koja su ponovo oglašena nakon godinu ili dvije.
## Slična vozila u prodaji
Najbliži oglasi istog modela na dan procjene, s godištem, kilometražom, motorom, gradom i koliko dugo su u prodaji. Svaki je procijenjen Cifrom, a kolona **Odnos** kaže je li tražena cijena skupa ili povoljna za to vozilo.
## Osnovni i cijeli izvještaj
S Free planom vidite **osnovni izvještaj**: sažetak, za koliko oglasiti, podatke o vozilu i metodologiju. Ostali dijelovi su zaključani, a svaki kaže šta o vašem vozilu sadrži, npr. broj oglasa u prodaji. **Otključaj cijeli izvještaj** vodi na Plus.
Sve je izračunato kad je procjena napravljena. Zato se nakon pretplate otvaraju i izvještaji koje ste napravili ranije, bez nove procjene.
## Podaci o vozilu i metodologija
**Podaci o vozilu** su unos kakav je bio za procjenu. **Metodologija i pouzdanost** pokazuje tipičnu grešku modela, koliko procjena pogodi cijenu unutar ±10%, koliko često raspon pogađa i na koliko oglasa je model učen, uz odgovore šta procjena ne vidi i kako provjeriti izvještaj.
## Česta pitanja
**Zašto je tržišna vrijednost viša od onoga što mi nude?**
Tržišna vrijednost je tražena cijena kod privatnog prodavca. Otkup, zamjena ili salon nude manje, jer vozilo moraju pripremiti, platiti porez i prodati s maržom. Prodajna cijena među privatnim osobama je obično nešto niža od tražene, zavisno od stanja i pregovora.
**Zašto je raspon tako širok?**
Raspon je kalibrisan da u njega padne 8 od 10 stvarnih cijena. Širi je kad je oglasa tog modela malo ili kad nedostaju gorivo, mjenjač, snaga i zapremina. Popunite ih i [procijenite ponovo](https://www.cifra.ba/docs/cifra/history#procijeni-ponovo).
**Mijenja li se izvještaj s vremenom?**
Ne. Izvještaj je snimak dana procjene i ostaje takav, i za one kojima ste ga poslali. Za današnju vrijednost odaberite **Procijeni ponovo**: nastaje novi izvještaj koji pokazuje promjenu u odnosu na raniji.
**Šta ako mislim da procjena nije tačna?**
Pri dnu izvještaja odgovorite na **Je li procjena realna?**. Ako odaberete **Ne baš**, možete upisati koliko mislite da vozilo vrijedi i zašto. Svaki odgovor čitamo i koristimo za bolje modele.
---
# Dijeljenje i provjera
Pošaljite izvještaj kupcu ili prodavcu linkom, QR kodom ili kao PDF, odredite ko ga vidi i provjerite svaki izvještaj po broju.
## Pregled
Izvještaj je napravljen da se šalje: kupcu kao argument za cijenu, prodavcu kao provjera ponude, porodici prije kupovine. Svaki ima stalni link, broj za provjeru i verziju za štampu s QR kodom.
## Podijelite link
### 1. Otvorite izvještaj
Iz **Moje procjene** ili direktno nakon procjene.
### 2. Odaberite Podijeli
Na računaru se otvara meni: **Kopiraj link**, **WhatsApp**, **Viber** ili **Email**. Na telefonu se otvara dijeljenje telefona, sa svim aplikacijama koje imate.
### 3. Pošaljite
Ko otvori link vidi izvještaj bez prijave. Izvještaj napravljen na Pro planu primalac vidi cijeli, s vašim imenom i kontaktom; na Free i Plus planu osnovni.
## PDF i štampa
Odaberite **PDF** u zaglavlju izvještaja: otvara se štampa preglednika, gdje birate pisač ili **Sačuvaj kao PDF**. Verzija za štampu na vrhu ima QR kod, link i broj izvještaja, a dugmad i ponude su izostavljeni.
## Ko može otvoriti izvještaj
Izvještaji su vidljivi svakome ko ima link. Pri dnu izvještaja, pod **Ko može otvoriti izvještaj**, to možete promijeniti:
- **Link**: svako ko ima link, npr. kupac, prodavac ili porodica.
- **Privatno**: samo vi, kad ste prijavljeni. Ostali vide poruku da je izvještaj privatan.
Ikona korpe briše izvještaj: nestaje iz historije, a link prestaje raditi za sve kojima ste ga poslali. Brisanje se ne može poništiti.
## Provjera izvještaja
Svako kome pokažete izvještaj, na papiru ili ekranu, može provjeriti da je pravi. Na [cifra.ba/provjera](https://www.cifra.ba/provjera) upiše broj iz zaglavlja izvještaja ili skenira QR kod s PDF-a i vidi vozilo, kilometražu, vrijednost, raspon i datum kako ih je Cifra izdala.
> **Napomena:** Za privatne izvještaje provjera potvrđuje samo da izvještaj postoji i kad je napravljen, nikad sadržaj.
> **Savjet:** Broj je otporan na greške pri prepisivanju: velika i mala slova, razmaci i zamjena slova O nulom ne smetaju.
## Vaše ime na izvještaju
Na Pro planu svaki novi izvještaj i PDF nosi **Pripremio** s vašim imenom, firmom i telefonom, pa kupac zna kome da se javi. Podatke unosite u [Profil](https://www.cifra.ba/docs/cifra/account#profil) pod **Tvoje ime na izvještajima**.
Izvještaji koje ste već napravili ostaju kakvi jesu: promjena imena ili telefona vrijedi za nove.
## Česta pitanja
**Vidi li kupac cijeli izvještaj?**
Ako je izvještaj napravljen na Pro planu, da. Izvještaj s Free ili Plus plana primalac vidi kao osnovni, osim ako i sam ima Plus ili Pro.
**Mogu li povući link koji sam poslao?**
Da. Postavite izvještaj na **Privatno** i link više ne otvara sadržaj. Kad ga vratite na **Link**, isti link radi ponovo. Ako izvještaj obrišete, link prestaje raditi zauvijek.
**Da li link otkriva moje podatke?**
Ne. Izvještaj pokazuje vozilo i procjenu, bez vašeg imena i emaila. Ime i kontakt se vide samo na Pro planu, i to samo ako ih unesete.
---
# Moje procjene
Sve vaše procjene na jednom mjestu, ponovna procjena istog vozila i prodajna cijena koja poboljšava modele.
## Pregled
**Moje procjene** je prva stranica naloga. Izvještaji su poredani od najnovijeg, s vozilom, kilometražom, datumom, vrijednošću i rasponom. Privatni izvještaji imaju ikonu lokota.
- Gore je današnja potrošnja: koliko procjena ste napravili od dnevnog limita vašeg plana.
- Filteri **Automobili**, **Motocikli** i **Kamioni** sužavaju listu.
- Pretraga traži po marki, modelu i godištu.
- **Nova procjena** u zaglavlju otvara unos vozila.
## Procijeni ponovo
Vrijednost se mijenja s kilometrima i tržištem. Da biste dobili današnju, otvorite izvještaj i odaberite **Procijeni ponovo**: unos se popuni podacima iz izvještaja, promijenite šta treba i odaberite **Prikaži procjenu**.
Novi izvještaj je vezan za raniji i na vrhu pokazuje promjenu:
> **Napomena:** Ponovna procjena je nova procjena i broji se u dnevni limit. Raniji izvještaj ostaje kakav je bio.
## Prodali ste vozilo?
Oglasi pokazuju traženu cijenu, a vi znate stvarnu. Pri dnu svog izvještaja, pod **Prodao si vozilo?**, upišite za koliko ste prodali. Izvještaj zatim pokazuje prodajnu cijenu i razliku u odnosu na procjenu.
Prodajne cijene su ono što oglasi ne mogu naučiti modele, pa svaka čini procjene tačnijim za sve. Cijenu ne prikazujemo nikome.
## Česta pitanja
**Koliko dugo se čuvaju moje procjene?**
Dok imate nalog. Izvještaji ne ističu, ni kad pređete na manji plan. Izvještaj možete obrisati sami, a cijelu historiju izvesti u Excel; vidi [Nalog i privatnost](https://www.cifra.ba/docs/cifra/account#podaci).
**Ne vidim procjenu koju sam napravio.**
Provjerite da ste prijavljeni istim emailom kojim ste napravili procjenu i da filter nije na drugoj vrsti vozila. Procjene koje ste napravili za kompaniju na Cifra Enterprise su na platformi kompanije, ne ovdje.
---
# Planovi i plaćanje
Free, Plus i Pro: šta dobijate, koliko košta i kako promijeniti ili otkazati plan.
## Pregled
| | Free | Plus | Pro |
| --- | --- | --- | --- |
| Cijena | Besplatno | 12 KM mjesečno ili 120 KM godišnje | 25 KM mjesečno ili 250 KM godišnje |
| Prvi mjesec | — | 2 KM (−83%) | 7 KM (−72%) |
| Procjene | 1 dnevno | 10 dnevno | Neograničeno |
| Izvještaj | Osnovni | Cijeli | Cijeli, i za one s linkom |
Godišnje plaćanje košta kao 10 mjeseci: dva mjeseca su gratis. Cijena prvog mjeseca vrijedi za nove pretplatnike uz mjesečno plaćanje, jednom po osobi i kartici; zatim plaćate redovnu cijenu dok ne otkažete.
## Sve razlike
| | Free | Plus | Pro |
| --- | --- | --- | --- |
| **Procjene** | | | |
| Procjene | 1 dnevno | 10 dnevno | Neograničeno |
| Automobili, motocikli i kamioni | ✓ | ✓ | ✓ |
| Tržišna vrijednost, raspon i ocjena pouzdanosti | ✓ | ✓ | ✓ |
| Najčešće verzije modela jednim dodirom | ✓ | ✓ | ✓ |
| Procijeni ponovo i vidi promjenu | ✓ | ✓ | ✓ |
| **Izvještaj** | | | |
| Ukratko: zaključci iz podataka | ✓ | ✓ | ✓ |
| Za koliko oglasiti | ✓ | ✓ | ✓ |
| Tržište: ponuda, cijene, trend, gradovi | — | ✓ | ✓ |
| Šta pomjera cijenu | — | ✓ | ✓ |
| Slična vozila u prodaji | — | ✓ | ✓ |
| Kilometraža i cijena | — | ✓ | ✓ |
| Vrijednost kroz vrijeme | — | ✓ | ✓ |
| **Dijeljenje** | | | |
| Link, QR kod i PDF | ✓ | ✓ | ✓ |
| Provjera izvještaja po broju | ✓ | ✓ | ✓ |
| Kupac s linkom vidi cijeli izvještaj | — | — | ✓ |
| Tvoje ime i kontakt na izvještaju | — | — | ✓ |
| **Nalog i podrška** | | | |
| Historija svih procjena | ✓ | ✓ | ✓ |
| Izvoz podataka | ✓ | ✓ | ✓ |
| Podrška | Email | Email | Prioritetna, isti dan |
## Kako se pretplatiti
### 1. Odaberite plan
Na [Cjenovnik](https://www.cifra.ba/cjenovnik) odaberite **Odaberi Plus** ili **Odaberi Pro**, ili **Otključaj cijeli izvještaj** u izvještaju. Plan možete promijeniti i u nalogu, pod **Pretplata**.
### 2. Provjerite narudžbu
Lijevo je narudžba: plan, mjesečno ili godišnje, cijena prvog mjeseca i šta plan otvara. Promo kod unosite pod **Imaš promo kod?**, a **Danas plaćaš** je tačan iznos koji se tereti.
### 3. Platite
Platite karticom (Visa, Mastercard, Maestro), Apple Payom ili Google Payom. Plan vrijedi odmah, a ako ste došli iz izvještaja ili procjene, vraćate se tačno tamo.
> **Napomena:** Plaćanje obrađuje Stripe. Podaci o kartici nikad ne dolaze do servera Cifre.
## Upravljanje pretplatom
U nalogu, pod **Pretplata**, je sve o planu: trenutni plan, sljedeća naplata i njen iznos, kartica i svi računi.
| Želite | Kako |
| --- | --- |
| Veći plan | **Promijeni plan**. Vrijedi odmah, a neiskorišteni dio trenutnog plana se uračunava. |
| Manji plan | **Promijeni plan**. Počinje kad istekne plaćeni period; do tada imate sve iz trenutnog. |
| Godišnje plaćanje | **Pređi na godišnje**. Dva mjeseca su gratis. |
| Drugu karticu | **Promijeni karticu**. Vrijedi za sva sljedeća plaćanja. |
| Račun | Svako plaćanje ima račun za preuzimanje, a stiže i na email. |
| Otkazati | **Otkaži pretplatu**. Plan ostaje do kraja plaćenog perioda i više vas ne teretimo. |
Dok traje otkazana pretplata, možete je obnoviti jednim klikom, bez dvostruke naplate.
> **Pažnja:** Ako plaćanje ne prođe, npr. kad kartica istekne, pretplata ima status **Plaćanje kasni**. Promijenite karticu u **Pretplata** i dugovanje se naplati odmah.
## Česta pitanja
**Šta je s izvještajima koje sam napravio prije pretplate?**
S Plus ili Pro planom i oni se otvaraju u cijelosti, jer je sve izračunato kad je procjena napravljena. Izvještaji napravljeni na Plus ili Pro planu ostaju potpuni i ako kasnije pređete na Free.
**Koja je razlika između Plus i Pro?**
Plus je za vas: 10 procjena dnevno i cijeli izvještaj. Pro je za one koji prodaju drugima: neograničene procjene, a kupac kojem pošaljete link vidi cijeli izvještaj, s vašim imenom i kontaktom. Uz to je prioritetna podrška, s odgovorom isti dan.
**Kad se resetuje dnevni limit?**
U ponoć po bosanskom vremenu. Na ekranu limita vidite koliko je ostalo do sljedeće procjene.
**Mogu li dobiti povrat novca?**
Pretplata je bez ugovora: otkažite je bilo kada i plan traje do kraja plaćenog perioda, bez nove naplate. Ako mislite da je neka naplata pogrešna, [pišite podršci](https://www.cifra.ba/kontakt) s brojem računa.
**Procjenjujem za firmu. Koji plan mi treba?**
Pro je za samostalne preprodavače, posrednike i servise. Ako procjenjujete u timu, s logom firme ili iz vlastitog softvera, pogledajte [Cifra Enterprise](https://www.cifra.ba/docs/enterprise) i [planove za kompanije](https://www.cifra.ba/cjenovnik?za=kompanije).
---
# Nalog i privatnost
Registracija i prijava, profil, lozinka i uređaji, email obavještenja, izvoz podataka i brisanje naloga.
## Pregled
Nalog čuva vaše procjene, plan i račune. Otvarate ga na [cifra.ba](https://www.cifra.ba/register) emailom i lozinkom, a adresu potvrđujete kodom iz emaila, jednom. Lijevo u nalogu su **Moje procjene**, **Profil**, **Sigurnost**, **Pretplata** i **Podaci i privatnost**.
## Registracija
### 1. Napravite nalog
Na [Napravi nalog](https://www.cifra.ba/register) upišite ime, email i lozinku od najmanje 8 znakova. Novosti o tržištu su neobavezne.
### 2. Potvrdite email
Na email stiže šestocifreni kod koji vrijedi 10 minuta. Upišite ga i nalog je spreman. Ako kod ne stigne za minut, pogledajte neželjenu poštu ili odaberite **Pošalji novi kod**.
> **Savjet:** Ako nalog pravite usred procjene, unos vozila vas čeka: nakon potvrde koda izvještaj se otvara odmah.
## Prijava
Prijavite se na [Prijava](https://www.cifra.ba/login) emailom i lozinkom. Zaboravljenu lozinku mijenjate preko **Zaboravljena lozinka?**: na email stiže link za novu lozinku, koji vrijedi sat vremena i radi jednom.
Jedna prijava vrijedi i za Cifra Enterprise. Ako je za vaš nalog uključena dvofaktorska prijava, nakon lozinke upisujete kod iz aplikacije za autentifikaciju ili rezervni kod.
## Profil
- **Profilna slika**: kliknite na sliku ili je prevucite. JPG, PNG ili WebP, do 15 MB.
- **Ime i prezime**: kako vam se obraćamo i kako se vidite u meniju.
- **Email adresa**: **Promijeni** šalje link za potvrdu na novu adresu; promjena vrijedi kad je potvrdite.
- **Email obavijesti**: **Novosti i savjeti** (najviše jednom mjesečno) možete isključiti; emailovi o izvještajima, sigurnosti naloga i plaćanju su uvijek uključeni.
- **Tvoje ime na izvještajima** (Pro): ime, telefon i firma za [Pripremio](https://www.cifra.ba/docs/cifra/sharing#pripremio) na novim izvještajima.
## Sigurnost
Pod **Sigurnost** mijenjate lozinku i vidite **Prijavljeni uređaji**: gdje je nalog trenutno otvoren. Ne prepoznajete uređaj? Odjavite ga i promijenite lozinku. Pri promjeni lozinke možete odmah odjaviti sve druge uređaje.
## Podaci i privatnost
Vaši podaci su vaši. Pod **Podaci i privatnost** ih preuzimate u bilo kojem trenutku:
- **Procjene (CSV)**: vozilo, vrijednost, raspon i link svake procjene. Otvara se u Excelu.
- **Svi podaci (JSON)**: profil, procjene, pretplata i plaćanja, sve što o vama čuvamo.
### Brisanje naloga
**Obriši nalog** trajno briše profil, prijave i sliku. Za izvještaje birate:
- **Zadrži ih bez mog imena**: podijeljeni linkovi i PDF-ovi i dalje rade, ali nisu povezani s vama.
- **Obriši ih**: podijeljeni linkovi prestaju raditi.
Brisanje potvrđujete lozinkom. Aktivna pretplata se odmah otkazuje, bez povrata za ostatak perioda. Računi ostaju kao knjigovodstveni zapis, bez veze s nalogom.
> **Pažnja:** Brisanje naloga se ne može poništiti. Prije toga preuzmite podatke.
## Česta pitanja
**Kod za potvrdu nije stigao.**
Pogledajte neželjenu poštu i promotivne poruke. Novi kod možete tražiti nakon 30 sekundi. Ako ste pogriješili adresu, odaberite **Promijeni adresu**.
**Mogu li koristiti Cifru bez naloga?**
Unos vozila i [provjera izvještaja](https://www.cifra.ba/provjera) rade bez naloga, a izvještaje koje vam neko pošalje otvarate bez prijave. Za vlastitu procjenu treba besplatan nalog.
**Kako da vam pošaljem prijedlog ili prijavim grešku?**
U nalogu odaberite **Pošalji utisak**, ili nam [pišite](https://www.cifra.ba/kontakt). Na planu Pro odgovaramo isti dan.
---
# Cifra Enterprise
Platforma za timove koji procjenjuju vozila svaki dan: procjene s logom kompanije, masovne liste, provjera rizika, praćenje portfelja, lager, tržište i rezidualne vrijednosti.
## Pregled
Cifra Enterprise je radno mjesto za salone, lizing kuće, banke, osiguranja i flote. Isti modeli kao na cifra.ba, ali za tim: svaka procjena nosi logo i podatke kompanije, ostaje u zajedničkoj historiji, ima svrhu i vašu oznaku (broj ugovora, štete ili VIN), a uz nju dolazi alat za odluku koju donosite.
Platforma je na [enterprise.cifra.ba](https://enterprise.cifra.ba). Prijavljujete se istim nalogom kao na cifra.ba; jedna prijava vrijedi za oba mjesta.
## Šta je na platformi
- [Procjene](https://www.cifra.ba/docs/enterprise/valuations): Vođena procjena ili brzi unos, izvještaj s logom i alat za odluku: otkup, prodaja, finansiranje, osiguranje.
- [Masovna procjena](https://www.cifra.ba/docs/enterprise/bulk): Cijeli portfelj ili lager iz Excela, na dan koji odaberete, vraćen kao vaš fajl s Cifrinim kolonama.
- [Provjera](https://www.cifra.ba/docs/enterprise/check): Šta oglasi govore o vozilu: vraćena kilometraža, tuđe fotografije, cijena van tržišta.
- [Vozila i alarmi](https://www.cifra.ba/docs/enterprise/watchlist): Flota, kolateral ili tražena vozila, procijenjena svako jutro, s LTV-om i alarmima.
- [Lager](https://www.cifra.ba/docs/enterprise/inventory): Vaša vozila na prodaji poređena s tržištem: šta sniziti, šta stoji, šta vrijedi kupiti.
- [Rezidual](https://www.cifra.ba/docs/enterprise/residuals): Vrijednost na kraju ugovora iz domaćeg tržišta, s preporučenim ostatkom.
- [Radar](https://www.cifra.ba/docs/enterprise/radar): Tržište bilo kojeg segmenta: cijene, ponuda, brzina prodaje, karta i trgovci.
- [Vaš model](https://www.cifra.ba/docs/enterprise/models): Model naučen na vašim prodajnim ili otkupnim cijenama.
- [Razvoj](https://www.cifra.ba/docs/enterprise/developers): API ključevi, potrošnja, log zahtjeva, webhookovi i widgeti za vašu stranicu.
## Prvi koraci
Nova kompanija na početnoj stranici vidi listu **Prvi koraci**. Svaki korak vodi tamo gdje se radi, a lista se sama štiklira.
### 1. Napravite prvu procjenu
Odaberite **Procijeni vozilo** na vrhu bočne trake. Izvještaj se sprema u historiju tima, s imenom kompanije. Vidi [Procjene](https://www.cifra.ba/docs/enterprise/valuations).
### 2. Pozovite tim
U **Postavke → Tim** odaberite **Pozovite** i upišite email adrese kolega. Vidi [Tim i postavke](https://www.cifra.ba/docs/enterprise/team#tim).
### 3. Dodajte logo kompanije
U **Postavke → Općenito** postavite logo: vidi se u bočnoj traci, na svakom izvještaju i u zaglavlju PDF-a.
### 4. Pratite prvo vozilo
Vozilo iz flote, lagera ili kolaterala procjenjuje se svako jutro, s alarmima kad pređe vaš prag. Vidi [Vozila i alarmi](https://www.cifra.ba/docs/enterprise/watchlist).
### 5. Povežite svoj sistem
API ključ za vaš DMS, CRM ili portal pravite sami u **Razvoj**. Vidi [Razvoj](https://www.cifra.ba/docs/enterprise/developers).
## Kretanje kroz platformu
- **Bočna traka**: kompanija gore (i prelazak u drugu, ako ste u više njih), dugme **Procijeni vozilo**, pretraga, proizvodi po grupama, a vaš nalog dolje.
- **⌘K** (Ctrl+K na Windowsu) otvara pretragu stranica i radnji: upišite npr. „lager” ili „novi ključ”.
- **⌘B** skuplja bočnu traku u traku s ikonama, a **⌘/** prikazuje sve prečice.
- Proizvod koji vaš plan nema ostaje u traci, označen planom koji ga ima.
### Svijetlo i tamno
Platforma prati podešavanje računara: danju svijetla, noću tamna. Izgled mijenjate u **Postavke → Profil → Izgled**.
## Pomoć i podrška
**Pomoć i podrška** u bočnoj traci (ili krug u donjem desnom uglu) otvara razgovor. Asistentkinja Mira odgovara odmah, s podacima vaše kompanije: plan i potrošnja, procjene, tim i API ključevi. Kad treba, razgovor preuzima vaš tim podrške. Odgovor stiže i na email.
## Česta pitanja
**Kako kompanija dolazi na platformu?**
Za Team i Business sami, na [enterprise.cifra.ba/signup](https://enterprise.cifra.ba/signup?plan=business&interval=month), uz 7 dana besplatno. Enterprise ugovore postavlja Cifra s vašim prvim vlasnikom. Vidi [Plan i naplata](https://www.cifra.ba/docs/enterprise/billing).
**Je li ovo isti nalog kao na cifra.ba?**
Da. Isto ime, email, lozinka i dvofaktorska prijava. Lični plan na cifra.ba i plan kompanije su odvojeni: procjene u ime kompanije pravite ovdje, i one pripadaju timu.
**Radim za dvije kompanije. Kako prelazim?**
Kliknite naziv kompanije na vrhu bočne trake ili potražite kompaniju u ⌘K. Sve što zatim radite pripada toj kompaniji.
**Gdje su podaci?**
Na serverima u EU. Procjene kompanije su privatne i vidi ih samo vaš tim; podaci za [Vaš model](https://www.cifra.ba/docs/enterprise/models) su u odvojenom spremištu i nikad ne ulaze u Cifrin tržišni model.
---
# Tim i postavke
Podaci i logo kompanije, članovi i uloge, pravila izvještaja, sigurnost prijave i dnevnik aktivnosti.
## Pregled
Sve postavke su na jednoj stranici, s menijem lijevo: gore **Vaš nalog** (profil, prijava i sigurnost), ispod kompanija (**Općenito**, **Tim**, **Procjene i izvještaji**, **Sigurnost**, **Aktivnost**, **Plan i naplata**). Svaka kartica se čuva za sebe. Članovi vide iste kartice, ali ih ne mogu mijenjati.
## Kompanija
U **Općenito** su logo i podaci kompanije: naziv u Cifri, puni registrovani naziv, JIB, PDV broj, adresa, telefon, web i email za račune. Ti podaci pišu se u zaglavlju izvještaja i na fakturama.
> **Savjet:** Logo najbolje izgleda kao SVG ili PNG s prozirnom pozadinom (do 5 MB). Novi logo zamjenjuje stari na svim izvještajima, i onim već napravljenim.
## Tim
Tim pokazuje mjesta (članovi i otvoreni pozivi prema ugovoru), sve članove s ulogom, brojem procjena u 30 dana i zadnjom aktivnošću, i pozive koji čekaju.
### 1. Pozovite kolege
Odaberite **Pozovite**, upišite email adrese (zarezom ili zalijepite listu) i odaberite ulogu. Dugme kaže koliko poziva šaljete.
### 2. Kolega prihvata poziv
Poziv stiže emailom i vrijedi 7 dana. Ko nema Cifra nalog, napravi ga na istoj stranici: ime i lozinka, a email je već potvrđen samim linkom.
### 3. Upravljajte pozivima
Poziv koji čeka možete kopirati kao link, poslati ponovo ili otkazati. Dok je otvoren, zauzima mjesto u timu.
### Uloge
| Uloga | Može |
| --- | --- |
| **Član** | Procjene, provjere, vozila, tržište i historija tima. |
| **Administrator** | Sve što član, plus tim, postavke kompanije, sigurnost, dnevnik aktivnosti, vaš model i API. |
| **Vlasnik** | Sve, uključujući plan, plaćanje i druge vlasnike. |
> **Napomena:** Samo vlasnik može napraviti drugog vlasnika, a zadnji vlasnik ne može napustiti kompaniju.
## Procjene i izvještaji
Ovdje birate kako izgleda izvještaj na papiru i kako tim pravi procjene:
- **Kontakt podaci** ispod logotipa i vlastiti **Tekst na dnu** (npr. napomena pravne službe), uz pregled uživo.
- Zadana **svrha** nove procjene, obavezna interna oznaka i kako je zovete (npr. „Broj ugovora”).
- Polazne vrijednosti za otkup: vaša marža i trošak pripreme.
## Sigurnost
- **Dvofaktorska potvrda za cijeli tim**: uključuje je onaj ko je i sam koristi; do tada vidite ko je još nema.
- **Ko smije biti pozvan**: pozivi samo na adrese domena vaše kompanije (Business i Enterprise).
- **Jedinstvena prijava (SSO)** je dio Enterprise plana.
### Vaša prijava
U **Prijava i sigurnost** uključujete dvofaktorsku potvrdu za sebe: lozinka, pa QR kod u aplikaciji za autentifikaciju (Google Authenticator, Microsoft Authenticator, 1Password…) i prvi kod, pa 10 rezervnih kodova. Pouzdan preglednik ne traži kod 30 dana. Tu su i promjena lozinke i uređaji na kojima ste prijavljeni.
## Dnevnik aktivnosti
Ko je šta uradio u kompaniji i kada: pozivi i uloge, podaci i logo, procjene, provjere, liste, vozila, segmenti, kalkulacije, model, API ključevi i webhookovi, izvozi, prijave i svaka prijava Cifrine podrške u vaš nalog, s razlogom. Svaki unos se otvara i pokazuje šta se promijenilo. Filteri po radnji, osobi i periodu; **Izvoz za Excel**.
## Česta pitanja
**Koliko članova može imati tim?**
Team: 3, Business: 10, Enterprise: po ugovoru. Otvoreni pozivi zauzimaju mjesto; istekli ne.
**Kolegi nije stigao poziv.**
U **Tim** kod poziva odaberite **Pošaljite ponovo** ili **Kopirajte link** i pošaljite mu ga sami. Ako kompanija dozvoljava samo svoje domene, adresa mora biti na jednoj od njih.
**Šta se desi s procjenama člana kojeg uklonimo?**
Ostaju u historiji kompanije. Član gubi pristup kompaniji, a njegov lični Cifra nalog ostaje.
---
# Plan i naplata
Team, Business i Enterprise: šta je u kojem planu, probni period, potrošnja i računi.
## Pregled
| | Team | Business | Enterprise |
| --- | --- | --- | --- |
| Za koga | Za manje salone i agencije koje procjenjuju svaki dan. | Za salone, lizing kuće i timove koji rade s tržištem. | Za banke, osiguranja, uvoznike i flote. |
| Cijena | 150 KM mjesečno ili 1.500 KM godišnje | 500 KM mjesečno ili 5.000 KM godišnje | Po dogovoru |
| Probni period | 7 dana | 7 dana | Pilot s Cifrom |
| Članovi | 3 | 10 | Po ugovoru |
| Procjene | 500 mjesečno | Neograničeno | Neograničeno |
Godišnje plaćanje košta kao 10 mjeseci. Enterprise može plaćati po fakturi, virmanski.
## Sve razlike
| | Team | Business | Enterprise |
| --- | --- | --- | --- |
| **Tim i procjene** | | | |
| Članovi tima | 3 | 10 | Po dogovoru |
| Procjene | 500 mjesečno | Neograničeno | Neograničeno |
| Vođena procjena i brzi unos | ✓ | ✓ | ✓ |
| Izvještaj s logom i podacima kompanije | ✓ | ✓ | ✓ |
| Alati po namjeni: otkup, prodaja, finansiranje, osiguranje | ✓ | ✓ | ✓ |
| Zajednička historija i izvoz u Excel | ✓ | ✓ | ✓ |
| Masovna procjena iz Excela | — | ✓ | ✓ |
| **Vozila i tržište** | | | |
| Provjera oglasa | 100 mjesečno | 1.000 mjesečno | Po dogovoru |
| Lager: zalihe naspram tržišta | ✓ | ✓ | ✓ |
| Praćena vozila i alarmi | 50 vozila | 1.000 vozila | Po dogovoru |
| Cifra Radar | — | ✓ | ✓ |
| Rezidualne vrijednosti | — | ✓ | ✓ |
| Vaš model, učen na vašim podacima | — | — | ✓ |
| **Integracija** | | | |
| Cifra API i webhookovi | — | 10.000 jedinica mjesečno | Po dogovoru |
| Testni ključevi (sandbox) | — | ✓ | ✓ |
| Widgeti za vašu web stranicu | 50 vozila | 1.000 vozila | Po dogovoru |
| **Sigurnost i podrška** | | | |
| Dvofaktorska prijava za cijeli tim | ✓ | ✓ | ✓ |
| Dnevnik aktivnosti | ✓ | ✓ | ✓ |
| Pozivi samo na domene kompanije | — | ✓ | ✓ |
| Jedinstvena prijava (SSO) | — | — | ✓ |
| Ugovor, SLA i obrada podataka (DPA) | — | — | ✓ |
| Plaćanje | Kartica | Kartica | Faktura ili kartica |
| Podrška | Email | Prioritetna, isti dan | Posvećeni menadžer |
## Pretplata za kompaniju
### 1. Nalog
Na [enterprise.cifra.ba/signup](https://enterprise.cifra.ba/signup?plan=business&interval=month) napravite nalog ili se prijavite postojećim Cifra nalogom. Postajete vlasnik kompanije.
### 2. Kompanija
Naziv, registrovani naziv, JIB i PDV broj, grad i email za račune. Ti podaci idu na svaki račun.
### 3. Plaćanje
Unesite karticu. Prvih 7 dana je besplatno, a prvo plaćanje je osmi dan, osim ako otkažete. Tri dana prije kraja probnog perioda javljamo se emailom. Probni period je jednom po kompaniji.
## Plan i naplata
U **Postavke → Plan i naplata** vlasnici i administratori vide plan, a samo vlasnici ga mijenjaju:
- Šta je potrošeno ovaj mjesec: mjesta, procjene, provjere, praćena vozila i API jedinice.
- Šta je uključeno u plan i šta otvara veći plan.
- Kartica, računi u PDF-u i podaci za račune.
- **Promijenite plan**: veći plan vrijedi odmah, uz uračunat neiskorišteni dio; manji počinje kad istekne plaćeni period, i ne može ako tim ima više članova nego manji plan.
- Otkazivanje s razlogom, obnova otkazane pretplate i poništavanje promjene koja čeka.
> **Napomena:** Mjesečne kvote (procjene na Team planu, provjere, API jedinice) računaju se po kalendarskom mjesecu u Sarajevu. Kad se kvota potroši, zahtjev se odbija prije bilo kakvog rada, a plan i naplata kažu koliko je ostalo.
## Česta pitanja
**Dobijamo li račun na kompaniju?**
Da. Svaki račun nosi registrovani naziv, adresu, JIB i PDV broj iz postavki i stiže na adresu za račune.
**Šta je s podacima ako otkažemo?**
Plan traje do kraja plaćenog perioda. Zatim se pristup pauzira, a procjene, vozila i postavke ostaju: kad obnovite pretplatu, sve je gdje ste ostavili. Prije toga možete sve izvesti u Excel.
**Kada nam treba Enterprise?**
Za više od 10 članova ili poseban obim, vaš model učen na vašim cijenama, jedinstvenu prijavu (SSO), ugovor sa SLA i obradom podataka (DPA) ili plaćanje po fakturi. [Pišite nam](https://www.cifra.ba/kontakt).
---
# Procjene
Procjena s logom kompanije, svrhom i vašom oznakom, i izvještaj s alatom za odluku: otkup, prodaja, finansiranje ili osiguranje.
[Video: Vođena procjena: automobil, Škoda, Octavia, 2019, 142.000 km, izvedba motora, detalji, svrha i oznaka, pregled i gotov izvještaj](https://www.cifra.ba/docs/enterprise/procjena.mp4)
## Pregled
Procjenu pravite na dva načina: **vođeno**, jedno pitanje po ekranu, ili kao **brzi unos**, sva polja na jednoj stranici. Obje vode do istog izvještaja, koji ostaje u historiji tima, privatan za kompaniju.
## Vođena procjena
### 1. Vozilo
Vrsta, marka, model i godište, sve kao velike pločice. Marke i modeli su poredani po broju oglasa, a pretraga prašta pravopis („skoda” nalazi Škodu). Odabir pločice sam prelazi dalje.
### 2. Kilometraža i motor
Jedan veliki broj, s prečicama za okrugle vrijednosti i provjerom ako upišete „185” umjesto 185.000. Zatim najčešće izvedbe tog modela i godišta; ako vaše nema, **Moje vozilo nije na listi** otvara gorivo, mjenjač, snagu i zapreminu.
### 3. Detalji
Grad, vlasnik po redu, servisna knjižica, carina i karoserija. Sve se može preskočiti, ali svaki odgovor sužava raspon.
### 4. Svrha i oznaka
Zašto procjenjujete i vaša oznaka, po kojoj procjenu kasnije nađete (broj ugovora, štete, lagera ili VIN). Svrha određuje alat za odluku u izvještaju.
### 5. Pregledajte i procijenite
Svi odgovori na jednom mjestu, svaki s **Promijeni**. Odaberite **Procijeni vozilo** i izvještaj se otvara za par sekundi.
Kartica **Vaše vozilo** desno raste s odgovorima i pokazuje preciznost procjene. **Nazad**, traka napretka i dugme za nazad u pregledniku vode između koraka, a nedovršen unos preživi osvježavanje stranice.
### Brzi unos
Za ljude koji procjenjuju mnogo dnevno: **Radite puno procjena? Prebacite na brzi unos** stavlja sva polja na jednu stranicu, a **⌘↵** procjenjuje. Platforma pamti koji način koristite.
## Izvještaj
Na vrhu su vozilo i logo marke, svrha i oznaka, a ispod traka dijelova koja ostaje u vidu: **Pregled**, **Odluka**, **Zašto ova cijena**, **Tržište**, **Kilometraža**, **Budućnost**, **Slična vozila** i **Metodologija**. Svaki dio počinje zaključkom u jednoj rečenici.
Desno je traka za tim: svrha i interna oznaka (**Uredi**), **Ishod** (prodajna cijena kad vozilo ode, koja uči model) i podaci o vozilu, uz savjet šta dodati za uži raspon.
### Od procjene do odluke
Alat za odluku otvara se prema svrsi, a možete ga promijeniti u izvještaju:
| Alat | Odgovara na | Vi unosite |
| --- | --- | --- |
| **Otkup** | Koliko najviše ponuditi: očekivana prodajna cijena minus priprema i vaša marža, i oprezna ponuda od donje granice raspona. | Prodajnu cijenu, pripremu, maržu |
| **Prodaja** | Gdje vaša tražena cijena stoji prema rasponu i sličnim oglasima. | Traženu cijenu |
| **Finansiranje** | LTV danas i kroz 12–60 mjeseci prema prognozi, i ostatak vrijednosti na kraju. | Iznos i trajanje |
| **Osiguranje** | Je li naknada u skladu s tržištem, uz gotov pasus za spis. | Predloženu naknadu |
Cijenu za koju se odlučite sačuvajte (**Sačuvaj kao našu ponudu**, **Sačuvaj iznos**, **Sačuvaj naknadu**): vidi se u listi procjena, u koloni **Vaša cijena**.
### Zašto ova cijena
Faktori od polazne vrijednosti modela do vašeg vozila: lijevo oni koji spuštaju cijenu, desno oni koji je dižu, u KM.
### Tržište, budućnost i slična vozila
- **Tržište**: koliko je sličnih u prodaji, srednja cijena, koliko stoje, kretanje cijena i raspodjela traženih cijena, s linkom na cijeli segment u [Radaru](https://www.cifra.ba/docs/enterprise/radar).
- **Budućnost**: vrijednost za jednu, dvije i tri godine, pa krivulja.
- **Slična vozila**: najbliži oglasi, svaki s presudom: tržišna cijena, ili koliko je skuplji ili jeftiniji od svoje vrijednosti.
### Radnje u izvještaju
| Radnja | Šta radi |
| --- | --- |
| **PDF** | A4 izvještaj sa zaglavljem kompanije: logo, kontakt i vaš tekst na dnu. |
| **Prati vozilo** | Dodaje vozilo u [Praćena vozila](https://www.cifra.ba/docs/enterprise/watchlist), s podacima iz procjene. |
| **S izmjenama** | Otvara pregled s odgovorima ove procjene, da promijenite šta treba. |
| **Procijeni danas** | Isto vozilo, današnji model i tržište; novi izvještaj je vezan za ovaj. |
## Historija procjena
**Procjene** je historija cijelog tima: pretraga po vozilu i vašoj oznaci, **Tim** ili **Moje**, filteri po vrsti vozila, periodu, svrsi i članu, i **Izvoz** u CSV za Excel. Procjenu briše njen autor ili administrator.
## Česta pitanja
**Vide li klijenti naše procjene na cifra.ba?**
Ne. Procjene kompanije prave se samo na platformi i privatne su za tim. Klijentu dajete PDF.
**Zašto izvještaj pokazuje „Prodajna cijena po vašem modelu”?**
Jer kompanija ima uključen [vaš model](https://www.cifra.ba/docs/enterprise/models). Procjena tada dolazi iz modela učenog na vašim cijenama, a tržišna vrijednost je odmah ispod, radi poređenja.
**Ima li ograničenje broja procjena?**
Team uključuje 500 procjena mjesečno; Business i Enterprise su neograničeni. Kompanija može napraviti do 30 procjena u minuti.
---
# Masovna procjena
Lager, lizing portfelj ili flota iz Excel tabele, procijenjeni odjednom, na dan koji odaberete, i vraćeni kao vaš fajl s Cifrinim kolonama.
[Video: Masovna procjena: odabir Excel fajla s 150 ugovora, svrha Finansiranje, ispravka nepoznatog modela i rezultat liste](https://www.cifra.ba/docs/enterprise/masovna.mp4)
## Pregled
Masovna procjena uzima vašu tabelu kakva jeste, procijeni svako vozilo na isti dan za istu svrhu i vrati vam isti fajl, s Cifrinim kolonama na kraju. Lista do 10.000 vozila; kompanija može procijeniti do 100.000 redova dnevno.
## Vodič
### 1. Dodajte vozila
Prevucite .xlsx, .csv ili .tsv, odaberite **Odaberite datoteku** ili **Zalijepite iz Excela**. Fajl se čita u pregledniku: ništa se ne šalje dok ne odaberete **Procijeni**. **Preuzmite predložak tabele** ako počinjete od nule.
### 2. Provjerite kolone
Svaka kolona je prikazana s primjerima i poljem koje smo prepoznali po nazivu. Pogrešno prepoznatu promijenite. Motor se čita i iz naziva („1.6 TDI 110 KS DSG” daje 1.600 cm³, dizel, 81 kW, automatski).
### 3. Ispravite nazive
Pod **Nazivi koje ne prepoznajemo** je svaki nepoznati naziv jednom, s brojem redova. Marka i model koje odaberete vrijede za svaki red s tim nazivom.
### 4. Odaberite svrhu i dan
Svrha kaže šta znači kolona s iznosom: **Otkup** (cijena po kojoj kupujete), **Prodaja** (tražena cijena), **Finansiranje** (preostali dug, s mjesecima i balonom), **Osiguranje** (osigurana suma), **Flota** (knjigovodstvena vrijednost) ili **Samo vrijednost**. **Vrijednost na dan** je danas, kraj prošlog mjeseca, kvartala ili godine, ili bilo koji dan od 2015; kolona s datumom daje redu njegov dan, npr. dan štete.
### 5. Procijenite
**Procijeni N vozila** (ili ⌘↵). Oko 1.200 vozila traje petnaestak sekundi. Ako zatvorite stranicu, procjena se pauzira i nastavlja kad je otvorite.
## Rezultat
Gore su ukupna vrijednost i zbir raspona, vrijednost za 12 mjeseci i zaključak svrhe s presudama kao trakom. Svaka presuda je i filter. Ispod su četiri broja za vaš posao: kod finansiranja preostali dug, LTV portfelja, ugovori iznad limita i dug iznad vrijednosti.
Ispod je svaki red: vrijednost i raspon, traka raspona s vašim iznosom, presuda s razlikom i ocjena. Redovi se sortiraju, filtriraju (presuda, **Za provjeru**, nisu procijenjeni, marka) i pretražuju odmah, i kod 10.000 vozila.
### Jedan red
Klik na red otvara ga sa strane: vrijednost na skali s vašim iznosom, obračun svrhe u KM, vrijednost unaprijed, tržište i ćelije iz vašeg fajla. **Puni izvještaj** pravi izvještaj tog vozila na dan liste, **Pratimo ga** ga dodaje u praćena vozila, a **Ispravi** mijenja marku, model, godište, kilometražu ili iznos i procjenjuje ponovo.
## Šta dalje s listom
| Radnja | Šta radi |
| --- | --- |
| **Excel** | Vaš fajl, sve kolone kakve su bile, pa Cifrine (vozilo kako smo ga pročitali, vrijednost, raspon, ocjena, kolone svrhe, 12 mjeseci, promjena, napomene, link izvještaja) i list „Sažetak”. |
| **PDF** | Štampa sa zaglavljem kompanije: sažetak i svaki red. |
| **Procijeni ponovo** | Isti redovi na drugi dan, kao nova lista poređena red po red. |
| **Prati sva vozila** | Svaki procijenjeni red u praćena vozila, u grupi s imenom liste; lista za finansiranje s dugom i LTV alarmima. |
## Česta pitanja
**Kojim redom moraju biti kolone?**
Bilo kojim, i s vašim nazivima. Obavezni su marka i model, godište i kilometraža; ostalo sužava raspon.
**Neki redovi nisu procijenjeni.**
Rezultat kaže zašto (npr. **Bez kilometraže: 2**). Otvorite red i odaberite **Ispravi**, ili ispravite fajl i procijenite ponovo. Excel može izvesti samo problematične redove.
**Mogu li procijeniti portfelj na kraj kvartala?**
Da: **Vrijednost na dan** → kraj kvartala. Procjena je kakva bi bila tog dana, s tržištem tog dana.
**Briše li se lista s izvještajima?**
Ne. Listu briše autor ili administrator; izvještaji napravljeni iz nje i praćena vozila ostaju.
---
# Provjera
Šta oglasi govore o vozilu, a prodavac ne kaže: vraćena kilometraža, tuđe fotografije, cijena van tržišta, lizing. Uz odluku vašeg tima.
[Video: Provjera vozila: zalijepljen link OLX oglasa, Provjeri i izvještaj s nivoom pažnje Visok rizik](https://www.cifra.ba/docs/enterprise/provjera.mp4)
## Pregled
Provjera pronalazi sve oglase istog vozila na OLX.ba, AutoBum.ba i AutoPlac.ba, i iz njih čita signale: kilometraža koja pada, iste fotografije kod drugog vozila, cijena daleko ispod tržišta, vozilo na lizingu, česti ponovni oglasi. Za dilera koji kupuje, banku koja finansira i osiguranje koje isplaćuje štetu.
> **Pažnja:** Provjera nije registar ni VIN provjera. Signal je razlog da pitate, ne presuda: uz svaki stoji šta tačno provjeriti.
## Vodič
### 1. Zalijepite link
Link oglasa s OLX.ba, AutoBum.ba ili AutoPlac.ba, ili samo broj OLX oglasa, pa **Provjeri** (ili Enter). Pod **Svrha, oznaka, datum** dodajte svrhu, vašu oznaku i datum događaja.
### 2. Pročitajte nivo pažnje
**Visok rizik**: signal koji, ako je tačan, mijenja posao. **Povećan oprez**: vrijedi pitati. **Bez upozorenja**: oglasi ne pokazuju ništa neobično.
### 3. Pregledajte dokaze
Svaki signal kaže šta smo vidjeli, zašto je važno, šta provjeriti (**Provjerite:**) i koliko je čest. Ispod su dokazi: svi oglasi vozila na vremenskoj liniji, kilometraža prema uobičajenoj za model i starost, cijena prema tržištu, prodavci, fotografije i papiri kako ih oglas navodi.
### 4. Zabilježite odluku
U traci desno: **Odobreno**, **Dodatna provjera** ili **Odbijeno**, uz obrazloženje. Odluka bilježi ko i kada, i ulazi u dnevnik aktivnosti. Lista **Prije odluke** daje provjere koje se štikliraju i čuvaju za tim.
## Nivoi i signali
Pragovi dolaze s tržišta svako jutro: cijena ispod 5. ili 2. percentila tražene cijene prema Cifrinoj, kilometraža ispod 3. percentila za model i starost. Važno je i šta je u pitanju: jeftin auto daleko ispod tržišta je napomena, ne alarm. Na automobilima u prodaji visok nivo ima oko 1% oglasa, a povećan oprez oko 7%; tačne udjele jutros vidite na **Pregled** pod **Tržište jutros**.
Detalji o svakom signalu i koliko je čest jutros su u **Metodologija**, a šifre signala u [API referenci](https://www.cifra.ba/docs/api/vehicle-history).
## Bez linka i više oglasa
- **Pronađi vozilo**: nemate link? Opišite vozilo (marka, model, godište, snaga, gorivo, kilometraža i dan očitanja, mjesto, boja) i tražimo ga među svim oglasima koje smo vidjeli, s onim što se slaže i ne slaže. Datum postaje datum događaja: korisno za štete.
- **Više oglasa**: do 100 linkova odjednom, svaki postaje provjera u historiji tima, poredani po nivou, uz Excel.
## Historija provjera
**Provjere** su sve provjere tima: pretraga po vozilu, oznaci ili broju oglasa, filteri po nivou, odluci (i bez odluke), svrsi i **Samo moje**, i **Excel**. Izvještaj je snimak dana provjere; **Provjeri ponovo** čita današnje podatke i kaže kakav je nivo bio.
> **Savjet:** Provjera je i u drugim modulima: oglasi u Radaru i prilike u Lageru imaju oznaku za povećan i visok nivo, a vozilo na lageru ima **Provjeri historiju**.
## Česta pitanja
**Koliko provjera imamo?**
Team: 100 mjesečno, Business: 1.000 mjesečno, Enterprise: po ugovoru.
**Oglas je objavljen danas i nema ga.**
Novi oglasi ulaze u podatke sljedećeg jutra. U **Više oglasa** takve linkove označavamo i oni stižu sutra.
**Da li prodavac saznaje da smo provjerili vozilo?**
Ne. Provjera čita javne oglase koje smo već vidjeli; nikoga ne kontaktiramo.
---
# Vozila i alarmi
Flota, lager, kolateral ili vozila koja tražite, procijenjeni ponovo svako jutro, s izloženošću, LTV-om i alarmima.
## Pregled
Vozila koja pratite procjenjuju se svako jutro, s današnjim modelom i tržištem. Lista pokazuje vrijednost i raspon, 30 dana, promjenu od dodavanja, LTV prema vašem pravilu, koliko se brzo takva vozila prodaju i otvorene alarme.
| Vrsta | Šta pratite |
| --- | --- |
| **Vlastito** | Vozilo koje imate ili finansirate: vrijednost pada s godinama i kilometrima (kilometraža može rasti po vašem godišnjem prosjeku). |
| **Traženo** | Specifikacija koju želite kupiti: tržišna cijena i novi oglasi ispod Cifrine cijene. |
## Dodavanje vozila
- **Dodajte vozilo**: vozilo, naziv, oznaka (ugovor ili broj šasije), grupe, iznos i pravila alarma.
- **Prati vozilo** na svakom izvještaju i **Prati sva vozila** na masovnoj listi.
- **Uvoz iz Excela**: do 10.000 vozila, kolone prepoznate po nazivu, s dugom, rokom i kamatom ako ih imate; problematični redovi se mogu preuzeti.
- Cifra API: vozila koja dodaju vaši ključevi su ista ova vozila.
### Iznos i LTV
Uz vlastito vozilo možete vezati iznos: **Kredit ili lizing** (stanje danas, preostali mjeseci, kamata i balon, kao anuitet, pa dug pada svaki dan), **Osiguranje** (osigurana suma) ili **Nabavka** (trošak). LTV je iznos podijeljen vrijednošću, danas i kroz prognozu.
## Jedno vozilo
Stranica vozila ima vrijednost s rasponom i promjenama, dnevne vrijednosti s rasponom i iznosom (crtkano), s označenim danima promjene modela i alarmima, te **Naredne tri godine**: prognozu uz dug koji se otplaćuje. Ispod su tržište tog vozila iz Radara i oglasi najviše ispod Cifrine cijene. Desno su pravila, iznos, kilometraža i podaci tima.
Za traženo vozilo stranica pokazuje tržišnu cijenu specifikacije i oglase koji su bar 3% ispod Cifrine cijene.
## Portfolio
**Portfolio** je cijela lista (ili jedna grupa): vrijednost i raspon, 30 dana, 12 mjeseci unaprijed i LTV; šta traži pažnju; vrijednost kroz vrijeme kao indeks istih vozila (dodana i uklonjena vozila ne pomjeraju krivulju) ili ukupno; raspodjela LTV-a; sastav po marki, vrsti, starosti i grupi s koncentracijom; likvidnost i najveće promjene.
## Alarmi
**Alarmi** su sanduče tima: šta se jutros promijenilo, po danu, dok ga neko ne označi **Pregledano**. Filteri po vrsti, grupi, periodu i **Moja vozila**; tastatura: ↑↓ ili j k za kretanje, E za pregledano, ↵ za otvaranje.
| Alarm | Kada se javlja |
| --- | --- |
| **Promjena vrijednosti** | Vrijednost se pomjerila za vaš postotak (najmanje 3%) od dodavanja, pa od zadnjeg alarma. |
| **Pad ispod / rast iznad cijene** | Vrijednost je prešla iznos koji ste postavili. |
| **Izloženost (LTV)** | Dug, osigurana suma ili nabavna cijena dostigli su vaš udio vrijednosti. |
| **Prilika na tržištu** | Novi oglas tražene specifikacije traži bar vaš postotak manje od Cifrine cijene. |
> **Napomena:** Novi model pomjeri vrijednosti za oko 2% i bez promjene tržišta, zato pragovi ne idu ispod 3%, a alarm kaže kad je tog dana počeo raditi novi model.
### Pravila i obavijesti
U **Pravila** su pragovi s kojima počinje svako novo vozilo (vlasnici i administratori), uz broj vozila na koje se svako pravilo odnosi i **Primijeni na postojeća vozila**. U **Obavijesti** svako bira jutarnji email: uključen ili ne, svoja ili sva vozila, vrste alarma i grupe, uz **Pošalji mi probni email**. Za vaš sistem tu su [webhookovi](https://www.cifra.ba/docs/enterprise/developers#webhookovi).
## Česta pitanja
**Koliko vozila možemo pratiti?**
Team: 50 vozila, Business: 1.000 vozila, Enterprise: po ugovoru.
**Kada se vozila procjenjuju?**
Svako jutro, nakon noćnog učenja modela. Jutarnji email stiže kad su sva vozila procijenjena, i samo ako ima alarma.
**Mijenja li se kilometraža sama?**
Za vlastito vozilo s godišnjom kilometražom, da: raste svaki dan. Novo očitanje upisujete na stranici vozila i prognoza kreće od njega.
---
# Lager
Vaša vozila na prodaji poređena s tržištem svako jutro: šta je preskupo, šta stoji, koliko će se čekati i šta vrijedi kupiti.
## Pregled
Lager su vaši aktivni oglasi s javnih profila salona koje povežete, plus vozila koja dodate sami. Svako jutro svako vozilo dobija Cifrinu cijenu, dane na prodaji, šansu prodaje i preporuku.
## Povezivanje lagera
### 1. Povežite profil
U **Postavke** lagera potražite salon po nazivu ili gradu, ili zalijepite link profila (`olx.ba/profil/…`), pa **Poveži**. Povežite sve profile salona, npr. jedan po poslovnici.
### 2. Podesite cilj i troškove
Ciljni broj dana na prodaji (45), trošak kapitala (8% godišnje), fiksni trošak po vozilu (5 KM dnevno) i priprema vozila iz otkupa (800 KM). Iz njih se računa preporuka i trošak držanja.
### 3. Dodajte vozila bez oglasa
Vozilo u pripremi ili bez profila: **Dodajte vozilo** ili **Uvoz iz Excela** (do 5.000). Cifrina cijena za njih dolazi s krive vrijednosti modela, a dani se broje od datuma prijema.
## Pregled lagera
**Za danas** je kratka lista: vozila za sniženje (s uštedom troška držanja), ona ispod tržišta i spora. Ispod su cijena prema tržištu i dani na prodaji na jednoj mapi, starost lagera s troškom držanja, marke i prodaje u 90 dana.
## Vozila i preporuke
**Vozila** je cijela tabela: cijena, Cifra, cijena prema tržištu, dani na prodaji, šansa prodaje za 30 dana i očekivano vrijeme, uz filtere **Sniziti**, **Sporo**, **Može više** i **Dobro**.
| Preporuka | Kada |
| --- | --- |
| **Sniziti** | Vozilo stoji duže od ¾ ciljnih dana (ili je 15%+ iznad tržišta) i skuplje je od tržišta: snižavanje do tržišta, najviše 12%, nikad ispod nabavke i pripreme. |
| **Sporo** | Prešlo je cilj, a cijena je već tržišna: nije problem cijene. |
| **Može više** | 8% ili više ispod tržišta. |
| **Dobro** | Ostalo: zadržite cijenu. |
### Jedno vozilo
Stranica vozila daje preporuku s krivuljama šanse prodaje, šta bi uradila druga cijena (dani, šansa za 30 dana, trošak držanja, marža), slična vozila u prodaji, vaše podatke (nabavna cijena, priprema, datum prijema, oznaka) i trošak po danu. **Provjeri historiju** otvara [Provjeru](https://www.cifra.ba/docs/enterprise/check) tog oglasa.
## Prilike za nabavku
Oglasi drugih prodavaca 8–30% ispod Cifrine cijene, po zadanom u onome što vi prodajete (vaši modeli i godišta iz 12 mjeseci oglasa), s procjenom za koliko biste prodali po vašoj uobičajenoj marži, minus priprema i držanje. 20% i više ispod je označeno za provjeru.
## Konkurencija
Trgovci s većinom vozila u vašim regijama: lager, prodaja u 4 sedmice, dani na prodaji, cijene prema tržištu, snižavanja i koliko drže vaše modele, s vašim redom za poređenje.
> **Napomena:** Nazivi trgovaca na slikama su izmišljeni. Na platformi vidite stvarne nazive salona iz njihovih javnih oglasa.
## Česta pitanja
**Kako znate da je vozilo prodano?**
Oglas je skinut, a isto vozilo se nije vratilo na tržište. Portali skidaju i istekle oglase, pa je to procjena, ne knjiga prodaje; vozilo koje sami označite kao **Prodano** računa se tačno.
**Ponovo smo oglasili vozilo. Gubimo li podatke?**
Ne. Isto vozilo prepoznajemo i u novom oglasu, a vaša nabavna cijena, priprema i napomena ga prate.
---
# Rezidual
Koliko će vozilo vrijediti na kraju lizinga ili kredita, iz domaćeg tržišta, s rasponom i preporučenim ostatkom vrijednosti.
## Pregled
Rezidual računa vrijednost na kraju ugovora iz krivih gubitka vrijednosti koje Cifra uči na oglasima u BiH. Krive izlaze jednom mjesečno kao izdanje (npr. **Izdanje oktobar 2026**) i više se ne mijenjaju, pa se svaka kalkulacija može ponoviti.
## Kalkulator
### 1. Vozilo
Vrsta, marka, model, novo ili polovno (godište i kilometraža danas) i gorivo.
### 2. Ugovor
Vrijednost danas (nabavna ili današnja; prazno je tipična tržišna cijena modela), trajanje (6–84 mjeseca) i kilometri godišnje. Ispod, sklopljeno: tržišni scenarij, sigurnost preporučenog ostatka (50–90%) i finansiranje (iznos, kamata, balon).
### 3. Odgovor
Vrijednost na kraju, raspon od 80% na skali i **Preporučeni ostatak vrijednosti**: vrijednost koju vozilo dostiže s izabranom sigurnošću, balon koji kompanija može potpisati.
Ispod su vrijednost mjesec po mjesec sa rasponima od 50% i 80%, tablica trajanja × kilometara godišnje (klik na polje ga izračuna), šta pomjera broj u KM, trošak držanja po godini, mjesecu i kilometru, mjesto modela u klasi, oglasi iza krive i finansiranje: rata, učešće, LTV i šansa da vozilo na kraju vrijedi manje od balona.
Unos je u adresi stranice, pa link pokazuje istu kalkulaciju. **Sačuvaj kalkulaciju** je sprema za tim, **Prati vozilo** ga dodaje u praćena vozila s kilometražom i finansiranjem, a PDF ide preko štampe.
## Tablice i poređenje
- **Tablice**: svaki model s vlastitom krivom, koliko vrijednosti zadrži nakon 12–60 mjeseci od novog ili 1, 3, 5 ili 8 godina, pri 10–30.000 km godišnje, uz pouzdanost i promjenu od prethodnog izdanja. Excel.
- **Poređenje**: do četiri modela jedan pored drugog, krive kroz sedam godina prema tržištu i tabela s najboljim označenim.
## Portfolio i kalkulacije
**Portfolio** nosi vaša praćena vozila naprijed po krivoj svakog modela. Za finansirana vozila s rokom i balonom: prognoza na dospijeću, šansa manjka i očekivani manjak, dospijeća po polugodištima i test stresa (tržište −10, −20 ili −30%). **Kalkulacije** su sačuvane kalkulacije tima, s izdanjem koje su koristile i šta današnje izdanje kaže pored.
## Česta pitanja
**Zašto nema mog modela u tablicama?**
Model ima vlastitu krivu tek kad ima dovoljno oglasa; modeli s manje od 60 oglasa su skriveni dok ih ne zatražite. Prikazuje se i samo za starosti koje njegovi oglasi pokrivaju.
**Šta se desi sa sačuvanom kalkulacijom kad izađe novo izdanje?**
Ostaje na svom izdanju. Kad je otvorite, vidite i šta bi današnje izdanje reklo.
---
# Radar
Tržište BiH za bilo koji segment, svaki dan: cijene, ponuda i potražnja, brzina prodaje, karta po općinama, trgovci i oglasi.
[Video: Radar: odabir segmenta Golf 7 2015–2018, indeks cijena i karta tržišta po općinama](https://www.cifra.ba/docs/enterprise/radar.mp4)
## Pregled
Radar je slika tržišta iz svih oglasa na OLX.ba, AutoBum.ba i AutoPlac.ba, obnovljena svako jutro. Segment birate filterima: vrsta vozila, marka, modeli, godište, cijena, općina ili regija, a pod **Više filtera** kilometraža, gorivo, mjenjač, karoserija i privatni ili trgovci. Filteri su u adresi stranice, pa link kolegi pokazuje isto.
### Segmenti tima
**Sačuvaj segment** sprema filtere pod imenom, za cijelu kompaniju. Sačuvani segmenti su kartice na vrhu, s pulsom tržišta, i u meniju **Segmenti**.
## Kartice
| Kartica | Šta pokazuje |
| --- | --- |
| **Pregled** | Tipična cijena, ponuda, prodaja, koliko brzo se prodaje pola vozila, zaliha; Cifra indeks cijena; ponuda i potražnja; krivulja prodaje; cijena i brzina; za jedan model cijene po godištu i prema kilometraži. |
| **Modeli i segmenti** | Segment po modelu, marki, gorivu, karoseriji, mjenjaču, starosti, cijeni ili prodavcu, sortirano po bilo kojem broju. |
| **Karta** | BiH po općinama: cijene prema prosjeku BiH, ponuda, prodaja ili brzina, s najskupljim i najjeftinijim. |
| **Trgovci** | Udio trgovaca, njihove cijene prema privatnima, brzina i starost lagera, pa svaki trgovac. |
| **Oglasi** | Vozila na prodaji s Cifrinom cijenom svakog, razlikom, danima na prodaji, snižavanjima i prodavcem. |
| **Poređenje** | Do četiri segmenta jedan pored drugog: svaki broj, indeksi i krivulje prodaje. |
| **Metodologija** | Pokrivenost, tačnost, svježina i šta tačno znači svaki broj. |
## Šta znače brojevi
- **Prodano** je oglas koji je skinut dok smo ga pratili, a vozilo se nije vratilo. Portali skidaju i istekle oglase; povlačenje i prodaja se ne mogu razlikovati, i Metodologija to kaže.
- **Pola se proda za** računa se iz svih vozila na tržištu, i onih još neprodanih, i prikazuje se od 25 prodaja.
- **Cifra indeks cijena** prati cijenu istih vozila kroz vrijeme, s rasponom od 95%; mjesec s premalo oglasa je prazan.
- Broj iz premalo oglasa je „—”, nikad procjena.
Svaka tabela, indeks i tokovi idu u Excel, a **Štampaj** štampa karticu bez kontrola.
> **Napomena:** Nazivi trgovaca na slikama su izmišljeni. Na platformi vidite stvarne nazive salona iz javnih oglasa.
## Česta pitanja
**Koliko su svježi podaci?**
Radar se gradi svako jutro iz oglasa prethodnog dana. Na kartici piše datum podataka, npr. „Podaci od 19. okt 2026”.
**Mogu li Radar dobiti u svoj sistem?**
Svaka tabela i indeks idu u Excel. Ako vam tržišni podaci trebaju direktno u vašem sistemu, javite nam se preko **Pomoć i podrška**.
---
# Vaš model
Cifrin model naučen na vašim prodajnim, otkupnim, traženim ili procijenjenim cijenama, za procjene kakve vaša kompanija zaista postiže.
## Pregled
Tržišna vrijednost je tražena cijena kod privatnog prodavca. Vaša kompanija prodaje, kupuje ili procjenjuje po svojim cijenama. **Vaš model** uči razliku između vaših cijena i Cifrinog tržišnog modela, po marki, starosti, kilometraži, motoru i gradu, i zatim procjenjuje vaša vozila tako, s tržišnom vrijednošću uvijek pored.
Vaš model je dio Enterprise ugovora. Svi u kompaniji vide stranice, a podatke, učenje i uključivanje rade vlasnici i administratori.
## Vodič
### 1. Dodajte podatke
U **Vaš model** odaberite **Dodajte podatke**: koje su cijene u tabeli (**Prodajne cijene**, **Otkupne cijene**, **Tražene cijene**, **Procijenjene vrijednosti**), vrsta vozila i Excel ili CSV fajl, do 150.000 redova. Fajl se čita u pregledniku.
### 2. Provjerite kolone
Svaka kolona s primjerima i poljem koje smo prepoznali po nazivu („Prodajna cijena (KM)”, „Snaga (KS)”), valuta (KM ili EUR) i datum za sve redove ako ga fajl nema.
### 3. Provjerite redove
Prije čuvanja vidite koliko redova model može koristiti, šta je izostavljeno i zašto (s brojem reda iz vašeg fajla) i koliko redova ima dodatne podatke. Tek **Sačuvajte podatke** ih sprema.
### 4. Trenirajte model
**Trenirajte model**: naziv, podaci i koliko se model smije udaljiti od standardnog (**Oprezno**, **Uravnoteženo** ili **Snažno**). **Prati tržište** ga nauči ponovo na svakom novom tržišnom modelu. Učenje traje oko minut i vidi se uživo.
### 5. Pročitajte rezultat
Presuda u rečenici, greška vašeg modela pored standardnog na vašim vozilima koja nije vidio, koliko koji model promaši (dva histograma), koliko se vaše cijene razlikuju od tržišnih i svaka provjera.
### 6. Uključite ga
Verzija koja prođe sve provjere može se **Uključiti**. Cifra prvo dokaže da je može služiti, pa tek onda prebacuje. Od tada nove procjene kompanije, u aplikaciji i preko API-ja, radi vaš model.
## Provjere
Model može u upotrebu samo ako prođe svaku:
| Provjera | Šta znači |
| --- | --- |
| **Dovoljno podataka** | Najmanje 200 upotrebljivih redova. |
| **Vaše cijene se razlikuju od tržišnih** | Model je našao pravilnosti u razlici; ako ih nema, standardni model vas već dobro opisuje. |
| **Tačniji od standardnog modela** | Manja greška na vašim vozilima, i to izvan svake slučajnosti. |
| **Raspon nije preuzak / preširok** | Stvarna cijena je u rasponu od 80% u 76–84% slučajeva. |
| **Razlika prema tržištu je uvjerljiva** | Tipično vozilo pomjera najviše 30%; više je obično pogrešna valuta ili kolona. |
| **Nema ekstremnih pomaka** | Ni najpogođenijih 1% vozila ne pomjera više od 60%. |
## U upotrebi
Model u upotrebi ima oznaku **U upotrebi**. Izvještaj tada pokazuje **Prodajna cijena po vašem modelu** (ili otkupna, tražena, procijenjena), a tržišnu vrijednost ispod. Isključujete ga ili vraćate raniju verziju jednim klikom.
## Vaši podaci
Podaci služe samo modelu vaše kompanije: ne ulaze u Cifrin tržišni model, ne vidi ih nijedna druga kompanija i brišu se čim obrišete skup podataka. Model zadrži ono što je naučio, ne redove.
| Ograničenje | |
| --- | --- |
| Skupova podataka | 20 |
| Modela | 10 |
| Redova po učitavanju | 150.000 (4 MB sažeto) |
| Treninga dnevno | 30 |
## Česta pitanja
**Model nije prošao provjere. Šta sada?**
Pogledajte koja provjera nije prošla. Najčešće: premalo redova, cijene koje se ne razlikuju od tržišnih (tada vam standardni model već odgovara), pogrešna valuta ili kolona s pogrešnim iznosom. Dodajte podatke (svako dodavanje je nova verzija) i trenirajte ponovo.
**Mijenja li vaš model već napravljene procjene?**
Ne. Mijenja samo procjene napravljene nakon što ga uključite.
**Koristi li ga i praćenje vozila?**
Ne. Praćena vozila, slična vozila i alarmi uvijek rade s tržišnim modelom, da budu uporedivi s tržištem.
---
# Razvoj
API ključevi, potrošnja, log zahtjeva i webhookovi vašeg sistema, sve na platformi.
## Pregled
**Razvoj** je mjesto za integraciju s [Cifra API-jem](https://www.cifra.ba/docs/api): ključevi, potrošnja, zahtjevi i webhookovi. Tu su i [Widgeti](https://www.cifra.ba/docs/enterprise/widgets), vaša vozila na vašoj stranici. Vide ga i mijenjaju vlasnici i administratori. API je dio Business (10.000 jedinica mjesečno, dijeljeno između produkcijskih ključeva) i Enterprise plana.
Ugovor je na vrhu **API ključevi** i **Upotreba**: potrošnja produkcijskih jedinica ovog mjeseca prema kvoti, tempo do kraja mjeseca i brzina (zahtjeva u minuti).
## Novi ključ
### 1. Napravite ključ
**Novi ključ**: naziv, okruženje (**Test**: fiksni primjeri, bez troška; **Produkcija**: prave procjene, troše jedinice) i usluge (**Procjene**, **Praćenje vozila**, **Provjera vozila**). Pod **Ograničenja i sigurnost** su mjesečni limit jedinica, dozvoljene IP adrese (CIDR), datum isteka i napomena.
### 2. Sačuvajte ga
Ključ se prikazuje samo jednom, uz cURL, JavaScript i Python primjer za probu. Panel se ne zatvara dok ne potvrdite **Ključ je sačuvan na sigurnom**.
## Jedan ključ
Stranica ključa ima **Pregled** (mjesec prema limitu, 30 dana zahtjeva, jedinica i grešaka, po usluzi, najčešće greške i zadnji zahtjevi), **Postavke** i **Historija**. Radnje:
- **Zamijeni**: novi token s istim postavkama, a stari radi još neko vrijeme (odmah, 1 h, 24 h ili 7 dana).
- **Pauziraj**: ključ dobija `403 key_paused` dok ga ne nastavite.
- **Opozovi**: zauvijek. Ključ korišten u zadnjoj sedmici traži da upišete njegov naziv.
## Upotreba
Jedinice, zahtjevi, stopa grešaka i vrijeme odgovora za ovaj ili prošli mjesec, ili 7, 30 i 90 dana; po danu i usluzi, po endpointu i po ključu, i greške koje su dobili vaši sistemi, svaka s linkom na zahtjeve. **CSV za Excel**. Pod **Obavijesti emailom** su pragovi potrošnje (50–100%) i dodatne adrese za obavijesti API-ja.
## Zahtjevi
Log svih zahtjeva vaših ključeva u zadnjih 30 dana, najnoviji prvi, s filterima po ishodu, periodu, ključu, pozivu i ID-u zahtjeva ili šifri greške, i **Uživo**. Zahtjev se otvara sa strane: greška riječima, ID zahtjeva, ključ, trajanje, jedinice, adresa i klijent, tijelo odbijenog zahtjeva i cURL za ponavljanje.
## Webhookovi
Webhookovi javljaju vašem sistemu čim se nešto desi: alarm za praćeno vozilo, dnevni izvještaj, nova procjena, provjera ili odluka, završena masovna lista, potrošnja kvote. Svaki događaj je potpisan.
### 1. Dodajte adresu
**Dodaj adresu**: URL (https, javna adresa, provjerena dok kucate), opis, okruženje i svi ili odabrani događaji.
### 2. Provjerite potpis
Dobijate tajnu za potpis i kod za provjeru zaglavlja `Cifra-Signature` u Node.js, Pythonu, PHP-u i C#. Zatim **Pošalji test** šalje primjer bilo kojeg događaja.
Stranica adrese ima zdravlje (uspješnost i vrijeme odgovora za 7 dana, isporuke po danu), **Isporuke** sa svakim pokušajem i odgovorom i **Pošalji ponovo**, **Postavke**, **Potpis** (otkrivanje i zamjena tajne, uz period u kojem potpisuju obje) i **Historija**. Neuspjela slanja ponavljamo oko dva dana; adresu koja tri dana ništa ne primi isključujemo i javljamo emailom.
Sve vrste događaja s primjerima su u **Događaji** i u [API referenci](https://www.cifra.ba/docs/api-reference/webhook-events).
## Česta pitanja
**Koliko ključeva možemo imati?**
Do 50, u testnom i produkcijskom okruženju zajedno.
**Troše li testni ključevi jedinice?**
Ne. Testni ključ provjerava zahtjeve kao pravi i vraća fiksne primjere. Vidi [Sandbox](https://www.cifra.ba/docs/api/sandbox).
**Ključ koji je napravila Cifra.**
Ključeve koje je izdao Cifrin tim vidite s autorom „Cifra”. Ponašaju se kao vaši, a pauza koju postavi Cifra ne može se skinuti ovdje.
**Gdje je tehnička dokumentacija?**
U [Cifra API](https://www.cifra.ba/docs/api) vodičima i [API referenci](https://www.cifra.ba/docs/api-reference), s primjerima u sedam jezika i **Isprobaj** za svaki endpoint.
---
# Widgeti
Vaša vozila na vašoj stranici: nezavisna ocjena tražene cijene, tržište i slična vozila, svako jutro ažurirano.
## Pregled
**Widgeti** (u odjeljku **Razvoj**) stavljaju Cifrinu procjenu na stranicu vašeg vozila, kao rezultate na sportskim portalima: jedno vozilo, više pogleda. Kupac uz vašu cijenu vidi nezavisnu ocjenu — **Odlična**, **Dobra**, **Fer**, **Povišena** ili **Visoka cijena** — s procentom, tržište, slična vozila u prodaji i vrijednost kroz vrijeme.
Svaki widget stoji na procjeni vaše kompanije: vozilo procijenite jednom (na platformi ili [kroz API](https://www.cifra.ba/docs/api/widgets)), objavite ga i zalijepite kod na stranicu. Cifra ga zatim procjenjuje ponovo svako jutro, a stranice samo čitaju gotov rezultat — javno se ništa ne računa i ne poziva API. Widgete imaju svi planovi: Team do 50 vozila, Business do 1.000 vozila, Enterprise po ugovoru. Objavljuju svi u timu; izgled i domene mijenjaju vlasnici i administratori.
## Ocjena cijene
Ocjena poredi vašu traženu cijenu s Cifrinom tržišnom vrijednošću i njenim realnim rasponom (80%):
| Ocjena | Kad |
| --- | --- |
| **Odlična cijena** | Cijena je ispod realnog raspona vrijednosti. |
| **Dobra cijena** | U rasponu, jasno ispod vrijednosti. |
| **Fer cijena** | Blizu vrijednosti, u pojasu fer cijene. |
| **Povišena cijena** | U rasponu, jasno iznad vrijednosti. |
| **Visoka cijena** | Iznad realnog raspona vrijednosti. |
Pojas fer cijene je 35% polovine raspona, najmanje 3% i najviše 8% vrijednosti: precizna procjena je stroga, a vozilo s malo podataka blaže. Cijena ispod 40% ili preko 250% vrijednosti se ne ocjenjuje (to je obično greška u unosu), a widget tada pokazuje samo vrijednost.
> **Napomena:** Widgeti uvijek koriste Cifrin standardni tržišni model, nikad **Vaš model**: model naučen na vašim cijenama ne bi bio nezavisan sudija vaših cijena. Boje ocjena su iste na svakoj stranici, da ih kupci čitaju jednako.
## Vrste widgeta
Za svako vozilo postoji osam widgeta, a uz njih **Cijene modela** za članke i vodiče. Stavite onaj koji vašoj stranici treba, ili više njih:
| Widget | Šta pokazuje | Gdje stoji |
| --- | --- | --- |
| **Ocjena cijene** (`badge`) | Oznaka uz cijenu: odlična, dobra, fer, povišena ili visoka — s procentom. | Uz cijenu u listi vozila i na stranici vozila |
| **Cijena i tržišna vrijednost** (`price`) | Cijena na skali tržišne vrijednosti, s ocjenom, rasponom i razlikom u KM. | Stranica vozila, odmah ispod cijene |
| **Tržište** (`market`) | Koliko sličnih je u prodaji, gdje je ova cijena među njima i koliko se brzo prodaju. | Stranica vozila, uz opis |
| **Slična vozila** (`comparables`) | Slična vozila u prodaji i kako ova ponuda stoji među njima — anonimno, bez linkova. | Stranica vozila, na dnu |
| **Vrijednost kroz vrijeme** (`forecast`) | Koliko će vozilo vrijediti za godinu, dvije i tri — za kupce koji računaju. | Stranica vozila, uz finansiranje ili lizing |
| **Šta čini cijenu** (`factors`) | Od čega se sastoji tržišna vrijednost: godište, kilometraža, motor, oprema. | Stranica vozila, uz tehničke podatke |
| **Kilometraža** (`mileage`) | Kilometraža naspram vozila istog modela i godišta, i šta znači za cijenu. | Stranica vozila, uz kilometražu |
| **Cifra izvještaj** (`report`) | Sve na jednom mjestu, u karticama: cijena, tržište, slična vozila, vrijednost kroz vrijeme. | Stranica vozila, kao zaseban odjeljak |
| **Cijene modela** (`model`) | Cijene jednog modela po godištu, ponuda i trend — za blogove, portale i vodiče. | Članci, vodiči za kupce, stranice modela |
## Objava vozila
**Objavite vozilo** nudi tri puta. Svako objavljeno vozilo dobija sve widgete i stranicu za kupce.
### 1. Iz procjene
Odaberite izvještaj vašeg tima i upišite traženu cijenu (izvještaj prodaje je već ima). Isto radi **Objavi na web** u radnjama svakog izvještaja. Procjena se ne troši ponovo.
### 2. Link oglasa
Zalijepite link vašeg oglasa s olx.ba, autobum.ba ili autoplac.ba. Cifra pročita oglas, procijeni vozilo (jedna procjena plana) i objavi ga s cijenom iz oglasa; cijena zatim prati oglas, a kad oglas nestane, widget kaže **Prodano**.
### 3. Iz lagera
Ako imate [Lager](https://www.cifra.ba/docs/enterprise/inventory), odaberite vozila iz povezanih profila trgovca i vlastitog unosa i objavite ih odjednom, s napretkom za svako. Svako vozilo je jedna procjena plana; objava staje na limitu plana.
## Vozilo
Klik na vozilo otvara njegov studio: lijevo svi widgeti tačno kako ih stranica prikazuje, na svijetloj ili tamnoj stranici, za računar ili telefon; desno cijena, izgled ovog koda, vozilo i procjena, i ko gleda.
- **Cijena**: ocjena se mijenja dok kucate, prije čuvanja. **Cijena za svaku ocjenu** pokazuje raspon u KM za svaku od pet ocjena; klik na ocjenu postavi cijenu na nju.
- **Prati cijenu iz oglasa** (vozila objavljena s linkom): nova cijena u oglasu stiže na widget sljedeće jutro.
- **Vozilo i procjena**: naziv na widgetu, vaša interna oznaka i kilometraža — novo očitanje se odmah procjenjuje ponovo.
- **Link za kupce**, **Kartica za vozilo**, **Pauziraj** i uklanjanje su gore desno. Uklonjeno vozilo nestaje sa svih stranica; procjena ostaje u historiji.
### Kod za ugradnju
Ispod pregleda je kod za odabrani widget. Zalijepite ga na stranicu vozila, gdje želite da se widget prikaže; radi u svakom sistemu (WordPress blok „Custom HTML”, Wix, Shopify, vlastiti sajt).
**Skripta**
```html
```
- **Skripta** (preporučeno) sama prilagodi visinu i učitava widget tek kad je blizu ekrana. Dovoljno ju je dodati jednom po stranici, za sve widgete na njoj — i za one koje stranica doda kasnije.
- **iframe** je za sisteme koji ne dozvoljavaju skripte; visina je fiksna.
- **Link za kupce** vodi na stranicu vozila na cifra.ba, za Viber, WhatsApp i email.
**Izgled ovog koda** mijenja samo taj kod; u kod ide samo ono što se razlikuje od postavki kompanije, pa promjena u **Izgled i domene** stiže na sve ostale. Isto možete napisati ručno, kao atribute:
| Atribut | Vrijednosti |
| --- | --- |
| `data-cifra-widget` | `badge`, `price`, `market`, `comparables`, `forecast`, `factors`, `mileage`, `report`. |
| `data-id` | Javni kod vozila (u studiju i u kodu). |
| `data-theme` | `light`, `dark` ili `auto` (prati posjetioca). |
| `data-accent` | Boja detalja, heksadecimalno, npr. `0f766e`. |
| `data-radius` | `sharp`, `soft` ili `round`. |
| `data-lang` | `bs` ili `en`. |
| `data-frame` | `0`: bez okvira i pozadine, widget se stapa sa stranicom. |
| `data-show-price` | `0`: samo ocjena i procenat, bez iznosa. |
| `data-eur` | `1`: iznosi i u eurima, za kupce iz dijaspore. |
| `data-cobrand` | `1`: vaš logo i naziv u zaglavlju widgeta. |
| `data-variant` | Za `badge`: `pill` (oznaka) ili `card` (kartica). |
## Stranica za kupce i kartica
Svako vozilo ima stranicu na cifra.ba (**Link za kupce**) pod vašim nazivom: ocjena cijene i šta svaka ocjena znači za to vozilo, tržište, slična vozila, vrijednost kroz vrijeme, šta čini cijenu i kilometraža — za poruke kupcima i oglase bez vlastite stranice. Posjete se broje u **Statistika**. **Kartica za vozilo** je A5 ili A4 kartica za staklo vozila: cijena, ocjena, Cifrina vrijednost i QR kod do te stranice.
## Svako jutro
- Vozilo se procijeni ponovo s današnjim tržištem, a ocjena se preračuna. Ponovna procjena je besplatna; novu kilometražu upišite u studiju.
- Vozilo objavljeno s linkom prati oglas: nova cijena, a kad oglas nestane, **Prodano** — widget to kaže kupcu, a u studiju ga vraćate s **Vrati u prodaju**.
- Izmjena na platformi (cijena, pauza, izgled) stiže na stranice za najviše 5 minuta.
## Statistika
**Statistika** pokazuje prikaze po danu, otvaranja izvještaja (klik na oznaku ili link u widgetu), stopu otvaranja i stranice na kojima su widgeti, za 7, 30 ili 90 dana; po widgetu, stranici i vozilu, s **CSV za Excel**. Widget se broji kad ga posjetilac zaista vidi (pola widgeta na ekranu barem sekundu), ne kad se stranica samo učita, i bez kolačića.
## Izgled i domene
**Izgled i domene** su postavke koje prate svi widgeti kompanije, s pregledom uživo: tema (svijetla, tamna ili auto), boja detalja, uglovi, jezik (bosanski ili engleski), okvir i pozadina, vaš logo i naziv, prikaz tražene cijene i iznosi u eurima. Ocjena uvijek ima svoje boje.
Pod **Domene** su stranice na kojima se widgeti smiju prikazati (domena važi i za poddomene). Prazno znači bilo gdje; s domenama preglednik odbija widget na svakoj drugoj stranici. **Javni ključ** je za widget **Cijene modela**, da prikaže vaš izgled.
## Cijene modela
Widget **Cijene modela** nije vezan za vaše vozilo: pokazuje tipičnu cijenu modela u BiH i cijene po godištu, za članke, vodiče za kupce i stranice modela. U **Galerija** odaberite model, izgled i kopirajte kod; ne troši procjene ni mjesta u planu.
## Česta pitanja
**Troše li widgeti procjene?**
Objava iz postojeće procjene ne troši ništa. Link oglasa i Lager prave novu procjenu (jednu po vozilu). Jutarnje procjene, prikazi i stranica za kupce su besplatni; plan ograničava samo broj objavljenih vozila.
**Usporavaju li widgeti našu stranicu?**
Ne. Widget je mala HTML stranica bez biblioteka, s cifra.ba iz keša, učitava se tek kad je blizu ekrana i ne postavlja kolačiće.
**Može li widget koristiti naš model?**
Ne. Kupac vjeruje ocjeni zato što je nezavisna, pa widgeti uvijek koriste Cifrin standardni model. Vaš model ostaje za vaše procjene na platformi.
**Vozilo je prodano. Šta da radim?**
Ako je objavljeno s linkom oglasa, Cifra to vidi sama kad oglas nestane. Inače ga uklonite. Prodana i uklonjena vozila ne zauzimaju mjesto u planu; pauzirana zauzimaju.
**Zašto se widget ne prikazuje?**
Provjerite da je vozilo **Objavljeno** (ne pauzirano) i, ako ste upisali domene, da je stranica na jednoj od njih. Pauziran ili uklonjen widget ne ostavlja prazno mjesto: skripta skupi njegov prostor.
**Vidi li se ko je šta objavio?**
Da. Objave, izmjene, pauze, uklanjanja, promjene izgleda i izvozi statistike su u [dnevniku aktivnosti](https://www.cifra.ba/docs/enterprise/team).
---
# Cifra API
Tržišna vrijednost vozila, provjera oglasa i praćenje portfelja u vašem sistemu: REST, JSON, jedan ključ.
Cifra API daje vašem sistemu isto što i Cifra: procjenu automobila, motocikla ili kamiona s rasponom i obračunom, historiju vozila kroz oglase sa signalima rizika, portfelj koji se procjenjuje svako jutro, s alarmima i webhookovima, i widgete s ocjenom vaše cijene za vašu stranicu. Koriste ga lizing kuće, banke, osiguranja, saloni i oglasnici.
**Osnovna adresa**
```text
https://api.cifra.ba
```
## Šta možete
- [Procjena vozila](https://www.cifra.ba/docs/api-reference/valuations/create): Vrijednost, raspon od 80%, ocjena, obračun po faktorima, prognoza i slična vozila.
- [Masovna procjena](https://www.cifra.ba/docs/api/batch): Stotine vozila u jednom pozivu; svako uspije ili padne samo za sebe.
- [Provjera vozila](https://www.cifra.ba/docs/api/vehicle-history): Svi oglasi istog vozila i signali: vraćena kilometraža, tuđe fotografije, lizing.
- [Praćenje i alarmi](https://www.cifra.ba/docs/api/watchlist): Portfelj procijenjen svako jutro; alarmi za pad vrijednosti, ciljne cijene i LTV.
- [Webhookovi](https://www.cifra.ba/docs/api/webhooks): Alarmi, dnevni izvještaj i rad tima na platformi, potpisani i s ponovnim pokušajima.
- [Widgeti](https://www.cifra.ba/docs/api/widgets): Vaše procjene na vašoj stranici: ocjena tražene cijene, tržište i slična vozila.
- [Vaš model](https://www.cifra.ba/docs/api/company-models): Procjene naučene na vašim prodajama i otkupima, uz tržišnu vrijednost.
## Prvi koraci
1. Napravite testni ključ na platformi ([Razvoj → API ključevi](https://enterprise.cifra.ba/developers)).
2. Pošaljite prvu procjenu — [Brzi početak](https://www.cifra.ba/docs/api/quickstart) vas vodi kroz to za pet minuta.
3. Pročitajte [Tržišna vrijednost](https://www.cifra.ba/docs/api/valuations) da znate šta tačno broj znači.
4. Prije produkcije prođite [kontrolnu listu](https://www.cifra.ba/docs/api/go-live).
## Za alate i AI asistente
- OpenAPI 3.1: [/docs/openapi.json](https://www.cifra.ba/docs/openapi.json) — za Postman, Insomniju ili generisanje klijenta.
- Cijela dokumentacija kao tekst za AI asistente: [/docs/llms-full.txt](https://www.cifra.ba/docs/llms-full.txt), pregled: [/docs/llms.txt](https://www.cifra.ba/docs/llms.txt).
- Svaka stranica ima „Kopiraj stranicu” (Markdown) gore desno.
---
# Brzi početak
Od ključa do prve procjene za pet minuta.
### 1. Napravite ključ
Na platformi otvorite [Razvoj → API ključevi](https://enterprise.cifra.ba/developers) i napravite **testni** ključ (`cfr_test_…`). Testni ključ provjerava zahtjeve kao pravi, vraća fiksne primjer-vrijednosti i ništa ne naplaćuje.
> **Napomena:** API je dio Business i Enterprise plana. Nemate nalog? [Isprobajte Business 7 dana](https://www.cifra.ba/api#cijene) ili nam [pišite](https://www.cifra.ba/kontakt).
### 2. Sačuvajte ključ
Ključ se prikazuje samo jednom. Držite ga u varijabli okruženja ili trezoru tajni, nikad u kodu:
```bash
export CIFRA_API_KEY="cfr_test_…"
```
### 3. Pošaljite procjenu
Obavezni su samo marka, model, godište i kilometraža. Šifre marki i modela su u [šifarniku](https://www.cifra.ba/docs/api/vehicle-types).
```bash
curl -X POST "https://api.cifra.ba/v1/valuations" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"make": "škoda",
"model": "octavia",
"year": 2015,
"mileage_km": 210000,
"include": []
}'
```
```python
import os
import requests
response = requests.post(
"https://api.cifra.ba/v1/valuations",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
json={
"make": "škoda",
"model": "octavia",
"year": 2015,
"mileage_km": 210000,
"include": [],
},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
### 4. Pročitajte odgovor
`market_value.point` je tržišna vrijednost u KM, `low`–`high` raspon u kojem je cijena s vjerovatnoćom od 80%, a `confidence_grade` koliko je raspon uzak. `warnings` kaže šta bi poboljšalo procjenu:
```json
{
"id": "val_gcizgqyFRuEGurraw8v6",
"object": "valuation",
"created_at": "2026-10-18T21:57:27.584Z",
"model_version": "car-20261017-1",
"valued_by": {
"kind": "standard",
"version": "car-20261017-1"
},
"vehicle": {
"vehicle_type": "car",
"make": "škoda",
"make_name": "Škoda",
"model": "octavia",
"model_name": "Octavia",
"year": 2015,
"mileage_km": 210000
},
"as_of": "2026-10-18",
"market_value": {
"currency": "BAM",
"point": 15600,
"low": 12370,
"high": 19690,
"confidence_grade": "B",
"range_probability": 0.8,
"definition": "Asking price at which a comparable vehicle is listed by a private seller on the valuation date; the range holds the price with 80% probability."
},
"sale_price": {
"status": "unavailable",
"detail": "Needs transaction data; planned as an experimental output."
},
"time_to_sell": {
"status": "unavailable",
"detail": "Needs a few months of market exit data; planned."
},
"warnings": [
{
"code": "partial_inputs",
"message": "Add power, engine size, fuel and transmission for a tighter range."
}
]
}
```
### 5. Pređite na produkcijski ključ
Kad integracija radi, napravite live ključ (`cfr_live_…`) samo s pristupom koji treba i, ako zovete sa poznatih servera, s listom dozvoljenih IP adresa. Live procjene se naplaćuju po jedinici.
## Dalje
- [Potpuniji unos](https://www.cifra.ba/docs/api/valuations): Snaga, zapremina, gorivo i mjenjač sužavaju raspon.
- [Obračun i prognoza](https://www.cifra.ba/docs/api/explanation): Zašto baš ta cijena, i koliko će vrijediti za 3 godine.
- [Greške](https://www.cifra.ba/docs/api/errors): Stabilne šifre, `request_id` i kad ponoviti zahtjev.
- [API referenca](https://www.cifra.ba/docs/api-reference): Svaki endpoint, polje i primjer.
---
# Autentifikacija
Ključevi, okruženja, pristupi, IP adrese i zamjena ključa bez prekida.
Svaki zahtjev nosi ključ u zaglavlju `Authorization`:
```http
Authorization: Bearer cfr_live_6fN0cA2kQ9xR7vT1bL4mZ8pW3yH5gD0e
```
Ako vaš alat ne može postaviti `Authorization`, pošaljite isti ključ u `x-api-key`.
## Okruženja
| Ključ | Okruženje | Šta vraća | Naplata |
| --- | --- | --- | --- |
| `cfr_live_…` | Produkcija | Prave procjene, prave provjere | Po jedinici |
| `cfr_test_…` | Sandbox | Prava provjera zahtjeva, fiksne vrijednosti | Besplatno |
Okruženja su potpuno odvojena: test ključ ne vidi procjene, praćena vozila ni webhookove live ključeva, i obrnuto. Više u [Sandbox](https://www.cifra.ba/docs/api/sandbox).
## Pristup (scope)
Ključ može samo ono što mu dozvolite. Dajte svakom sistemu najmanji pristup koji treba.
| Pristup | Šta otvara |
| --- | --- |
| `valuations` | Procjene (jedna, masovna, čitanje, prodajna cijena) i šifarnik. |
| `watchlist` | Praćena vozila, dnevni izvještaj, alarmi i webhook adrese. |
| `listings` | Historija vozila i signali Provjere, i šifarnik. |
| `widgets` | Objava procjena kao widgeta na vašoj stranici (samo produkcijski ključ). |
Zahtjev bez potrebnog pristupa vraća `403 insufficient_scope`.
## Zaštita ključa
| Postavka | Šta radi | Greška |
| --- | --- | --- |
| Dozvoljene IP adrese | Ključ radi samo s navedenih adresa ili CIDR raspona (do 50). | `403 ip_not_allowed` |
| Mjesečni limit | Ključ troši najviše toliko jedinica mjesečno, i kad ugovor ima više. | `429 key_limit_reached` |
| Datum isteka | Ključ prestaje raditi tog dana. | `401 token_expired` |
| Pauza | Privremeno zaustavlja ključ; nastavlja se jednim klikom. | `403 key_paused` |
Sve se mijenja na platformi bez novog ključa; API vidi promjenu za najviše 30 sekundi.
## Zamjena ključa bez prekida
### 1. Zamijenite ključ na platformi
U Razvoj → API ključevi odaberite **Zamijeni ključ**. Dobijate novi ključ s istim pristupom i postavkama, a stari radi još 1 sat, 24 sata ili 7 dana — vi birate.
### 2. Postavite novi ključ
Uvedite novi ključ u svoje servere. Zahtjevi sa starog i novog ključa vide se odvojeno u logu zahtjeva.
### 3. Pustite stari da istekne
Kad stari ključ više nema zahtjeva, opozovite ga ili ga pustite da istekne sam.
> **Ako ključ procuri:** Procuren ključ odmah opozovite (ne pauzirajte): opozvan ključ vraća `401 invalid_token` i ne može se vratiti.
## Ključ ne ide u preglednik
Ključ je tajna vaše kompanije: zovite API sa svog servera, nikad iz mobilne aplikacije ili JavaScripta u pregledniku. Jedini izuzetak je „Isprobaj” u ovoj dokumentaciji: šalje ključ samo direktno na `api.cifra.ba`, a pamti ga najduže do zatvaranja kartice, i to samo ako to izaberete. Za isprobavanje koristite testni ključ.
---
# Sandbox
Testni ključevi: prava provjera zahtjeva, fiksni odgovori, bez naplate.
Sandbox je za razvoj i automatske testove. Testni ključ (`cfr_test_…`) prolazi kroz istu provjeru kao live: neispravno polje, nepoznata marka ili prevelika lista vraćaju istu grešku kao u produkciji. Ispravan zahtjev dobija **fiksnu primjer-vrijednost** i `"sandbox": true`.
## Šta se razlikuje
| | Live | Sandbox |
| --- | --- | --- |
| Provjera zahtjeva | Da | Da, ista |
| Procjena | Model | Fiksna: 24.350 KM (22.650–26.050) |
| Naplata | Po jedinici | Ništa |
| Limit | Po planu | 60 zahtjeva u minuti, 10 praćenih vozila, 10 vozila u listi |
| Podaci | Vaši live podaci | Odvojeni; test ključ ne vidi live i obrnuto |
| Webhookovi | `livemode: true` | `livemode: false`, adrese posebno za test |
> **Savjet:** Jedan scenarij vrijedi testirati namjerno: pošaljite nepoznatu marku i provjerite da vaš sistem pokaže korisniku smislenu poruku (`422 unknown_make`, polje u `field`).
## Prelazak u produkciju
Promijenite samo ključ. Adrese, zahtjevi i odgovori su isti; prije toga prođite [kontrolnu listu](https://www.cifra.ba/docs/api/go-live).
---
# 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).
```js
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`.
---
# Limiti i kvote
Zahtjevi u minuti, jedinice u mjesecu, veličina liste i kako ih poštovati.
| Plan | Cijena | Zahtjeva u minuti | Jedinica mjesečno | Vozila u listi | Praćenih vozila |
| --- | --- | --- | --- | --- | --- |
| Sandbox | Besplatno (uz svaki nalog s API pristupom) | 60 / min | Bez naplate | 10 | 10 |
| Business | 500 KM (mjesečno, uz cijelu platformu) | 120 / min | 10.000 jedinica | 100 | 1.000 |
| Enterprise | Po dogovoru (ugovor, SLA i vaš model) | Po ugovoru | Po ugovoru | Do 1.000 | Po ugovoru |
## Zahtjevi u minuti
Limit važi u kliznom prozoru od 60 sekundi. Svi live ključevi kompanije s ugovorom dijele isti limit, pa i više ključeva ne daje više zahtjeva. Svaki odgovor kaže gdje ste:
| Zaglavlje | Značenje |
| --- | --- |
| `x-request-id` | Oznaka zahtjeva. Pošaljite svoju (`x-request-id`, 8–64 znaka) da je pratite kroz svoje logove. |
| `x-ratelimit-limit` | Zahtjeva u minuti koje plan dozvoljava. |
| `x-ratelimit-remaining` | Koliko ih je ostalo u tekućem prozoru. |
| `x-ratelimit-reset` | Sekundi do novog prozora. |
| `x-quota-remaining` | Live ključevi s mjesečnom kvotom: preostale jedinice (manja od kvote ugovora i limita ključa). |
| `retry-after` | Uz `429 rate_limited`: sekundi do ponovnog pokušaja. |
Preko limita API vraća `429 rate_limited` sa zaglavljem `Retry-After` u sekundama.
## Jedinice u mjesecu
Kvota ugovora važi za kalendarski mjesec po UTC-u i dijele je svi live ključevi kompanije. Kad je potrošena, naplatni endpointi vraćaju `429 quota_exceeded` s `quota`, `used` i `resets_at`; besplatna čitanja rade i dalje. Ključ može imati i svoj, manji mjesečni limit (`429 key_limit_reached`). Šta troši jedinice: [Obračun](https://www.cifra.ba/docs/api/billing).
> **Savjet:** Na platformi odaberite pragove (npr. 80% i 100% kvote) za obavještenje emailom i webhookom `usage.threshold_reached`, da kvota ne istekne iznenada.
## Kako poštovati limite
- Ponavljajte samo `429` i `5xx`. Ostale greške ne nestaju ponavljanjem.
- Na `429 rate_limited` sačekajte `Retry-After`; na `5xx` eksponencijalno (1 s, 2 s, 4 s…) s malo slučajnosti, najviše nekoliko puta.
- `429 quota_exceeded` ne ponavljajte do `resets_at`.
- Za mnogo vozila koristite masovnu procjenu umjesto stotina pojedinačnih poziva.
**JavaScript**
```js
async function cifra(path, init = {}, attempt = 0) {
const res = await fetch(`https://api.cifra.ba${path}`, {
...init,
headers: {
Authorization: `Bearer ${process.env.CIFRA_API_KEY}`,
"Content-Type": "application/json",
...init.headers,
},
});
const retryable = res.status === 429 || res.status >= 500;
if (retryable && attempt < 4) {
const problem = await res.json().catch(() => ({}));
if (problem.code === "quota_exceeded") throw new Error(problem.detail);
const wait = Number(res.headers.get("retry-after")) * 1000 ||
2 ** attempt * 1000 + Math.random() * 250;
await new Promise((r) => setTimeout(r, wait));
return cifra(path, init, attempt + 1);
}
const body = await res.json();
if (!res.ok) throw Object.assign(new Error(body.detail), body);
return body;
}
```
**Python**
```python
import os, random, time
import requests
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['CIFRA_API_KEY']}"
def cifra(method, path, **kwargs):
for attempt in range(5):
res = session.request(method, "https://api.cifra.ba" + path, timeout=30, **kwargs)
retryable = res.status_code == 429 or res.status_code >= 500
if not retryable or attempt == 4:
break
if res.json().get("code") == "quota_exceeded":
break
wait = float(res.headers.get("retry-after") or 2 ** attempt + random.random() / 4)
time.sleep(wait)
res.raise_for_status()
return res.json()
```
---
# Obračun
Šta troši jedinice, šta je besplatno i gdje pratite potrošnju.
API se obračunava u **jedinicama**. Jedinica je jedan rezultat koji Cifra izračuna za vas: procjena, provjera ili vozilo koje počne da se prati. Čitanje onoga što već postoji je besplatno, kao i svaka greška i sve u sandboxu.
**Procjene**
| Endpoint | | Obračun |
| --- | --- | --- |
| `POST /v1/valuations` | [Procjena vozila](https://www.cifra.ba/docs/api-reference/valuations/create) | 1 jedinica |
| `POST /v1/valuations/batch` | [Masovna procjena](https://www.cifra.ba/docs/api-reference/valuations/batch) | 1 jedinica po stavci |
| `GET /v1/valuations/{id}` | [Čitanje procjene](https://www.cifra.ba/docs/api-reference/valuations/retrieve) | besplatno |
| `POST /v1/valuations/{id}/outcome` | [Prijava prodajne cijene](https://www.cifra.ba/docs/api-reference/valuations/outcome) | besplatno |
**Šifarnik**
| Endpoint | | Obračun |
| --- | --- | --- |
| `GET /v1/taxonomy/makes` | [Marke](https://www.cifra.ba/docs/api-reference/taxonomy/makes) | besplatno |
| `GET /v1/taxonomy/makes/{make}/models` | [Modeli marke](https://www.cifra.ba/docs/api-reference/taxonomy/models) | besplatno |
| `GET /v1/taxonomy/values` | [Dozvoljene vrijednosti](https://www.cifra.ba/docs/api-reference/taxonomy/values) | besplatno |
**Provjera vozila**
| Endpoint | | Obračun |
| --- | --- | --- |
| `GET /v1/vehicle-history` | [Historija vozila](https://www.cifra.ba/docs/api-reference/vehicle-history/retrieve) | 1 jedinica |
**Praćenje vozila**
| Endpoint | | Obračun |
| --- | --- | --- |
| `POST /v1/watchlist` | [Praćenje vozila](https://www.cifra.ba/docs/api-reference/watchlist/create) | 1 jedinica |
| `POST /v1/watchlist/batch` | [Uvoz portfelja](https://www.cifra.ba/docs/api-reference/watchlist/batch) | 1 jedinica po stavci |
| `GET /v1/watchlist` | [Lista praćenih vozila](https://www.cifra.ba/docs/api-reference/watchlist/list) | besplatno |
| `GET /v1/watchlist/{id}` | [Praćeno vozilo](https://www.cifra.ba/docs/api-reference/watchlist/retrieve) | besplatno |
| `PATCH /v1/watchlist/{id}` | [Izmjena praćenog vozila](https://www.cifra.ba/docs/api-reference/watchlist/update) | besplatno |
| `DELETE /v1/watchlist/{id}` | [Prestanak praćenja](https://www.cifra.ba/docs/api-reference/watchlist/delete) | besplatno |
| `GET /v1/watchlist/{id}/history` | [Historija vrijednosti](https://www.cifra.ba/docs/api-reference/watchlist/history) | besplatno |
| `GET /v1/watchlist/report` | [Dnevni izvještaj](https://www.cifra.ba/docs/api-reference/watchlist/report) | besplatno |
**Alarmi**
| Endpoint | | Obračun |
| --- | --- | --- |
| `GET /v1/alerts` | [Lista alarma](https://www.cifra.ba/docs/api-reference/alerts/list) | besplatno |
**Webhookovi**
| Endpoint | | Obračun |
| --- | --- | --- |
| `POST /v1/webhooks` | [Nova webhook adresa](https://www.cifra.ba/docs/api-reference/webhooks/create) | besplatno |
| `GET /v1/webhooks` | [Lista webhook adresa](https://www.cifra.ba/docs/api-reference/webhooks/list) | besplatno |
| `DELETE /v1/webhooks/{id}` | [Isključivanje adrese](https://www.cifra.ba/docs/api-reference/webhooks/delete) | besplatno |
| `POST /v1/webhooks/{id}/test` | [Probni događaj](https://www.cifra.ba/docs/api-reference/webhooks/test) | besplatno |
| `GET /v1/webhooks/{id}/deliveries` | [Isporuke](https://www.cifra.ba/docs/api-reference/webhooks/deliveries) | besplatno |
**Widgeti**
| Endpoint | | Obračun |
| --- | --- | --- |
| `POST /v1/widgets` | [Objava widgeta](https://www.cifra.ba/docs/api-reference/widgets/create) | besplatno |
| `POST /v1/widgets/batch` | [Objava više widgeta](https://www.cifra.ba/docs/api-reference/widgets/batch) | besplatno |
| `GET /v1/widgets` | [Lista widgeta](https://www.cifra.ba/docs/api-reference/widgets/list) | besplatno |
| `GET /v1/widgets/{id}` | [Widget](https://www.cifra.ba/docs/api-reference/widgets/retrieve) | besplatno |
| `PATCH /v1/widgets/{id}` | [Izmjena widgeta](https://www.cifra.ba/docs/api-reference/widgets/update) | besplatno |
| `DELETE /v1/widgets/{id}` | [Uklanjanje widgeta](https://www.cifra.ba/docs/api-reference/widgets/delete) | besplatno |
## Primjeri
| Poziv | Jedinice |
| --- | --- |
| Procjena jednog vozila (s obračunom, prognozom i sličnim vozilima) | 1 |
| Masovna procjena 100 vozila, od kojih 3 s greškom | 97 |
| Uvoz portfelja od 500 vozila u praćenje | 500 jednom; dnevne procjene besplatno |
| Provjera oglasa | 1 |
| Šifarnik, čitanje procjene, lista alarma, dnevni izvještaj | 0 |
| Bilo koji zahtjev koji vrati grešku | 0 |
## Praćenje potrošnje
- Zaglavlje `x-quota-remaining` na svakom live odgovoru.
- Razvoj → Potrošnja na platformi: jedinice po danu, ključu i endpointu.
- Razvoj → Zahtjevi: svaki zahtjev zadnjih 30 dana, sa statusom, trajanjem, jedinicama i, kod grešaka, tijelom zahtjeva.
- Obavještenja na odabranim pragovima kvote (email i webhook `usage.threshold_reached`).
---
# Greške
Format grešaka, šta znači svaki status i kad zahtjev ponoviti.
Greške se vraćaju kao `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) sa stabilnom šifrom u `code`. Granajte kod po `code`, ne po tekstu u `detail` — tekst se može poboljšati, šifra ostaje.
**400 invalid_request**
```json
{
"type": "https://api.cifra.ba/errors/invalid_request",
"title": "Bad Request",
"status": 400,
"code": "invalid_request",
"detail": "The request does not match the schema.",
"request_id": "033ce4b4-d930-4b5a-9cf9-6b2b006ac473",
"errors": [
{
"path": "year",
"message": "year is in the future",
"code": "custom"
},
{
"path": "mileage_km",
"message": "Too small: expected number to be >=0",
"code": "too_small"
},
{
"path": "doors",
"message": "doors applies to car only, not motorcycle",
"code": "custom"
}
]
}
```
## Statusi
| Status | Značenje | Ponoviti? |
| --- | --- | --- |
| `400` | Zahtjev nije ispravan: polja, JSON, parametri. | Ne, ispravite zahtjev |
| `401` | Nema ključa, nepoznat ili istekao. | Ne |
| `403` | Ključ ne smije ovo: pristup, IP adresa, pauza. | Ne |
| `404` | Ne postoji (ili je druge kompanije ili okruženja). | Ne |
| `409` | Sukob sa stanjem: pun limit praćenja, isključena adresa. | Ne, promijenite stanje |
| `413` | Prevelik zahtjev ili lista. | Ne, podijelite |
| `422` | Ispravan oblik, ali nemoguć sadržaj: nepoznata marka, datum u budućnosti. | Ne |
| `429` | Limit u minuti ili mjesečna kvota. | Da, nakon `Retry-After` (osim kvote) |
| `5xx` | Greška kod nas. | Da, s eksponencijalnim čekanjem |
## Greške u listama
Masovna procjena i uvoz portfelja ne padaju zbog jednog vozila: odgovor je `200`, a svako vozilo ima ili rezultat ili `error` na svom mjestu (`index`). Naplaćuju se samo uspjeli.
**Stavka s greškom**
```json
{
"index": 2,
"error": {
"code": "unknown_model",
"detail": "Unknown model \"pasat\" for Volkswagen. See GET /v1/taxonomy/makes/volkswagen/models."
}
}
```
## Upozorenja nisu greške
Procjena može uspjeti i nositi `warnings`: npr. nedostaju podaci pa je raspon širi. Prikažite ih ili zabilježite; nepoznatu šifru upozorenja tretirajte kao informaciju. Sva upozorenja: [Tržišna vrijednost](https://www.cifra.ba/docs/api/valuations#upozorenja).
## Sve šifre
Potpuna lista sa statusom, uzrokom i rješenjem: [Šifre grešaka](https://www.cifra.ba/docs/api-reference/errors).
### Česte greške
| Status | Šifra | Kad | Šta uraditi |
| --- | --- | --- | --- |
| `400` | `invalid_body` | Tijelo nije JSON. | Pošaljite `Content-Type: application/json` i ispravan JSON. |
| `401` | `missing_token` | Zahtjev nema ključ. | Pošaljite `Authorization: Bearer cfr_live_…` (ili `x-api-key`). |
| `401` | `invalid_token` | Ključ ne postoji, opozvan je ili nije dobrog oblika. | Provjerite da šaljete cijeli ključ, bez razmaka; napravite novi u Razvoj → API ključevi. |
| `401` | `token_expired` | Ključu je prošao datum isteka. | Napravite novi ključ ili produžite postojeći na platformi. |
| `403` | `key_paused` | Vaša kompanija je pauzirala ključ. | Administrator ga nastavlja u Razvoj → API ključevi. |
| `403` | `token_suspended` | Cifra je privremeno zaustavila ključ. | Javite se podršci. |
| `403` | `ip_not_allowed` | Ključ prima zahtjeve samo s dozvoljenih adresa, a ova nije među njima (odgovor nosi `ip`). | Dodajte adresu ili CIDR raspon ključu na platformi. |
| `403` | `insufficient_scope` | Ključ nema pristup ovoj usluzi (npr. Provjera vozila bez `listings`). | Dodajte pristup ključu ili koristite drugi ključ. |
| `413` | `payload_too_large` | Tijelo je veće od 2 MB. | Podijelite listu na manje zahtjeve. |
| `429` | `rate_limited` | Previše zahtjeva u minuti. | Sačekajte `Retry-After` sekundi i ponovite; ravnomjerno raspodijelite zahtjeve. |
| `429` | `quota_exceeded` | Potrošena mjesečna kvota ugovora (odgovor nosi `quota`, `used`, `resets_at`). | Kvota se obnavlja 1. u mjesecu (UTC); za veću se javite prodaji. |
| `429` | `key_limit_reached` | Ključ je potrošio mjesečni limit koji mu je postavila vaša kompanija (`limit`, `used`, `resets_at`). | Administrator povećava limit ključa na platformi. |
| `500` | `internal_error` | Greška na strani Cifre. | Ponovite zahtjev; ako se ponavlja, pošaljite `request_id` podršci. |
---
# Tržišna vrijednost
Šta tačno znači broj koji API vraća, kako čitati raspon i ocjenu, i koji podaci ga čine preciznijim.
`POST /v1/valuations` vraća **tržišnu vrijednost**: cijenu po kojoj se uporedivo vozilo oglašava kod privatnog prodavca u BiH na dan procjene. To je referenca tržišta, ne ponuda za otkup — za otkup, kredit ili osiguranje na nju primijenite svoja pravila ili [svoj model](https://www.cifra.ba/docs/api/company-models).
```bash
curl -X POST "https://api.cifra.ba/v1/valuations" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"engine_cc": 1598,
"fuel": "diesel",
"transmission": "manual",
"body_type": "hatchback",
"city": "Sarajevo",
"include": [
"explanation",
"forecast",
"comparables"
]
}'
```
```python
import os
import requests
response = requests.post(
"https://api.cifra.ba/v1/valuations",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
json={
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"engine_cc": 1598,
"fuel": "diesel",
"transmission": "manual",
"body_type": "hatchback",
"city": "Sarajevo",
"include": ["explanation", "forecast", "comparables"],
},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
## Vrijednost, raspon, ocjena
| Polje | Značenje |
| --- | --- |
| `market_value.point` | Tržišna vrijednost u KM, zaokružena na 10 KM. |
| `market_value.low` / `high` | Raspon u kojem je cijena s vjerovatnoćom od 80%. Kalibrisan na novim oglasima: pogađa 8 od 10. |
| `market_value.confidence_grade` | `A`, `B` ili `C`: koliko je raspon uzak za takvo vozilo, u odnosu na ostala. |
| `model_version` | Model koji je procijenio; čuvajte ga uz procjenu radi revizije. |
| `as_of` | Dan na koji vrijednost važi. |
> **Savjet:** Za odluke s rizikom (kolateral, isplata štete) koristite i raspon, ne samo `point`: npr. donju granicu kao konzervativnu vrijednost, ili ručnu provjeru kad je ocjena `C`.
## Šta sužava raspon
Obavezni su `make`, `model`, `year` i `mileage_km`. Svaki dodatni podatak pomaže, a ovi najviše — bez njih procjena nosi upozorenje `partial_inputs` i širi raspon:
| Vrsta | Ključni podaci |
| --- | --- |
| Automobil | `power_kw` (ili `power_hp`), `engine_cc`, `fuel`, `transmission` |
| Motocikl | `engine_cc`, `category` |
| Kamion | `power_kw` |
Zatim: `power_kw` i `fuel` za sve vrste, `city` (regionalna potražnja), `body_type`, `drivetrain`, `owners_count`, `service_history`, `customs_cleared`, `equipment`; za kamione i `category` i `payload_class`.
## Upozorenja
`warnings` objašnjava ono što broj sam ne kaže. Procjena je i dalje ispravna; upozorenje kaže kako je čitati.
| Upozorenje | Značenje |
| --- | --- |
| `partial_inputs` | Nedostaje neki od ključnih podataka — automobili: snaga, zapremina, gorivo, mjenjač; motocikli: zapremina i tip; kamioni: snaga. Poruka navodi šta fali; raspon je širi. |
| `model_not_in_market_data` | Model nismo vidjeli u oglasima; procjena se oslanja na marku i slična vozila. |
| `few_market_examples` | Malo oglasa ovog modela, pa je raspon širi. |
| `unusual_mileage` | Kilometraža je neobična za starost vozila. Provjerite je; ako je tačna, cijena može više odstupati. |
| `old_vehicle` | Vozila starija od 25 godina cijene se manje ujednačeno. |
| `market_level_as_of_data_end` | Najnoviji podaci modela su stariji od 7 dana; nivo tržišta je onaj s tog dana. |
| `comparables_not_in_batch` | Slična vozila se ne vraćaju u masovnoj procjeni. |
| `custom_model_unavailable` | Vaš model trenutno nije mogao odgovoriti; vrijednost je standardnog modela. |
| `custom_model_unseen_make` | U podacima vašeg modela nema ove marke: vrijednost je tržišna, pomjerena za vašu opštu razliku. |
| `custom_model_few_examples` | U podacima vašeg modela je malo vozila ovog modela; procjena se više oslanja na tržišni model. |
## Sva polja zahtjeva
- `vehicle_type` (enum, podrazumijevano "car") — Vrsta vozila. Svaka vrsta ima svoj model, šifarnik i polja koja prima. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno, do 64 znaka) — Marka kao šifra iz `GET /v1/taxonomy/makes`, npr. `volkswagen`, `mercedes_benz`, `škoda`.
- `model` (string, obavezno, do 64 znaka) — Model kao šifra iz `GET /v1/taxonomy/makes/{make}/models`, npr. `golf_7`.
- `year` (integer, obavezno, najmanje 1950) — Godište (modelska godina). Najviše sljedeća godina.
- `mileage_km` (integer, obavezno, 0 – 2.000.000) — Pređeni kilometri na dan procjene.
- `power_kw` (number, 2 – 1000) — Snaga motora u kW. Jedan od najvažnijih podataka za cijenu.
- `power_hp` (number, 3 – 1400) — Snaga u KS; koristi se samo kad `power_kw` nije poslan.
- `engine_cc` (integer, 40 – 20.000) — Zapremina motora u cm³.
- `fuel` (enum) — Gorivo. Vrijednosti: `petrol`, `diesel`, `lpg`, `cng`, `hybrid`, `plugin_hybrid`, `electric`, `hydrogen`, `other`.
- `transmission` (enum) — Mjenjač. Vrijednosti: `manual`, `automatic`, `semi_automatic`.
- `drivetrain` (enum) — Pogon. Samo automobili. Vrijednosti: `fwd`, `rwd`, `awd`.
- `body_type` (enum) — Karoserija. Samo automobili. Vrijednosti: `sedan`, `hatchback`, `wagon`, `suv`, `coupe`, `convertible`, `minivan`, `van`, `pickup`, `other`.
- `doors` (integer, 2 – 5) — Broj vrata. Samo automobili.
- `condition` (enum) — Stanje: `used` (podrazumijevano) ili `new`. Vrijednosti: `used`, `new`.
- `seller_type` (enum) — Ko prodaje: privatna osoba ili salon. Vrijednosti: `private`, `dealer`.
- `city` (string, do 80 znakova) — Grad u BiH, npr. `Sarajevo` ili `Banja Luka`. Regionalna potražnja pomjera cijenu.
- `equipment` (string[], do 150 stavki) — Oprema kako je navodi oglas ili vaš sistem, npr. `navigacija`, `kožna sjedišta`.
- `owners_count` (integer, 1 – 20) — Broj dosadašnjih vlasnika.
- `customs_cleared` (boolean) — Je li vozilo ocarinjeno.
- `service_history` (boolean) — Ima li vozilo servisnu historiju (knjižicu).
- `category` (string, do 60 znakova) — Motocikli: tip (`Naked`, `Scooter`, `Enduro`…); kamioni: nadogradnja (`Kiper`, `Kombi`…). Vrijednosti: `GET /v1/taxonomy/values`.
- `abs` (boolean) — ABS. Samo motocikli.
- `axles` (integer, 1 – 6) — Broj osovina. Samo kamioni.
- `payload_class` (string, do 40 znakova) — Nosivost kao razred iz `GET /v1/taxonomy/values`. Samo kamioni.
- `as_of` (date) — Datum procjene (`YYYY-MM-DD`), od 2015-01-01 do danas: vrijednost kakva je bila tog dana, npr. na dan štete. Podrazumijevano danas (UTC).
- `include` (enum[], do 3 stavke) — Dodaci odgovoru: `explanation` (obračun cijene), `forecast` (vrijednost kroz 6–36 mjeseci), `comparables` (slična vozila u prodaji). Bez polja: `explanation` i `forecast`; `[]` vraća samo vrijednost. Vrijednosti: `explanation`, `forecast`, `comparables`.
- `km_per_year` (integer, 0 – 150.000) — Koliko će vozilo prelaziti godišnje, za prognozu. Podrazumijevano: njegov dosadašnji prosjek.
- `valuation_model` (enum) — `auto` (podrazumijevano): vaš model kompanije kad je u upotrebi, inače standardni; `standard`: uvijek standardni tržišni model. Vrijednosti: `auto`, `standard`.
## Čuvanje i revizija
Svaka live procjena se čuva s tačnim zahtjevom. Pročitajte je kasnije s [`GET /v1/valuations/{id}`](https://www.cifra.ba/docs/api-reference/valuations/retrieve), npr. kad treba pokazati na osnovu čega je odobren kredit. Kad saznate stvarnu prodajnu cijenu, javite je s [`POST /v1/valuations/{id}/outcome`](https://www.cifra.ba/docs/api-reference/valuations/outcome) — besplatno je i poboljšava buduće procjene prodajne cijene.
---
# Vrste vozila i šifarnik
Automobili, motocikli i kamioni: šifre marki i modela, polja svake vrste i kako povezati vaš šifarnik.
Marke i modeli se šalju kao **šifre** iz šifarnika, ne kao slobodan tekst. Tako „VW Golf VII 1.6 TDI”, „Golf 7” i „golf7” postaju isto vozilo: `volkswagen` / `golf_7`.
```bash
curl "https://api.cifra.ba/v1/taxonomy/makes?vehicle_type=car" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```python
import os
import requests
response = requests.get(
"https://api.cifra.ba/v1/taxonomy/makes?vehicle_type=car",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
## Pravila šifri
- Mala slova, brojevi i `_`. Slova s kvačicama ostaju: **`škoda`**, ne `skoda`.
- Generacije i jače izvedbe su zasebni modeli: `golf_6`, `golf_7`, `golf_7_gti`. Općeniti `golf` postoji za oglase bez generacije, ali daje širi raspon.
- Modeli koji nisu u šifarniku marke vode se pod „Drugi modeli” te marke (npr. `drugi`); procjena je tada manje precizna.
## Vrste vozila
`vehicle_type` bira model i šifarnik. Neka polja ima samo jedna vrsta — poslano za drugu, vraća `400 invalid_request`.
| Polje | Automobil | Motocikl | Kamion |
| --- | --- | --- | --- |
| `drivetrain`, `body_type`, `doors` | ✓ | — | — |
| `category` | — | tip: `Naked`, `Scooter`… | nadogradnja: `Kiper`, `Kombi`… |
| `abs` | — | ✓ | — |
| `axles`, `payload_class` | — | — | ✓ |
Dozvoljene vrijednosti za polja s izborom, za svaku vrstu, daje `GET /v1/taxonomy/values?vehicle_type=…`:
```bash
curl "https://api.cifra.ba/v1/taxonomy/values?vehicle_type=car" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```python
import os
import requests
response = requests.get(
"https://api.cifra.ba/v1/taxonomy/values?vehicle_type=car",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
## Povezivanje s vašim šifarnikom
Ako vaš sistem (DMS, core banking, oglasnik) ima svoje šifre vozila, napravite tabelu veza jednom, a ne pri svakoj procjeni:
- Preuzmite marke i modele za sve tri vrste.
- Povežite po nazivu (`name`); nesigurne veze provjerite ručno.
- Osvježavajte šifarnik jednom dnevno — dodaju se novi modeli, postojeće šifre se ne mijenjaju.
- Na `422 unknown_model` zabilježite vozilo i dopunite vezu, umjesto da procjenu tiho preskočite.
**Cijeli šifarnik (besplatno)**
```python
import requests, os
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['CIFRA_API_KEY']}"
base = "https://api.cifra.ba/v1/taxonomy"
catalog = {}
for vehicle_type in ("car", "motorcycle", "truck"):
makes = session.get(f"{base}/makes", params={"vehicle_type": vehicle_type}).json()["data"]
for make in makes:
models = session.get(
f"{base}/makes/{make['slug']}/models", params={"vehicle_type": vehicle_type}
).json()["data"]
catalog[(vehicle_type, make["slug"])] = {m["slug"]: m["name"] for m in models}
```
---
# Obračun cijene
Zašto baš ta vrijednost: doprinos svakog faktora, u KM, koji se tačno sabira.
Uz `include: ["explanation"]` (podrazumijevano kod pojedinačne procjene) odgovor sadrži obračun: prva linija je bazna vrijednost modela, a svaka sljedeća kaže koliko faktor dodaje ili oduzima. Linije se **tačno sabiraju** u `market_value.point`, pa ih možete prikazati korisniku kao račun.
```json
{
"lines": [
{
"id": "base",
"label": "Bazna vrijednost modela",
"amount_bam": 22950
},
{
"id": "mileage",
"label": "Kilometraža",
"amount_bam": 3270
},
{
"id": "equipment",
"label": "Oprema i motorizacija",
"amount_bam": -3090
},
{
"id": "history",
"label": "Stanje i historija vozila",
"amount_bam": -20
},
{
"id": "region",
"label": "Regionalna potražnja",
"amount_bam": -230
},
{
"id": "market",
"label": "Stanje tržišta",
"amount_bam": -530
}
],
"method": "TreeSHAP contributions of the valuation model, grouped by factor and applied in order."
}
```
| `id` | Faktor |
| --- | --- |
| `base` | Bazna vrijednost modela i godišta |
| `mileage` | Kilometraža naspram tipične za tu starost |
| `equipment` | Oprema i motorizacija (snaga, zapremina, gorivo, mjenjač, oprema) |
| `history` | Stanje i historija (vlasnici, servis, carina) |
| `region` | Regionalna potražnja (grad) |
| `market` | Stanje tržišta na dan procjene |
| `adjustment` | Privremena korekcija Cifrinog tržišnog tima (rijetko; razlog u `adjustment.reason`) |
Obračun dolazi iz samog modela (TreeSHAP), ne iz pravila napisanih sa strane: pokazuje šta je model zaista uzeo u obzir. `label` je na bosanskom, spreman za prikaz.
> **Napomena:** Obračun traje oko 50 ms po vozilu; samo vrijednost oko 0,2 ms. U masovnoj procjeni ga tražite samo kad vam treba.
---
# Prognoza vrijednosti
Koliko će vozilo vrijediti za 6, 12, 24 i 36 mjeseci, s rasponom.
Uz `include: ["forecast"]` (podrazumijevano) odgovor daje očekivanu vrijednost za 6, 12, 24 i 36 mjeseci, s rasponom koji se širi s vremenom. Prognoza koristi naučenu krivu gubitka vrijednosti za starost i klasu marke, a nivo tržišta drži na današnjem.
```json
{
"status": "beta",
"km_per_year": 15110,
"points": [
{
"months": 6,
"point": 21380,
"low": 16350,
"high": 26450
},
{
"months": 12,
"point": 20450,
"low": 14670,
"high": 25990
},
{
"months": 24,
"point": 18710,
"low": 13890,
"high": 23530
},
{
"months": 36,
"point": 17150,
"low": 12190,
"high": 22020
}
],
"method": "Learned depreciation curve for this age and brand tier; market level held at today's."
}
```
- `km_per_year` u zahtjevu određuje koliko vozilo prelazi godišnje; podrazumijevano je njegov dosadašnji prosjek.
- Provjereno na 693 vozila ponovo oglašenih nakon 12 i 24 mjeseca: medijan greške 9,2%.
- Status je `beta`: oblik odgovora je stabilan, a metoda će se poboljšavati.
> **Savjet:** Za lizing i kredite prognoza na kraju ugovora je polazna tačka za rezidualnu vrijednost; za cijele krive po modelu vidi Rezidual na platformi.
---
# Slična vozila
Vozila u prodaji danas koja liče na procijenjeno, s Cifrinom vrijednošću svakog.
Uz `include: ["comparables"]` odgovor vraća do 8 najsličnijih vozila trenutno u prodaji: isti model, godište ±2, poredano po sličnosti godišta, kilometraže, goriva i mjenjača. `total` kaže koliko ih je ukupno u prodaji.
```json
{
"total": 502,
"items": [
{
"year": 2017,
"mileage_km": 154115,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85,
"engine_cc": 1600,
"city": "Bihać",
"asking_price_bam": 20999,
"cifra_value_bam": 22370,
"price_vs_value_pct": -6.1,
"days_listed": 103
},
{
"year": 2017,
"mileage_km": 160000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85,
"engine_cc": 1600,
"city": "Bijeljina",
"asking_price_bam": 23500,
"cifra_value_bam": 22480,
"price_vs_value_pct": 4.5,
"days_listed": 70
},
{
"year": 2017,
"mileage_km": 142000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85,
"engine_cc": 1600,
"city": "Konjic",
"asking_price_bam": 27300,
"cifra_value_bam": 22520,
"price_vs_value_pct": 21.2,
"days_listed": 43
}
]
}
```
- `cifra_value_bam` je Cifrina vrijednost tog vozila, a `price_vs_value_pct` koliko oglas traži iznad ili ispod nje.
- Anonimizovano: bez prodavca, naslova i linka oglasa.
- Samo kod pojedinačne procjene; u masovnoj vraća upozorenje `comparables_not_in_batch`.
---
# Procjena na dan
Vrijednost kakva je bila određenog dana: dan štete, dan kupovine, kraj kvartala.
Pošaljite `as_of` (`YYYY-MM-DD`, od 2015-01-01 do danas) i procjena se računa za taj dan: s nivoom tržišta tog dana i starošću vozila tog dana. Kilometražu pošaljite onakvu kakva je bila tog dana.
**Vrijednost na dan štete**
```bash
curl -X POST "https://api.cifra.ba/v1/valuations" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 140000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual",
"as_of": "2026-03-15",
"include": []
}'
```
```python
import os
import requests
response = requests.post(
"https://api.cifra.ba/v1/valuations",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
json={
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 140000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual",
"as_of": "2026-03-15",
"include": [],
},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
- Osiguranja: vrijednost vozila na dan štete ili krađe.
- Lizing i banke: vrijednost kolaterala na kraju kvartala, za izvještaje.
- Sudski i porezni postupci: tržišna vrijednost na dan prometa.
> **Napomena:** Za datume poslije zadnjeg dana podataka modela nivo tržišta je onaj iz najnovijih podataka; ako su stariji od 7 dana, odgovor to kaže upozorenjem `market_level_as_of_data_end`. Za budućnost koristite [prognozu](https://www.cifra.ba/docs/api/forecast).
---
# Masovna procjena
Stotine vozila u jednom pozivu: portfelji, lageri, cjenovnici.
`POST /v1/valuations/batch` prima listu vozila, svako kao tijelo pojedinačne procjene. Svako se provjerava i procjenjuje zasebno: neispravno vraća `error` na svom mjestu, ostala se procijene. Odgovor je istim redom; `index` je mjesto u listi.
```bash
curl -X POST "https://api.cifra.ba/v1/valuations/batch" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"include": [
"explanation"
],
"items": [
{
"make": "audi",
"model": "a4",
"year": 2016,
"mileage_km": 190000,
"fuel": "diesel",
"transmission": "automatic"
},
{
"make": "škoda",
"model": "octavia",
"year": 2015,
"mileage_km": 210000
},
{
"make": "volkswagen",
"model": "pasat",
"year": 2015,
"mileage_km": 200000
}
]
}'
```
```python
import os
import requests
response = requests.post(
"https://api.cifra.ba/v1/valuations/batch",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
json={
"include": ["explanation"],
"items": [
{
"make": "audi",
"model": "a4",
"year": 2016,
"mileage_km": 190000,
"fuel": "diesel",
"transmission": "automatic",
},
{
"make": "škoda",
"model": "octavia",
"year": 2015,
"mileage_km": 210000,
},
{
"make": "volkswagen",
"model": "pasat",
"year": 2015,
"mileage_km": 200000,
},
],
},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
## Veličina i brzina
| | Business | Enterprise | Sandbox |
| --- | --- | --- | --- |
| Vozila u pozivu | 100 | do 1.000 (ugovor) | 10 |
| Tijelo zahtjeva | do 2 MB | do 2 MB | do 2 MB |
- Bez `include` lista vraća samo vrijednosti — najbrže. Obračun traži samo kad ga prikazujete (oko 50 ms po vozilu).
- Veće liste podijelite na dijelove i šaljite ih jedan za drugim ili s malo paralelnih zahtjeva, u okviru limita u minuti.
- Ponovite samo vozila s greškom `5xx`/`429`, ne cijelu listu: uspjela su već naplaćena.
**JavaScript**
```js
const CHUNK = 100;
const results = [];
for (let i = 0; i < vehicles.length; i += CHUNK) {
const items = vehicles.slice(i, i + CHUNK);
const res = await cifra("/v1/valuations/batch", {
method: "POST",
body: JSON.stringify({ items }),
});
for (const r of res.data) results[i + r.index] = r;
}
const failed = results.filter((r) => r.error);
```
**Python**
```python
CHUNK = 100
results = [None] * len(vehicles)
for i in range(0, len(vehicles), CHUNK):
res = cifra("POST", "/v1/valuations/batch", json={"items": vehicles[i:i + CHUNK]})
for r in res["data"]:
results[i + r["index"]] = r
failed = [r for r in results if "error" in r]
```
> **Savjet:** Na platformi isto radi Masovna procjena: učitate Excel, mapirate kolone i preuzmete rezultat, bez koda. Webhook `bulk.completed` javi kad je lista gotova.
---
# Vaš model
Procjene naučene na vašim cijenama — prodajnim, otkupnim ili procjenama — uz tržišnu vrijednost.
Kompanija s Enterprise ugovorom može na platformi (Vaš model) učitati svoje cijene — prodaje, otkupe, oglase ili procjene — i dobiti model koji vrednuje kao ona. Model ne uči ispočetka: zadržava Cifrin tržišni model i uči samo **razliku** između vaših cijena i tržišta, po marki, starosti, kilometraži i drugim osobinama.
## Kako ga API koristi
- Kad je vaš model u upotrebi, procjene vaših ključeva dolaze iz njega (`valuation_model: "auto"`, podrazumijevano).
- `valued_by.kind` je `custom`, a `valued_by.price_kind` kaže koje cijene je učio — pa šta vrijednost znači.
- `standard_value` je tržišna vrijednost istog vozila, za poređenje.
- Pošaljite `valuation_model: "standard"` kad trebate samo tržišnu vrijednost.
```bash
curl -X POST "https://api.cifra.ba/v1/valuations" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"engine_cc": 1598,
"fuel": "diesel",
"transmission": "manual",
"body_type": "hatchback",
"city": "Sarajevo",
"include": []
}'
```
```python
import os
import requests
response = requests.post(
"https://api.cifra.ba/v1/valuations",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
json={
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"engine_cc": 1598,
"fuel": "diesel",
"transmission": "manual",
"body_type": "hatchback",
"city": "Sarajevo",
"include": [],
},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
**valued_by**
```json
{
"kind": "custom",
"version": "custom-17-v3",
"custom_model_id": 17,
"name": "Otkup 2026",
"price_kind": "purchase",
"base_version": "car-20261017-1"
}
```
## Kad nešto nije sigurno
| Upozorenje | Značenje |
| --- | --- |
| `custom_model_unseen_make` | U vašim podacima nema te marke: vrijednost je tržišna, pomjerena za vašu opštu razliku. |
| `custom_model_few_examples` | Malo vozila tog modela u vašim podacima: procjena se više oslanja na tržište. |
| `custom_model_unavailable` | Vaš model trenutno nije mogao odgovoriti; vrijednost je standardnog. Procjena nikad ne pada zbog toga. |
> **Napomena:** Vaši podaci nikad ne ulaze u Cifrin tržišni model i ne vide ih druge kompanije. Model prati tržište: kad Cifra uvede novi tržišni model, vaš se automatski obnavlja na njemu i prelazi tek kad prođe provjeru.
> **Pažnja:** Model kompanije se uključuje ugovorom i na platformi; API ga samo koristi. Praćena vozila i slična vozila uvijek vrednuje tržišni model.
---
# Provjera vozila
Za link oglasa: svi oglasi istog vozila koje je Cifra vidjela i signali na koje treba obratiti pažnju.
Cifra svaki dan prati oglase i povezuje oglase **istog vozila**: ponovno objavljivanje, isti auto na drugoj stranici, drugi prodavac. `GET /v1/vehicle-history` za jedan oglas vraća tu historiju — datume, cijene, kilometražu, mjesto — i signale Cifra Provjere, iste kao na platformi.
```bash
curl "https://api.cifra.ba/v1/vehicle-history?listing_url=https%3A%2F%2Folx.ba%2Fartikal%2F61234567" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```python
import os
import requests
response = requests.get(
"https://api.cifra.ba/v1/vehicle-history?listing_url=https%3A%2F%2Folx.ba%2Fartikal%2F61234567",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
## Kako čitati odgovor
| Polje | Značenje |
| --- | --- |
| `level` | `high`, `elevated` ili `low`: koliko pažnje vozilo traži prije odluke. |
| `signals` | Razlozi za pažnju, od najtežeg: `summary` i `message` za prikaz (bosanski), `check` šta provjeriti. |
| `in_favour` | Šta govori u prilog vozilu: dosljedna kilometraža, servisna knjiga, jedan vlasnik. |
| `listings` | Svi oglasi vozila, od najstarijeg, s vezom `link` (šta se poklopilo i koliko je pouzdano). |
| `market` | Oglas naspram Cifrine vrijednosti, i kilometraža naspram vozila iste starosti. |
**signals**
```json
[
{
"code": "relisted_often",
"severity": "medium",
"summary": "Na prodaji 5 mj., oglašeno 3 puta",
"message": "Prvi oglas 25. 6. 2026. Vozilo koje se dugo ne proda često ima razlog — cijenu, stanje ili papire.",
"check": "Pitajte koliko dugo se prodaje i zašto se još nije prodalo."
},
{
"code": "changed_hands",
"severity": "info",
"summary": "Mijenjalo prodavca",
"message": "Vozilo je nudio više od jednog prodavca; pogledajte historiju.",
"check": null
}
]
```
## Signali
| Šifra | Značenje |
| --- | --- |
| `mileage_rollback` | Kilometraža smanjena između oglasa |
| `mileage_edited_down` | Kilometraža smanjena u oglasu |
| `mileage_low` | Neobično mala kilometraža |
| `mileage_unclear` | Kilometraža nejasno upisana |
| `photos_other_vehicle` | Fotografije drugog vozila |
| `photos_other_seller` | Iste fotografije kod drugog prodavca |
| `price_far_below` | Cijena daleko ispod tržišta |
| `price_below` | Cijena ispod tržišta |
| `price_above` | Cijena iznad tržišta |
| `on_lease` | Vozilo na lizingu |
| `listed_before_event` | Na prodaji prije datuma događaja |
| `specs_changed` | Mijenjani podaci o vozilu |
| `relisted_often` | Dugo i često oglašavano |
| `relisted` | Ranije oglašavano |
| `changed_hands` | Mijenjalo prodavca |
| `many_sellers` | Više prodavaca |
| `undeclared_dealer` | Preprodavač kao privatnik |
| `not_cleared` | Nije ocarinjeno |
| `foreign_plates` | Strane tablice |
| `damaged` | Oštećeno vozilo |
| `many_owners` | Više vlasnika |
| `price_cut` | Cijena snižavana |
| `no_history` | Bez ranijih oglasa |
| `mileage_consistent` | Kilometraža dosljedna |
| `service_book` | Servisna knjiga |
| `one_owner` | Jedan vlasnik |
| `registered` | Ocarinjeno i registrovano |
| `warranty` | Garancija |
> **Pažnja:** Veze se prave iz podataka oglasa (specifikacije, trag kilometraže, naslov, prodavac, mjesto, fotografije), ne iz registra vozila. Signal je razlog da se pogleda bolje, ne presuda — konačnu odluku donosi čovjek, uz dokumente vozila.
## Oglasi koje pratimo
- olx.ba, autobum.ba i autoplac.ba; pošaljite link ili `source` + `listing_id`.
- Stranice se pregledaju dnevno: oglas objavljen danas možda još nije poznat (`404 listing_not_found`) — pokušajte sutra.
- Odgovor je anonimizovan: bez linkova, naslova i prodavaca drugih oglasa.
> **Savjet:** Na platformi isto radi Provjera, uz odluku tima (odobreno, dodatna provjera, odbijeno); webhookovi `check.completed` i `check.decided` javljaju oba koraka.
---
# Praćenje vozila
Portfelj koji se procjenjuje svako jutro, s alarmima i dnevnim izvještajem.
Praćeno vozilo se procjenjuje **svako jutro** (oko 7–8 h po našem vremenu, nakon noćnog treniranja modela), istim modelom i zaokruživanjem kao `POST /v1/valuations`. Zatim se provjere pravila alarma, napravi dnevni izvještaj i pošalju webhookovi.
| Vrsta | Za šta | Šta se mijenja svaki dan |
| --- | --- | --- |
| `owned` | Vaša vozila: lizing, kolateral, flota, lager. | Vozilo stari, kilometraža raste za `km_per_year`; vrijednost prati to i tržište. |
| `wanted` | Specifikacija koju tražite za kupca ili otkup. | Tržišna cijena te specifikacije; novi povoljni oglasi (`deal_pct`). |
```bash
curl -X POST "https://api.cifra.ba/v1/watchlist" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "owned",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"vehicle": {
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual"
},
"km_per_year": 18000,
"exposure": {
"kind": "financing",
"amount_bam": 18500,
"as_of": "2026-10-18",
"term_months": 36,
"annual_rate_pct": 6.9,
"balloon_bam": 12000
},
"alerts": {
"change_pct": 5,
"direction": "down",
"exposure_pct": 85
},
"tags": [
"lizing",
"sarajevo"
]
}'
```
```python
import os
import requests
response = requests.post(
"https://api.cifra.ba/v1/watchlist",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
json={
"kind": "owned",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"vehicle": {
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual",
},
"km_per_year": 18000,
"exposure": {
"kind": "financing",
"amount_bam": 18500,
"as_of": "2026-10-18",
"term_months": 36,
"annual_rate_pct": 6.9,
"balloon_bam": 12000,
},
"alerts": {
"change_pct": 5,
"direction": "down",
"exposure_pct": 85,
},
"tags": ["lizing", "sarajevo"],
},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
## Šta se plaća
Dodavanje vozila je 1 jedinica (procjenjuje se odmah). Dnevne procjene, izvještaj, alarmi, historija i webhookovi su besplatni.
## Portfelj odjednom
Do 500 vozila u pozivu s [`POST /v1/watchlist/batch`](https://www.cifra.ba/docs/api-reference/watchlist/batch): svako uspije ili padne samo za sebe. Postavite `external_ref` na vašu oznaku (broj ugovora, šasije) — po njoj filtrirate listu i izvještaj, a dolazi i u svakom alarmu.
## Održavanje
- Novo očitanje brojila: [`PATCH`](https://www.cifra.ba/docs/api-reference/watchlist/update) s `mileage_km` — kilometraža dalje raste od njega.
- Rata kredita plaćena ili ugovor promijenjen: `PATCH` s novom `exposure`.
- Vozilo prodano ili ugovor zatvoren: `DELETE` (ne broji se više u limit).
- Privremeno bez procjena: `status: "paused"`.
## Dnevni izvještaj
Kad je jutarnja procjena gotova, stiže webhook `watchlist.report_ready`; [`GET /v1/watchlist/report`](https://www.cifra.ba/docs/api-reference/watchlist/report) zatim daje svako vozilo: vrijednost, promjenu od juče i od početka, izloženost i LTV, i alarme dana. Jedan poziv za cijeli portfelj, besplatno.
**summary**
```json
{
"vehicles": 412,
"valued": 412,
"up": 37,
"down": 351,
"alerts": 1
}
```
## Limiti
Business: 1.000 praćenih vozila, Sandbox: 10, Enterprise po ugovoru. Preko limita API vraća `409 watchlist_full` s `max` i `count`.
---
# Izloženost i LTV
Koliko duga, osigurane sume ili troška stoji iza vozila, i kad pređe njegovu vrijednost.
Vlastitom vozilu dodajte `exposure` — iznos koji ste vezali za njega — i API svaki dan računa koliko on iznosi danas i koliki je dio vrijednosti vozila (**LTV**).
| `kind` | Šta je | Kako se mijenja |
| --- | --- | --- |
| `financing` | Stanje kredita ili lizinga | Otplaćuje se anuitetno kroz `term_months` po `annual_rate_pct` do `balloon_bam`; nakon roka je nula. `annual_rate_pct: 0` znači linearno. |
| `insured` | Osigurana suma | Ostaje ista |
| `cost` | Nabavna cijena | Ostaje ista |
**exposure**
- `kind` (enum, obavezno) — `financing`: stanje kredita ili lizinga (otplaćuje se); `insured`: osigurana suma; `cost`: nabavna cijena. Vrijednosti: `financing`, `insured`, `cost`.
- `amount_bam` (integer, obavezno, 100 – 20.000.000) — Iznos u KM na dan `as_of`.
- `as_of` (date) — Dan na koji važi `amount_bam` (podrazumijevano danas).
- `term_months` (integer, može biti null, 1 – 240) — `financing`: preostali broj mjeseci; stanje se otplaćuje do `balloon_bam`, a nakon roka je nula.
- `annual_rate_pct` (number, može biti null, 0 – 40) — `financing`: nominalna godišnja kamata za anuitetnu otplatu; `0` znači linearnu.
- `balloon_bam` (integer, može biti null, 0 – 20.000.000) — `financing`: ostatak na kraju roka (balon rata, otkupna vrijednost).
## LTV alarm
S `alerts.exposure_pct` (10–300) dobijate alarm **onog dana** kad izloženost dostigne taj postotak vrijednosti — samo pri rastu, ne svaki dan dok je iznad. Za kolateral je tipično 80–100%.
**Alarm exposure_above**
```json
{
"object": "alert",
"id": "alr_8fK2mQ9xLp4TvB7nR1sW",
"type": "exposure_above",
"watched_vehicle": {
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"kind": "owned"
},
"day": "2026-12-02",
"previous_value": 22350,
"value": 21400,
"change_pct": -4.25,
"threshold": 85,
"details": {
"exposure": {
"kind": "financing",
"amount": 18259,
"ratio": 0.8532
}
},
"created_at": "2026-12-02T06:12:44.000Z"
}
```
> **Savjet:** `ratio` u odgovoru, izvještaju i alarmu je izloženost ÷ vrijednost: `0.853` znači da dug iznosi 85,3% vrijednosti vozila.
---
# Alarmi
Pravila po vozilu: pad ili rast vrijednosti, ciljne cijene, LTV i povoljni oglasi.
Svako praćeno vozilo ima svoja pravila (`alerts`). Provjeravaju se nakon jutarnje procjene; alarm se čuva, stiže webhookom `watchlist.alert`, ulazi u dnevni izvještaj i na listu [`GET /v1/alerts`](https://www.cifra.ba/docs/api-reference/alerts/list).
**alerts**
- `change_pct` (number, može biti null, 3 – 90) — Alarm kad se vrijednost pomjeri za ovoliko posto: od početne vrijednosti, zatim od vrijednosti pri zadnjem alarmu. Najmanje 3, jer samo ponovno treniranje modela pomjeri vrijednosti ~2%. `null` isključuje.
- `direction` (enum) — Koji pomak broji za `change_pct`: `any` (podrazumijevano), `up` ili `down`. Vrijednosti: `any`, `up`, `down`.
- `below_bam` (integer, može biti null, 100 – 5.000.000) — Alarm kad vrijednost padne ispod ove cijene (KM).
- `above_bam` (integer, može biti null, 100 – 5.000.000) — Alarm kad vrijednost poraste iznad ove cijene (KM).
- `exposure_pct` (number, može biti null, 10 – 300) — Vlastita vozila: alarm na dan kad izloženost (dug, osigurana suma, trošak) dostigne ovaj postotak vrijednosti (LTV), samo pri rastu.
- `deal_pct` (number, može biti null, 5 – 50) — Tražena vozila: alarm za svaki novi oglas iste specifikacije koji traži ovoliko posto manje od Cifrine cijene (najviše 5 dnevno).
## Kako pravila rade
| Pravilo | Kad javlja |
| --- | --- |
| `change_pct` | Vrijednost se pomjerila za toliko posto od polazne, a nakon prvog alarma od vrijednosti pri zadnjem alarmu. Spori pad se tako javi kad se nakupi, a jedan pomak ne javlja svaki dan. `direction` ograničava na pad ili rast. |
| `below_bam` / `above_bam` | Vrijednost je **prešla** ciljnu cijenu (ne svaki dan dok je preko nje). |
| `exposure_pct` | LTV je dostigao prag, pri rastu. |
| `deal_pct` | Traženo vozilo: novi oglas istog modela, godište ±1, kilometraža ±30% (najmanje ±30.000 km), isto gorivo i mjenjač, traži toliko posto ispod Cifrine cijene. Najviše 5 dnevno, najbolji prvi; oglasi ispod 55% vrijednosti se preskaču (to je obično oštećenje, ne prilika). |
> **Napomena:** Dva modela trenirana na skoro istim podacima razlikuju se oko 2% po vozilu. Zato `change_pct` ne ide ispod 3%, a alarm nosi `details.modelChanged` kad je tog dana počeo raditi novi model — dio pomaka je tada model, ne tržište.
## Alarm
**market_deal**
```json
{
"object": "alert",
"id": "alr_Vb3nQ7xR2kLp9TzW5mYc",
"type": "market_deal",
"watched_vehicle": {
"id": "wv_9QeL2mXc7TbN4vR8kPz1",
"label": "Traži: Octavia 2018+",
"external_ref": null,
"kind": "wanted"
},
"day": "2026-10-20",
"previous_value": 24900,
"value": 21500,
"change_pct": -13.65,
"threshold": 12,
"details": {
"listing": {
"id": 9812334,
"title": "Škoda Octavia 2.0 TDI Style",
"year": 2018,
"km": 168000,
"price": 21500,
"fairPrice": 24900,
"place": "Mostar",
"url": "https://olx.ba/artikal/61234567",
"seller": "PRIVATE"
}
},
"created_at": "2026-10-20T06:09:31.000Z"
}
```
## Ne propustite alarm
Webhook je najbrži put, a lista je rezerva: ako je vaš sistem bio nedostupan, pročitajte `GET /v1/alerts?since=…` od zadnjeg obrađenog trenutka. Alarm ima stabilan `id`, pa isti alarm iz webhooka i liste obradite jednom.
---
# Webhookovi
Događaji u vaš sistem čim se dese: potpisani, s ponovnim pokušajima i logom isporuka.
Webhook je HTTPS adresa vašeg sistema na koju Cifra šalje `POST` s događajem. Dodajte je na platformi (Razvoj → Webhookovi) ili kroz API, odaberite događaje i sačuvajte tajnu (`whsec_…`) kojom provjeravate potpis.
```bash
curl -X POST "https://api.cifra.ba/v1/webhooks" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.firma.ba/cifra",
"events": [
"watchlist.alert",
"watchlist.report_ready"
],
"description": "Produkcija — kreditni sistem"
}'
```
```python
import os
import requests
response = requests.post(
"https://api.cifra.ba/v1/webhooks",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
json={
"url": "https://hooks.firma.ba/cifra",
"events": ["watchlist.alert", "watchlist.report_ready"],
"description": "Produkcija — kreditni sistem",
},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
## Događaji
### `watchlist.alert`
Alarm za praćeno vozilo. Pravilo vozila se aktiviralo: vrijednost se promijenila, prešla ciljnu cijenu ili LTV prag, ili je stigao povoljan oglas.
```json
{
"alert": {
"object": "alert",
"id": "alr_8fK2mQ9xLp4TvB7nR1sW",
"type": "value_changed",
"watched_vehicle": {
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"label": "VW Golf 1.6 TDI — ugovor 2024/118",
"external_ref": "2024/118",
"kind": "owned"
},
"day": "2026-10-15",
"previous_value": 21400,
"value": 20550,
"change_pct": -3.97,
"threshold": 3,
"details": null,
"created_at": "2026-10-15T06:12:44.000Z"
}
}
```
### `watchlist.report_ready`
Dnevni izvještaj spreman. Jutarnja procjena svih praćenih vozila je gotova; izvještaj dana čita se jednim pozivom.
```json
{
"day": "2026-10-15",
"vehicles": 412,
"alerts": 7,
"report_url": "/v1/watchlist/report?day=2026-10-15"
}
```
### `widget.rating_changed`
Promijenjena ocjena cijene. Jutarnja procjena je pomjerila ocjenu tražene cijene na vašem widgetu (npr. iz „Fer” u „Povišena”), ili je vozilo iz oglasa prodano.
```json
{
"widget": {
"object": "widget",
"id": "wgt_7Hq2Lm9PzX4cV1bN8sKd",
"public_id": "k3M9xQ2vTa",
"external_ref": "LAG-0412",
"title": "Volkswagen Golf 7 1.6 TDI Highline",
"status": "active",
"asking_price": 23900,
"value": 22950,
"previous_level": "fair",
"level": "high",
"pct": 4.14,
"day": "2026-10-15"
}
}
```
### `report.created`
Nova procjena na platformi. Nova procjena vozila na platformi: vrijednost, raspon, svrha i vaša referenca, da procjena odmah stigne u vaš sistem.
```json
{
"report": {
"object": "report",
"id": "cm2x8k1q00001",
"url": "https://enterprise.cifra.ba/valuations/cm2x8k1q00001",
"purpose": "financing",
"reference": "2024/118",
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf",
"make_name": "Volkswagen",
"model_name": "Golf",
"year": 2019,
"mileage_km": 98000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85
},
"value": 20550,
"low": 19300,
"high": 21900,
"currency": "BAM",
"grade": "A",
"as_of": "2026-10-15",
"created_by": {
"name": "Amra Hodžić",
"email": "amra@firma.ba"
},
"created_at": "2026-10-15T09:41:12.000Z"
}
}
```
### `check.completed`
Provjera vozila završena. Provjera oglasa je gotova (nova ili ponovljena): nivo pažnje i signali koje treba provjeriti.
```json
{
"check": {
"object": "vehicle_check",
"id": "cm2x9a7d00004",
"url": "https://enterprise.cifra.ba/check/cm2x9a7d00004",
"vehicle": "Volkswagen Golf 2016",
"listing_url": "https://olx.ba/artikal/61234567",
"level": "elevated",
"headline": "Kilometraža niža nego u ranijem oglasu",
"signals": [
{
"code": "mileage_rollback",
"severity": "high"
},
{
"code": "relisted_often",
"severity": "medium"
}
],
"purpose": "financing",
"reference": "2024/118",
"created_by": {
"name": "Amra Hodžić",
"email": "amra@firma.ba"
},
"checked_at": "2026-10-15T09:52:03.000Z"
}
}
```
### `check.decided`
Odluka o provjeri. Odluka tima o provjerenom vozilu: odobreno, dodatna provjera ili odbijeno, s napomenom.
```json
{
"check": {
"object": "vehicle_check",
"id": "cm2x9a7d00004",
"url": "https://enterprise.cifra.ba/check/cm2x9a7d00004",
"vehicle": "Volkswagen Golf 2016",
"level": "elevated",
"reference": "2024/118",
"decision": "review",
"decision_note": "Tražiti servisnu knjižicu prije odobrenja.",
"decided_by": {
"name": "Emir Kovač",
"email": "emir@firma.ba"
},
"decided_at": "2026-10-15T10:05:27.000Z"
}
}
```
### `bulk.completed`
Masovna procjena gotova. Svi redovi liste su procijenjeni: koliko vozila, ukupna vrijednost i veza na listu.
```json
{
"batch": {
"object": "valuation_batch",
"id": "cm2xa0b3k0009",
"url": "https://enterprise.cifra.ba/valuations/bulk/cm2xa0b3k0009",
"name": "Lizing portfelj Q3",
"purpose": "financing",
"as_of": "2026-09-30",
"rows": 1240,
"valued": 1228,
"failed": 12,
"total_value": 24118400,
"currency": "BAM",
"created_by": {
"name": "Amra Hodžić",
"email": "amra@firma.ba"
},
"completed_at": "2026-10-15T11:20:45.000Z"
}
}
```
### `usage.threshold_reached`
Potrošnja API-ja prešla prag. Ovomjesečne obračunske jedinice su prešle prag koji ste odabrali (npr. 80% ugovorene kvote).
```json
{
"month": "2026-10",
"threshold_pct": 80,
"units": 80214,
"quota": 100000,
"resets_at": "2026-11-01T00:00:00.000Z"
}
```
### `webhook.test`
Test. Probna poruka koju šaljete sami, da provjerite da adresa prima i provjerava potpis.
```json
{
"message": "A test event from Cifra."
}
```
## Zahtjev koji stiže
| Zaglavlje | Vrijednost |
| --- | --- |
| `Cifra-Signature` | `t=,v1=`; nakon zamjene tajne dva `v1` |
| `Cifra-Event-Id` | Oznaka događaja (`evt_…`), ista u svakom ponovnom pokušaju |
| `Cifra-Event-Type` | npr. `watchlist.alert` |
| `User-Agent` | `Cifra-Webhooks/1.0` |
**Tijelo**
```json
{
"id": "evt_2kQ9mX7vR4tL8bN1cZ5p",
"type": "watchlist.alert",
"created_at": "2026-12-02T06:12:44.000Z",
"livemode": true,
"data": {
"alert": {
"object": "alert",
"id": "alr_8fK2mQ9xLp4TvB7nR1sW",
"type": "exposure_above",
"watched_vehicle": {
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"kind": "owned"
},
"day": "2026-12-02",
"previous_value": 22350,
"value": 21400,
"change_pct": -4.25,
"threshold": 85,
"details": {
"exposure": {
"kind": "financing",
"amount": 18259,
"ratio": 0.8532
}
},
"created_at": "2026-12-02T06:12:44.000Z"
}
}
}
```
## Provjera potpisa
Potpis je HMAC-SHA256 nad `"."` vašom tajnom, heksadecimalno. Provjerite ga nad **sirovim** tijelom (prije parsiranja JSON-a), odbijte zahtjeve starije od 5 minuta i uporedite u konstantnom vremenu. Nakon zamjene tajne Cifra neko vrijeme potpisuje i starom (drugi `v1`): prihvatite ako odgovara bilo koji.
**Node.js**
```js
import crypto from "node:crypto";
import express from "express";
const SECRET = process.env.CIFRA_WEBHOOK_SECRET;
const app = express();
// The raw body: the signature is over the bytes as sent.
app.post("/cifra", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("Cifra-Signature") ?? "";
const t = Number(header.match(/t=(\d+)/)?.[1]);
const given = [...header.matchAll(/v1=([0-9a-f]+)/g)].map((m) => m[1]);
const expected = crypto
.createHmac("sha256", SECRET)
.update(`${t}.${req.body}`)
.digest("hex");
const fresh = Math.abs(Date.now() / 1000 - t) < 300;
const valid = given.some(
(v) => v.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)),
);
if (!fresh || !valid) return res.sendStatus(400);
const event = JSON.parse(req.body);
// A retried event carries the same id: process each id once.
queue.push(event);
res.sendStatus(200);
});
```
**Python**
```python
import hashlib, hmac, json, os, re, time
from flask import Flask, request, abort
SECRET = os.environ["CIFRA_WEBHOOK_SECRET"].encode()
app = Flask(__name__)
@app.post("/cifra")
def cifra():
header = request.headers.get("Cifra-Signature", "")
t = int(re.search(r"t=(\d+)", header).group(1))
given = re.findall(r"v1=([0-9a-f]+)", header)
raw = request.get_data() # the raw body, as sent
expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
if abs(time.time() - t) > 300 or not any(hmac.compare_digest(v, expected) for v in given):
abort(400)
event = json.loads(raw)
# A retried event carries the same id: process each id once.
enqueue(event)
return "", 200
```
**PHP**
```php
300) {
http_response_code(400);
exit;
}
$event = json_decode($raw, true);
// A retried event carries the same id: process each id once.
http_response_code(200);
```
**C#**
```csharp
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
app.MapPost("/cifra", async (HttpRequest request) =>
{
var secret = Environment.GetEnvironmentVariable("CIFRA_WEBHOOK_SECRET")!;
using var reader = new StreamReader(request.Body);
var raw = await reader.ReadToEndAsync(); // the raw body, as sent
var header = request.Headers["Cifra-Signature"].ToString();
var t = long.Parse(Regex.Match(header, @"t=(\d+)").Groups[1].Value);
var expected = Convert.ToHexString(
HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret),
Encoding.UTF8.GetBytes($"{t}.{raw}"))).ToLowerInvariant();
var valid = Regex.Matches(header, @"v1=([0-9a-f]+)")
.Any(m => CryptographicOperations.FixedTimeEquals(
Encoding.UTF8.GetBytes(m.Groups[1].Value), Encoding.UTF8.GetBytes(expected)));
if (!valid || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300)
return Results.BadRequest();
// A retried event carries the same id: process each id once.
return Results.Ok();
});
```
## Odgovor i ponovni pokušaji
Odgovorite `2xx` u roku od 10 sekundi — najbolje odmah, a događaj obradite u pozadini. Sve ostalo (drugi status, istek vremena, nedostupna adresa) je neuspjeh i Cifra pokušava ponovo:
| Pokušaj | Kad | Ukupno |
| --- | --- | --- |
| 1. | odmah | — |
| 2. | 1 min nakon prethodnog | ~1 min od prvog |
| 3. | 5 min nakon prethodnog | ~6 min od prvog |
| 4. | 30 min nakon prethodnog | ~36 min od prvog |
| 5. | 2 h nakon prethodnog | ~2.6 h od prvog |
| 6. | 6 h nakon prethodnog | ~8.6 h od prvog |
| 7. | 12 h nakon prethodnog | ~20.6 h od prvog |
| 8. | 1 dan nakon prethodnog | ~1.8583333333333334 dan od prvog |
- Nakon zadnjeg pokušaja isporuka je `failed`; vidi se u isporukama i može se ponovo poslati s platforme.
- Ako sve isporuke na adresu padaju **1 sat**, administratori kompanije dobiju email.
- Nakon **3 dana** samo neuspjeha adresa se isključuje (`disabled`), da ne gomila događaje; uključuje se na platformi.
- Redoslijed nije zagarantovan: koristite `created_at` događaja, ne redoslijed dolaska.
## Isprobavanje
[`POST /v1/webhooks/{id}/test`](https://www.cifra.ba/docs/api-reference/webhooks/test) šalje `webhook.test` odmah, a [isporuke](https://www.cifra.ba/docs/api-reference/webhooks/deliveries) pokazuju status, HTTP odgovor vaše adrese i grešku. Za lokalni razvoj koristite tunel (npr. ngrok) — adresa mora biti javna i HTTPS.
### Ograničenja
- Najviše 5 aktivnih adresa po okruženju (live i test odvojeno).
- Samo HTTPS na javne adrese; lokalne i privatne mreže se odbijaju, i pri dodavanju i pri svakoj isporuci.
- Zamjena tajne je na platformi: stara potpisuje još do 7 dana, po izboru.
> **Napomena:** Pogledajte i [listu svih događaja s primjerima](https://www.cifra.ba/docs/api-reference/webhook-events) i [vodič za alarme](https://www.cifra.ba/docs/api/alerts).
---
# Widgeti
Vaše procjene na vašoj stranici: ocjena tražene cijene, tržište i slična vozila, svako jutro ažurirano.
Widget prikazuje vozilo koje prodajete na vašoj stranici, uz nezavisnu ocjenu vaše cijene (odlična, dobra, fer, povišena ili visoka), tržište, slična vozila i vrijednost kroz vrijeme. Kroz API objavljujete **procjenu koju ste već napravili**: `POST /v1/widgets` s njenim `valuation_id` i vašom cijenom vraća javni kod i kod za ugradnju.
```bash
curl -X POST "https://api.cifra.ba/v1/widgets" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"valuation_id": "val_8fK2mQ9xLp4TvB7nR1sW",
"asking_price": 23900,
"external_ref": "LAG-0412"
}'
```
```python
import os
import requests
response = requests.post(
"https://api.cifra.ba/v1/widgets",
headers={"Authorization": f"Bearer {os.environ['CIFRA_API_KEY']}"},
json={
"valuation_id": "val_8fK2mQ9xLp4TvB7nR1sW",
"asking_price": 23900,
"external_ref": "LAG-0412",
},
timeout=30,
)
response.raise_for_status()
data = response.json()
```
## Kako radi
1. Procijenite vozilo produkcijskim ključem ([`POST /v1/valuations`](https://www.cifra.ba/docs/api-reference/valuations/create)) — to je jedina naplaćena radnja.
2. Objavite procjenu s `POST /v1/widgets`: `valuation_id`, `asking_price` i vaša oznaka (`external_ref`, npr. broj u lageru).
3. Iz odgovora sačuvajte `public_id` i stavite `embed.script` u predložak stranice vozila.
4. Cifra vozilo procjenjuje ponovo svako jutro; vi javljate samo promjene (`PATCH`) i prodaju (`DELETE`).
> **Pažnja:** Javna strana nikad ne poziva API: widgeti s cifra.ba čitaju gotov, keširan rezultat po `public_id`. API ključ ne ide u stranicu, a posjetilac ne može pokrenuti procjenu.
## Ocjena
`rating` poredi `asking_price` s tržišnom vrijednošću (`value.point`) u njenom realnom rasponu (`value.low`–`value.high`):
| `level` | Na widgetu | Kad |
| --- | --- | --- |
| `great` | Odlična cijena | Ispod raspona. |
| `good` | Dobra cijena | U rasponu, ispod pojasa fer cijene. |
| `fair` | Fer cijena | U pojasu oko vrijednosti: 35% polovine raspona, najmanje 3%, najviše 8%. |
| `high` | Povišena cijena | U rasponu, iznad pojasa fer cijene. |
| `over` | Visoka cijena | Iznad raspona. |
**rating**
```json
{
"level": "good",
"pct": -7.18,
"diff_bam": -1850
}
```
`pct` je razlika od vrijednosti u procentima (`-7.18` = 7,18% ispod), `diff_bam` u KM. Bez `asking_price`, ili s cijenom ispod 40% ili preko 250% vrijednosti, `rating` je `null` i widget pokazuje samo vrijednost.
> **Napomena:** Widget uvijek koristi Cifrin standardni tržišni model, i kad je procjena napravljena [vašim modelom](https://www.cifra.ba/docs/api/company-models): ocjena vaše cijene mora biti nezavisna.
## Ugradnja
Odgovor nosi gotov kod u `embed`:
- `script` (preporučeno): `widget.js` sam prilagodi visinu, učitava widget tek kad je blizu ekrana i dovoljan je jednom po stranici.
- `iframe`: za sisteme bez skripti, fiksne visine.
- `page_url`: stranica vozila na cifra.ba sa svim widgetima, za poruke kupcima.
`data-cifra-widget` bira widget: `badge` (oznaka uz cijenu), `price`, `market`, `comparables`, `forecast`, `factors`, `mileage` ili `report`. Izgled (`data-theme`, `data-accent`, `data-lang`…) i dozvoljene domene podešavate na platformi; sve opcije su u [vodiču za platformu](https://www.cifra.ba/docs/enterprise/widgets#kod).
**Oznaka uz cijenu i tržište na istoj stranici**
```html
```
> **Savjet:** Predložak stranice obično zna vašu oznaku, ne `public_id`: [`GET /v1/widgets?external_ref=…`](https://www.cifra.ba/docs/api-reference/widgets/list) ga vraća, ili ga sačuvajte uz vozilo pri objavi.
## Cijeli lager odjednom
[`POST /v1/widgets/batch`](https://www.cifra.ba/docs/api-reference/widgets/batch) objavljuje do 500 procjena u jednom pozivu; svaka uspije ili padne sama za sebe, s `index` stavke i greškom.
## Održavanje
- Nova cijena: [`PATCH`](https://www.cifra.ba/docs/api-reference/widgets/update) s `asking_price` (`null` je skriva i ostavlja samo vrijednost). Stranice je pokazuju za najviše 5 minuta.
- Novo očitanje kilometraže: `PATCH` s `mileage_km` — vozilo se odmah procjenjuje ponovo.
- Privremeno skriveno: `status: "paused"`; nazad s `"active"`.
- Prodano: [`DELETE`](https://www.cifra.ba/docs/api-reference/widgets/delete). Widgeti nestaju sa svih stranica, a mjesto u planu se oslobađa (pauzirana vozila ga zauzimaju).
## Webhook
Kad jutarnja procjena pomjeri ocjenu (npr. iz `fair` u `high`), stiže [`widget.rating_changed`](https://www.cifra.ba/docs/api-reference/webhook-events) — dobar trenutak da prodavac preispita cijenu. Adrese i potpis su u [Webhookovi](https://www.cifra.ba/docs/api/webhooks).
## Pravila
| Pravilo | Greška |
| --- | --- |
| Ključ s pristupom `widgets`, napravljen na platformi vaše kompanije. | `403 insufficient_scope`, `403 organization_required` |
| Samo produkcijski ključ: widgeti su javni i stoje na stvarnim procjenama. | `403 live_key_required` |
| Procjena napravljena produkcijskim ključem vaše kompanije. | `404 valuation_not_found` |
| `external_ref` jedinstven među vašim widgetima. | `409 duplicate_external_ref` |
| Objavljenih vozila najviše koliko plan dozvoljava: Business 1.000, Enterprise po ugovoru. | `409 widget_limit_reached` (s `limit` i `used`) |
Objava, izmjene, lista, jutarnje procjene i prikazi su besplatni. Widgeti objavljeni kroz API i na platformi su isti: vide se u **Razvoj → Widgeti**, sa statistikom prikaza po stranici i vozilu.
---
# Osiguranje: vrijednost na dan štete
Tržišna vrijednost vozila na dan štete ili krađe, s rasponom za odluku i zapisom za reviziju.
Kod totalne štete ili krađe trebate vrijednost vozila **na dan događaja**, ne na dan obrade. Procjena s `as_of` računa tačno to: nivo tržišta i starost vozila tog dana.
### 1. Sakupite podatke iz polise i prijave
Marka, model i godište iz polise; kilometraža na dan štete iz zapisnika; snaga, zapremina, gorivo i mjenjač iz saobraćajne. Što potpuniji unos, uži raspon.
### 2. Procijenite na dan događaja
```python
def claim_value(claim):
valuation = cifra("POST", "/v1/valuations", json={
"make": claim.make_slug, # iz vaše tabele veza sa šifarnikom
"model": claim.model_slug,
"year": claim.year,
"mileage_km": claim.mileage_at_loss,
"power_kw": claim.power_kw,
"engine_cc": claim.engine_cc,
"fuel": claim.fuel,
"transmission": claim.transmission,
"city": claim.city,
"as_of": claim.loss_date.isoformat(), # dan štete
"include": ["explanation"],
})
mv = valuation["market_value"]
return {
"valuation_id": valuation["id"], # čuvajte za reviziju
"model_version": valuation["model_version"],
"value": mv["point"],
"range": (mv["low"], mv["high"]),
"grade": mv["confidence_grade"],
"needs_review": mv["confidence_grade"] == "C" or bool(valuation["warnings"]),
"explanation": valuation["explanation"]["lines"],
}
```
### 3. Odlučite uz raspon
- Ocjena `A` ili `B` bez upozorenja: vrijednost može ići u automatski prijedlog isplate.
- Ocjena `C` ili `partial_inputs`: tražite dopunu podataka ili procjenitelja.
- Obračun (`explanation`) priložite uz rješenje: korisniku objašnjava iznos po stavkama.
### 4. Sačuvajte trag
Uz štetu čuvajte `valuation_id` i `model_version`. Procjenu i tačan zahtjev uvijek možete ponovo pročitati s [`GET /v1/valuations/{id}`](https://www.cifra.ba/docs/api-reference/valuations/retrieve).
> **Savjet:** Kad vozilo bude prodano kao ostatak ili popravljeno pa prodano, javite cijenu s `POST /v1/valuations/{id}/outcome` — besplatno je i poboljšava procjene prodajne cijene.
---
# Lizing: portfelj s LTV alarmima
Cijeli portfelj u praćenju, dnevni LTV svakog ugovora i alarm kad dug pređe vrijednost vozila.
Za lizing kuće i banke vrijednost kolaterala se mijenja svaki dan, a dug pada po otplatnom planu. Praćenje vozila računa oboje i javi kad odnos postane rizičan.
### 1. Uvezite portfelj
Svaki ugovor kao vlastito vozilo s izloženošću `financing`; broj ugovora u `external_ref`.
```js
const items = contracts.map((c) => ({
kind: "owned",
external_ref: c.contractNo,
label: `${c.vehicleName} — ${c.contractNo}`,
vehicle: {
make: c.makeSlug, model: c.modelSlug, year: c.year,
mileage_km: c.mileageAtStart, power_kw: c.powerKw,
fuel: c.fuel, transmission: c.transmission,
},
km_per_year: c.expectedKmPerYear,
exposure: {
kind: "financing",
amount_bam: c.outstanding, // stanje danas
as_of: today,
term_months: c.monthsLeft,
annual_rate_pct: c.ratePct,
balloon_bam: c.residual ?? 0, // otkupna vrijednost na kraju
},
alerts: { exposure_pct: 90, change_pct: 10, direction: "down" },
tags: [c.branch],
}));
for (let i = 0; i < items.length; i += 500) {
const res = await cifra("/v1/watchlist/batch", {
method: "POST",
body: JSON.stringify({ items: items.slice(i, i + 500) }),
});
for (const r of res.data.filter((r) => r.error)) log(items[i + r.index], r.error);
}
```
### 2. Primajte alarme
Dodajte webhook za `watchlist.alert` i `watchlist.report_ready`. Alarm `exposure_above` nosi ugovor (`external_ref`), dug i LTV tog dana.
### 3. Čitajte jutarnji izvještaj
Na `watchlist.report_ready` pročitajte [dnevni izvještaj](https://www.cifra.ba/docs/api-reference/watchlist/report): za svaki ugovor vrijednost, promjenu i `exposure.ratio`. Filtrirajte po `external_ref` za jedan ugovor.
### 4. Održavajte stanje
- Dug se otplaćuje sam po planu; `PATCH` s novom `exposure` samo kad se plan promijeni (prijevremena otplata, reprogram).
- Novo očitanje kilometraže (servis, povrat vozila): `PATCH` s `mileage_km`.
- Ugovor zatvoren: `DELETE`.
> **Napomena:** Za rezidualne vrijednosti na kraju ugovora koristite prognozu procjene (`forecast`) ili Rezidual na platformi s krivama po modelu.
---
# Otkup: provjera i ponuda
Od linka oglasa do ponude za otkup: historija vozila, signali, tržišna vrijednost i slična vozila.
Salon dobije link oglasa ili vozilo na otkup. U dva poziva ima sve za ponudu:
1. **Provjera vozila**: historija oglasa i signali — ako je `level` `high`, vozilo ide na detaljan pregled prije ponude.
2. **Procjena** sa sličnim vozilima: tržišna vrijednost i šta konkurencija traži za isto vozilo danas.
**JavaScript**
```js
async function intake(listingUrl, vehicle) {
const [history, valuation] = await Promise.all([
cifra(`/v1/vehicle-history?listing_url=${encodeURIComponent(listingUrl)}`),
cifra("/v1/valuations", {
method: "POST",
body: JSON.stringify({ ...vehicle, include: ["explanation", "comparables"] }),
}),
]);
const value = valuation.market_value.point;
const margin = 0.12; // vaša marža i troškovi pripreme
return {
offer: Math.round((value * (1 - margin)) / 100) * 100,
value,
range: [valuation.market_value.low, valuation.market_value.high],
review: history.level === "high",
signals: history.signals.map((s) => s.summary),
competing: valuation.comparables.items, // isto vozilo u prodaji danas
};
}
```
> **Pažnja:** Signal nije presuda: `mileage_rollback` ili `photos_other_vehicle` znače da treba pogledati dokumente i vozilo, ne da je prodavac prevarant.
> **Savjet:** Za vlastitu politiku otkupa umjesto fiksne marže koristite [Vaš model](https://www.cifra.ba/docs/api/company-models): naučen na vašim otkupima, vraća otkupnu cijenu kakvu biste vi dali.
---
# Kontrolna lista za produkciju
Šta provjeriti prije nego što integracija pređe na live ključ.
| | Provjera |
| --- | --- |
| Ključevi | Live ključ samo s pristupom koji treba, u trezoru tajni, ne u kodu ni u repozitoriju. Poseban ključ po sistemu (core, CRM, web), da ih možete odvojeno pratiti i opozvati. |
| IP adrese | Ako zovete s poznatih servera, ograničite ključ na njih. |
| Šifarnik | Tabela veza s vašim šiframa vozila, osvježavanje jednom dnevno, obrada `unknown_make`/`unknown_model`. |
| Greške | Granjanje po `code`; ponavljanje samo `429` i `5xx` s čekanjem; `request_id` u vašim logovima. |
| Limiti | Zahtjevi raspoređeni u okviru limita u minuti; velike liste kroz masovnu procjenu. |
| Kvota | Pragovi obavještenja postavljeni na platformi (npr. 80% i 100%). |
| Upozorenja | Prikazana ili zabilježena; nepoznata šifra ne ruši integraciju. |
| Webhookovi | Provjera potpisa nad sirovim tijelom, odgovor `2xx` odmah, obrada u pozadini, svaki `id` jednom. |
| Revizija | Uz svaku odluku sačuvani `valuation_id` i `model_version`. |
| Nepoznata polja | Integracija zanemaruje nova polja u odgovorima. |
## Test u sandboxu
1. Ispravna procjena s potpunim i s minimalnim unosom.
2. Nepoznata marka i model, godište u budućnosti, nepoznato polje.
3. Masovna lista s jednim neispravnim vozilom.
4. `webhook.test` na vašu adresu i provjera potpisa.
---
# Sigurnost
Kako čuvamo vaše podatke i kako da vi čuvate ključeve.
## Kod nas
- Samo HTTPS. Ključevi se čuvaju kao SHA-256 sažeci; ni Cifra ne može pročitati vaš ključ nakon što ga napravite.
- Podaci vaše kompanije (procjene, praćena vozila, webhookovi, podaci vašeg modela) vidljivi su samo vašim ključevima i timu na platformi, odvojeno za live i test.
- Vaše cijene nikad ne ulaze u Cifrin tržišni model niti ih vide druge kompanije.
- Log zahtjeva čuva se 30 dana; tijelo zahtjeva samo kod grešaka, do 4 KB.
- Webhookovi idu samo na javne HTTPS adrese, potpisani vašom tajnom.
## Kod vas
- Ključ samo na serveru, u varijabli okruženja ili trezoru tajni.
- Najmanji potreban pristup, dozvoljene IP adrese, mjesečni limit po ključu.
- Redovna zamjena ključeva bez prekida (stari radi još do 7 dana).
- Procuren ključ odmah opozovite na platformi.
> **Napomena:** Za DPA, pitanja o obradi podataka ili sigurnosne upitnike pišite na [podrska@cifra.ba](mailto:podrska@cifra.ba).
---
# Podrška
Kako najbrže doći do odgovora kad nešto ne radi.
1. Pogledajte Razvoj → Zahtjevi na platformi: svaki zahtjev zadnjih 30 dana, s greškom i tijelom neuspjelog zahtjeva.
2. Provjerite šifru greške u [Šifre grešaka](https://www.cifra.ba/docs/api-reference/errors).
3. Pišite na [podrska@cifra.ba](mailto:podrska@cifra.ba) ili u chatu na platformi, s `request_id`, vremenom i šifrom greške.
Enterprise ugovori imaju posvećenog menadžera i vrijeme odgovora iz ugovora.
---
# OpenAPI i alati
Specifikacija za Postman, generisanje klijenta i AI asistente.
Cijeli API je opisan u OpenAPI 3.1, iz istih šema kojima API provjerava zahtjeve: [/docs/openapi.json](https://www.cifra.ba/docs/openapi.json) (isto na `https://api.cifra.ba/v1/openapi.json`). Sadrži sve endpointe, polja, primjere, greške i webhook događaje.
## Postman i Insomnia
Import → Link → zalijepite adresu specifikacije. Kolekcija ima sve endpointe s primjerima; ključ postavite kao Bearer token.
## Generisanje klijenta
```bash
# TypeScript tipovi
npx openapi-typescript https://www.cifra.ba/docs/openapi.json -o cifra.d.ts
# Klijent za C#, Javu, PHP, Python… (openapi-generator)
npx @openapitools/openapi-generator-cli generate \
-i https://www.cifra.ba/docs/openapi.json -g csharp -o ./cifra-client
```
## AI asistenti
- [/docs/llms.txt](https://www.cifra.ba/docs/llms.txt): pregled dokumentacije s linkovima, po standardu llms.txt.
- [/docs/llms-full.txt](https://www.cifra.ba/docs/llms-full.txt): cijela dokumentacija kao jedan tekst — dajte je asistentu kao kontekst.
- „Kopiraj stranicu” na svakoj stranici: Markdown za razgovor s asistentom.
---
# API referenca
Svaki endpoint Cifra API-ja: parametri, polja odgovora, greške i primjeri u sedam jezika.
**Osnovna adresa**
```text
https://api.cifra.ba/v1
```
| | |
| --- | --- |
| Autentifikacija | `Authorization: Bearer cfr_live_…` ([više](https://www.cifra.ba/docs/api/authentication)) |
| Format | JSON, UTF-8, `snake_case`; nepoznata polja se odbijaju ([konvencije](https://www.cifra.ba/docs/api/conventions)) |
| Greške | `application/problem+json` sa stabilnom šifrom u `code` ([šifre](https://www.cifra.ba/docs/api-reference/errors)) |
| Limiti | `x-ratelimit-*` i `x-quota-remaining` u svakom odgovoru ([limiti](https://www.cifra.ba/docs/api/limits)) |
| Specifikacija | [OpenAPI 3.1](https://www.cifra.ba/docs/openapi.json) — Postman, generisanje klijenta |
## Endpointi
**Procjene**
| Endpoint | | Obračun |
| --- | --- | --- |
| `POST /v1/valuations` | [Procjena vozila](https://www.cifra.ba/docs/api-reference/valuations/create) | 1 jedinica |
| `POST /v1/valuations/batch` | [Masovna procjena](https://www.cifra.ba/docs/api-reference/valuations/batch) | 1 jedinica po stavci |
| `GET /v1/valuations/{id}` | [Čitanje procjene](https://www.cifra.ba/docs/api-reference/valuations/retrieve) | besplatno |
| `POST /v1/valuations/{id}/outcome` | [Prijava prodajne cijene](https://www.cifra.ba/docs/api-reference/valuations/outcome) | besplatno |
**Šifarnik**
| Endpoint | | Obračun |
| --- | --- | --- |
| `GET /v1/taxonomy/makes` | [Marke](https://www.cifra.ba/docs/api-reference/taxonomy/makes) | besplatno |
| `GET /v1/taxonomy/makes/{make}/models` | [Modeli marke](https://www.cifra.ba/docs/api-reference/taxonomy/models) | besplatno |
| `GET /v1/taxonomy/values` | [Dozvoljene vrijednosti](https://www.cifra.ba/docs/api-reference/taxonomy/values) | besplatno |
**Provjera vozila**
| Endpoint | | Obračun |
| --- | --- | --- |
| `GET /v1/vehicle-history` | [Historija vozila](https://www.cifra.ba/docs/api-reference/vehicle-history/retrieve) | 1 jedinica |
**Praćenje vozila**
| Endpoint | | Obračun |
| --- | --- | --- |
| `POST /v1/watchlist` | [Praćenje vozila](https://www.cifra.ba/docs/api-reference/watchlist/create) | 1 jedinica |
| `POST /v1/watchlist/batch` | [Uvoz portfelja](https://www.cifra.ba/docs/api-reference/watchlist/batch) | 1 jedinica po stavci |
| `GET /v1/watchlist` | [Lista praćenih vozila](https://www.cifra.ba/docs/api-reference/watchlist/list) | besplatno |
| `GET /v1/watchlist/{id}` | [Praćeno vozilo](https://www.cifra.ba/docs/api-reference/watchlist/retrieve) | besplatno |
| `PATCH /v1/watchlist/{id}` | [Izmjena praćenog vozila](https://www.cifra.ba/docs/api-reference/watchlist/update) | besplatno |
| `DELETE /v1/watchlist/{id}` | [Prestanak praćenja](https://www.cifra.ba/docs/api-reference/watchlist/delete) | besplatno |
| `GET /v1/watchlist/{id}/history` | [Historija vrijednosti](https://www.cifra.ba/docs/api-reference/watchlist/history) | besplatno |
| `GET /v1/watchlist/report` | [Dnevni izvještaj](https://www.cifra.ba/docs/api-reference/watchlist/report) | besplatno |
**Alarmi**
| Endpoint | | Obračun |
| --- | --- | --- |
| `GET /v1/alerts` | [Lista alarma](https://www.cifra.ba/docs/api-reference/alerts/list) | besplatno |
**Webhookovi**
| Endpoint | | Obračun |
| --- | --- | --- |
| `POST /v1/webhooks` | [Nova webhook adresa](https://www.cifra.ba/docs/api-reference/webhooks/create) | besplatno |
| `GET /v1/webhooks` | [Lista webhook adresa](https://www.cifra.ba/docs/api-reference/webhooks/list) | besplatno |
| `DELETE /v1/webhooks/{id}` | [Isključivanje adrese](https://www.cifra.ba/docs/api-reference/webhooks/delete) | besplatno |
| `POST /v1/webhooks/{id}/test` | [Probni događaj](https://www.cifra.ba/docs/api-reference/webhooks/test) | besplatno |
| `GET /v1/webhooks/{id}/deliveries` | [Isporuke](https://www.cifra.ba/docs/api-reference/webhooks/deliveries) | besplatno |
**Widgeti**
| Endpoint | | Obračun |
| --- | --- | --- |
| `POST /v1/widgets` | [Objava widgeta](https://www.cifra.ba/docs/api-reference/widgets/create) | besplatno |
| `POST /v1/widgets/batch` | [Objava više widgeta](https://www.cifra.ba/docs/api-reference/widgets/batch) | besplatno |
| `GET /v1/widgets` | [Lista widgeta](https://www.cifra.ba/docs/api-reference/widgets/list) | besplatno |
| `GET /v1/widgets/{id}` | [Widget](https://www.cifra.ba/docs/api-reference/widgets/retrieve) | besplatno |
| `PATCH /v1/widgets/{id}` | [Izmjena widgeta](https://www.cifra.ba/docs/api-reference/widgets/update) | besplatno |
| `DELETE /v1/widgets/{id}` | [Uklanjanje widgeta](https://www.cifra.ba/docs/api-reference/widgets/delete) | besplatno |
## Isprobajte odmah
Svaka stranica endpointa ima **Isprobaj**: pošaljite zahtjev s vašim ključem direktno iz dokumentacije i vidite pravi odgovor sa zaglavljima. Testni ključ (`cfr_test_…`) ništa ne naplaćuje.
- [Brzi početak](https://www.cifra.ba/docs/api/quickstart): Od ključa do prve procjene.
- [Webhook događaji](https://www.cifra.ba/docs/api-reference/webhook-events): Svi događaji s primjerima tijela.
---
# Procjena vozila
`POST https://api.cifra.ba/v1/valuations`
Tržišna vrijednost vozila s rasponom od 80% i ocjenom pouzdanosti, uz obračun po faktorima, prognozu i slična vozila u prodaji. Obavezni su `make`, `model`, `year` i `mileage_km`; svaki dodatni podatak sužava raspon.
Pristup: `valuations`. Obračun: 1 jedinica.
## Tijelo zahtjeva
- `vehicle_type` (enum, podrazumijevano "car") — Vrsta vozila. Svaka vrsta ima svoj model, šifarnik i polja koja prima. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno, do 64 znaka) — Marka kao šifra iz `GET /v1/taxonomy/makes`, npr. `volkswagen`, `mercedes_benz`, `škoda`.
- `model` (string, obavezno, do 64 znaka) — Model kao šifra iz `GET /v1/taxonomy/makes/{make}/models`, npr. `golf_7`.
- `year` (integer, obavezno, najmanje 1950) — Godište (modelska godina). Najviše sljedeća godina.
- `mileage_km` (integer, obavezno, 0 – 2.000.000) — Pređeni kilometri na dan procjene.
- `power_kw` (number, 2 – 1000) — Snaga motora u kW. Jedan od najvažnijih podataka za cijenu.
- `power_hp` (number, 3 – 1400) — Snaga u KS; koristi se samo kad `power_kw` nije poslan.
- `engine_cc` (integer, 40 – 20.000) — Zapremina motora u cm³.
- `fuel` (enum) — Gorivo. Vrijednosti: `petrol`, `diesel`, `lpg`, `cng`, `hybrid`, `plugin_hybrid`, `electric`, `hydrogen`, `other`.
- `transmission` (enum) — Mjenjač. Vrijednosti: `manual`, `automatic`, `semi_automatic`.
- `drivetrain` (enum) — Pogon. Samo automobili. Vrijednosti: `fwd`, `rwd`, `awd`.
- `body_type` (enum) — Karoserija. Samo automobili. Vrijednosti: `sedan`, `hatchback`, `wagon`, `suv`, `coupe`, `convertible`, `minivan`, `van`, `pickup`, `other`.
- `doors` (integer, 2 – 5) — Broj vrata. Samo automobili.
- `condition` (enum) — Stanje: `used` (podrazumijevano) ili `new`. Vrijednosti: `used`, `new`.
- `seller_type` (enum) — Ko prodaje: privatna osoba ili salon. Vrijednosti: `private`, `dealer`.
- `city` (string, do 80 znakova) — Grad u BiH, npr. `Sarajevo` ili `Banja Luka`. Regionalna potražnja pomjera cijenu.
- `equipment` (string[], do 150 stavki) — Oprema kako je navodi oglas ili vaš sistem, npr. `navigacija`, `kožna sjedišta`.
- `owners_count` (integer, 1 – 20) — Broj dosadašnjih vlasnika.
- `customs_cleared` (boolean) — Je li vozilo ocarinjeno.
- `service_history` (boolean) — Ima li vozilo servisnu historiju (knjižicu).
- `category` (string, do 60 znakova) — Motocikli: tip (`Naked`, `Scooter`, `Enduro`…); kamioni: nadogradnja (`Kiper`, `Kombi`…). Vrijednosti: `GET /v1/taxonomy/values`.
- `abs` (boolean) — ABS. Samo motocikli.
- `axles` (integer, 1 – 6) — Broj osovina. Samo kamioni.
- `payload_class` (string, do 40 znakova) — Nosivost kao razred iz `GET /v1/taxonomy/values`. Samo kamioni.
- `as_of` (date) — Datum procjene (`YYYY-MM-DD`), od 2015-01-01 do danas: vrijednost kakva je bila tog dana, npr. na dan štete. Podrazumijevano danas (UTC).
- `include` (enum[], do 3 stavke) — Dodaci odgovoru: `explanation` (obračun cijene), `forecast` (vrijednost kroz 6–36 mjeseci), `comparables` (slična vozila u prodaji). Bez polja: `explanation` i `forecast`; `[]` vraća samo vrijednost. Vrijednosti: `explanation`, `forecast`, `comparables`.
- `km_per_year` (integer, 0 – 150.000) — Koliko će vozilo prelaziti godišnje, za prognozu. Podrazumijevano: njegov dosadašnji prosjek.
- `valuation_model` (enum) — `auto` (podrazumijevano): vaš model kompanije kad je u upotrebi, inače standardni; `standard`: uvijek standardni tržišni model. Vrijednosti: `auto`, `standard`.
## Odgovor 201
- `id` (string, obavezno) — Oznaka procjene (`val_…`); po njoj je čitate i javljate prodajnu cijenu.
- `object` (string, obavezno) — Uvijek `valuation`. Vrijednosti: `valuation`.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `model_version` (string, obavezno) — Verzija modela koji je procijenio, npr. `car-20261017-1`.
- `valued_by` (object, obavezno) — Koji model je odgovorio.
- `kind` (enum, obavezno) — `standard`: Cifrin tržišni model; `custom`: model vaše kompanije. Vrijednosti: `standard`, `custom`.
- `version` (string, obavezno) — Verzija modela koji je odgovorio, npr. `car-20261017-1`.
- `custom_model_id` (integer) — Model kompanije: njegov broj.
- `name` (string) — Model kompanije: naziv koji ste mu dali.
- `price_kind` (enum) — Model kompanije: koje cijene je učio, pa šta vrijednost znači — prodajne, nabavne, oglasne ili procjene. Vrijednosti: `sale`, `purchase`, `asking`, `appraisal`.
- `base_version` (string) — Model kompanije: standardni model na kojem je napravljen.
- `fallback` (string) — Vaš model trenutno nije mogao odgovoriti, pa je odgovorio standardni. Vrijednosti: `custom_model_unavailable`.
- `sandbox` (boolean) — Samo testni ključevi: fiksne primjer-vrijednosti. Vrijednosti: `true`.
- `vehicle` (object, obavezno) — Procijenjeno vozilo, s nazivima iz šifarnika.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `make_name` (string, obavezno) — Naziv marke, npr. `Volkswagen`.
- `model` (string, obavezno) — Šifra modela.
- `model_name` (string, obavezno) — Naziv modela, npr. `Golf 7`.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `as_of` (string, obavezno) — Dan na koji važi vrijednost.
- `market_value` (object, obavezno) — Tržišna vrijednost s rasponom od 80% i ocjenom pouzdanosti.
- `currency` (string, obavezno) — Uvijek `BAM` (konvertibilna marka). Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Tržišna vrijednost, zaokružena na 10 KM.
- `low` (integer, obavezno) — Donja granica raspona.
- `high` (integer, obavezno) — Gornja granica raspona.
- `confidence_grade` (enum, obavezno) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `range_probability` (number, obavezno) — Vjerovatnoća da je cijena u rasponu: `0.8` (80%).
- `definition` (string, obavezno) — Šta tačno vrijednost znači, jednom rečenicom.
- `standard_value` (object) — Samo uz model kompanije: šta kaže standardni tržišni model, za poređenje.
- `currency` (string, obavezno) — `BAM`. Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Vrijednost po standardnom modelu.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `confidence_grade` (enum, obavezno) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `model_version` (string, obavezno) — Verzija standardnog modela.
- `explanation` (object) — Obračun cijene po faktorima (uz `include: ["explanation"]`).
- `lines` (object[], obavezno) — Linije koje se tačno sabiraju u `market_value.point`.
- `id` (enum, obavezno) — Faktor: `base` (bazna vrijednost modela), `mileage`, `equipment` (oprema i motorizacija), `history` (stanje i historija), `region`, `market`, `adjustment` (korekcija tržišnog tima). Vrijednosti: `base`, `mileage`, `equipment`, `history`, `region`, `market`, `adjustment`.
- `label` (string, obavezno) — Naziv faktora na bosanskom, za prikaz korisniku.
- `amount_bam` (integer, obavezno) — Prva linija: bazna vrijednost; ostale: koliko faktor dodaje ili oduzima.
- `method` (string, obavezno) — Kako je obračun nastao.
- `forecast` (object) — Prognoza vrijednosti (uz `include: ["forecast"]`): naučena kriva gubitka vrijednosti, uz današnji nivo tržišta.
- `status` (string, obavezno) — `beta`. Vrijednosti: `beta`.
- `km_per_year` (integer, obavezno) — Godišnja kilometraža pretpostavljena u prognozi.
- `points` (object[], obavezno) — Vrijednost kroz vrijeme, s rasponom koji se širi.
- `months` (integer, obavezno) — Mjeseci od `as_of`: 6, 12, 24, 36.
- `point` (integer, obavezno) — Očekivana vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `method` (string, obavezno) — Kako je prognoza nastala.
- `sale_price` (object, obavezno) — Procjena stvarne prodajne cijene: u pripremi.
- `status` (string, obavezno) — Još nije dostupno. Vrijednosti: `unavailable`.
- `detail` (string, obavezno) — Zašto.
- `time_to_sell` (object, obavezno) — Očekivano vrijeme do prodaje: u pripremi.
- `status` (string, obavezno) — Još nije dostupno. Vrijednosti: `unavailable`.
- `detail` (string, obavezno) — Zašto.
- `adjustment` (object) — Kad Cifrin tržišni tim privremeno koriguje model za neki segment (najviše ±15%, do 180 dana).
- `multiplier` (number, obavezno) — Faktor korekcije, npr. `0.97`.
- `reason` (string, obavezno) — Razlog korekcije.
- `warnings` (object[], obavezno) — Upozorenja uz procjenu. Prazna lista znači da nema ničeg posebnog.
- `code` (string, obavezno) — Stabilna šifra upozorenja, npr. `partial_inputs`.
- `message` (string, obavezno) — Objašnjenje na engleskom, za logove i podršku.
- `comparables` (object) — Slična vozila trenutno u prodaji (uz `include: ["comparables"]`): ista marka i model, godište ±2, poredana po sličnosti.
- `total` (integer, obavezno) — Koliko sličnih vozila je trenutno u prodaji.
- `items` (object[], obavezno) — Do 8 najsličnijih.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `fuel` (string, obavezno) — Gorivo.
- `transmission` (string, obavezno) — Mjenjač.
- `power_kw` (number, obavezno) — Snaga u kW.
- `engine_cc` (integer, obavezno, može biti null) — Zapremina u cm³.
- `city` (string, obavezno) — Mjesto.
- `asking_price_bam` (integer, obavezno) — Cijena u oglasu.
- `cifra_value_bam` (integer, obavezno) — Cifrina vrijednost tog vozila.
- `price_vs_value_pct` (number, obavezno) — Koliko oglas traži iznad (+) ili ispod (−) Cifrine vrijednosti, u %.
- `days_listed` (integer, obavezno, može biti null) — Dana u prodaji.
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `422 unknown_make` — Marka nije u šifarniku (odgovor nosi `field`).
- `422 unknown_model` — Model nije u šifarniku te marke.
- `422 vehicle_type_unavailable` — Procjene za tu vrstu vozila trenutno nisu dostupne.
- `422 as_of_in_future` — `as_of` je u budućnosti.
- `422 as_of_too_early` — `as_of` je prije 2015-01-01.
- `422 year_after_as_of` — Godište je kasnije od datuma procjene.
- `409 pinned_model_unavailable` — Ključ je vezan za verziju modela koja trenutno ne radi za ovu vrstu vozila.
- `503 model_unavailable` — Model trenutno nije dostupan (npr. tokom pokretanja).
## Primjer
```bash
curl -X POST "https://api.cifra.ba/v1/valuations" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"engine_cc": 1598,
"fuel": "diesel",
"transmission": "manual",
"body_type": "hatchback",
"city": "Sarajevo",
"include": [
"explanation",
"forecast",
"comparables"
]
}'
```
```json
{
"id": "val_yXpheA0qNLw6gYKCq6k1",
"object": "valuation",
"created_at": "2026-10-18T21:57:02.773Z",
"model_version": "car-20261017-1",
"valued_by": {
"kind": "standard",
"version": "car-20261017-1"
},
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"make_name": "Volkswagen",
"model": "golf_7",
"model_name": "Golf 7",
"year": 2017,
"mileage_km": 148000
},
"as_of": "2026-10-18",
"market_value": {
"currency": "BAM",
"point": 22350,
"low": 18610,
"high": 26790,
"confidence_grade": "A",
"range_probability": 0.8,
"definition": "Asking price at which a comparable vehicle is listed by a private seller on the valuation date; the range holds the price with 80% probability."
},
"explanation": {
"lines": [
{
"id": "base",
"label": "Bazna vrijednost modela",
"amount_bam": 22950
},
{
"id": "mileage",
"label": "Kilometraža",
"amount_bam": 3270
},
{
"id": "equipment",
"label": "Oprema i motorizacija",
"amount_bam": -3090
},
{
"id": "history",
"label": "Stanje i historija vozila",
"amount_bam": -20
},
{
"id": "region",
"label": "Regionalna potražnja",
"amount_bam": -230
},
{
"id": "market",
"label": "Stanje tržišta",
"amount_bam": -530
}
],
"method": "TreeSHAP contributions of the valuation model, grouped by factor and applied in order."
},
"forecast": {
"status": "beta",
"km_per_year": 15110,
"points": [
{
"months": 6,
"point": 21380,
"low": 16350,
"high": 26450
},
{
"months": 12,
"point": 20450,
"low": 14670,
"high": 25990
},
{
"months": 24,
"point": 18710,
"low": 13890,
"high": 23530
},
{
"months": 36,
"point": 17150,
"low": 12190,
"high": 22020
}
],
"method": "Learned depreciation curve for this age and brand tier; market level held at today's."
},
"comparables": {
"total": 502,
"items": [
{
"year": 2017,
"mileage_km": 154115,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85,
"engine_cc": 1600,
"city": "Bihać",
"asking_price_bam": 20999,
"cifra_value_bam": 22370,
"price_vs_value_pct": -6.1,
"days_listed": 103
},
{
"year": 2017,
"mileage_km": 160000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85,
"engine_cc": 1600,
"city": "Bijeljina",
"asking_price_bam": 23500,
"cifra_value_bam": 22480,
"price_vs_value_pct": 4.5,
"days_listed": 70
},
{
"year": 2017,
"mileage_km": 142000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85,
"engine_cc": 1600,
"city": "Konjic",
"asking_price_bam": 27300,
"cifra_value_bam": 22520,
"price_vs_value_pct": 21.2,
"days_listed": 43
}
]
},
"sale_price": {
"status": "unavailable",
"detail": "Needs transaction data; planned as an experimental output."
},
"time_to_sell": {
"status": "unavailable",
"detail": "Needs a few months of market exit data; planned."
},
"warnings": []
}
```
---
# Masovna procjena
`POST https://api.cifra.ba/v1/valuations/batch`
Do `batch_max_items` vozila u jednom pozivu (Business: 100). Svako vozilo se provjerava i procjenjuje zasebno: neispravno vraća grešku na svom mjestu, ostala se procijene. Naplaćuje se svako procijenjeno vozilo.
Pristup: `valuations`. Obračun: 1 jedinica po stavci.
## Tijelo zahtjeva
- `items` (any[], obavezno, 1–1000 stavki) — Vozila, svako kao tijelo `POST /v1/valuations`. Najviše koliko dozvoljava vaš plan (`batch_max_items`).
- `include` (enum[], do 3 stavke) — Dodaci za svako vozilo koje nema svoj `include`. Bez polja: samo vrijednost. `comparables` se ne vraća u masovnoj procjeni. Vrijednosti: `explanation`, `forecast`, `comparables`.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `data` (object[], obavezno) — Rezultat za svako vozilo, istim redom kao `items`.
- `index` (integer, obavezno) — Mjesto vozila u `items`.
- `valuation` (object) — Procjena, ako je uspjela.
- `id` (string, obavezno) — Oznaka procjene (`val_…`); po njoj je čitate i javljate prodajnu cijenu.
- `object` (string, obavezno) — Uvijek `valuation`. Vrijednosti: `valuation`.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `model_version` (string, obavezno) — Verzija modela koji je procijenio, npr. `car-20261017-1`.
- `valued_by` (object, obavezno) — Koji model je odgovorio.
- `kind` (enum, obavezno) — `standard`: Cifrin tržišni model; `custom`: model vaše kompanije. Vrijednosti: `standard`, `custom`.
- `version` (string, obavezno) — Verzija modela koji je odgovorio, npr. `car-20261017-1`.
- `custom_model_id` (integer) — Model kompanije: njegov broj.
- `name` (string) — Model kompanije: naziv koji ste mu dali.
- `price_kind` (enum) — Model kompanije: koje cijene je učio, pa šta vrijednost znači — prodajne, nabavne, oglasne ili procjene. Vrijednosti: `sale`, `purchase`, `asking`, `appraisal`.
- `base_version` (string) — Model kompanije: standardni model na kojem je napravljen.
- `fallback` (string) — Vaš model trenutno nije mogao odgovoriti, pa je odgovorio standardni. Vrijednosti: `custom_model_unavailable`.
- `sandbox` (boolean) — Samo testni ključevi: fiksne primjer-vrijednosti. Vrijednosti: `true`.
- `vehicle` (object, obavezno) — Procijenjeno vozilo, s nazivima iz šifarnika.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `make_name` (string, obavezno) — Naziv marke, npr. `Volkswagen`.
- `model` (string, obavezno) — Šifra modela.
- `model_name` (string, obavezno) — Naziv modela, npr. `Golf 7`.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `as_of` (string, obavezno) — Dan na koji važi vrijednost.
- `market_value` (object, obavezno) — Tržišna vrijednost s rasponom od 80% i ocjenom pouzdanosti.
- `currency` (string, obavezno) — Uvijek `BAM` (konvertibilna marka). Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Tržišna vrijednost, zaokružena na 10 KM.
- `low` (integer, obavezno) — Donja granica raspona.
- `high` (integer, obavezno) — Gornja granica raspona.
- `confidence_grade` (enum, obavezno) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `range_probability` (number, obavezno) — Vjerovatnoća da je cijena u rasponu: `0.8` (80%).
- `definition` (string, obavezno) — Šta tačno vrijednost znači, jednom rečenicom.
- `standard_value` (object) — Samo uz model kompanije: šta kaže standardni tržišni model, za poređenje.
- `currency` (string, obavezno) — `BAM`. Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Vrijednost po standardnom modelu.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `confidence_grade` (enum, obavezno) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `model_version` (string, obavezno) — Verzija standardnog modela.
- `explanation` (object) — Obračun cijene po faktorima (uz `include: ["explanation"]`).
- `lines` (object[], obavezno) — Linije koje se tačno sabiraju u `market_value.point`.
- `id` (enum, obavezno) — Faktor: `base` (bazna vrijednost modela), `mileage`, `equipment` (oprema i motorizacija), `history` (stanje i historija), `region`, `market`, `adjustment` (korekcija tržišnog tima). Vrijednosti: `base`, `mileage`, `equipment`, `history`, `region`, `market`, `adjustment`.
- `label` (string, obavezno) — Naziv faktora na bosanskom, za prikaz korisniku.
- `amount_bam` (integer, obavezno) — Prva linija: bazna vrijednost; ostale: koliko faktor dodaje ili oduzima.
- `method` (string, obavezno) — Kako je obračun nastao.
- `forecast` (object) — Prognoza vrijednosti (uz `include: ["forecast"]`): naučena kriva gubitka vrijednosti, uz današnji nivo tržišta.
- `status` (string, obavezno) — `beta`. Vrijednosti: `beta`.
- `km_per_year` (integer, obavezno) — Godišnja kilometraža pretpostavljena u prognozi.
- `points` (object[], obavezno) — Vrijednost kroz vrijeme, s rasponom koji se širi.
- `months` (integer, obavezno) — Mjeseci od `as_of`: 6, 12, 24, 36.
- `point` (integer, obavezno) — Očekivana vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `method` (string, obavezno) — Kako je prognoza nastala.
- `sale_price` (object, obavezno) — Procjena stvarne prodajne cijene: u pripremi.
- `status` (string, obavezno) — Još nije dostupno. Vrijednosti: `unavailable`.
- `detail` (string, obavezno) — Zašto.
- `time_to_sell` (object, obavezno) — Očekivano vrijeme do prodaje: u pripremi.
- `status` (string, obavezno) — Još nije dostupno. Vrijednosti: `unavailable`.
- `detail` (string, obavezno) — Zašto.
- `adjustment` (object) — Kad Cifrin tržišni tim privremeno koriguje model za neki segment (najviše ±15%, do 180 dana).
- `multiplier` (number, obavezno) — Faktor korekcije, npr. `0.97`.
- `reason` (string, obavezno) — Razlog korekcije.
- `warnings` (object[], obavezno) — Upozorenja uz procjenu. Prazna lista znači da nema ničeg posebnog.
- `code` (string, obavezno) — Stabilna šifra upozorenja, npr. `partial_inputs`.
- `message` (string, obavezno) — Objašnjenje na engleskom, za logove i podršku.
- `comparables` (object) — Slična vozila trenutno u prodaji (uz `include: ["comparables"]`): ista marka i model, godište ±2, poredana po sličnosti.
- `total` (integer, obavezno) — Koliko sličnih vozila je trenutno u prodaji.
- `items` (object[], obavezno) — Do 8 najsličnijih.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `fuel` (string, obavezno) — Gorivo.
- `transmission` (string, obavezno) — Mjenjač.
- `power_kw` (number, obavezno) — Snaga u kW.
- `engine_cc` (integer, obavezno, može biti null) — Zapremina u cm³.
- `city` (string, obavezno) — Mjesto.
- `asking_price_bam` (integer, obavezno) — Cijena u oglasu.
- `cifra_value_bam` (integer, obavezno) — Cifrina vrijednost tog vozila.
- `price_vs_value_pct` (number, obavezno) — Koliko oglas traži iznad (+) ili ispod (−) Cifrine vrijednosti, u %.
- `days_listed` (integer, obavezno, može biti null) — Dana u prodaji.
- `error` (object) — Greška, ako ovo vozilo nije procijenjeno.
- `code` (string, obavezno) — Šifra greške, kao u odgovoru s greškom.
- `detail` (string) — Objašnjenje.
- `errors` (object[]) — Za `invalid_request`: svako neispravno polje.
- `path` (string, obavezno) — Polje.
- `message` (string, obavezno) — Šta nije u redu.
- `valued` (integer, obavezno) — Koliko je procijenjeno (i naplaćeno).
- `failed` (integer, obavezno) — Koliko nije.
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `413 batch_too_large` — Više vozila nego što plan dozvoljava u jednom pozivu.
- `503 model_unavailable` — Model trenutno nije dostupan (npr. tokom pokretanja).
## Primjer
```bash
curl -X POST "https://api.cifra.ba/v1/valuations/batch" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"include": [
"explanation"
],
"items": [
{
"make": "audi",
"model": "a4",
"year": 2016,
"mileage_km": 190000,
"fuel": "diesel",
"transmission": "automatic"
},
{
"make": "škoda",
"model": "octavia",
"year": 2015,
"mileage_km": 210000
},
{
"make": "volkswagen",
"model": "pasat",
"year": 2015,
"mileage_km": 200000
}
]
}'
```
```json
{
"object": "list",
"data": [
{
"index": 0,
"valuation": {
"id": "val_lbVQ4f6WuLaD9h85G4Gf",
"object": "valuation",
"created_at": "2026-10-18T22:04:59.768Z",
"model_version": "car-20261017-1",
"valued_by": {
"kind": "standard",
"version": "car-20261017-1"
},
"vehicle": {
"vehicle_type": "car",
"make": "audi",
"make_name": "Audi",
"model": "a4",
"model_name": "A4",
"year": 2016,
"mileage_km": 190000
},
"as_of": "2026-10-18",
"market_value": {
"currency": "BAM",
"point": 29450,
"low": 24170,
"high": 36240,
"confidence_grade": "A",
"range_probability": 0.8,
"definition": "Asking price at which a comparable vehicle is listed by a private seller on the valuation date; the range holds the price with 80% probability."
},
"explanation": {
"lines": [
{
"id": "base",
"label": "Bazna vrijednost modela",
"amount_bam": 22390
},
{
"id": "mileage",
"label": "Kilometraža",
"amount_bam": 1370
},
{
"id": "equipment",
"label": "Oprema i motorizacija",
"amount_bam": 6190
},
{
"id": "history",
"label": "Stanje i historija vozila",
"amount_bam": -10
},
{
"id": "region",
"label": "Regionalna potražnja",
"amount_bam": -290
},
{
"id": "market",
"label": "Stanje tržišta",
"amount_bam": -200
}
],
"method": "TreeSHAP contributions of the valuation model, grouped by factor and applied in order."
},
"sale_price": {
"status": "unavailable",
"detail": "Needs transaction data; planned as an experimental output."
},
"time_to_sell": {
"status": "unavailable",
"detail": "Needs a few months of market exit data; planned."
},
"warnings": [
{
"code": "partial_inputs",
"message": "Add power and engine size for a tighter range."
}
]
}
},
{
"index": 1,
"valuation": {
"id": "val_Hc2WqLx9TzE4nVb7RkPa",
"object": "valuation",
"created_at": "2026-10-18T21:57:27.584Z",
"model_version": "car-20261017-1",
"valued_by": {
"kind": "standard",
"version": "car-20261017-1"
},
"vehicle": {
"vehicle_type": "car",
"make": "škoda",
"make_name": "Škoda",
"model": "octavia",
"model_name": "Octavia",
"year": 2015,
"mileage_km": 210000
},
"as_of": "2026-10-18",
"market_value": {
"currency": "BAM",
"point": 15600,
"low": 12370,
"high": 19690,
"confidence_grade": "B",
"range_probability": 0.8,
"definition": "Asking price at which a comparable vehicle is listed by a private seller on the valuation date; the range holds the price with 80% probability."
},
"sale_price": {
"status": "unavailable",
"detail": "Needs transaction data; planned as an experimental output."
},
"time_to_sell": {
"status": "unavailable",
"detail": "Needs a few months of market exit data; planned."
},
"warnings": [
{
"code": "partial_inputs",
"message": "Add power, engine size, fuel and transmission for a tighter range."
}
]
}
},
{
"index": 2,
"error": {
"code": "unknown_model",
"detail": "Unknown model \"pasat\" for Volkswagen. See GET /v1/taxonomy/makes/volkswagen/models."
}
}
],
"valued": 2,
"failed": 1
}
```
---
# Čitanje procjene
`GET https://api.cifra.ba/v1/valuations/{id}`
Sačuvana procjena s tačnim zahtjevom kojim je nastala, npr. za reviziju odluke. Vidljiva samo ključevima iste kompanije i istog okruženja.
Pristup: `valuations`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka procjene (`val_…`).
## Odgovor 200
- `id` (string, obavezno) — Oznaka procjene (`val_…`); po njoj je čitate i javljate prodajnu cijenu.
- `object` (string, obavezno) — Uvijek `valuation`. Vrijednosti: `valuation`.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `model_version` (string, obavezno) — Verzija modela koji je procijenio, npr. `car-20261017-1`.
- `valued_by` (object, obavezno) — Koji model je odgovorio.
- `kind` (enum, obavezno) — `standard`: Cifrin tržišni model; `custom`: model vaše kompanije. Vrijednosti: `standard`, `custom`.
- `version` (string, obavezno) — Verzija modela koji je odgovorio, npr. `car-20261017-1`.
- `custom_model_id` (integer) — Model kompanije: njegov broj.
- `name` (string) — Model kompanije: naziv koji ste mu dali.
- `price_kind` (enum) — Model kompanije: koje cijene je učio, pa šta vrijednost znači — prodajne, nabavne, oglasne ili procjene. Vrijednosti: `sale`, `purchase`, `asking`, `appraisal`.
- `base_version` (string) — Model kompanije: standardni model na kojem je napravljen.
- `fallback` (string) — Vaš model trenutno nije mogao odgovoriti, pa je odgovorio standardni. Vrijednosti: `custom_model_unavailable`.
- `sandbox` (boolean) — Samo testni ključevi: fiksne primjer-vrijednosti. Vrijednosti: `true`.
- `vehicle` (object, obavezno) — Procijenjeno vozilo, s nazivima iz šifarnika.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `make_name` (string, obavezno) — Naziv marke, npr. `Volkswagen`.
- `model` (string, obavezno) — Šifra modela.
- `model_name` (string, obavezno) — Naziv modela, npr. `Golf 7`.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `as_of` (string, obavezno) — Dan na koji važi vrijednost.
- `market_value` (object, obavezno) — Tržišna vrijednost s rasponom od 80% i ocjenom pouzdanosti.
- `currency` (string, obavezno) — Uvijek `BAM` (konvertibilna marka). Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Tržišna vrijednost, zaokružena na 10 KM.
- `low` (integer, obavezno) — Donja granica raspona.
- `high` (integer, obavezno) — Gornja granica raspona.
- `confidence_grade` (enum, obavezno) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `range_probability` (number, obavezno) — Vjerovatnoća da je cijena u rasponu: `0.8` (80%).
- `definition` (string, obavezno) — Šta tačno vrijednost znači, jednom rečenicom.
- `standard_value` (object) — Samo uz model kompanije: šta kaže standardni tržišni model, za poređenje.
- `currency` (string, obavezno) — `BAM`. Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Vrijednost po standardnom modelu.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `confidence_grade` (enum, obavezno) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `model_version` (string, obavezno) — Verzija standardnog modela.
- `explanation` (object) — Obračun cijene po faktorima (uz `include: ["explanation"]`).
- `lines` (object[], obavezno) — Linije koje se tačno sabiraju u `market_value.point`.
- `id` (enum, obavezno) — Faktor: `base` (bazna vrijednost modela), `mileage`, `equipment` (oprema i motorizacija), `history` (stanje i historija), `region`, `market`, `adjustment` (korekcija tržišnog tima). Vrijednosti: `base`, `mileage`, `equipment`, `history`, `region`, `market`, `adjustment`.
- `label` (string, obavezno) — Naziv faktora na bosanskom, za prikaz korisniku.
- `amount_bam` (integer, obavezno) — Prva linija: bazna vrijednost; ostale: koliko faktor dodaje ili oduzima.
- `method` (string, obavezno) — Kako je obračun nastao.
- `forecast` (object) — Prognoza vrijednosti (uz `include: ["forecast"]`): naučena kriva gubitka vrijednosti, uz današnji nivo tržišta.
- `status` (string, obavezno) — `beta`. Vrijednosti: `beta`.
- `km_per_year` (integer, obavezno) — Godišnja kilometraža pretpostavljena u prognozi.
- `points` (object[], obavezno) — Vrijednost kroz vrijeme, s rasponom koji se širi.
- `months` (integer, obavezno) — Mjeseci od `as_of`: 6, 12, 24, 36.
- `point` (integer, obavezno) — Očekivana vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `method` (string, obavezno) — Kako je prognoza nastala.
- `sale_price` (object, obavezno) — Procjena stvarne prodajne cijene: u pripremi.
- `status` (string, obavezno) — Još nije dostupno. Vrijednosti: `unavailable`.
- `detail` (string, obavezno) — Zašto.
- `time_to_sell` (object, obavezno) — Očekivano vrijeme do prodaje: u pripremi.
- `status` (string, obavezno) — Još nije dostupno. Vrijednosti: `unavailable`.
- `detail` (string, obavezno) — Zašto.
- `adjustment` (object) — Kad Cifrin tržišni tim privremeno koriguje model za neki segment (najviše ±15%, do 180 dana).
- `multiplier` (number, obavezno) — Faktor korekcije, npr. `0.97`.
- `reason` (string, obavezno) — Razlog korekcije.
- `warnings` (object[], obavezno) — Upozorenja uz procjenu. Prazna lista znači da nema ničeg posebnog.
- `code` (string, obavezno) — Stabilna šifra upozorenja, npr. `partial_inputs`.
- `message` (string, obavezno) — Objašnjenje na engleskom, za logove i podršku.
- `comparables_total` (integer) — Ako su tražena slična vozila: koliko ih je tad bilo u prodaji.
- `request` (object, obavezno) — Tijelo zahtjeva kojim je procjena napravljena.
## Greške
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
## Primjer
```bash
curl "https://api.cifra.ba/v1/valuations/val_yXpheA0qNLw6gYKCq6k1" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"id": "val_yXpheA0qNLw6gYKCq6k1",
"object": "valuation",
"created_at": "2026-10-18T21:57:02.773Z",
"model_version": "car-20261017-1",
"valued_by": {
"kind": "standard",
"version": "car-20261017-1"
},
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"make_name": "Volkswagen",
"model": "golf_7",
"model_name": "Golf 7",
"year": 2017,
"mileage_km": 148000
},
"as_of": "2026-10-18",
"market_value": {
"currency": "BAM",
"point": 22350,
"low": 18610,
"high": 26790,
"confidence_grade": "A",
"range_probability": 0.8,
"definition": "Asking price at which a comparable vehicle is listed by a private seller on the valuation date; the range holds the price with 80% probability."
},
"explanation": {
"lines": [
{
"id": "base",
"label": "Bazna vrijednost modela",
"amount_bam": 22950
},
{
"id": "mileage",
"label": "Kilometraža",
"amount_bam": 3270
},
{
"id": "equipment",
"label": "Oprema i motorizacija",
"amount_bam": -3090
},
{
"id": "history",
"label": "Stanje i historija vozila",
"amount_bam": -20
},
{
"id": "region",
"label": "Regionalna potražnja",
"amount_bam": -230
},
{
"id": "market",
"label": "Stanje tržišta",
"amount_bam": -530
}
],
"method": "TreeSHAP contributions of the valuation model, grouped by factor and applied in order."
},
"forecast": {
"status": "beta",
"km_per_year": 15110,
"points": [
{
"months": 6,
"point": 21380,
"low": 16350,
"high": 26450
},
{
"months": 12,
"point": 20450,
"low": 14670,
"high": 25990
},
{
"months": 24,
"point": 18710,
"low": 13890,
"high": 23530
},
{
"months": 36,
"point": 17150,
"low": 12190,
"high": 22020
}
],
"method": "Learned depreciation curve for this age and brand tier; market level held at today's."
},
"sale_price": {
"status": "unavailable",
"detail": "Needs transaction data; planned as an experimental output."
},
"time_to_sell": {
"status": "unavailable",
"detail": "Needs a few months of market exit data; planned."
},
"warnings": [],
"comparables_total": 502,
"request": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"engine_cc": 1598,
"fuel": "diesel",
"transmission": "manual",
"body_type": "hatchback",
"city": "Sarajevo",
"include": [
"explanation",
"forecast",
"comparables"
]
}
}
```
---
# Prijava prodajne cijene
`POST https://api.cifra.ba/v1/valuations/{id}/outcome`
Javite za koliko je vozilo stvarno prodano ili otkupljeno. Ne naplaćuje se; stvarne cijene su podaci od kojih se uči procjena prodajne cijene.
Pristup: `valuations`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka procjene (`val_…`).
## Tijelo zahtjeva
- `sold_price_bam` (integer, obavezno, 100 – 5.000.000) — Cijena za koju je vozilo stvarno prodano ili otkupljeno, u KM.
- `sold_at` (date) — Datum prodaje (`YYYY-MM-DD`).
## Odgovor 201
- `object` (string, obavezno) — `valuation_outcome`. Vrijednosti: `valuation_outcome`.
- `id` (integer, obavezno) — Oznaka zapisa.
- `valuation_id` (string, obavezno) — Procjena na koju se odnosi.
- `sold_price_bam` (integer, obavezno) — Prijavljena cijena.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
## Primjer
```bash
curl -X POST "https://api.cifra.ba/v1/valuations/val_yXpheA0qNLw6gYKCq6k1/outcome" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sold_price_bam": 21500,
"sold_at": "2026-10-25"
}'
```
```json
{
"object": "valuation_outcome",
"id": 4812,
"valuation_id": "val_yXpheA0qNLw6gYKCq6k1",
"sold_price_bam": 21500,
"created_at": "2026-10-26T08:14:51.120Z"
}
```
---
# Marke
`GET https://api.cifra.ba/v1/taxonomy/makes`
Sve marke koje Cifra procjenjuje, za jednu vrstu vozila, sa šiframa (`slug`) koje šaljete u procjeni. Besplatno; šifarnik se rijetko mijenja, pa ga keširajte (npr. jednom dnevno).
Pristup: `valuations`. Obračun: besplatno.
## Parametri upita
- `vehicle_type` (enum, podrazumijevano "car") — Vrsta vozila čiji šifarnik tražite. Vrijednosti: `car`, `motorcycle`, `truck`.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `data` (object[], obavezno) — Marke, abecedno.
- `slug` (string, obavezno) — Šifra marke za zahtjeve.
- `name` (string, obavezno) — Naziv za prikaz.
- `models` (integer, obavezno) — Broj modela.
## Greške
- `400 invalid_vehicle_type` — `vehicle_type` nije `car`, `motorcycle` ni `truck`.
## Primjer
```bash
curl "https://api.cifra.ba/v1/taxonomy/makes?vehicle_type=car" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "list",
"data": [
{
"slug": "alfa_romeo",
"name": "Alfa Romeo",
"models": 16
},
{
"slug": "alpina",
"name": "Alpina",
"models": 2
},
{
"slug": "aston_martin",
"name": "Aston Martin",
"models": 4
},
{
"slug": "audi",
"name": "Audi",
"models": 54
}
]
}
```
---
# Modeli marke
`GET https://api.cifra.ba/v1/taxonomy/makes/{make}/models`
Modeli jedne marke sa šiframa za procjenu. Generacije su zasebni modeli (`golf_6`, `golf_7`), kao i jače izvedbe (`golf_7_gti`).
Pristup: `valuations`. Obračun: besplatno.
## Parametri putanje
- `make` (string, obavezno) — Šifra marke, npr. `volkswagen`.
## Parametri upita
- `vehicle_type` (enum, podrazumijevano "car") — Vrsta vozila čiji šifarnik tražite. Vrijednosti: `car`, `motorcycle`, `truck`.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `data` (object[], obavezno) — Modeli marke, abecedno.
- `slug` (string, obavezno) — Šifra modela za zahtjeve.
- `name` (string, obavezno) — Naziv za prikaz.
## Greške
- `422 unknown_make` — Marka nije u šifarniku (odgovor nosi `field`).
- `400 invalid_vehicle_type` — `vehicle_type` nije `car`, `motorcycle` ni `truck`.
## Primjer
```bash
curl "https://api.cifra.ba/v1/taxonomy/makes/volkswagen/models" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "list",
"data": [
{
"slug": "golf",
"name": "Golf"
},
{
"slug": "golf_6",
"name": "Golf 6"
},
{
"slug": "golf_7",
"name": "Golf 7"
},
{
"slug": "golf_7_gti",
"name": "Golf 7 GTI"
},
{
"slug": "golf_8",
"name": "Golf 8"
}
]
}
```
---
# Dozvoljene vrijednosti
`GET https://api.cifra.ba/v1/taxonomy/values`
Vrijednosti koje primaju polja s izborom (gorivo, mjenjač, karoserija…) za jednu vrstu vozila. Za motocikle i kamione i `category`/`payload_class` koje model zna.
Pristup: `valuations`. Obračun: besplatno.
## Parametri upita
- `vehicle_type` (enum, podrazumijevano "car") — Vrsta vozila čiji šifarnik tražite. Vrijednosti: `car`, `motorcycle`, `truck`.
## Odgovor 200
- `fuel` (string[], obavezno) — Gorivo.
- `transmission` (string[]) — Mjenjač (automobili i kamioni).
- `drivetrain` (string[]) — Pogon (automobili).
- `body_type` (string[]) — Karoserija (automobili).
- `category` (string[]) — Tip motocikla ili nadogradnja kamiona, kako ih zna model.
- `payload_class` (string[]) — Razred nosivosti (kamioni).
- `condition` (string[], obavezno) — Stanje.
- `seller_type` (string[], obavezno) — Vrsta prodavca.
## Greške
- `400 invalid_vehicle_type` — `vehicle_type` nije `car`, `motorcycle` ni `truck`.
## Primjer
```bash
curl "https://api.cifra.ba/v1/taxonomy/values?vehicle_type=car" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"fuel": [
"petrol",
"diesel",
"lpg",
"cng",
"hybrid",
"plugin_hybrid",
"electric",
"hydrogen",
"other"
],
"transmission": [
"manual",
"automatic",
"semi_automatic"
],
"drivetrain": [
"fwd",
"rwd",
"awd"
],
"body_type": [
"sedan",
"hatchback",
"wagon",
"suv",
"coupe",
"convertible",
"minivan",
"van",
"pickup",
"other"
],
"condition": [
"used",
"new"
],
"seller_type": [
"private",
"dealer"
]
}
```
---
# Historija vozila
`GET https://api.cifra.ba/v1/vehicle-history`
Za jedan oglas: svi drugi oglasi istog vozila koje je Cifra vidjela (ponovna objavljivanja, druge stranice), s datumima, cijenama i kilometražom, i signali Cifra Provjere — vraćena kilometraža, tuđe fotografije, lizing, preprodavač kao privatnik.
Pristup: `listings`. Obračun: 1 jedinica.
## Parametri upita
- `listing_url` (url, do 500 znakova) — Link oglasa na olx.ba, autobum.ba ili autoplac.ba. Umjesto njega: `source` i `listing_id`.
- `source` (enum) — Stranica oglasa, uz `listing_id`. Vrijednosti: `olx`, `autobum`, `autoplac`.
- `listing_id` (string) — Broj oglasa na toj stranici, npr. `61234567`.
## Odgovor 200
- `object` (string, obavezno) — `vehicle_history`. Vrijednosti: `vehicle_history`.
- `query` (object, obavezno) — Oglas koji ste poslali.
- `source` (string, obavezno) — Stranica.
- `listing_id` (string, obavezno) — Broj oglasa.
- `vehicle` (object, obavezno) — Vozilo iz oglasa.
- `make` (string, obavezno) — Marka.
- `model` (string, obavezno) — Model.
- `year` (integer, obavezno, može biti null) — Godište.
- `fuel` (string, obavezno) — Gorivo.
- `power_kw` (number, obavezno) — Snaga u kW.
- `identity` (object, obavezno, može biti null) — Vozilo kako ga vidi Cifra kroz sve oglase; `null` kad nema drugih.
- `listings` (integer, obavezno) — Broj oglasa istog vozila.
- `sites` (integer, obavezno) — Na koliko stranica.
- `first_seen_on` (string, obavezno, može biti null) — Prvi put viđeno.
- `last_seen_on` (string, obavezno, može biti null) — Zadnji put viđeno.
- `mileage_range_km` (any[], obavezno) — Najmanja i najveća kilometraža kroz oglase.
- `confidence` (number, obavezno) — Pouzdanost povezivanja oglasa, 0–1.
- `listings` (object[], obavezno) — Svi oglasi vozila, od najstarijeg. Bez linkova, naslova i prodavaca.
- `source` (string, obavezno) — Stranica: `olx`, `autobum`, `autoplac`.
- `is_query` (boolean, obavezno) — Je li ovo oglas koji ste poslali.
- `status` (enum, obavezno) — `active`, `sold` ili `gone` (uklonjen). Vrijednosti: `active`, `sold`, `gone`.
- `listed_on` (string, obavezno, može biti null) — Objavljen.
- `last_seen_on` (string, obavezno, može biti null) — Zadnji put viđen.
- `days_listed` (integer, obavezno) — Dana u prodaji.
- `mileage_km` (integer, obavezno, može biti null) — Kilometraža u oglasu.
- `first_price_bam` (integer, obavezno, može biti null) — Prva cijena.
- `last_price_bam` (integer, obavezno, može biti null) — Zadnja cijena.
- `city` (string, obavezno) — Mjesto.
- `link` (object, obavezno, može biti null) — Zašto je oglas povezan s prethodnim; `null` za prvi.
- `confidence` (number, obavezno) — Pouzdanost veze, 0–1.
- `matched_on` (string[], obavezno) — Šta se poklopilo, npr. `identical_mileage`, `same_city`, `similar_title`, `same_listing_other_site`.
- `mileage_change_km` (integer, obavezno, može biti null) — Promjena kilometraže od prethodnog oglasa.
- `days_after_previous` (integer, obavezno, može biti null) — Dana nakon prethodnog oglasa.
- `level` (enum, obavezno) — Nivo pažnje: `high`, `elevated` ili `low`. Vrijednosti: `high`, `elevated`, `low`.
- `signals` (object[], obavezno) — Razlozi da se pogleda bolje, od najtežeg.
- `code` (string, obavezno) — Šifra signala, npr. `mileage_rollback`.
- `severity` (enum, obavezno) — Težina: `high`, `medium`, `info`. Vrijednosti: `high`, `medium`, `info`.
- `summary` (string, obavezno) — Naslov, s brojkama (bosanski).
- `message` (string, obavezno) — Šta smo vidjeli (bosanski).
- `check` (string, obavezno) — Šta provjeriti prije odluke (bosanski).
- `in_favour` (object[], obavezno) — Šta govori u prilog vozilu.
- `code` (string, obavezno) — Šifra, npr. `mileage_consistent`.
- `summary` (string, obavezno) — Opis (bosanski).
- `market` (object, obavezno, može biti null) — Cijena i kilometraža naspram tržišta.
- `asking_price_bam` (integer, obavezno, može biti null) — Cijena u oglasu.
- `cifra_price_bam` (integer, obavezno, može biti null) — Cifrina vrijednost.
- `vs_market` (number, obavezno) — Oglas naspram vrijednosti: `0.21` = 21% iznad.
- `mileage_percentile_for_age` (number, obavezno) — Kilometraža naspram vozila iste starosti, 0–1 (`0.57` = više od 57%).
- `note` (string, obavezno) — Napomena o porijeklu podataka.
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `422 unsupported_listing_url` — Iz linka se ne može pročitati stranica i broj oglasa.
- `404 listing_not_found` — Cifra još nije vidjela oglas: nov je (stranice se pregledaju dnevno) ili je sa stranice koju ne pratimo.
## Primjer
```bash
curl "https://api.cifra.ba/v1/vehicle-history?listing_url=https%3A%2F%2Folx.ba%2Fartikal%2F61234567" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "vehicle_history",
"query": {
"source": "olx",
"listing_id": "61234567"
},
"vehicle": {
"make": "Volkswagen",
"model": "T6 Kombi",
"year": 2016,
"fuel": "diesel",
"power_kw": 75
},
"identity": {
"listings": 3,
"sites": 2,
"first_seen_on": "2026-06-25",
"last_seen_on": "2026-10-18",
"mileage_range_km": [
255000,
256000
],
"confidence": 0.5
},
"listings": [
{
"source": "olx",
"is_query": false,
"status": "active",
"listed_on": "2026-06-25",
"last_seen_on": "2026-10-17",
"days_listed": 113,
"mileage_km": 255540,
"first_price_bam": 32000,
"last_price_bam": 30000,
"city": "Tuzla",
"link": null
},
{
"source": "autobum",
"is_query": false,
"status": "active",
"listed_on": "2026-09-06",
"last_seen_on": "2026-10-18",
"days_listed": 42,
"mileage_km": 255000,
"first_price_bam": 30000,
"last_price_bam": 30000,
"city": "Tuzla",
"link": {
"confidence": 0.818,
"matched_on": [
"same_city",
"same_power",
"close_mileage",
"similar_price",
"similar_title"
],
"mileage_change_km": -540,
"days_after_previous": 73
}
},
{
"source": "olx",
"is_query": true,
"status": "active",
"listed_on": "2026-10-16",
"last_seen_on": "2026-10-18",
"days_listed": 1,
"mileage_km": 256000,
"first_price_bam": 34000,
"last_price_bam": 34000,
"city": "Tuzla",
"link": {
"confidence": 0.5,
"matched_on": [
"same_city",
"same_power",
"close_mileage",
"similar_price",
"similar_title"
],
"mileage_change_km": 1000,
"days_after_previous": 40
}
}
],
"level": "elevated",
"signals": [
{
"code": "relisted_often",
"severity": "medium",
"summary": "Na prodaji 5 mj., oglašeno 3 puta",
"message": "Prvi oglas 25. 6. 2026. Vozilo koje se dugo ne proda često ima razlog — cijenu, stanje ili papire.",
"check": "Pitajte koliko dugo se prodaje i zašto se još nije prodalo."
},
{
"code": "changed_hands",
"severity": "info",
"summary": "Mijenjalo prodavca",
"message": "Vozilo je nudio više od jednog prodavca; pogledajte historiju.",
"check": null
}
],
"in_favour": [
{
"code": "mileage_consistent",
"summary": "Kilometraža raste dosljedno kroz oglase"
}
],
"market": {
"asking_price_bam": 34000,
"cifra_price_bam": 28100,
"vs_market": 0.21,
"mileage_percentile_for_age": 0.57
},
"note": "Matches come from listing data (specs, mileage trail, title, seller, place, photos), not a vehicle registry. Signals are reasons to look closer, not verdicts. Signal texts are in Bosnian, as on Cifra's reports."
}
```
---
# Praćenje vozila
`POST https://api.cifra.ba/v1/watchlist`
Vozilo koje se procjenjuje svako jutro, s alarmima po vašim pravilima. Vlastitom vozilu (`owned`) kilometraža raste svaki dan; za traženo (`wanted`) stižu i povoljni oglasi. Procjenjuje se odmah (1 jedinica); dnevne procjene su besplatne.
Pristup: `watchlist`. Obračun: 1 jedinica.
## Tijelo zahtjeva
- `vehicle` (object, obavezno) — Vozilo, s istim poljima kao tijelo `POST /v1/valuations`.
- `vehicle_type` (enum, podrazumijevano "car") — Vrsta vozila. Svaka vrsta ima svoj model, šifarnik i polja koja prima. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno, do 64 znaka) — Marka kao šifra iz `GET /v1/taxonomy/makes`, npr. `volkswagen`, `mercedes_benz`, `škoda`.
- `model` (string, obavezno, do 64 znaka) — Model kao šifra iz `GET /v1/taxonomy/makes/{make}/models`, npr. `golf_7`.
- `year` (integer, obavezno, najmanje 1950) — Godište (modelska godina). Najviše sljedeća godina.
- `mileage_km` (integer, obavezno, 0 – 2.000.000) — Pređeni kilometri na dan procjene.
- `power_kw` (number, 2 – 1000) — Snaga motora u kW. Jedan od najvažnijih podataka za cijenu.
- `power_hp` (number, 3 – 1400) — Snaga u KS; koristi se samo kad `power_kw` nije poslan.
- `engine_cc` (integer, 40 – 20.000) — Zapremina motora u cm³.
- `fuel` (enum) — Gorivo. Vrijednosti: `petrol`, `diesel`, `lpg`, `cng`, `hybrid`, `plugin_hybrid`, `electric`, `hydrogen`, `other`.
- `transmission` (enum) — Mjenjač. Vrijednosti: `manual`, `automatic`, `semi_automatic`.
- `drivetrain` (enum) — Pogon. Samo automobili. Vrijednosti: `fwd`, `rwd`, `awd`.
- `body_type` (enum) — Karoserija. Samo automobili. Vrijednosti: `sedan`, `hatchback`, `wagon`, `suv`, `coupe`, `convertible`, `minivan`, `van`, `pickup`, `other`.
- `doors` (integer, 2 – 5) — Broj vrata. Samo automobili.
- `condition` (enum) — Stanje: `used` (podrazumijevano) ili `new`. Vrijednosti: `used`, `new`.
- `seller_type` (enum) — Ko prodaje: privatna osoba ili salon. Vrijednosti: `private`, `dealer`.
- `city` (string, do 80 znakova) — Grad u BiH, npr. `Sarajevo` ili `Banja Luka`. Regionalna potražnja pomjera cijenu.
- `equipment` (string[], do 150 stavki) — Oprema kako je navodi oglas ili vaš sistem, npr. `navigacija`, `kožna sjedišta`.
- `owners_count` (integer, 1 – 20) — Broj dosadašnjih vlasnika.
- `customs_cleared` (boolean) — Je li vozilo ocarinjeno.
- `service_history` (boolean) — Ima li vozilo servisnu historiju (knjižicu).
- `category` (string, do 60 znakova) — Motocikli: tip (`Naked`, `Scooter`, `Enduro`…); kamioni: nadogradnja (`Kiper`, `Kombi`…). Vrijednosti: `GET /v1/taxonomy/values`.
- `abs` (boolean) — ABS. Samo motocikli.
- `axles` (integer, 1 – 6) — Broj osovina. Samo kamioni.
- `payload_class` (string, do 40 znakova) — Nosivost kao razred iz `GET /v1/taxonomy/values`. Samo kamioni.
- `kind` (enum, obavezno) — `owned`: vaše vozilo, prati se njegova vrijednost kako stari; `wanted`: tražena specifikacija, prati se tržišna cijena i povoljni oglasi. Vrijednosti: `owned`, `wanted`.
- `label` (string, do 120 znakova) — Naziv koji vidite u izvještajima, npr. broj ugovora.
- `external_ref` (string, do 120 znakova) — Vaša oznaka (ugovor, klijent, vozilo). Po njoj filtrirate listu i izvještaj.
- `km_per_year` (integer, 0 – 150.000) — Vlastita vozila: kilometraža raste ovoliko godišnje, svaki dan. Podrazumijevano: dosadašnji prosjek vozila.
- `alerts` (object) — Pravila alarma.
- `change_pct` (number, može biti null, 3 – 90) — Alarm kad se vrijednost pomjeri za ovoliko posto: od početne vrijednosti, zatim od vrijednosti pri zadnjem alarmu. Najmanje 3, jer samo ponovno treniranje modela pomjeri vrijednosti ~2%. `null` isključuje.
- `direction` (enum) — Koji pomak broji za `change_pct`: `any` (podrazumijevano), `up` ili `down`. Vrijednosti: `any`, `up`, `down`.
- `below_bam` (integer, može biti null, 100 – 5.000.000) — Alarm kad vrijednost padne ispod ove cijene (KM).
- `above_bam` (integer, može biti null, 100 – 5.000.000) — Alarm kad vrijednost poraste iznad ove cijene (KM).
- `exposure_pct` (number, može biti null, 10 – 300) — Vlastita vozila: alarm na dan kad izloženost (dug, osigurana suma, trošak) dostigne ovaj postotak vrijednosti (LTV), samo pri rastu.
- `deal_pct` (number, može biti null, 5 – 50) — Tražena vozila: alarm za svaki novi oglas iste specifikacije koji traži ovoliko posto manje od Cifrine cijene (najviše 5 dnevno).
- `exposure` (object) — Vlastita vozila: iznos vezan za vozilo, za LTV i alarm `exposure_pct`.
- `kind` (enum, obavezno) — `financing`: stanje kredita ili lizinga (otplaćuje se); `insured`: osigurana suma; `cost`: nabavna cijena. Vrijednosti: `financing`, `insured`, `cost`.
- `amount_bam` (integer, obavezno, 100 – 20.000.000) — Iznos u KM na dan `as_of`.
- `as_of` (date) — Dan na koji važi `amount_bam` (podrazumijevano danas).
- `term_months` (integer, može biti null, 1 – 240) — `financing`: preostali broj mjeseci; stanje se otplaćuje do `balloon_bam`, a nakon roka je nula.
- `annual_rate_pct` (number, može biti null, 0 – 40) — `financing`: nominalna godišnja kamata za anuitetnu otplatu; `0` znači linearnu.
- `balloon_bam` (integer, može biti null, 0 – 20.000.000) — `financing`: ostatak na kraju roka (balon rata, otkupna vrijednost).
- `tags` (string[], do 10 stavki) — Vaše grupe, npr. portfelj ili poslovnica (do 10).
- `note` (string, do 2000 znakova) — Interna napomena.
- `created_by` (string, 8–64 znaka) — Samo Cifrine aplikacije; kod vaših ključeva se zanemaruje.
## Odgovor 201
- `object` (string, obavezno) — `watched_vehicle`. Vrijednosti: `watched_vehicle`.
- `id` (string, obavezno) — Oznaka (`wv_…`).
- `kind` (enum, obavezno) — `owned` ili `wanted`. Vrijednosti: `owned`, `wanted`.
- `status` (enum, obavezno) — `active` ili `paused`. Vrijednosti: `active`, `paused`.
- `label` (string, obavezno) — Naziv.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `tags` (string[], obavezno) — Vaše grupe.
- `note` (string, obavezno) — Napomena.
- `vehicle` (object, obavezno) — Vozilo kako ste ga poslali, s nazivima iz šifarnika.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Naziv marke.
- `model_name` (string, obavezno) — Naziv modela.
- `mileage` (object, obavezno) — Kilometraža: vlastitim vozilima raste svaki dan.
- `today_km` (integer, obavezno) — Procijenjena kilometraža danas.
- `given_km` (integer, obavezno) — Zadnja kilometraža koju ste poslali.
- `given_on` (string, obavezno) — Kad ste je poslali.
- `km_per_year` (integer, obavezno, može biti null) — Godišnji prosjek.
- `alerts` (object, obavezno) — Pravila alarma.
- `change_pct` (number, obavezno) — Prag promjene, %.
- `direction` (enum, obavezno) — Smjer. Vrijednosti: `any`, `up`, `down`.
- `below_bam` (integer, obavezno, može biti null) — Donja ciljna cijena.
- `above_bam` (integer, obavezno, može biti null) — Gornja ciljna cijena.
- `exposure_pct` (number, obavezno) — LTV prag, %.
- `deal_pct` (number, obavezno) — Prag povoljnog oglasa, %.
- `exposure` (object, obavezno, može biti null) — Izloženost (samo vlastita vozila).
- `kind` (enum, obavezno) — Vrsta izloženosti. Vrijednosti: `financing`, `insured`, `cost`.
- `amount_bam` (integer, obavezno) — Iznos na dan `as_of`.
- `as_of` (string, obavezno) — Dan na koji važi iznos.
- `term_months` (integer, obavezno, može biti null) — Preostali mjeseci.
- `annual_rate_pct` (number, obavezno) — Godišnja kamata.
- `balloon_bam` (integer, obavezno, može biti null) — Ostatak na kraju.
- `today_bam` (integer, obavezno) — Iznos danas, nakon otplate.
- `ratio` (number, obavezno) — Iznos danas ÷ zadnja vrijednost (LTV), npr. `0.84`.
- `baseline` (object, obavezno) — Polazna vrijednost.
- `value` (integer, obavezno) — Vrijednost kad je praćenje počelo.
- `on` (string, obavezno) — Dan.
- `latest` (object, obavezno, može biti null) — Zadnja dnevna procjena.
- `on` (string, obavezno) — Dan zadnje procjene.
- `point` (integer, obavezno, može biti null) — Vrijednost.
- `low` (integer, obavezno, može biti null) — Donja granica.
- `high` (integer, obavezno, može biti null) — Gornja granica.
- `confidence_grade` (string, obavezno) — Ocjena.
- `model_version` (string, obavezno) — Verzija modela.
- `forecast` (object, obavezno, može biti null) — Prognoza iz zadnje dnevne procjene.
- `km_per_year` (integer, obavezno) — Pretpostavljena godišnja kilometraža.
- `points` (object[], obavezno) — Vrijednost kroz 6–36 mjeseci.
- `months` (integer, obavezno) — Mjeseci od zadnje procjene.
- `point` (integer, obavezno) — Vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `change_since_baseline_pct` (number, obavezno) — Promjena od polazne vrijednosti, %.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `422 unknown_make` — Marka nije u šifarniku (odgovor nosi `field`).
- `422 unknown_model` — Model nije u šifarniku te marke.
- `422 vehicle_type_unavailable` — Procjene za tu vrstu vozila trenutno nisu dostupne.
- `409 watchlist_full` — Dostignut broj praćenih vozila plana (odgovor nosi `max`, `count`).
## Primjer
```bash
curl -X POST "https://api.cifra.ba/v1/watchlist" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "owned",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"vehicle": {
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual"
},
"km_per_year": 18000,
"exposure": {
"kind": "financing",
"amount_bam": 18500,
"as_of": "2026-10-18",
"term_months": 36,
"annual_rate_pct": 6.9,
"balloon_bam": 12000
},
"alerts": {
"change_pct": 5,
"direction": "down",
"exposure_pct": 85
},
"tags": [
"lizing",
"sarajevo"
]
}'
```
```json
{
"object": "watched_vehicle",
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"kind": "owned",
"status": "active",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"tags": [
"lizing",
"sarajevo"
],
"note": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual",
"make_name": "Volkswagen",
"model_name": "Golf 7"
},
"mileage": {
"today_km": 148000,
"given_km": 148000,
"given_on": "2026-10-18",
"km_per_year": 18000
},
"alerts": {
"change_pct": 5,
"direction": "down",
"below_bam": null,
"above_bam": null,
"exposure_pct": 85,
"deal_pct": null
},
"exposure": {
"kind": "financing",
"amount_bam": 18500,
"as_of": "2026-10-18",
"term_months": 36,
"annual_rate_pct": 6.9,
"balloon_bam": 12000,
"today_bam": 18500,
"ratio": 0.8277
},
"baseline": {
"value": 22350,
"on": "2026-10-18"
},
"latest": {
"on": "2026-10-18",
"point": 22350,
"low": 18610,
"high": 26790,
"confidence_grade": "A",
"model_version": "car-20261017-1"
},
"forecast": {
"km_per_year": 18000,
"points": [
{
"months": 6,
"point": 21280,
"low": 16270,
"high": 26330
},
{
"months": 12,
"point": 20270,
"low": 14540,
"high": 25760
},
{
"months": 24,
"point": 18420,
"low": 13670,
"high": 23160
},
{
"months": 36,
"point": 16760,
"low": 11910,
"high": 21520
}
]
},
"change_since_baseline_pct": 0,
"created_at": "2026-10-18T22:04:11.532Z",
"updated_at": "2026-10-18T22:04:11.532Z"
}
```
---
# Uvoz portfelja
`POST https://api.cifra.ba/v1/watchlist/batch`
Do 500 vozila odjednom, npr. cijeli portfelj. Svako se provjerava i procjenjuje zasebno; naplaćuje se svako vozilo koje se počne pratiti.
Pristup: `watchlist`. Obračun: 1 jedinica po stavci.
## Tijelo zahtjeva
- `items` (any[], obavezno, 1–500 stavki) — Do 500 vozila, svako kao tijelo `POST /v1/watchlist`.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `created` (integer, obavezno) — Koliko vozila se sad prati (i naplaćeno).
- `data` (object[], obavezno) — Rezultat za svako vozilo, istim redom.
- `index` (integer, obavezno) — Mjesto u `items`.
- `watched_vehicle` (object) — Praćeno vozilo.
- `object` (string, obavezno) — `watched_vehicle`. Vrijednosti: `watched_vehicle`.
- `id` (string, obavezno) — Oznaka (`wv_…`).
- `kind` (enum, obavezno) — `owned` ili `wanted`. Vrijednosti: `owned`, `wanted`.
- `status` (enum, obavezno) — `active` ili `paused`. Vrijednosti: `active`, `paused`.
- `label` (string, obavezno) — Naziv.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `tags` (string[], obavezno) — Vaše grupe.
- `note` (string, obavezno) — Napomena.
- `vehicle` (object, obavezno) — Vozilo kako ste ga poslali, s nazivima iz šifarnika.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Naziv marke.
- `model_name` (string, obavezno) — Naziv modela.
- `mileage` (object, obavezno) — Kilometraža: vlastitim vozilima raste svaki dan.
- `today_km` (integer, obavezno) — Procijenjena kilometraža danas.
- `given_km` (integer, obavezno) — Zadnja kilometraža koju ste poslali.
- `given_on` (string, obavezno) — Kad ste je poslali.
- `km_per_year` (integer, obavezno, može biti null) — Godišnji prosjek.
- `alerts` (object, obavezno) — Pravila alarma.
- `change_pct` (number, obavezno) — Prag promjene, %.
- `direction` (enum, obavezno) — Smjer. Vrijednosti: `any`, `up`, `down`.
- `below_bam` (integer, obavezno, može biti null) — Donja ciljna cijena.
- `above_bam` (integer, obavezno, može biti null) — Gornja ciljna cijena.
- `exposure_pct` (number, obavezno) — LTV prag, %.
- `deal_pct` (number, obavezno) — Prag povoljnog oglasa, %.
- `exposure` (object, obavezno, može biti null) — Izloženost (samo vlastita vozila).
- `kind` (enum, obavezno) — Vrsta izloženosti. Vrijednosti: `financing`, `insured`, `cost`.
- `amount_bam` (integer, obavezno) — Iznos na dan `as_of`.
- `as_of` (string, obavezno) — Dan na koji važi iznos.
- `term_months` (integer, obavezno, može biti null) — Preostali mjeseci.
- `annual_rate_pct` (number, obavezno) — Godišnja kamata.
- `balloon_bam` (integer, obavezno, može biti null) — Ostatak na kraju.
- `today_bam` (integer, obavezno) — Iznos danas, nakon otplate.
- `ratio` (number, obavezno) — Iznos danas ÷ zadnja vrijednost (LTV), npr. `0.84`.
- `baseline` (object, obavezno) — Polazna vrijednost.
- `value` (integer, obavezno) — Vrijednost kad je praćenje počelo.
- `on` (string, obavezno) — Dan.
- `latest` (object, obavezno, može biti null) — Zadnja dnevna procjena.
- `on` (string, obavezno) — Dan zadnje procjene.
- `point` (integer, obavezno, može biti null) — Vrijednost.
- `low` (integer, obavezno, može biti null) — Donja granica.
- `high` (integer, obavezno, može biti null) — Gornja granica.
- `confidence_grade` (string, obavezno) — Ocjena.
- `model_version` (string, obavezno) — Verzija modela.
- `forecast` (object, obavezno, može biti null) — Prognoza iz zadnje dnevne procjene.
- `km_per_year` (integer, obavezno) — Pretpostavljena godišnja kilometraža.
- `points` (object[], obavezno) — Vrijednost kroz 6–36 mjeseci.
- `months` (integer, obavezno) — Mjeseci od zadnje procjene.
- `point` (integer, obavezno) — Vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `change_since_baseline_pct` (number, obavezno) — Promjena od polazne vrijednosti, %.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `error` (object) — Greška za ovo vozilo.
- `code` (string, obavezno) — Šifra greške.
- `message` (string, obavezno) — Objašnjenje.
- `path` (string) — Neispravno polje.
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `409 watchlist_full` — Dostignut broj praćenih vozila plana (odgovor nosi `max`, `count`).
## Primjer
```bash
curl -X POST "https://api.cifra.ba/v1/watchlist/batch" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"kind": "owned",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"vehicle": {
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual"
},
"km_per_year": 18000,
"exposure": {
"kind": "financing",
"amount_bam": 18500,
"as_of": "2026-10-18",
"term_months": 36,
"annual_rate_pct": 6.9,
"balloon_bam": 12000
},
"alerts": {
"change_pct": 5,
"direction": "down",
"exposure_pct": 85
},
"tags": [
"lizing",
"sarajevo"
]
},
{
"kind": "wanted",
"label": "Traži: Octavia 2018+",
"vehicle": {
"make": "škoda",
"model": "octavia",
"year": 2018,
"mileage_km": 150000,
"fuel": "diesel"
},
"alerts": {
"deal_pct": 12
}
}
]
}'
```
```json
{
"object": "list",
"created": 1,
"data": [
{
"index": 0,
"watched_vehicle": {
"object": "watched_vehicle",
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"kind": "owned",
"status": "active",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"tags": [
"lizing",
"sarajevo"
],
"note": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual",
"make_name": "Volkswagen",
"model_name": "Golf 7"
},
"mileage": {
"today_km": 148000,
"given_km": 148000,
"given_on": "2026-10-18",
"km_per_year": 18000
},
"alerts": {
"change_pct": 5,
"direction": "down",
"below_bam": null,
"above_bam": null,
"exposure_pct": 85,
"deal_pct": null
},
"exposure": {
"kind": "financing",
"amount_bam": 18500,
"as_of": "2026-10-18",
"term_months": 36,
"annual_rate_pct": 6.9,
"balloon_bam": 12000,
"today_bam": 18500,
"ratio": 0.8277
},
"baseline": {
"value": 22350,
"on": "2026-10-18"
},
"latest": {
"on": "2026-10-18",
"point": 22350,
"low": 18610,
"high": 26790,
"confidence_grade": "A",
"model_version": "car-20261017-1"
},
"forecast": {
"km_per_year": 18000,
"points": [
{
"months": 6,
"point": 21280,
"low": 16270,
"high": 26330
},
{
"months": 12,
"point": 20270,
"low": 14540,
"high": 25760
},
{
"months": 24,
"point": 18420,
"low": 13670,
"high": 23160
},
{
"months": 36,
"point": 16760,
"low": 11910,
"high": 21520
}
]
},
"change_since_baseline_pct": 0,
"created_at": "2026-10-18T22:04:11.532Z",
"updated_at": "2026-10-18T22:04:11.532Z"
}
},
{
"index": 1,
"error": {
"code": "watchlist_full",
"message": "This plan allows 1000 watched vehicles (1000 now); delete some or upgrade."
}
}
]
}
```
---
# Lista praćenih vozila
`GET https://api.cifra.ba/v1/watchlist`
Praćena vozila, od najnovijeg, po stranicama (`limit`, `starting_after`). Filtrirajte po vašoj oznaci ili statusu.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri upita
- `external_ref` (string, do 120 znakova) — Samo vozila s ovom vašom oznakom.
- `status` (enum) — Samo aktivna ili samo pauzirana vozila. Vrijednosti: `active`, `paused`.
- `limit` (integer, 1 – 100, podrazumijevano 50) — Koliko stavki po stranici.
- `starting_after` (string) — Kursor: `id` zadnje stavke prethodne stranice. Sljedeća stranica počinje iza nje.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `data` (object[], obavezno) — Vozila, od najnovijeg.
- `object` (string, obavezno) — `watched_vehicle`. Vrijednosti: `watched_vehicle`.
- `id` (string, obavezno) — Oznaka (`wv_…`).
- `kind` (enum, obavezno) — `owned` ili `wanted`. Vrijednosti: `owned`, `wanted`.
- `status` (enum, obavezno) — `active` ili `paused`. Vrijednosti: `active`, `paused`.
- `label` (string, obavezno) — Naziv.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `tags` (string[], obavezno) — Vaše grupe.
- `note` (string, obavezno) — Napomena.
- `vehicle` (object, obavezno) — Vozilo kako ste ga poslali, s nazivima iz šifarnika.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Naziv marke.
- `model_name` (string, obavezno) — Naziv modela.
- `mileage` (object, obavezno) — Kilometraža: vlastitim vozilima raste svaki dan.
- `today_km` (integer, obavezno) — Procijenjena kilometraža danas.
- `given_km` (integer, obavezno) — Zadnja kilometraža koju ste poslali.
- `given_on` (string, obavezno) — Kad ste je poslali.
- `km_per_year` (integer, obavezno, može biti null) — Godišnji prosjek.
- `alerts` (object, obavezno) — Pravila alarma.
- `change_pct` (number, obavezno) — Prag promjene, %.
- `direction` (enum, obavezno) — Smjer. Vrijednosti: `any`, `up`, `down`.
- `below_bam` (integer, obavezno, može biti null) — Donja ciljna cijena.
- `above_bam` (integer, obavezno, može biti null) — Gornja ciljna cijena.
- `exposure_pct` (number, obavezno) — LTV prag, %.
- `deal_pct` (number, obavezno) — Prag povoljnog oglasa, %.
- `exposure` (object, obavezno, može biti null) — Izloženost (samo vlastita vozila).
- `kind` (enum, obavezno) — Vrsta izloženosti. Vrijednosti: `financing`, `insured`, `cost`.
- `amount_bam` (integer, obavezno) — Iznos na dan `as_of`.
- `as_of` (string, obavezno) — Dan na koji važi iznos.
- `term_months` (integer, obavezno, može biti null) — Preostali mjeseci.
- `annual_rate_pct` (number, obavezno) — Godišnja kamata.
- `balloon_bam` (integer, obavezno, može biti null) — Ostatak na kraju.
- `today_bam` (integer, obavezno) — Iznos danas, nakon otplate.
- `ratio` (number, obavezno) — Iznos danas ÷ zadnja vrijednost (LTV), npr. `0.84`.
- `baseline` (object, obavezno) — Polazna vrijednost.
- `value` (integer, obavezno) — Vrijednost kad je praćenje počelo.
- `on` (string, obavezno) — Dan.
- `latest` (object, obavezno, može biti null) — Zadnja dnevna procjena.
- `on` (string, obavezno) — Dan zadnje procjene.
- `point` (integer, obavezno, može biti null) — Vrijednost.
- `low` (integer, obavezno, može biti null) — Donja granica.
- `high` (integer, obavezno, može biti null) — Gornja granica.
- `confidence_grade` (string, obavezno) — Ocjena.
- `model_version` (string, obavezno) — Verzija modela.
- `forecast` (object, obavezno, može biti null) — Prognoza iz zadnje dnevne procjene.
- `km_per_year` (integer, obavezno) — Pretpostavljena godišnja kilometraža.
- `points` (object[], obavezno) — Vrijednost kroz 6–36 mjeseci.
- `months` (integer, obavezno) — Mjeseci od zadnje procjene.
- `point` (integer, obavezno) — Vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `change_since_baseline_pct` (number, obavezno) — Promjena od polazne vrijednosti, %.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `has_more` (boolean, obavezno) — Ima li još stranica (`starting_after`).
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
## Primjer
```bash
curl "https://api.cifra.ba/v1/watchlist?external_ref=2024%2F118" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "list",
"data": [
{
"object": "watched_vehicle",
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"kind": "owned",
"status": "active",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"tags": [
"lizing",
"sarajevo"
],
"note": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual",
"make_name": "Volkswagen",
"model_name": "Golf 7"
},
"mileage": {
"today_km": 148000,
"given_km": 148000,
"given_on": "2026-10-18",
"km_per_year": 18000
},
"alerts": {
"change_pct": 5,
"direction": "down",
"below_bam": null,
"above_bam": null,
"exposure_pct": 85,
"deal_pct": null
},
"exposure": {
"kind": "financing",
"amount_bam": 18500,
"as_of": "2026-10-18",
"term_months": 36,
"annual_rate_pct": 6.9,
"balloon_bam": 12000,
"today_bam": 18500,
"ratio": 0.8277
},
"baseline": {
"value": 22350,
"on": "2026-10-18"
},
"latest": {
"on": "2026-10-18",
"point": 22350,
"low": 18610,
"high": 26790,
"confidence_grade": "A",
"model_version": "car-20261017-1"
},
"forecast": {
"km_per_year": 18000,
"points": [
{
"months": 6,
"point": 21280,
"low": 16270,
"high": 26330
},
{
"months": 12,
"point": 20270,
"low": 14540,
"high": 25760
},
{
"months": 24,
"point": 18420,
"low": 13670,
"high": 23160
},
{
"months": 36,
"point": 16760,
"low": 11910,
"high": 21520
}
]
},
"change_since_baseline_pct": 0,
"created_at": "2026-10-18T22:04:11.532Z",
"updated_at": "2026-10-18T22:04:11.532Z"
}
],
"has_more": false
}
```
---
# Praćeno vozilo
`GET https://api.cifra.ba/v1/watchlist/{id}`
Jedno vozilo: zadnja procjena, promjena od početka, izloženost i LTV, prognoza i pravila alarma.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka vozila (`wv_…`).
## Odgovor 200
- `object` (string, obavezno) — `watched_vehicle`. Vrijednosti: `watched_vehicle`.
- `id` (string, obavezno) — Oznaka (`wv_…`).
- `kind` (enum, obavezno) — `owned` ili `wanted`. Vrijednosti: `owned`, `wanted`.
- `status` (enum, obavezno) — `active` ili `paused`. Vrijednosti: `active`, `paused`.
- `label` (string, obavezno) — Naziv.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `tags` (string[], obavezno) — Vaše grupe.
- `note` (string, obavezno) — Napomena.
- `vehicle` (object, obavezno) — Vozilo kako ste ga poslali, s nazivima iz šifarnika.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Naziv marke.
- `model_name` (string, obavezno) — Naziv modela.
- `mileage` (object, obavezno) — Kilometraža: vlastitim vozilima raste svaki dan.
- `today_km` (integer, obavezno) — Procijenjena kilometraža danas.
- `given_km` (integer, obavezno) — Zadnja kilometraža koju ste poslali.
- `given_on` (string, obavezno) — Kad ste je poslali.
- `km_per_year` (integer, obavezno, može biti null) — Godišnji prosjek.
- `alerts` (object, obavezno) — Pravila alarma.
- `change_pct` (number, obavezno) — Prag promjene, %.
- `direction` (enum, obavezno) — Smjer. Vrijednosti: `any`, `up`, `down`.
- `below_bam` (integer, obavezno, može biti null) — Donja ciljna cijena.
- `above_bam` (integer, obavezno, može biti null) — Gornja ciljna cijena.
- `exposure_pct` (number, obavezno) — LTV prag, %.
- `deal_pct` (number, obavezno) — Prag povoljnog oglasa, %.
- `exposure` (object, obavezno, može biti null) — Izloženost (samo vlastita vozila).
- `kind` (enum, obavezno) — Vrsta izloženosti. Vrijednosti: `financing`, `insured`, `cost`.
- `amount_bam` (integer, obavezno) — Iznos na dan `as_of`.
- `as_of` (string, obavezno) — Dan na koji važi iznos.
- `term_months` (integer, obavezno, može biti null) — Preostali mjeseci.
- `annual_rate_pct` (number, obavezno) — Godišnja kamata.
- `balloon_bam` (integer, obavezno, može biti null) — Ostatak na kraju.
- `today_bam` (integer, obavezno) — Iznos danas, nakon otplate.
- `ratio` (number, obavezno) — Iznos danas ÷ zadnja vrijednost (LTV), npr. `0.84`.
- `baseline` (object, obavezno) — Polazna vrijednost.
- `value` (integer, obavezno) — Vrijednost kad je praćenje počelo.
- `on` (string, obavezno) — Dan.
- `latest` (object, obavezno, može biti null) — Zadnja dnevna procjena.
- `on` (string, obavezno) — Dan zadnje procjene.
- `point` (integer, obavezno, može biti null) — Vrijednost.
- `low` (integer, obavezno, može biti null) — Donja granica.
- `high` (integer, obavezno, može biti null) — Gornja granica.
- `confidence_grade` (string, obavezno) — Ocjena.
- `model_version` (string, obavezno) — Verzija modela.
- `forecast` (object, obavezno, može biti null) — Prognoza iz zadnje dnevne procjene.
- `km_per_year` (integer, obavezno) — Pretpostavljena godišnja kilometraža.
- `points` (object[], obavezno) — Vrijednost kroz 6–36 mjeseci.
- `months` (integer, obavezno) — Mjeseci od zadnje procjene.
- `point` (integer, obavezno) — Vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `change_since_baseline_pct` (number, obavezno) — Promjena od polazne vrijednosti, %.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
## Greške
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
## Primjer
```bash
curl "https://api.cifra.ba/v1/watchlist/wv_3JdP0aZr6YcN2uE5kHq8" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "watched_vehicle",
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"kind": "owned",
"status": "active",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"tags": [
"lizing",
"sarajevo"
],
"note": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual",
"make_name": "Volkswagen",
"model_name": "Golf 7"
},
"mileage": {
"today_km": 148000,
"given_km": 148000,
"given_on": "2026-10-18",
"km_per_year": 18000
},
"alerts": {
"change_pct": 5,
"direction": "down",
"below_bam": null,
"above_bam": null,
"exposure_pct": 85,
"deal_pct": null
},
"exposure": {
"kind": "financing",
"amount_bam": 18500,
"as_of": "2026-10-18",
"term_months": 36,
"annual_rate_pct": 6.9,
"balloon_bam": 12000,
"today_bam": 18500,
"ratio": 0.8277
},
"baseline": {
"value": 22350,
"on": "2026-10-18"
},
"latest": {
"on": "2026-10-18",
"point": 22350,
"low": 18610,
"high": 26790,
"confidence_grade": "A",
"model_version": "car-20261017-1"
},
"forecast": {
"km_per_year": 18000,
"points": [
{
"months": 6,
"point": 21280,
"low": 16270,
"high": 26330
},
{
"months": 12,
"point": 20270,
"low": 14540,
"high": 25760
},
{
"months": 24,
"point": 18420,
"low": 13670,
"high": 23160
},
{
"months": 36,
"point": 16760,
"low": 11910,
"high": 21520
}
]
},
"change_since_baseline_pct": 0,
"created_at": "2026-10-18T22:04:11.532Z",
"updated_at": "2026-10-18T22:04:11.532Z"
}
```
---
# Izmjena praćenog vozila
`PATCH https://api.cifra.ba/v1/watchlist/{id}`
Mijenja samo poslana polja: novo očitanje kilometraže, pravila alarma, izloženost (npr. nakon rate kredita), pauza.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka vozila (`wv_…`).
## Tijelo zahtjeva
- `label` (string, može biti null, do 120 znakova) — Novi naziv; `null` briše.
- `external_ref` (string, može biti null, do 120 znakova) — Nova vaša oznaka; `null` briše.
- `status` (enum) — `paused` zaustavlja dnevnu procjenu i alarme; `active` ih vraća. Vrijednosti: `active`, `paused`.
- `km_per_year` (integer, može biti null, 0 – 150.000) — Vlastita vozila: novi godišnji prosjek kilometara.
- `mileage_km` (integer, 0 – 2.000.000) — Vlastita vozila: novo očitanje brojila; kilometraža dalje raste od njega, od danas.
- `alerts` (object) — Pravila koja mijenjate; ostala ostaju kakva jesu.
- `change_pct` (number, može biti null, 3 – 90) — Alarm kad se vrijednost pomjeri za ovoliko posto: od početne vrijednosti, zatim od vrijednosti pri zadnjem alarmu. Najmanje 3, jer samo ponovno treniranje modela pomjeri vrijednosti ~2%. `null` isključuje.
- `direction` (enum) — Koji pomak broji za `change_pct`: `any` (podrazumijevano), `up` ili `down`. Vrijednosti: `any`, `up`, `down`.
- `below_bam` (integer, može biti null, 100 – 5.000.000) — Alarm kad vrijednost padne ispod ove cijene (KM).
- `above_bam` (integer, može biti null, 100 – 5.000.000) — Alarm kad vrijednost poraste iznad ove cijene (KM).
- `exposure_pct` (number, može biti null, 10 – 300) — Vlastita vozila: alarm na dan kad izloženost (dug, osigurana suma, trošak) dostigne ovaj postotak vrijednosti (LTV), samo pri rastu.
- `deal_pct` (number, može biti null, 5 – 50) — Tražena vozila: alarm za svaki novi oglas iste specifikacije koji traži ovoliko posto manje od Cifrine cijene (najviše 5 dnevno).
- `exposure` (object, može biti null) — Nova izloženost; `null` je uklanja.
- `kind` (enum, obavezno) — `financing`: stanje kredita ili lizinga (otplaćuje se); `insured`: osigurana suma; `cost`: nabavna cijena. Vrijednosti: `financing`, `insured`, `cost`.
- `amount_bam` (integer, obavezno, 100 – 20.000.000) — Iznos u KM na dan `as_of`.
- `as_of` (date) — Dan na koji važi `amount_bam` (podrazumijevano danas).
- `term_months` (integer, može biti null, 1 – 240) — `financing`: preostali broj mjeseci; stanje se otplaćuje do `balloon_bam`, a nakon roka je nula.
- `annual_rate_pct` (number, može biti null, 0 – 40) — `financing`: nominalna godišnja kamata za anuitetnu otplatu; `0` znači linearnu.
- `balloon_bam` (integer, može biti null, 0 – 20.000.000) — `financing`: ostatak na kraju roka (balon rata, otkupna vrijednost).
- `tags` (string[], do 10 stavki) — Zamjenjuje sve oznake.
- `note` (string, može biti null, do 2000 znakova) — Nova napomena; `null` briše.
## Odgovor 200
- `object` (string, obavezno) — `watched_vehicle`. Vrijednosti: `watched_vehicle`.
- `id` (string, obavezno) — Oznaka (`wv_…`).
- `kind` (enum, obavezno) — `owned` ili `wanted`. Vrijednosti: `owned`, `wanted`.
- `status` (enum, obavezno) — `active` ili `paused`. Vrijednosti: `active`, `paused`.
- `label` (string, obavezno) — Naziv.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `tags` (string[], obavezno) — Vaše grupe.
- `note` (string, obavezno) — Napomena.
- `vehicle` (object, obavezno) — Vozilo kako ste ga poslali, s nazivima iz šifarnika.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Naziv marke.
- `model_name` (string, obavezno) — Naziv modela.
- `mileage` (object, obavezno) — Kilometraža: vlastitim vozilima raste svaki dan.
- `today_km` (integer, obavezno) — Procijenjena kilometraža danas.
- `given_km` (integer, obavezno) — Zadnja kilometraža koju ste poslali.
- `given_on` (string, obavezno) — Kad ste je poslali.
- `km_per_year` (integer, obavezno, može biti null) — Godišnji prosjek.
- `alerts` (object, obavezno) — Pravila alarma.
- `change_pct` (number, obavezno) — Prag promjene, %.
- `direction` (enum, obavezno) — Smjer. Vrijednosti: `any`, `up`, `down`.
- `below_bam` (integer, obavezno, može biti null) — Donja ciljna cijena.
- `above_bam` (integer, obavezno, može biti null) — Gornja ciljna cijena.
- `exposure_pct` (number, obavezno) — LTV prag, %.
- `deal_pct` (number, obavezno) — Prag povoljnog oglasa, %.
- `exposure` (object, obavezno, može biti null) — Izloženost (samo vlastita vozila).
- `kind` (enum, obavezno) — Vrsta izloženosti. Vrijednosti: `financing`, `insured`, `cost`.
- `amount_bam` (integer, obavezno) — Iznos na dan `as_of`.
- `as_of` (string, obavezno) — Dan na koji važi iznos.
- `term_months` (integer, obavezno, može biti null) — Preostali mjeseci.
- `annual_rate_pct` (number, obavezno) — Godišnja kamata.
- `balloon_bam` (integer, obavezno, može biti null) — Ostatak na kraju.
- `today_bam` (integer, obavezno) — Iznos danas, nakon otplate.
- `ratio` (number, obavezno) — Iznos danas ÷ zadnja vrijednost (LTV), npr. `0.84`.
- `baseline` (object, obavezno) — Polazna vrijednost.
- `value` (integer, obavezno) — Vrijednost kad je praćenje počelo.
- `on` (string, obavezno) — Dan.
- `latest` (object, obavezno, može biti null) — Zadnja dnevna procjena.
- `on` (string, obavezno) — Dan zadnje procjene.
- `point` (integer, obavezno, može biti null) — Vrijednost.
- `low` (integer, obavezno, može biti null) — Donja granica.
- `high` (integer, obavezno, može biti null) — Gornja granica.
- `confidence_grade` (string, obavezno) — Ocjena.
- `model_version` (string, obavezno) — Verzija modela.
- `forecast` (object, obavezno, može biti null) — Prognoza iz zadnje dnevne procjene.
- `km_per_year` (integer, obavezno) — Pretpostavljena godišnja kilometraža.
- `points` (object[], obavezno) — Vrijednost kroz 6–36 mjeseci.
- `months` (integer, obavezno) — Mjeseci od zadnje procjene.
- `point` (integer, obavezno) — Vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `change_since_baseline_pct` (number, obavezno) — Promjena od polazne vrijednosti, %.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
- `422 not_owned` — `km_per_year`, `mileage_km` ili `exposure` za traženo (`wanted`) vozilo.
- `422 not_wanted` — `deal_pct` za vlastito (`owned`) vozilo.
## Primjer
```bash
curl -X PATCH "https://api.cifra.ba/v1/watchlist/wv_3JdP0aZr6YcN2uE5kHq8" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mileage_km": 151200,
"alerts": {
"change_pct": 4
},
"exposure": {
"kind": "financing",
"amount_bam": 18425,
"as_of": "2026-11-01",
"term_months": 35,
"annual_rate_pct": 6.9,
"balloon_bam": 12000
}
}'
```
```json
{
"object": "watched_vehicle",
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"kind": "owned",
"status": "active",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"tags": [
"lizing",
"sarajevo"
],
"note": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"year": 2017,
"mileage_km": 148000,
"power_kw": 85,
"fuel": "diesel",
"transmission": "manual",
"make_name": "Volkswagen",
"model_name": "Golf 7"
},
"mileage": {
"today_km": 151200,
"given_km": 151200,
"given_on": "2026-11-01",
"km_per_year": 18000
},
"alerts": {
"change_pct": 4,
"direction": "down",
"below_bam": null,
"above_bam": null,
"exposure_pct": 85,
"deal_pct": null
},
"exposure": {
"kind": "financing",
"amount_bam": 18425,
"as_of": "2026-11-01",
"term_months": 35,
"annual_rate_pct": 6.9,
"balloon_bam": 12000,
"today_bam": 18425,
"ratio": 0.8244
},
"baseline": {
"value": 22350,
"on": "2026-10-18"
},
"latest": {
"on": "2026-10-18",
"point": 22350,
"low": 18610,
"high": 26790,
"confidence_grade": "A",
"model_version": "car-20261017-1"
},
"forecast": {
"km_per_year": 18000,
"points": [
{
"months": 6,
"point": 21280,
"low": 16270,
"high": 26330
},
{
"months": 12,
"point": 20270,
"low": 14540,
"high": 25760
},
{
"months": 24,
"point": 18420,
"low": 13670,
"high": 23160
},
{
"months": 36,
"point": 16760,
"low": 11910,
"high": 21520
}
]
},
"change_since_baseline_pct": 0,
"created_at": "2026-10-18T22:04:11.532Z",
"updated_at": "2026-11-01T10:02:37.118Z"
}
```
---
# Prestanak praćenja
`DELETE https://api.cifra.ba/v1/watchlist/{id}`
Vozilo se više ne procjenjuje i ne broji se u limit praćenih vozila.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka vozila (`wv_…`).
## Odgovor 200
- `object` (string, obavezno) — `watched_vehicle`. Vrijednosti: `watched_vehicle`.
- `id` (string, obavezno) — Oznaka.
- `deleted` (boolean, obavezno) — `true`. Vrijednosti: `true`.
## Greške
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
## Primjer
```bash
curl -X DELETE "https://api.cifra.ba/v1/watchlist/wv_3JdP0aZr6YcN2uE5kHq8" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "watched_vehicle",
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"deleted": true
}
```
---
# Historija vrijednosti
`GET https://api.cifra.ba/v1/watchlist/{id}/history`
Vrijednost vozila za svaki dan praćenja, s rasponom, kilometražom i verzijom modela. Podrazumijevano zadnjih 90 dana.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka vozila (`wv_…`).
## Parametri upita
- `from` (date) — Od dana (`YYYY-MM-DD`); podrazumijevano 90 dana prije `to`.
- `to` (date) — Do dana (`YYYY-MM-DD`); podrazumijevano danas.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `watched_vehicle_id` (string, obavezno) — Vozilo.
- `from` (string, obavezno) — Od dana.
- `to` (string, obavezno) — Do dana.
- `data` (object[], obavezno) — Vrijednost za svaki dan, od najstarijeg.
- `day` (string, obavezno) — Dan, `YYYY-MM-DD`.
- `point` (integer, obavezno) — Vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `confidence_grade` (string, obavezno) — Ocjena.
- `change_pct` (number, obavezno) — Promjena od prethodne procjene, %.
- `mileage_km` (integer, obavezno) — Kilometraža tog dana.
- `model_version` (string, obavezno) — Verzija modela.
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
## Primjer
```bash
curl "https://api.cifra.ba/v1/watchlist/wv_3JdP0aZr6YcN2uE5kHq8/history?from=2026-10-18&to=2026-10-21" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "list",
"watched_vehicle_id": "wv_3JdP0aZr6YcN2uE5kHq8",
"from": "2026-10-18",
"to": "2026-10-21",
"data": [
{
"day": "2026-10-18",
"point": 22350,
"low": 18610,
"high": 26790,
"confidence_grade": "A",
"change_pct": null,
"mileage_km": 148000,
"model_version": "car-20261017-1"
},
{
"day": "2026-10-19",
"point": 22330,
"low": 18590,
"high": 26770,
"confidence_grade": "A",
"change_pct": -0.09,
"mileage_km": 148049,
"model_version": "car-20261017-1"
},
{
"day": "2026-10-20",
"point": 22310,
"low": 18580,
"high": 26740,
"confidence_grade": "A",
"change_pct": -0.09,
"mileage_km": 148099,
"model_version": "car-20261017-1"
},
{
"day": "2026-10-21",
"point": 22300,
"low": 18570,
"high": 26730,
"confidence_grade": "A",
"change_pct": -0.04,
"mileage_km": 148148,
"model_version": "car-20261017-1"
}
]
}
```
---
# Dnevni izvještaj
`GET https://api.cifra.ba/v1/watchlist/report`
Svako praćeno vozilo na jedan dan: vrijednost, promjena od prethodne i od polazne, izloženost i LTV, i alarmi tog dana. Spreman svako jutro; javlja ga webhook `watchlist.report_ready`.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri upita
- `day` (date) — Dan izvještaja (`YYYY-MM-DD`); podrazumijevano zadnji procijenjeni dan.
- `external_ref` (string, do 120 znakova) — Samo vozila s ovom vašom oznakom.
## Odgovor 200
- `object` (string, obavezno) — `watchlist_report`. Vrijednosti: `watchlist_report`.
- `day` (string, obavezno) — Dan izvještaja.
- `summary` (object, obavezno) — Sažetak dana.
- `vehicles` (integer, obavezno) — Vozila u izvještaju.
- `valued` (integer, obavezno) — Procijenjena tog dana.
- `up` (integer, obavezno) — Porasla.
- `down` (integer, obavezno) — Pala.
- `alerts` (integer, obavezno) — Alarmi tog dana.
- `data` (object[], obavezno) — Svako vozilo.
- `id` (string, obavezno) — Vozilo.
- `label` (string, obavezno) — Naziv.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `kind` (enum, obavezno) — Vrsta. Vrijednosti: `owned`, `wanted`.
- `status` (enum, obavezno) — Status. Vrijednosti: `active`, `paused`.
- `tags` (string[], obavezno) — Grupe.
- `value` (object, obavezno, može biti null) — Vrijednost tog dana; `null` ako nije procijenjeno.
- `point` (integer, obavezno) — Vrijednost.
- `low` (integer, obavezno) — Donja granica.
- `high` (integer, obavezno) — Gornja granica.
- `confidence_grade` (enum, obavezno) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `previous` (object, obavezno, može biti null) — Prethodna procjena.
- `day` (string, obavezno) — Dan, `YYYY-MM-DD`.
- `point` (integer, obavezno) — Vrijednost.
- `change_pct` (number, obavezno) — Promjena od prethodne, %.
- `change_since_baseline_pct` (number, obavezno) — Promjena od polazne, %.
- `exposure` (object, obavezno, može biti null) — Izloženost i LTV tog dana.
- `amount_bam` (integer, obavezno) — Izloženost tog dana.
- `ratio` (number, obavezno) — LTV.
- `alerts` (object[], obavezno) — Alarmi tog dana.
- `object` (string, obavezno) — `alert`. Vrijednosti: `alert`.
- `id` (string, obavezno) — Oznaka (`alr_…`).
- `type` (enum, obavezno) — `value_changed` (`change_pct`), `below_target` / `above_target` (`below_bam` / `above_bam`), `exposure_above` (`exposure_pct`), `market_deal` (`deal_pct`). Vrijednosti: `value_changed`, `below_target`, `above_target`, `exposure_above`, `market_deal`.
- `watched_vehicle` (object, obavezno) — Vozilo na koje se alarm odnosi.
- `id` (string, obavezno) — Vozilo.
- `label` (string, obavezno) — Naziv.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `kind` (enum, obavezno) — Vrsta. Vrijednosti: `owned`, `wanted`.
- `day` (string, obavezno) — Dan procjene koji je pokrenuo alarm.
- `previous_value` (integer, obavezno) — Vrijednost od koje se mjeri (za `market_deal`: Cifrina cijena oglasa).
- `value` (integer, obavezno) — Nova vrijednost (za `market_deal`: cijena u oglasu).
- `change_pct` (number, obavezno) — Promjena, %.
- `threshold` (number, obavezno) — Prag pravila koje se aktiviralo.
- `details` (object, obavezno, može biti null) — Pojedinosti, zavisno od vrste.
- `exposure` (object) — `exposure_above`: izloženost tog dana.
- `kind` (string, obavezno) — Vrsta izloženosti.
- `amount` (integer, obavezno) — Iznos tog dana.
- `ratio` (number, obavezno) — LTV tog dana.
- `listing` (object) — `market_deal`: oglas.
- `id` (integer, obavezno) — Oznaka oglasa kod Cifre.
- `title` (string, obavezno) — Naslov.
- `year` (integer, obavezno) — Godište.
- `km` (integer, obavezno, može biti null) — Kilometraža.
- `price` (integer, obavezno) — Cijena.
- `fairPrice` (integer, obavezno) — Cifrina cijena.
- `place` (string, obavezno) — Mjesto.
- `url` (string, obavezno) — Link oglasa.
- `seller` (string, obavezno) — Vrsta prodavca.
- `modelChanged` (object) — Tog dana je počeo raditi novi model: dio pomaka može biti model, ne tržište.
- `from` (string, obavezno) — Prethodni model.
- `to` (string, obavezno) — Novi model.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
## Primjer
```bash
curl "https://api.cifra.ba/v1/watchlist/report?day=2026-12-02" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "watchlist_report",
"day": "2026-12-02",
"summary": {
"vehicles": 412,
"valued": 412,
"up": 37,
"down": 351,
"alerts": 1
},
"data": [
{
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"kind": "owned",
"status": "active",
"tags": [
"lizing",
"sarajevo"
],
"value": {
"point": 21400,
"low": 17820,
"high": 25650,
"confidence_grade": "A"
},
"previous": {
"day": "2026-12-01",
"point": 21560
},
"change_pct": -0.74,
"change_since_baseline_pct": -4.25,
"exposure": {
"amount_bam": 18259,
"ratio": 0.8532
},
"alerts": [
{
"object": "alert",
"id": "alr_8fK2mQ9xLp4TvB7nR1sW",
"type": "exposure_above",
"watched_vehicle": {
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"kind": "owned"
},
"day": "2026-12-02",
"previous_value": 22350,
"value": 21400,
"change_pct": -4.25,
"threshold": 85,
"details": {
"exposure": {
"kind": "financing",
"amount": 18259,
"ratio": 0.8532
}
},
"created_at": "2026-12-02T06:12:44.000Z"
}
]
}
]
}
```
---
# Lista alarma
`GET https://api.cifra.ba/v1/alerts`
Alarmi svih praćenih vozila, od najnovijeg, po stranicama. Isti alarmi stižu i webhookom `watchlist.alert`; lista služi za pregled i za nadoknadu propuštenog.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri upita
- `watched_vehicle_id` (string) — Samo alarmi jednog praćenog vozila (`wv_…`).
- `since` (datetime) — Samo alarmi nastali od ovog trenutka (ISO 8601).
- `limit` (integer, 1 – 100, podrazumijevano 50) — Koliko stavki po stranici.
- `starting_after` (string) — Kursor: `id` zadnje stavke prethodne stranice. Sljedeća stranica počinje iza nje.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `data` (object[], obavezno) — Alarmi, od najnovijeg.
- `object` (string, obavezno) — `alert`. Vrijednosti: `alert`.
- `id` (string, obavezno) — Oznaka (`alr_…`).
- `type` (enum, obavezno) — `value_changed` (`change_pct`), `below_target` / `above_target` (`below_bam` / `above_bam`), `exposure_above` (`exposure_pct`), `market_deal` (`deal_pct`). Vrijednosti: `value_changed`, `below_target`, `above_target`, `exposure_above`, `market_deal`.
- `watched_vehicle` (object, obavezno) — Vozilo na koje se alarm odnosi.
- `id` (string, obavezno) — Vozilo.
- `label` (string, obavezno) — Naziv.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `kind` (enum, obavezno) — Vrsta. Vrijednosti: `owned`, `wanted`.
- `day` (string, obavezno) — Dan procjene koji je pokrenuo alarm.
- `previous_value` (integer, obavezno) — Vrijednost od koje se mjeri (za `market_deal`: Cifrina cijena oglasa).
- `value` (integer, obavezno) — Nova vrijednost (za `market_deal`: cijena u oglasu).
- `change_pct` (number, obavezno) — Promjena, %.
- `threshold` (number, obavezno) — Prag pravila koje se aktiviralo.
- `details` (object, obavezno, može biti null) — Pojedinosti, zavisno od vrste.
- `exposure` (object) — `exposure_above`: izloženost tog dana.
- `kind` (string, obavezno) — Vrsta izloženosti.
- `amount` (integer, obavezno) — Iznos tog dana.
- `ratio` (number, obavezno) — LTV tog dana.
- `listing` (object) — `market_deal`: oglas.
- `id` (integer, obavezno) — Oznaka oglasa kod Cifre.
- `title` (string, obavezno) — Naslov.
- `year` (integer, obavezno) — Godište.
- `km` (integer, obavezno, može biti null) — Kilometraža.
- `price` (integer, obavezno) — Cijena.
- `fairPrice` (integer, obavezno) — Cifrina cijena.
- `place` (string, obavezno) — Mjesto.
- `url` (string, obavezno) — Link oglasa.
- `seller` (string, obavezno) — Vrsta prodavca.
- `modelChanged` (object) — Tog dana je počeo raditi novi model: dio pomaka može biti model, ne tržište.
- `from` (string, obavezno) — Prethodni model.
- `to` (string, obavezno) — Novi model.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `has_more` (boolean, obavezno) — Ima li još stranica.
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
## Primjer
```bash
curl "https://api.cifra.ba/v1/alerts?since=2026-10-01T00%3A00%3A00Z" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "list",
"data": [
{
"object": "alert",
"id": "alr_8fK2mQ9xLp4TvB7nR1sW",
"type": "exposure_above",
"watched_vehicle": {
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"label": "VW Golf 7 — ugovor 2024/118",
"external_ref": "2024/118",
"kind": "owned"
},
"day": "2026-12-02",
"previous_value": 22350,
"value": 21400,
"change_pct": -4.25,
"threshold": 85,
"details": {
"exposure": {
"kind": "financing",
"amount": 18259,
"ratio": 0.8532
}
},
"created_at": "2026-12-02T06:12:44.000Z"
},
{
"object": "alert",
"id": "alr_Vb3nQ7xR2kLp9TzW5mYc",
"type": "market_deal",
"watched_vehicle": {
"id": "wv_9QeL2mXc7TbN4vR8kPz1",
"label": "Traži: Octavia 2018+",
"external_ref": null,
"kind": "wanted"
},
"day": "2026-10-20",
"previous_value": 24900,
"value": 21500,
"change_pct": -13.65,
"threshold": 12,
"details": {
"listing": {
"id": 9812334,
"title": "Škoda Octavia 2.0 TDI Style",
"year": 2018,
"km": 168000,
"price": 21500,
"fairPrice": 24900,
"place": "Mostar",
"url": "https://olx.ba/artikal/61234567",
"seller": "PRIVATE"
}
},
"created_at": "2026-10-20T06:09:31.000Z"
}
],
"has_more": false
}
```
---
# Nova webhook adresa
`POST https://api.cifra.ba/v1/webhooks`
Adresa na koju Cifra šalje događaje, potpisane vašom tajnom. Tajna se vraća samo u ovom odgovoru. Najviše 5 aktivnih adresa po okruženju.
Pristup: `watchlist`. Obračun: besplatno.
## Tijelo zahtjeva
- `url` (string, obavezno, 8–2048 znakova) — HTTPS adresa koja prima događaje. Mora biti javno dostupna (ne lokalna ni privatna mreža).
- `events` (enum[], do 9 stavki) — Događaji koje adresa prima. Bez polja ili `[]`: svi. Vrijednosti: `watchlist.alert`, `watchlist.report_ready`, `widget.rating_changed`, `report.created`, `check.completed`, `check.decided`, `bulk.completed`, `usage.threshold_reached`, `webhook.test`.
- `description` (string, do 200 znakova) — Vaš opis, npr. `Produkcija — core banking`.
## Odgovor 201
- `object` (string, obavezno) — `webhook_endpoint`. Vrijednosti: `webhook_endpoint`.
- `id` (string, obavezno) — Oznaka (`whe_…`).
- `url` (string, obavezno) — Adresa.
- `events` (string[], obavezno) — Događaji; `["*"]` znači svi.
- `description` (string, obavezno) — Opis.
- `status` (enum, obavezno) — `disabled`: isključena (ručno ili nakon 3 dana neuspješnih isporuka). Vrijednosti: `active`, `disabled`.
- `secret_hint` (string, obavezno) — Zadnja 4 znaka tajne, npr. `…x9Qa`.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `disabled_at` (string, obavezno, može biti null) — Trenutak u ISO 8601 (UTC).
- `secret` (string, obavezno) — Tajna za provjeru potpisa (`whsec_…`). Prikazuje se samo sada — sačuvajte je.
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `400 invalid_webhook_url` — Adresa nije HTTPS ili vodi na lokalnu ili privatnu mrežu.
- `409 too_many_webhooks` — Već 5 aktivnih adresa u ovom okruženju.
## Primjer
```bash
curl -X POST "https://api.cifra.ba/v1/webhooks" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.firma.ba/cifra",
"events": [
"watchlist.alert",
"watchlist.report_ready"
],
"description": "Produkcija — kreditni sistem"
}'
```
```json
{
"object": "webhook_endpoint",
"id": "whe_K7pX2mQ9vN4tR8bL1cZe",
"url": "https://hooks.firma.ba/cifra",
"events": [
"watchlist.alert",
"watchlist.report_ready"
],
"description": "Produkcija — kreditni sistem",
"status": "active",
"secret_hint": "…x9Qa",
"created_at": "2026-10-18T22:10:03.441Z",
"disabled_at": null,
"secret": "whsec_4fJ8kL2mQ9xR7vT1bN6cZ3pW5yH0gD9x9Qa"
}
```
---
# Lista webhook adresa
`GET https://api.cifra.ba/v1/webhooks`
Adrese okruženja ključa (live ili test), s dijelom tajne i statusom.
Pristup: `watchlist`. Obračun: besplatno.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `data` (object[], obavezno) — Adrese ovog okruženja (live ili test).
- `object` (string, obavezno) — `webhook_endpoint`. Vrijednosti: `webhook_endpoint`.
- `id` (string, obavezno) — Oznaka (`whe_…`).
- `url` (string, obavezno) — Adresa.
- `events` (string[], obavezno) — Događaji; `["*"]` znači svi.
- `description` (string, obavezno) — Opis.
- `status` (enum, obavezno) — `disabled`: isključena (ručno ili nakon 3 dana neuspješnih isporuka). Vrijednosti: `active`, `disabled`.
- `secret_hint` (string, obavezno) — Zadnja 4 znaka tajne, npr. `…x9Qa`.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `disabled_at` (string, obavezno, može biti null) — Trenutak u ISO 8601 (UTC).
## Primjer
```bash
curl "https://api.cifra.ba/v1/webhooks" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "list",
"data": [
{
"object": "webhook_endpoint",
"id": "whe_K7pX2mQ9vN4tR8bL1cZe",
"url": "https://hooks.firma.ba/cifra",
"events": [
"watchlist.alert",
"watchlist.report_ready"
],
"description": "Produkcija — kreditni sistem",
"status": "active",
"secret_hint": "…x9Qa",
"created_at": "2026-10-18T22:10:03.441Z",
"disabled_at": null
}
]
}
```
---
# Isključivanje adrese
`DELETE https://api.cifra.ba/v1/webhooks/{id}`
Adresa prestaje primati događaje, a isporuke koje su čekale se otkazuju.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka adrese (`whe_…`).
## Odgovor 200
- `object` (string, obavezno) — `webhook_endpoint`. Vrijednosti: `webhook_endpoint`.
- `id` (string, obavezno) — Oznaka (`whe_…`).
- `url` (string, obavezno) — Adresa.
- `events` (string[], obavezno) — Događaji; `["*"]` znači svi.
- `description` (string, obavezno) — Opis.
- `status` (enum, obavezno) — `disabled`: isključena (ručno ili nakon 3 dana neuspješnih isporuka). Vrijednosti: `active`, `disabled`.
- `secret_hint` (string, obavezno) — Zadnja 4 znaka tajne, npr. `…x9Qa`.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `disabled_at` (string, obavezno, može biti null) — Trenutak u ISO 8601 (UTC).
## Greške
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
## Primjer
```bash
curl -X DELETE "https://api.cifra.ba/v1/webhooks/whe_K7pX2mQ9vN4tR8bL1cZe" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "webhook_endpoint",
"id": "whe_K7pX2mQ9vN4tR8bL1cZe",
"url": "https://hooks.firma.ba/cifra",
"events": [
"watchlist.alert",
"watchlist.report_ready"
],
"description": "Produkcija — kreditni sistem",
"status": "disabled",
"secret_hint": "…x9Qa",
"created_at": "2026-10-18T22:10:03.441Z",
"disabled_at": "2026-11-02T09:00:12.000Z"
}
```
---
# Probni događaj
`POST https://api.cifra.ba/v1/webhooks/{id}/test`
Šalje `webhook.test` na adresu odmah, da provjerite prijem i provjeru potpisa. Ishod vidite u isporukama.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka adrese (`whe_…`).
## Odgovor 202
- `object` (string, obavezno) — `webhook_delivery`. Vrijednosti: `webhook_delivery`.
- `id` (integer, obavezno) — Oznaka isporuke.
- `event_id` (string, obavezno) — Oznaka događaja (`evt_…`).
## Greške
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
- `409 webhook_disabled` — Adresa je isključena.
## Primjer
```bash
curl -X POST "https://api.cifra.ba/v1/webhooks/whe_K7pX2mQ9vN4tR8bL1cZe/test" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "webhook_delivery",
"id": 90412,
"event_id": "evt_2kQ9mX7vR4tL8bN1cZ5p"
}
```
---
# Isporuke
`GET https://api.cifra.ba/v1/webhooks/{id}/deliveries`
Zadnje isporuke adrese: status, broj pokušaja, sljedeći pokušaj, HTTP status vaše adrese i greška.
Pristup: `watchlist`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka adrese (`whe_…`).
## Parametri upita
- `limit` (integer, 1 – 100, podrazumijevano 50) — Koliko zadnjih isporuka.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `data` (object[], obavezno) — Isporuke, od najnovije.
- `id` (integer, obavezno) — Oznaka isporuke.
- `event_id` (string, obavezno) — Događaj.
- `event_type` (string, obavezno) — Vrsta događaja.
- `status` (enum, obavezno) — `pending` (čeka pokušaj), `sending`, `succeeded`, `failed`. Vrijednosti: `pending`, `sending`, `succeeded`, `failed`.
- `attempts` (integer, obavezno) — Broj pokušaja.
- `next_attempt_at` (string, obavezno, može biti null) — Sljedeći pokušaj.
- `last_status_code` (integer, obavezno, može biti null) — Zadnji HTTP status vaše adrese.
- `last_error` (string, obavezno) — Zadnja greška.
- `duration_ms` (integer, obavezno, može biti null) — Trajanje zadnjeg pokušaja.
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `delivered_at` (string, obavezno, može biti null) — Kad je isporučeno.
## Greške
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
## Primjer
```bash
curl "https://api.cifra.ba/v1/webhooks/whe_K7pX2mQ9vN4tR8bL1cZe/deliveries" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "list",
"data": [
{
"id": 90412,
"event_id": "evt_2kQ9mX7vR4tL8bN1cZ5p",
"event_type": "webhook.test",
"status": "succeeded",
"attempts": 1,
"next_attempt_at": null,
"last_status_code": 200,
"last_error": null,
"duration_ms": 184,
"created_at": "2026-10-18T22:11:40.003Z",
"delivered_at": "2026-10-18T22:11:40.212Z"
},
{
"id": 90388,
"event_id": "evt_7vT1bN6cZ3pW5yH0gD9x",
"event_type": "watchlist.alert",
"status": "pending",
"attempts": 2,
"next_attempt_at": "2026-10-18T07:12:44.000Z",
"last_status_code": 503,
"last_error": "HTTP 503",
"duration_ms": 10000,
"created_at": "2026-10-18T06:12:44.000Z",
"delivered_at": null
}
]
}
```
---
# Objava widgeta
`POST https://api.cifra.ba/v1/widgets`
Objavljuje procjenu vaše kompanije (`valuation_id`) kao widgete za vašu stranicu: ocjenu tražene cijene, tržište, slična vozila, vrijednost kroz vrijeme. Vozilo se svako jutro procjenjuje ponovo, uvijek standardnim modelom. Javno se samo čita — widgeti nikad ne pozivaju API. Besplatno (naplaćena je procjena); plan određuje koliko vozila može biti objavljeno.
Pristup: `widgets`. Obračun: besplatno.
## Tijelo zahtjeva
- `valuation_id` (string, do 64 znaka) — Procjena napravljena produkcijskim ključem vaše kompanije (`val_…`, iz `POST /v1/valuations`). Widget prikazuje to vozilo, svako jutro ponovo procijenjeno.
- `report_id` (string, do 64 znaka) — Samo za Cifrinu platformu (izvještaj kompanije); vaš ključ šalje `valuation_id`.
- `asking_price` (integer, može biti null, 100 – 10.000.000) — Vaša tražena cijena u KM: widget je ocjenjuje naspram tržišne vrijednosti (odlična … visoka). Bez nje widget prikazuje samo vrijednost.
- `external_ref` (string, može biti null, do 80 znakova) — Vaša oznaka (broj u lageru), jedinstvena među vašim widgetima; po njoj ga i tražite.
- `title` (string, može biti null, do 120 znakova) — Naziv na widgetu, npr. `Golf 7 1.6 TDI Highline`. Bez njega: marka, model i godište.
- `listing_id` (integer, može biti null, najmanje 0) — Samo za Cifrinu platformu (oglas čija se cijena i prodaja prate).
- `price_from_listing` (boolean) — Samo za Cifrinu platformu: cijena prati oglas.
- `created_by` (string, do 64 znaka) — Samo za Cifrinu platformu: ko je objavio.
- `status` (enum) — `paused`: objavljen, ali se još ne prikazuje. Zadano `active`. Vrijednosti: `active`, `paused`.
## Odgovor 201
- `id` (string, obavezno) — Oznaka (`wgt_…`).
- `object` (string, obavezno) — `widget`. Vrijednosti: `widget`.
- `public_id` (string, obavezno) — Javni kod u adresi widgeta (`cifra.ba/embed//…`, `cifra.ba/w/`); ide u vašu stranicu.
- `status` (enum, obavezno) — `active`, `paused` ili `sold` (oglas s Cifrine platforme je skinut: widgeti kažu „Prodano”). Vrijednosti: `active`, `paused`, `sold`.
- `source` (enum, obavezno) — Iz API procjene ili izvještaja s platforme. Vrijednosti: `valuation`, `report`.
- `report_id` (string, obavezno) — Izvještaj s platforme, kad je odatle objavljen.
- `valuation_id` (string, obavezno) — API procjena iz koje je objavljen.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `title` (string, obavezno) — Naziv na widgetu (`null`: marka, model i godište).
- `vehicle` (object, obavezno) — Vozilo.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Marka.
- `model_name` (string, obavezno) — Model.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `fuel` (string, obavezno) — Gorivo.
- `transmission` (string, obavezno) — Mjenjač.
- `power_kw` (number, obavezno) — Snaga u kW.
- `asking_price` (integer, obavezno, može biti null) — Tražena cijena u KM.
- `value` (object, obavezno, može biti null) — Zadnja jutarnja procjena.
- `currency` (string, obavezno) — `BAM`. Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Tržišna vrijednost (standardni model, nezavisan od modela vaše kompanije).
- `low` (integer, obavezno, može biti null) — Donja granica raspona.
- `high` (integer, obavezno, može biti null) — Gornja granica raspona.
- `confidence_grade` (enum, obavezno, može biti null) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `as_of` (string, obavezno, može biti null) — Dan, `YYYY-MM-DD`.
- `rating` (object, obavezno, može biti null) — Ocjena kakvu widget prikazuje; `null` bez cijene, za prodano vozilo ili cijenu daleko van tržišta.
- `level` (enum, obavezno) — Ocjena cijene: `great` odlična, `good` dobra, `fair` fer, `high` povišena, `over` visoka. Vrijednosti: `great`, `good`, `fair`, `high`, `over`.
- `pct` (number, obavezno) — Tražena cijena naspram vrijednosti, u %.
- `diff_bam` (integer, obavezno) — Razlika u KM (negativna: ispod vrijednosti).
- `embed` (object, obavezno) — Gotov kod; druge vrste: `data-cifra-widget="badge|market|comparables|forecast|factors|mileage|report"`.
- `page_url` (string, obavezno) — Stranica vozila za kupce, s cijelim izvještajem.
- `script` (string, obavezno) — Kod widgeta „Cijena” sa skriptom (preporučeno).
- `iframe` (string, obavezno) — Isti widget kao iframe.
- `sold_at` (string, obavezno, može biti null) — Trenutak u ISO 8601 (UTC).
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `403 organization_required` — Ključ pripada klijentu koji nije vezan za kompaniju; widgeti su kompanijini.
- `403 live_key_required` — Testni ključ: widgeti su javni i objavljuju se samo iz stvarnih procjena.
- `404 valuation_not_found` — Procjena ne postoji ili nije napravljena ključem vaše kompanije.
- `409 duplicate_external_ref` — Vaša oznaka je već na drugom widgetu.
- `409 widget_limit_reached` — Objavljeno je onoliko vozila koliko plan dozvoljava (pauzirana se broje, prodana ne).
## Primjer
```bash
curl -X POST "https://api.cifra.ba/v1/widgets" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"valuation_id": "val_8fK2mQ9xLp4TvB7nR1sW",
"asking_price": 23900,
"external_ref": "LAG-0412"
}'
```
```json
{
"id": "wgt_7Hq2Lm9PzX4cV1bN8sKd",
"object": "widget",
"public_id": "k3M9xQ2vTa",
"status": "active",
"source": "valuation",
"report_id": null,
"valuation_id": "val_8fK2mQ9xLp4TvB7nR1sW",
"external_ref": "LAG-0412",
"title": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"make_name": "Volkswagen",
"model_name": "Golf 7",
"year": 2017,
"mileage_km": 148000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85
},
"asking_price": 23900,
"value": {
"currency": "BAM",
"point": 25750,
"low": 22600,
"high": 28900,
"confidence_grade": "B",
"as_of": "2026-10-21"
},
"rating": {
"level": "good",
"pct": -7.18,
"diff_bam": -1850
},
"embed": {
"page_url": "https://www.cifra.ba/w/k3M9xQ2vTa",
"script": "\n",
"iframe": ""
},
"sold_at": null,
"created_at": "2026-10-21T09:14:02.511Z",
"updated_at": "2026-10-21T09:14:02.640Z"
}
```
---
# Objava više widgeta
`POST https://api.cifra.ba/v1/widgets/batch`
Do 500 procjena odjednom (cijeli lager); svaka se objavljuje zasebno.
Pristup: `widgets`. Obračun: besplatno.
## Tijelo zahtjeva
- `items` (any[], obavezno, 1–500 stavki) — Do 500 vozila, svako kao tijelo `POST /v1/widgets`.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `created` (integer, obavezno) — Koliko je objavljeno.
- `data` (object[], obavezno) — Rezultat za svako vozilo.
- `index` (integer, obavezno) — Redni broj u `items`.
- `widget` (object) — Objavljeni widget.
- `id` (string, obavezno) — Oznaka (`wgt_…`).
- `object` (string, obavezno) — `widget`. Vrijednosti: `widget`.
- `public_id` (string, obavezno) — Javni kod u adresi widgeta (`cifra.ba/embed//…`, `cifra.ba/w/`); ide u vašu stranicu.
- `status` (enum, obavezno) — `active`, `paused` ili `sold` (oglas s Cifrine platforme je skinut: widgeti kažu „Prodano”). Vrijednosti: `active`, `paused`, `sold`.
- `source` (enum, obavezno) — Iz API procjene ili izvještaja s platforme. Vrijednosti: `valuation`, `report`.
- `report_id` (string, obavezno) — Izvještaj s platforme, kad je odatle objavljen.
- `valuation_id` (string, obavezno) — API procjena iz koje je objavljen.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `title` (string, obavezno) — Naziv na widgetu (`null`: marka, model i godište).
- `vehicle` (object, obavezno) — Vozilo.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Marka.
- `model_name` (string, obavezno) — Model.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `fuel` (string, obavezno) — Gorivo.
- `transmission` (string, obavezno) — Mjenjač.
- `power_kw` (number, obavezno) — Snaga u kW.
- `asking_price` (integer, obavezno, može biti null) — Tražena cijena u KM.
- `value` (object, obavezno, može biti null) — Zadnja jutarnja procjena.
- `currency` (string, obavezno) — `BAM`. Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Tržišna vrijednost (standardni model, nezavisan od modela vaše kompanije).
- `low` (integer, obavezno, može biti null) — Donja granica raspona.
- `high` (integer, obavezno, može biti null) — Gornja granica raspona.
- `confidence_grade` (enum, obavezno, može biti null) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `as_of` (string, obavezno, može biti null) — Dan, `YYYY-MM-DD`.
- `rating` (object, obavezno, može biti null) — Ocjena kakvu widget prikazuje; `null` bez cijene, za prodano vozilo ili cijenu daleko van tržišta.
- `level` (enum, obavezno) — Ocjena cijene: `great` odlična, `good` dobra, `fair` fer, `high` povišena, `over` visoka. Vrijednosti: `great`, `good`, `fair`, `high`, `over`.
- `pct` (number, obavezno) — Tražena cijena naspram vrijednosti, u %.
- `diff_bam` (integer, obavezno) — Razlika u KM (negativna: ispod vrijednosti).
- `embed` (object, obavezno) — Gotov kod; druge vrste: `data-cifra-widget="badge|market|comparables|forecast|factors|mileage|report"`.
- `page_url` (string, obavezno) — Stranica vozila za kupce, s cijelim izvještajem.
- `script` (string, obavezno) — Kod widgeta „Cijena” sa skriptom (preporučeno).
- `iframe` (string, obavezno) — Isti widget kao iframe.
- `sold_at` (string, obavezno, može biti null) — Trenutak u ISO 8601 (UTC).
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `error` (object) — Zašto nije objavljen.
- `code` (string, obavezno) — Šifra greške.
- `message` (string, obavezno) — Objašnjenje.
- `path` (string) — Polje s greškom.
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `403 organization_required` — Ključ pripada klijentu koji nije vezan za kompaniju; widgeti su kompanijini.
- `403 live_key_required` — Testni ključ: widgeti su javni i objavljuju se samo iz stvarnih procjena.
- `409 widget_limit_reached` — Objavljeno je onoliko vozila koliko plan dozvoljava (pauzirana se broje, prodana ne).
## Primjer
```bash
curl -X POST "https://api.cifra.ba/v1/widgets/batch" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"valuation_id": "val_8fK2mQ9xLp4TvB7nR1sW",
"asking_price": 23900,
"external_ref": "LAG-0412"
},
{
"valuation_id": "val_Q1wE2rT3yU4iO5pA6sD7",
"asking_price": 31500,
"external_ref": "LAG-0413"
}
]
}'
```
```json
{
"object": "list",
"created": 1,
"data": [
{
"index": 0,
"widget": {
"id": "wgt_7Hq2Lm9PzX4cV1bN8sKd",
"object": "widget",
"public_id": "k3M9xQ2vTa",
"status": "active",
"source": "valuation",
"report_id": null,
"valuation_id": "val_8fK2mQ9xLp4TvB7nR1sW",
"external_ref": "LAG-0412",
"title": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"make_name": "Volkswagen",
"model_name": "Golf 7",
"year": 2017,
"mileage_km": 148000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85
},
"asking_price": 23900,
"value": {
"currency": "BAM",
"point": 25750,
"low": 22600,
"high": 28900,
"confidence_grade": "B",
"as_of": "2026-10-21"
},
"rating": {
"level": "good",
"pct": -7.18,
"diff_bam": -1850
},
"embed": {
"page_url": "https://www.cifra.ba/w/k3M9xQ2vTa",
"script": "\n",
"iframe": ""
},
"sold_at": null,
"created_at": "2026-10-21T09:14:02.511Z",
"updated_at": "2026-10-21T09:14:02.640Z"
}
},
{
"index": 1,
"error": {
"code": "valuation_not_found",
"message": "No such valuation made with this company's keys."
}
}
]
}
```
---
# Lista widgeta
`GET https://api.cifra.ba/v1/widgets`
Objavljena vozila, od najnovijeg, po stranicama; po vašoj oznaci nađete `public_id` za predložak stranice.
Pristup: `widgets`. Obračun: besplatno.
## Parametri upita
- `external_ref` (string, do 80 znakova) — Samo widget s ovom vašom oznakom.
- `status` (enum) — Samo widgeti u ovom stanju (bez polja: svi osim uklonjenih). Vrijednosti: `active`, `paused`, `sold`.
- `limit` (integer, 1 – 100, podrazumijevano 50) — Koliko po stranici.
- `starting_after` (string, do 64 znaka) — `id` zadnjeg widgeta prethodne stranice.
## Odgovor 200
- `object` (string, obavezno) — `list`. Vrijednosti: `list`.
- `data` (object[], obavezno) — Widgeti, od najnovijeg.
- `id` (string, obavezno) — Oznaka (`wgt_…`).
- `object` (string, obavezno) — `widget`. Vrijednosti: `widget`.
- `public_id` (string, obavezno) — Javni kod u adresi widgeta (`cifra.ba/embed//…`, `cifra.ba/w/`); ide u vašu stranicu.
- `status` (enum, obavezno) — `active`, `paused` ili `sold` (oglas s Cifrine platforme je skinut: widgeti kažu „Prodano”). Vrijednosti: `active`, `paused`, `sold`.
- `source` (enum, obavezno) — Iz API procjene ili izvještaja s platforme. Vrijednosti: `valuation`, `report`.
- `report_id` (string, obavezno) — Izvještaj s platforme, kad je odatle objavljen.
- `valuation_id` (string, obavezno) — API procjena iz koje je objavljen.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `title` (string, obavezno) — Naziv na widgetu (`null`: marka, model i godište).
- `vehicle` (object, obavezno) — Vozilo.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Marka.
- `model_name` (string, obavezno) — Model.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `fuel` (string, obavezno) — Gorivo.
- `transmission` (string, obavezno) — Mjenjač.
- `power_kw` (number, obavezno) — Snaga u kW.
- `asking_price` (integer, obavezno, može biti null) — Tražena cijena u KM.
- `value` (object, obavezno, može biti null) — Zadnja jutarnja procjena.
- `currency` (string, obavezno) — `BAM`. Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Tržišna vrijednost (standardni model, nezavisan od modela vaše kompanije).
- `low` (integer, obavezno, može biti null) — Donja granica raspona.
- `high` (integer, obavezno, može biti null) — Gornja granica raspona.
- `confidence_grade` (enum, obavezno, može biti null) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `as_of` (string, obavezno, može biti null) — Dan, `YYYY-MM-DD`.
- `rating` (object, obavezno, može biti null) — Ocjena kakvu widget prikazuje; `null` bez cijene, za prodano vozilo ili cijenu daleko van tržišta.
- `level` (enum, obavezno) — Ocjena cijene: `great` odlična, `good` dobra, `fair` fer, `high` povišena, `over` visoka. Vrijednosti: `great`, `good`, `fair`, `high`, `over`.
- `pct` (number, obavezno) — Tražena cijena naspram vrijednosti, u %.
- `diff_bam` (integer, obavezno) — Razlika u KM (negativna: ispod vrijednosti).
- `embed` (object, obavezno) — Gotov kod; druge vrste: `data-cifra-widget="badge|market|comparables|forecast|factors|mileage|report"`.
- `page_url` (string, obavezno) — Stranica vozila za kupce, s cijelim izvještajem.
- `script` (string, obavezno) — Kod widgeta „Cijena” sa skriptom (preporučeno).
- `iframe` (string, obavezno) — Isti widget kao iframe.
- `sold_at` (string, obavezno, može biti null) — Trenutak u ISO 8601 (UTC).
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `has_more` (boolean, obavezno) — Ima li još stranica.
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `403 organization_required` — Ključ pripada klijentu koji nije vezan za kompaniju; widgeti su kompanijini.
## Primjer
```bash
curl "https://api.cifra.ba/v1/widgets?external_ref=LAG-0412" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"object": "list",
"data": [
{
"id": "wgt_7Hq2Lm9PzX4cV1bN8sKd",
"object": "widget",
"public_id": "k3M9xQ2vTa",
"status": "active",
"source": "valuation",
"report_id": null,
"valuation_id": "val_8fK2mQ9xLp4TvB7nR1sW",
"external_ref": "LAG-0412",
"title": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"make_name": "Volkswagen",
"model_name": "Golf 7",
"year": 2017,
"mileage_km": 148000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85
},
"asking_price": 23900,
"value": {
"currency": "BAM",
"point": 25750,
"low": 22600,
"high": 28900,
"confidence_grade": "B",
"as_of": "2026-10-21"
},
"rating": {
"level": "good",
"pct": -7.18,
"diff_bam": -1850
},
"embed": {
"page_url": "https://www.cifra.ba/w/k3M9xQ2vTa",
"script": "\n",
"iframe": ""
},
"sold_at": null,
"created_at": "2026-10-21T09:14:02.511Z",
"updated_at": "2026-10-21T09:14:02.640Z"
}
],
"has_more": false
}
```
---
# Widget
`GET https://api.cifra.ba/v1/widgets/{id}`
Jedan widget: vrijednost, ocjena, kod. `id` može biti i `public_id`.
Pristup: `widgets`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka (`wgt_…`) ili javni kod.
## Odgovor 200
- `id` (string, obavezno) — Oznaka (`wgt_…`).
- `object` (string, obavezno) — `widget`. Vrijednosti: `widget`.
- `public_id` (string, obavezno) — Javni kod u adresi widgeta (`cifra.ba/embed//…`, `cifra.ba/w/`); ide u vašu stranicu.
- `status` (enum, obavezno) — `active`, `paused` ili `sold` (oglas s Cifrine platforme je skinut: widgeti kažu „Prodano”). Vrijednosti: `active`, `paused`, `sold`.
- `source` (enum, obavezno) — Iz API procjene ili izvještaja s platforme. Vrijednosti: `valuation`, `report`.
- `report_id` (string, obavezno) — Izvještaj s platforme, kad je odatle objavljen.
- `valuation_id` (string, obavezno) — API procjena iz koje je objavljen.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `title` (string, obavezno) — Naziv na widgetu (`null`: marka, model i godište).
- `vehicle` (object, obavezno) — Vozilo.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Marka.
- `model_name` (string, obavezno) — Model.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `fuel` (string, obavezno) — Gorivo.
- `transmission` (string, obavezno) — Mjenjač.
- `power_kw` (number, obavezno) — Snaga u kW.
- `asking_price` (integer, obavezno, može biti null) — Tražena cijena u KM.
- `value` (object, obavezno, može biti null) — Zadnja jutarnja procjena.
- `currency` (string, obavezno) — `BAM`. Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Tržišna vrijednost (standardni model, nezavisan od modela vaše kompanije).
- `low` (integer, obavezno, može biti null) — Donja granica raspona.
- `high` (integer, obavezno, može biti null) — Gornja granica raspona.
- `confidence_grade` (enum, obavezno, može biti null) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `as_of` (string, obavezno, može biti null) — Dan, `YYYY-MM-DD`.
- `rating` (object, obavezno, može biti null) — Ocjena kakvu widget prikazuje; `null` bez cijene, za prodano vozilo ili cijenu daleko van tržišta.
- `level` (enum, obavezno) — Ocjena cijene: `great` odlična, `good` dobra, `fair` fer, `high` povišena, `over` visoka. Vrijednosti: `great`, `good`, `fair`, `high`, `over`.
- `pct` (number, obavezno) — Tražena cijena naspram vrijednosti, u %.
- `diff_bam` (integer, obavezno) — Razlika u KM (negativna: ispod vrijednosti).
- `embed` (object, obavezno) — Gotov kod; druge vrste: `data-cifra-widget="badge|market|comparables|forecast|factors|mileage|report"`.
- `page_url` (string, obavezno) — Stranica vozila za kupce, s cijelim izvještajem.
- `script` (string, obavezno) — Kod widgeta „Cijena” sa skriptom (preporučeno).
- `iframe` (string, obavezno) — Isti widget kao iframe.
- `sold_at` (string, obavezno, može biti null) — Trenutak u ISO 8601 (UTC).
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
## Greške
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
## Primjer
```bash
curl "https://api.cifra.ba/v1/widgets/wgt_7Hq2Lm9PzX4cV1bN8sKd" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"id": "wgt_7Hq2Lm9PzX4cV1bN8sKd",
"object": "widget",
"public_id": "k3M9xQ2vTa",
"status": "active",
"source": "valuation",
"report_id": null,
"valuation_id": "val_8fK2mQ9xLp4TvB7nR1sW",
"external_ref": "LAG-0412",
"title": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"make_name": "Volkswagen",
"model_name": "Golf 7",
"year": 2017,
"mileage_km": 148000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85
},
"asking_price": 23900,
"value": {
"currency": "BAM",
"point": 25750,
"low": 22600,
"high": 28900,
"confidence_grade": "B",
"as_of": "2026-10-21"
},
"rating": {
"level": "good",
"pct": -7.18,
"diff_bam": -1850
},
"embed": {
"page_url": "https://www.cifra.ba/w/k3M9xQ2vTa",
"script": "\n",
"iframe": ""
},
"sold_at": null,
"created_at": "2026-10-21T09:14:02.511Z",
"updated_at": "2026-10-21T09:14:02.640Z"
}
```
---
# Izmjena widgeta
`PATCH https://api.cifra.ba/v1/widgets/{id}`
Nova cijena, oznaka, naziv, kilometraža (procjenjuje se odmah ponovo) ili pauza. Stranice pokazuju izmjenu za najviše 5 minuta.
Pristup: `widgets`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka (`wgt_…`) ili javni kod.
## Tijelo zahtjeva
- `asking_price` (integer, može biti null, 100 – 10.000.000) — Nova tražena cijena; `null` prikazuje samo vrijednost. Na stranicama za najviše 5 minuta.
- `external_ref` (string, može biti null, do 80 znakova) — Vaša oznaka; `null` je briše.
- `title` (string, može biti null, do 120 znakova) — Naziv na widgetu; `null` vraća marku, model i godište.
- `status` (enum) — `paused` skriva widgete (stranica se zatvori), `active` ih vraća — i prodano vozilo koje je ponovo u prodaji. Vrijednosti: `active`, `paused`.
- `mileage_km` (integer, 0 – 3.000.000) — Novo očitanje kilometraže: vozilo se odmah procjenjuje ponovo.
- `price_from_listing` (boolean) — Samo za vozila objavljena s oglasom na Cifrinoj platformi: cijena prati oglas.
## Odgovor 200
- `id` (string, obavezno) — Oznaka (`wgt_…`).
- `object` (string, obavezno) — `widget`. Vrijednosti: `widget`.
- `public_id` (string, obavezno) — Javni kod u adresi widgeta (`cifra.ba/embed//…`, `cifra.ba/w/`); ide u vašu stranicu.
- `status` (enum, obavezno) — `active`, `paused` ili `sold` (oglas s Cifrine platforme je skinut: widgeti kažu „Prodano”). Vrijednosti: `active`, `paused`, `sold`.
- `source` (enum, obavezno) — Iz API procjene ili izvještaja s platforme. Vrijednosti: `valuation`, `report`.
- `report_id` (string, obavezno) — Izvještaj s platforme, kad je odatle objavljen.
- `valuation_id` (string, obavezno) — API procjena iz koje je objavljen.
- `external_ref` (string, obavezno) — Vaša oznaka.
- `title` (string, obavezno) — Naziv na widgetu (`null`: marka, model i godište).
- `vehicle` (object, obavezno) — Vozilo.
- `vehicle_type` (enum, obavezno) — Vrsta vozila. Vrijednosti: `car`, `motorcycle`, `truck`.
- `make` (string, obavezno) — Šifra marke.
- `model` (string, obavezno) — Šifra modela.
- `make_name` (string, obavezno) — Marka.
- `model_name` (string, obavezno) — Model.
- `year` (integer, obavezno) — Godište.
- `mileage_km` (integer, obavezno) — Kilometraža.
- `fuel` (string, obavezno) — Gorivo.
- `transmission` (string, obavezno) — Mjenjač.
- `power_kw` (number, obavezno) — Snaga u kW.
- `asking_price` (integer, obavezno, može biti null) — Tražena cijena u KM.
- `value` (object, obavezno, može biti null) — Zadnja jutarnja procjena.
- `currency` (string, obavezno) — `BAM`. Vrijednosti: `BAM`.
- `point` (integer, obavezno) — Tržišna vrijednost (standardni model, nezavisan od modela vaše kompanije).
- `low` (integer, obavezno, može biti null) — Donja granica raspona.
- `high` (integer, obavezno, može biti null) — Gornja granica raspona.
- `confidence_grade` (enum, obavezno, može biti null) — Ocjena pouzdanosti: `A` najuži rasponi za takva vozila, `C` najširi (rijetki modeli, malo podataka, nepotpun unos). Vrijednosti: `A`, `B`, `C`.
- `as_of` (string, obavezno, može biti null) — Dan, `YYYY-MM-DD`.
- `rating` (object, obavezno, može biti null) — Ocjena kakvu widget prikazuje; `null` bez cijene, za prodano vozilo ili cijenu daleko van tržišta.
- `level` (enum, obavezno) — Ocjena cijene: `great` odlična, `good` dobra, `fair` fer, `high` povišena, `over` visoka. Vrijednosti: `great`, `good`, `fair`, `high`, `over`.
- `pct` (number, obavezno) — Tražena cijena naspram vrijednosti, u %.
- `diff_bam` (integer, obavezno) — Razlika u KM (negativna: ispod vrijednosti).
- `embed` (object, obavezno) — Gotov kod; druge vrste: `data-cifra-widget="badge|market|comparables|forecast|factors|mileage|report"`.
- `page_url` (string, obavezno) — Stranica vozila za kupce, s cijelim izvještajem.
- `script` (string, obavezno) — Kod widgeta „Cijena” sa skriptom (preporučeno).
- `iframe` (string, obavezno) — Isti widget kao iframe.
- `sold_at` (string, obavezno, može biti null) — Trenutak u ISO 8601 (UTC).
- `created_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
- `updated_at` (string, obavezno) — Trenutak u ISO 8601 (UTC).
## Greške
- `400 invalid_request` — Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje.
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
- `409 duplicate_external_ref` — Vaša oznaka je već na drugom widgetu.
- `409 widget_limit_reached` — Objavljeno je onoliko vozila koliko plan dozvoljava (pauzirana se broje, prodana ne).
## Primjer
```bash
curl -X PATCH "https://api.cifra.ba/v1/widgets/wgt_7Hq2Lm9PzX4cV1bN8sKd" \
-H "Authorization: Bearer $CIFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"asking_price": 22900
}'
```
```json
{
"id": "wgt_7Hq2Lm9PzX4cV1bN8sKd",
"object": "widget",
"public_id": "k3M9xQ2vTa",
"status": "active",
"source": "valuation",
"report_id": null,
"valuation_id": "val_8fK2mQ9xLp4TvB7nR1sW",
"external_ref": "LAG-0412",
"title": null,
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf_7",
"make_name": "Volkswagen",
"model_name": "Golf 7",
"year": 2017,
"mileage_km": 148000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85
},
"asking_price": 22900,
"value": {
"currency": "BAM",
"point": 25750,
"low": 22600,
"high": 28900,
"confidence_grade": "B",
"as_of": "2026-10-21"
},
"rating": {
"level": "good",
"pct": -11.07,
"diff_bam": -2850
},
"embed": {
"page_url": "https://www.cifra.ba/w/k3M9xQ2vTa",
"script": "\n",
"iframe": ""
},
"sold_at": null,
"created_at": "2026-10-21T09:14:02.511Z",
"updated_at": "2026-10-21T09:14:02.640Z"
}
```
---
# Uklanjanje widgeta
`DELETE https://api.cifra.ba/v1/widgets/{id}`
Widgeti vozila nestaju sa svih stranica, a stranica za kupce prestaje raditi. Procjena ostaje.
Pristup: `widgets`. Obračun: besplatno.
## Parametri putanje
- `id` (string, obavezno) — Oznaka (`wgt_…`) ili javni kod.
## Odgovor 200
- `id` (string, obavezno) — Oznaka.
- `object` (string, obavezno) — `widget`. Vrijednosti: `widget`.
- `deleted` (boolean, obavezno) — `true`. Vrijednosti: `true`.
## Greške
- `404 not_found` — Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju.
## Primjer
```bash
curl -X DELETE "https://api.cifra.ba/v1/widgets/wgt_7Hq2Lm9PzX4cV1bN8sKd" \
-H "Authorization: Bearer $CIFRA_API_KEY"
```
```json
{
"id": "wgt_7Hq2Lm9PzX4cV1bN8sKd",
"object": "widget",
"deleted": true
}
```
---
# Webhook događaji
Događaji koje Cifra šalje na vaše webhook adrese, s primjerom tijela svakog.
Svaki događaj stiže kao `POST` s tijelom `{ id, type, created_at, livemode, data }`, potpisan zaglavljem `Cifra-Signature`. Kako primiti i provjeriti: [Webhookovi](https://www.cifra.ba/docs/api/webhooks).
### `watchlist.alert`
Alarm za praćeno vozilo. Pravilo vozila se aktiviralo: vrijednost se promijenila, prešla ciljnu cijenu ili LTV prag, ili je stigao povoljan oglas.
```json
{
"alert": {
"object": "alert",
"id": "alr_8fK2mQ9xLp4TvB7nR1sW",
"type": "value_changed",
"watched_vehicle": {
"id": "wv_3JdP0aZr6YcN2uE5kHq8",
"label": "VW Golf 1.6 TDI — ugovor 2024/118",
"external_ref": "2024/118",
"kind": "owned"
},
"day": "2026-10-15",
"previous_value": 21400,
"value": 20550,
"change_pct": -3.97,
"threshold": 3,
"details": null,
"created_at": "2026-10-15T06:12:44.000Z"
}
}
```
### `watchlist.report_ready`
Dnevni izvještaj spreman. Jutarnja procjena svih praćenih vozila je gotova; izvještaj dana čita se jednim pozivom.
```json
{
"day": "2026-10-15",
"vehicles": 412,
"alerts": 7,
"report_url": "/v1/watchlist/report?day=2026-10-15"
}
```
### `widget.rating_changed`
Promijenjena ocjena cijene. Jutarnja procjena je pomjerila ocjenu tražene cijene na vašem widgetu (npr. iz „Fer” u „Povišena”), ili je vozilo iz oglasa prodano.
```json
{
"widget": {
"object": "widget",
"id": "wgt_7Hq2Lm9PzX4cV1bN8sKd",
"public_id": "k3M9xQ2vTa",
"external_ref": "LAG-0412",
"title": "Volkswagen Golf 7 1.6 TDI Highline",
"status": "active",
"asking_price": 23900,
"value": 22950,
"previous_level": "fair",
"level": "high",
"pct": 4.14,
"day": "2026-10-15"
}
}
```
### `report.created`
Nova procjena na platformi. Nova procjena vozila na platformi: vrijednost, raspon, svrha i vaša referenca, da procjena odmah stigne u vaš sistem.
```json
{
"report": {
"object": "report",
"id": "cm2x8k1q00001",
"url": "https://enterprise.cifra.ba/valuations/cm2x8k1q00001",
"purpose": "financing",
"reference": "2024/118",
"vehicle": {
"vehicle_type": "car",
"make": "volkswagen",
"model": "golf",
"make_name": "Volkswagen",
"model_name": "Golf",
"year": 2019,
"mileage_km": 98000,
"fuel": "diesel",
"transmission": "manual",
"power_kw": 85
},
"value": 20550,
"low": 19300,
"high": 21900,
"currency": "BAM",
"grade": "A",
"as_of": "2026-10-15",
"created_by": {
"name": "Amra Hodžić",
"email": "amra@firma.ba"
},
"created_at": "2026-10-15T09:41:12.000Z"
}
}
```
### `check.completed`
Provjera vozila završena. Provjera oglasa je gotova (nova ili ponovljena): nivo pažnje i signali koje treba provjeriti.
```json
{
"check": {
"object": "vehicle_check",
"id": "cm2x9a7d00004",
"url": "https://enterprise.cifra.ba/check/cm2x9a7d00004",
"vehicle": "Volkswagen Golf 2016",
"listing_url": "https://olx.ba/artikal/61234567",
"level": "elevated",
"headline": "Kilometraža niža nego u ranijem oglasu",
"signals": [
{
"code": "mileage_rollback",
"severity": "high"
},
{
"code": "relisted_often",
"severity": "medium"
}
],
"purpose": "financing",
"reference": "2024/118",
"created_by": {
"name": "Amra Hodžić",
"email": "amra@firma.ba"
},
"checked_at": "2026-10-15T09:52:03.000Z"
}
}
```
### `check.decided`
Odluka o provjeri. Odluka tima o provjerenom vozilu: odobreno, dodatna provjera ili odbijeno, s napomenom.
```json
{
"check": {
"object": "vehicle_check",
"id": "cm2x9a7d00004",
"url": "https://enterprise.cifra.ba/check/cm2x9a7d00004",
"vehicle": "Volkswagen Golf 2016",
"level": "elevated",
"reference": "2024/118",
"decision": "review",
"decision_note": "Tražiti servisnu knjižicu prije odobrenja.",
"decided_by": {
"name": "Emir Kovač",
"email": "emir@firma.ba"
},
"decided_at": "2026-10-15T10:05:27.000Z"
}
}
```
### `bulk.completed`
Masovna procjena gotova. Svi redovi liste su procijenjeni: koliko vozila, ukupna vrijednost i veza na listu.
```json
{
"batch": {
"object": "valuation_batch",
"id": "cm2xa0b3k0009",
"url": "https://enterprise.cifra.ba/valuations/bulk/cm2xa0b3k0009",
"name": "Lizing portfelj Q3",
"purpose": "financing",
"as_of": "2026-09-30",
"rows": 1240,
"valued": 1228,
"failed": 12,
"total_value": 24118400,
"currency": "BAM",
"created_by": {
"name": "Amra Hodžić",
"email": "amra@firma.ba"
},
"completed_at": "2026-10-15T11:20:45.000Z"
}
}
```
### `usage.threshold_reached`
Potrošnja API-ja prešla prag. Ovomjesečne obračunske jedinice su prešle prag koji ste odabrali (npr. 80% ugovorene kvote).
```json
{
"month": "2026-10",
"threshold_pct": 80,
"units": 80214,
"quota": 100000,
"resets_at": "2026-11-01T00:00:00.000Z"
}
```
### `webhook.test`
Test. Probna poruka koju šaljete sami, da provjerite da adresa prima i provjerava potpis.
```json
{
"message": "A test event from Cifra."
}
```
---
# Šifre grešaka
Svaka šifra greške: HTTP status, kad se javlja i šta uraditi.
Granajte kod po `code`. Šifre označene kao opšte može vratiti svaki poziv s ključem; ostale samo endpointi koji ih navode. Format greške: [Greške](https://www.cifra.ba/docs/api/errors).
| Status | Šifra | Kad | Šta uraditi |
| --- | --- | --- | --- |
| `400` | `invalid_request` | Tijelo ili parametri ne odgovaraju šemi; `errors` navodi svako polje. | Ispravite polja iz `errors[].path`. Nepoznata polja se odbijaju. |
| `400` | `invalid_body` | Tijelo nije JSON. | Pošaljite `Content-Type: application/json` i ispravan JSON. |
| `400` | `invalid_vehicle_type` | `vehicle_type` nije `car`, `motorcycle` ni `truck`. | Pošaljite jednu od te tri vrijednosti. |
| `400` | `invalid_webhook_url` | Adresa nije HTTPS ili vodi na lokalnu ili privatnu mrežu. | Koristite javnu HTTPS adresu. |
| `401` | `missing_token` | Zahtjev nema ključ. | Pošaljite `Authorization: Bearer cfr_live_…` (ili `x-api-key`). |
| `401` | `invalid_token` | Ključ ne postoji, opozvan je ili nije dobrog oblika. | Provjerite da šaljete cijeli ključ, bez razmaka; napravite novi u Razvoj → API ključevi. |
| `401` | `token_expired` | Ključu je prošao datum isteka. | Napravite novi ključ ili produžite postojeći na platformi. |
| `403` | `key_paused` | Vaša kompanija je pauzirala ključ. | Administrator ga nastavlja u Razvoj → API ključevi. |
| `403` | `token_suspended` | Cifra je privremeno zaustavila ključ. | Javite se podršci. |
| `403` | `company_inactive` | Ugovor ili probni period kompanije kojoj ključ pripada je istekao ili je pauziran. | Javite se podršci ili vlasniku naloga kompanije. |
| `403` | `api_not_included` | Cifra API nije dio ugovora kompanije kojoj ključ pripada. | Javite se podršci da dodamo API u ugovor. |
| `403` | `ip_not_allowed` | Ključ prima zahtjeve samo s dozvoljenih adresa, a ova nije među njima (odgovor nosi `ip`). | Dodajte adresu ili CIDR raspon ključu na platformi. |
| `403` | `insufficient_scope` | Ključ nema pristup ovoj usluzi (npr. Provjera vozila bez `listings`). | Dodajte pristup ključu ili koristite drugi ključ. |
| `403` | `organization_required` | Ključ pripada klijentu koji nije vezan za kompaniju; widgeti su kompanijini. | Koristite ključ napravljen na Cifra platformi vaše kompanije (Razvoj → API ključevi). |
| `403` | `live_key_required` | Testni ključ: widgeti su javni i objavljuju se samo iz stvarnih procjena. | Objavite s produkcijskim ključem (`cfr_live_…`). |
| `404` | `not_found` | Ne postoji, ili pripada drugoj kompaniji ili drugom okruženju. | Provjerite oznaku i da koristite ključ istog okruženja (live/test). |
| `404` | `valuation_not_found` | Procjena ne postoji ili nije napravljena ključem vaše kompanije. | Pošaljite `id` iz odgovora `POST /v1/valuations` napravljenog vašim produkcijskim ključem. |
| `404` | `listing_not_found` | Cifra još nije vidjela oglas: nov je (stranice se pregledaju dnevno) ili je sa stranice koju ne pratimo. | Pokušajte sutra; pratimo olx.ba, autobum.ba i autoplac.ba. |
| `409` | `pinned_model_unavailable` | Ključ je vezan za verziju modela koja trenutno ne radi za ovu vrstu vozila. | Javite se podršci da ključ vežu za drugu verziju. |
| `409` | `duplicate_external_ref` | Vaša oznaka je već na drugom widgetu. | Izmijenite postojeći widget (`PATCH`) ili ga uklonite; oznaka je jedinstvena među živim widgetima. |
| `409` | `widget_limit_reached` | Objavljeno je onoliko vozila koliko plan dozvoljava (pauzirana se broje, prodana ne). | Uklonite vozila koja više ne prodajete ili pređite na veći plan. Odgovor nosi `limit` i `used`. |
| `409` | `watchlist_full` | Dostignut broj praćenih vozila plana (odgovor nosi `max`, `count`). | Uklonite vozila koja više ne trebate ili povećajte plan. |
| `409` | `too_many_webhooks` | Već 5 aktivnih adresa u ovom okruženju. | Isključite adresu koju ne koristite. |
| `409` | `webhook_disabled` | Adresa je isključena. | Dodajte je ponovo ili je uključite na platformi. |
| `413` | `payload_too_large` | Tijelo je veće od 2 MB. | Podijelite listu na manje zahtjeve. |
| `413` | `batch_too_large` | Više vozila nego što plan dozvoljava u jednom pozivu. | Podijelite listu na dijelove od najviše `batch_max_items`. |
| `422` | `unknown_make` | Marka nije u šifarniku (odgovor nosi `field`). | Uzmite šifru iz `GET /v1/taxonomy/makes` — npr. `škoda`, ne `skoda`. |
| `422` | `unknown_model` | Model nije u šifarniku te marke. | Uzmite šifru iz `GET /v1/taxonomy/makes/{make}/models`. |
| `422` | `vehicle_type_unavailable` | Procjene za tu vrstu vozila trenutno nisu dostupne. | Pokušajte kasnije ili se javite podršci. |
| `422` | `as_of_in_future` | `as_of` je u budućnosti. | Za buduće vrijednosti koristite prognozu (`include: ["forecast"]`). |
| `422` | `as_of_too_early` | `as_of` je prije 2015-01-01. | Pošaljite datum od 2015. naovamo. |
| `422` | `year_after_as_of` | Godište je kasnije od datuma procjene. | Provjerite `year` i `as_of`. |
| `422` | `unsupported_listing_url` | Iz linka se ne može pročitati stranica i broj oglasa. | Pošaljite link oglasa s olx.ba, autobum.ba ili autoplac.ba, ili `source` i `listing_id`. |
| `422` | `not_owned` | `km_per_year`, `mileage_km` ili `exposure` za traženo (`wanted`) vozilo. | Ta polja važe samo za vlastita (`owned`) vozila. |
| `422` | `not_wanted` | `deal_pct` za vlastito (`owned`) vozilo. | Povoljni oglasi se prate samo za tražena (`wanted`) vozila. |
| `429` | `rate_limited` | Previše zahtjeva u minuti. | Sačekajte `Retry-After` sekundi i ponovite; ravnomjerno raspodijelite zahtjeve. |
| `429` | `quota_exceeded` | Potrošena mjesečna kvota ugovora (odgovor nosi `quota`, `used`, `resets_at`). | Kvota se obnavlja 1. u mjesecu (UTC); za veću se javite prodaji. |
| `429` | `key_limit_reached` | Ključ je potrošio mjesečni limit koji mu je postavila vaša kompanija (`limit`, `used`, `resets_at`). | Administrator povećava limit ključa na platformi. |
| `500` | `internal_error` | Greška na strani Cifre. | Ponovite zahtjev; ako se ponavlja, pošaljite `request_id` podršci. |
| `503` | `model_unavailable` | Model trenutno nije dostupan (npr. tokom pokretanja). | Ponovite za nekoliko sekundi, s eksponencijalnim čekanjem. |