API referencaProcjene

Procjena vozila

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.

POSThttps://api.cifra.ba/v1/valuations

Pristup: valuations
Obračun: 1 jedinica po uspješnom pozivu

POST/v1/valuations

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"
    ]
  }'

Odgovor

{
  "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": []
}

Tijelo zahtjeva

application/json

vehicle_typeenumopcionalnopodrazumijevano "car"
Vrsta vozila. Svaka vrsta ima svoj model, šifarnik i polja koja prima.
carmotorcycletruck
makestringobaveznodo 64 znaka
Marka kao šifra iz GET /v1/taxonomy/makes, npr. volkswagen, mercedes_benz, škoda.
modelstringobaveznodo 64 znaka
Model kao šifra iz GET /v1/taxonomy/makes/{make}/models, npr. golf_7.
yearintegerobaveznonajmanje 1950
Godište (modelska godina). Najviše sljedeća godina.
mileage_kmintegerobavezno0 – 2.000.000
Pređeni kilometri na dan procjene.
power_kwnumberopcionalno2 – 1000
Snaga motora u kW. Jedan od najvažnijih podataka za cijenu.
power_hpnumberopcionalno3 – 1400
Snaga u KS; koristi se samo kad power_kw nije poslan.
engine_ccintegeropcionalno40 – 20.000
Zapremina motora u cm³.
fuelenumopcionalno
Gorivo.
petroldiesellpgcnghybridplugin_hybridelectrichydrogenother
transmissionenumopcionalno
Mjenjač.
manualautomaticsemi_automatic
drivetrainenumopcionalno
Pogon. Samo automobili.
fwdrwdawd
body_typeenumopcionalno
Karoserija. Samo automobili.
sedanhatchbackwagonsuvcoupeconvertibleminivanvanpickupother
doorsintegeropcionalno2 – 5
Broj vrata. Samo automobili.
conditionenumopcionalno
Stanje: used (podrazumijevano) ili new.
usednew
seller_typeenumopcionalno
Ko prodaje: privatna osoba ili salon.
privatedealer
citystringopcionalnodo 80 znakova
Grad u BiH, npr. Sarajevo ili Banja Luka. Regionalna potražnja pomjera cijenu.
equipmentstring[]opcionalnodo 150 stavki
Oprema kako je navodi oglas ili vaš sistem, npr. navigacija, kožna sjedišta.
owners_countintegeropcionalno1 – 20
Broj dosadašnjih vlasnika.
customs_clearedbooleanopcionalno
Je li vozilo ocarinjeno.
service_historybooleanopcionalno
Ima li vozilo servisnu historiju (knjižicu).
categorystringopcionalnodo 60 znakova
Motocikli: tip (Naked, Scooter, Enduro…); kamioni: nadogradnja (Kiper, Kombi…). Vrijednosti: GET /v1/taxonomy/values.
absbooleanopcionalno
ABS. Samo motocikli.
axlesintegeropcionalno1 – 6
Broj osovina. Samo kamioni.
payload_classstringopcionalnodo 40 znakova
Nosivost kao razred iz GET /v1/taxonomy/values. Samo kamioni.
as_ofdateopcionalno
Datum procjene (YYYY-MM-DD), od 2015-01-01 do danas: vrijednost kakva je bila tog dana, npr. na dan štete. Podrazumijevano danas (UTC).
includeenum[]opcionalnodo 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.
explanationforecastcomparables
km_per_yearintegeropcionalno0 – 150.000
Koliko će vozilo prelaziti godišnje, za prognozu. Podrazumijevano: njegov dosadašnji prosjek.
valuation_modelenumopcionalno
auto (podrazumijevano): vaš model kompanije kad je u upotrebi, inače standardni; standard: uvijek standardni tržišni model.
autostandard

Odgovor

201

idstringobavezno
Oznaka procjene (val_…); po njoj je čitate i javljate prodajnu cijenu.
objectstringobavezno
Uvijek valuation.
created_atstringobavezno
Trenutak u ISO 8601 (UTC).
model_versionstringobavezno
Verzija modela koji je procijenio, npr. car-20261017-1.
valued_byobjectobavezno
Koji model je odgovorio.
Prikaži 7 poljaSakrij polja
- kindenumobavezno
  standard: Cifrin tržišni model; custom: model vaše kompanije.
  standardcustom
- versionstringobavezno
  Verzija modela koji je odgovorio, npr. car-20261017-1.
- custom_model_idintegeropcionalno
  Model kompanije: njegov broj.
- namestringopcionalno
  Model kompanije: naziv koji ste mu dali.
- price_kindenumopcionalno
  Model kompanije: koje cijene je učio, pa šta vrijednost znači — prodajne, nabavne, oglasne ili procjene.
  salepurchaseaskingappraisal
- base_versionstringopcionalno
  Model kompanije: standardni model na kojem je napravljen.
- fallbackstringopcionalno
  Vaš model trenutno nije mogao odgovoriti, pa je odgovorio standardni.
sandboxbooleanopcionalno
Samo testni ključevi: fiksne primjer-vrijednosti.
vehicleobjectobavezno
Procijenjeno vozilo, s nazivima iz šifarnika.
Prikaži 7 poljaSakrij polja
- vehicle_typeenumobavezno
  Vrsta vozila.
  carmotorcycletruck
- makestringobavezno
  Šifra marke.
- make_namestringobavezno
  Naziv marke, npr. Volkswagen.
- modelstringobavezno
  Šifra modela.
- model_namestringobavezno
  Naziv modela, npr. Golf 7.
- yearintegerobavezno
  Godište.
- mileage_kmintegerobavezno
  Kilometraža.
