API referencaProcjene

Masovna procjena

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.

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

Pristup: valuations
Obračun: 1 jedinica po uspješnoj stavci

POST/v1/valuations/batch

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

Odgovor

{
  "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
}

Tijelo zahtjeva

application/json

itemsany[]obavezno1–1000 stavki
Vozila, svako kao tijelo POST /v1/valuations. Najviše koliko dozvoljava vaš plan (batch_max_items).
includeenum[]opcionalnodo 3 stavke
Dodaci za svako vozilo koje nema svoj include. Bez polja: samo vrijednost. comparables se ne vraća u masovnoj procjeni.
explanationforecastcomparables

Odgovor

200

objectstringobavezno
list.
dataobject[]obavezno
Rezultat za svako vozilo, istim redom kao items.
Prikaži 3 poljaSakrij polja
- indexintegerobavezno
  Mjesto vozila u items.
- valuationobjectopcionalno
  Procjena, ako je uspjela.
  Prikaži 17 poljaSakrij polja
  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.
- errorobjectopcionalno
  Greška, ako ovo vozilo nije procijenjeno.
  Prikaži 3 poljaSakrij polja
  codestringobavezno
  Šifra greške, kao u odgovoru s greškom.
  detailstringopcionalno
  Objašnjenje.
  errorsobject[]opcionalno
  Za invalid_request: svako neispravno polje.
  Prikaži 2 poljaSakrij polja
  pathstringobavezno
  Polje.
  messagestringobavezno
  Šta nije u redu.
valuedintegerobavezno
Koliko je procijenjeno (i naplaćeno).
failedintegerobavezno
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).

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

POST/v1/valuations/batch

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

Odgovor

{
  "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
}