Widgeti

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.

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

Kako radi#

1. Procijenite vozilo produkcijskim ključem (POST /v1/valuations) — 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).

Ocjena#

rating poredi asking_price s tržišnom vrijednošću (value.point) u njenom realnom rasponu (value.low–value.high):

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

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.

<span data-cifra-widget="badge" data-id="k3M9xQ2vTa"></span>
<div data-cifra-widget="market" data-id="k3M9xQ2vTa"></div>
<script async src="https://www.cifra.ba/widget.js"></script>

Cijeli lager odjednom#

POST /v1/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 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. 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 — dobar trenutak da prodavac preispita cijenu. Adrese i potpis su u Webhookovi.

Pravila#

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.