as_ofstringobavezno
Dan na koji važi vrijednost.
market_valueobjectobavezno
Tržišna vrijednost s rasponom od 80% i ocjenom pouzdanosti.
Prikaži 7 poljaSakrij polja
- currencystringobavezno
  Uvijek BAM (konvertibilna marka).
- pointintegerobavezno
  Tržišna vrijednost, zaokružena na 10 KM.
- lowintegerobavezno
  Donja granica raspona.
- highintegerobavezno
  Gornja granica raspona.
- confidence_gradeenumobavezno
  Ocjena pouzdanosti: A najuži rasponi za takva vozila, C najširi (rijetki modeli, malo podataka, nepotpun unos).
  ABC
- range_probabilitynumberobavezno
  Vjerovatnoća da je cijena u rasponu: 0.8 (80%).
- definitionstringobavezno
  Šta tačno vrijednost znači, jednom rečenicom.
standard_valueobjectopcionalno
Samo uz model kompanije: šta kaže standardni tržišni model, za poređenje.
Prikaži 6 poljaSakrij polja
- currencystringobavezno
  BAM.
- pointintegerobavezno
  Vrijednost po standardnom modelu.
- lowintegerobavezno
  Donja granica.
- highintegerobavezno
  Gornja granica.
- confidence_gradeenumobavezno
  Ocjena pouzdanosti: A najuži rasponi za takva vozila, C najširi (rijetki modeli, malo podataka, nepotpun unos).
  ABC
- model_versionstringobavezno
  Verzija standardnog modela.
explanationobjectopcionalno
Obračun cijene po faktorima (uz include: ["explanation"]).
Prikaži 2 poljaSakrij polja
- linesobject[]obavezno
  Linije koje se tačno sabiraju u market_value.point.
  Prikaži 3 poljaSakrij polja
  idenumobavezno
  Faktor: base (bazna vrijednost modela), mileage, equipment (oprema i motorizacija), history (stanje i historija), region, market, adjustment (korekcija tržišnog tima).
  basemileageequipmenthistoryregionmarketadjustment
  labelstringobavezno
  Naziv faktora na bosanskom, za prikaz korisniku.
  amount_bamintegerobavezno
  Prva linija: bazna vrijednost; ostale: koliko faktor dodaje ili oduzima.
- methodstringobavezno
  Kako je obračun nastao.
forecastobjectopcionalno
Prognoza vrijednosti (uz include: ["forecast"]): naučena kriva gubitka vrijednosti, uz današnji nivo tržišta.
Prikaži 4 poljaSakrij polja
- statusstringobavezno
  beta.
- km_per_yearintegerobavezno
  Godišnja kilometraža pretpostavljena u prognozi.
- pointsobject[]obavezno
  Vrijednost kroz vrijeme, s rasponom koji se širi.
  Prikaži 4 poljaSakrij polja
  monthsintegerobavezno
  Mjeseci od as_of: 6, 12, 24, 36.
  pointintegerobavezno
  Očekivana vrijednost.
  lowintegerobavezno
  Donja granica.
  highintegerobavezno
  Gornja granica.
- methodstringobavezno
  Kako je prognoza nastala.
sale_priceobjectobavezno
Procjena stvarne prodajne cijene: u pripremi.
Prikaži 2 poljaSakrij polja
- statusstringobavezno
  Još nije dostupno.
- detailstringobavezno
  Zašto.
time_to_sellobjectobavezno
Očekivano vrijeme do prodaje: u pripremi.
Prikaži 2 poljaSakrij polja
- statusstringobavezno
  Još nije dostupno.
- detailstringobavezno
  Zašto.
adjustmentobjectopcionalno
Kad Cifrin tržišni tim privremeno koriguje model za neki segment (najviše ±15%, do 180 dana).
Prikaži 2 poljaSakrij polja
- multipliernumberobavezno
  Faktor korekcije, npr. 0.97.
- reasonstringobavezno
  Razlog korekcije.
warningsobject[]obavezno
Upozorenja uz procjenu. Prazna lista znači da nema ničeg posebnog.
Prikaži 2 poljaSakrij polja
- codestringobavezno
  Stabilna šifra upozorenja, npr. partial_inputs.
- messagestringobavezno
  Objašnjenje na engleskom, za logove i podršku.
comparablesobjectopcionalno
Slična vozila trenutno u prodaji (uz include: ["comparables"]): ista marka i model, godište ±2, poredana po sličnosti.
Prikaži 2 poljaSakrij polja
- totalintegerobavezno
  Koliko sličnih vozila je trenutno u prodaji.
- itemsobject[]obavezno
  Do 8 najsličnijih.
  Prikaži 11 poljaSakrij polja
  yearintegerobavezno
  Godište.
  mileage_kmintegerobavezno
  Kilometraža.
  fuelstringobavezno
  Gorivo.
  transmissionstringobavezno
  Mjenjač.
  power_kwnumberobavezno
  Snaga u kW.
  engine_ccinteger | nullobavezno
  Zapremina u cm³.
  citystringobavezno
  Mjesto.
  asking_price_bamintegerobavezno
  Cijena u oglasu.
  cifra_value_bamintegerobavezno
  Cifrina vrijednost tog vozila.
  price_vs_value_pctnumberobavezno
  Koliko oglas traži iznad (+) ili ispod (−) Cifrine vrijednosti, u %.
  days_listedinteger | nullobavezno
  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).

Uz ove, svaki poziv s ključem može vratiti opšte greške (ključ, pristup, limiti).

POST/v1/valuations

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"
    ]
  }'

Odgovor

{
  "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": []
}