API referencaWidgeti

Objava widgeta

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.

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

Pristup: widgets
Obračun: Besplatno

POST/v1/widgets

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

Odgovor

{
  "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": "<div data-cifra-widget=\"price\" data-id=\"k3M9xQ2vTa\"></div>\n<script async src=\"https://www.cifra.ba/widget.js\"></script>",
    "iframe": "<iframe src=\"https://www.cifra.ba/embed/k3M9xQ2vTa/price\" title=\"Cifra — Cijena i tržišna vrijednost\" width=\"100%\" height=\"236\" style=\"border:0;max-width:100%\" loading=\"lazy\"></iframe>"
  },
  "sold_at": null,
  "created_at": "2026-10-21T09:14:02.511Z",
  "updated_at": "2026-10-21T09:14:02.640Z"
}

Tijelo zahtjeva

application/json

valuation_idstringopcionalnodo 64 znaka
Procjena napravljena produkcijskim ključem vaše kompanije (val_…, iz POST /v1/valuations). Widget prikazuje to vozilo, svako jutro ponovo procijenjeno.
report_idstringopcionalnodo 64 znaka
Samo za Cifrinu platformu (izvještaj kompanije); vaš ključ šalje valuation_id.
asking_priceinteger | nullopcionalno100 – 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_refstring | nullopcionalnodo 80 znakova
Vaša oznaka (broj u lageru), jedinstvena među vašim widgetima; po njoj ga i tražite.
titlestring | nullopcionalnodo 120 znakova
Naziv na widgetu, npr. Golf 7 1.6 TDI Highline. Bez njega: marka, model i godište.
listing_idinteger | nullopcionalnonajmanje 0
Samo za Cifrinu platformu (oglas čija se cijena i prodaja prate).
price_from_listingbooleanopcionalno
Samo za Cifrinu platformu: cijena prati oglas.
created_bystringopcionalnodo 64 znaka
Samo za Cifrinu platformu: ko je objavio.
statusenumopcionalno
paused: objavljen, ali se još ne prikazuje. Zadano active.
activepaused

Odgovor

201

idstringobavezno
Oznaka (wgt_…).
objectstringobavezno
widget.
public_idstringobavezno
Javni kod u adresi widgeta (cifra.ba/embed/<public_id>/…, cifra.ba/w/<public_id>); ide u vašu stranicu.
statusenumobavezno
active, paused ili sold (oglas s Cifrine platforme je skinut: widgeti kažu „Prodano”).
activepausedsold
sourceenumobavezno
Iz API procjene ili izvještaja s platforme.
valuationreport
report_idstringobavezno
Izvještaj s platforme, kad je odatle objavljen.
valuation_idstringobavezno
API procjena iz koje je objavljen.
external_refstringobavezno
Vaša oznaka.
titlestringobavezno
Naziv na widgetu (null: marka, model i godište).
vehicleobjectobavezno
Vozilo.
Prikaži 10 poljaSakrij polja
- vehicle_typeenumobavezno
  Vrsta vozila.
  carmotorcycletruck
- makestringobavezno
  Šifra marke.
- modelstringobavezno
  Šifra modela.
- make_namestringobavezno
  Marka.
- model_namestringobavezno
  Model.
- yearintegerobavezno
  Godište.
- mileage_kmintegerobavezno
  Kilometraža.
- fuelstringobavezno
  Gorivo.
- transmissionstringobavezno
  Mjenjač.
- power_kwnumberobavezno
  Snaga u kW.
asking_priceinteger | nullobavezno
Tražena cijena u KM.
valueobject | nullobavezno
Zadnja jutarnja procjena.
Prikaži 6 poljaSakrij polja
- currencystringobavezno
  BAM.
- pointintegerobavezno
  Tržišna vrijednost (standardni model, nezavisan od modela vaše kompanije).
- lowinteger | nullobavezno
  Donja granica raspona.
- highinteger | nullobavezno
  Gornja granica raspona.
- confidence_gradeenum | nullobavezno
  Ocjena pouzdanosti: A najuži rasponi za takva vozila, C najširi (rijetki modeli, malo podataka, nepotpun unos).
  ABC
- as_ofstring | nullobavezno
  Dan, YYYY-MM-DD.
ratingobject | nullobavezno
Ocjena kakvu widget prikazuje; null bez cijene, za prodano vozilo ili cijenu daleko van tržišta.
Prikaži 3 poljaSakrij polja
- levelenumobavezno
  Ocjena cijene: great odlična, good dobra, fair fer, high povišena, over visoka.
  greatgoodfairhighover
- pctnumberobavezno
  Tražena cijena naspram vrijednosti, u %.
- diff_bamintegerobavezno
  Razlika u KM (negativna: ispod vrijednosti).
embedobjectobavezno
Gotov kod; druge vrste: data-cifra-widget="badge|market|comparables|forecast|factors|mileage|report".
Prikaži 3 poljaSakrij polja
- page_urlstringobavezno
  Stranica vozila za kupce, s cijelim izvještajem.
- scriptstringobavezno
  Kod widgeta „Cijena” sa skriptom (preporučeno).
- iframestringobavezno
  Isti widget kao iframe.
sold_atstring | nullobavezno
Trenutak u ISO 8601 (UTC).
created_atstringobavezno
Trenutak u ISO 8601 (UTC).
updated_atstringobavezno
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).

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

POST/v1/widgets

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

Odgovor

{
  "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": "<div data-cifra-widget=\"price\" data-id=\"k3M9xQ2vTa\"></div>\n<script async src=\"https://www.cifra.ba/widget.js\"></script>",
    "iframe": "<iframe src=\"https://www.cifra.ba/embed/k3M9xQ2vTa/price\" title=\"Cifra — Cijena i tržišna vrijednost\" width=\"100%\" height=\"236\" style=\"border:0;max-width:100%\" loading=\"lazy\"></iframe>"
  },
  "sold_at": null,
  "created_at": "2026-10-21T09:14:02.511Z",
  "updated_at": "2026-10-21T09:14:02.640Z"
}