Zelvoo
Prijava
KorisnoUgovori
ZELVOO / DEVELOPER

Zelvoo API integracija

Dokumentacija za povezivanje sustava agencija i investitora: od API ključa do provjerenog uvoza nekretnina.

Dokumentacija ažurirana 1. studenoga 2026. · HTTPS · JSON · EUR

Pregled integracije

Postojeći partnerski API prima nove oglase tvrtke i sprema ih kao oglase u izradi (draft). Oglas nije javno objavljen: prije objave pregledajte podatke i dodajte fotografije u svom računu. Kontakt oglašivača preuzima se iz tvrtke, a izdavatelj oglasa je vlasnik tvrtke.

POST/api/public/importUvoz novih nacrta

Opseg: ovo nije API za čitanje cijele ponude, izmjenu, brisanje, objavljivanje ili potpunu sinkronizaciju portfelja. Takvi javni endpointi nisu dostupni. Za ponovljene uvoze s vanjskim ID-ovima koristite uvoz datoteka opisan niže.

Pristup i API ključ

  1. Prijavite se na Zelvoo račun koji upravlja tvrtkom i provjerite da aktivni paket uključuje API integraciju.
  2. Otvorite Moja tvrtka, odaberite tvrtku i pronađite API uvoz.
  3. Odaberite Izradi API ključ. Spremite ga odmah: cijeli ključ prikazuje se samo nakon izrade.
  4. Na svom poslužitelju spremite ključ u tajnu varijablu ZELVOO_API_KEY. Šaljite ga u zaglavlju Authorization: Bearer VAŠ_KLJUČ.

Ključ je vezan uz jednu tvrtku. Format je zv_ i 48 malih heksadekadskih znakova. Izrada novog ključa odmah poništava stari; ažurirajte sve sustave koji ga koriste. API provjerava valjanost ključa i prava paketa pri svakom zahtjevu.

Moja tvrtkaPaketi i prava

Slanje zahtjeva

Adresa: https://zelvoo.hr/api/public/import. Šaljite UTF-8 JSON uz Content-Type: application/json i Bearer ključ. Pozive šaljite sa svog poslužitelja, ne iz javnog preglednika.

Tijelo je JSON popis oglasa ili objekt oblika { "oglasi": [...] }. Jedan zahtjev smije imati do 200 oglasa i najviše 2.000.000 bajtova. Veće skupove podijelite prije slanja.

oglasi.json
[
  {
    "naslov": "Trosobni stan u Zagrebu",
    "ponuda": "prodaja",
    "vrsta": "stan",
    "cijena": 245000,
    "povrsina": 78.5,
    "sobe": 3,
    "grad": "Zagreb",
    "adresa": "Primjer adrese 12",
    "opis": "Primjer podataka za integraciju; zamijenite stvarnim podatcima nekretnine."
  }
]

Primjer je ilustrativan i stvara stvarni nacrt ako ga pošaljete s valjanim ključem. Zamijenite ga stvarnim podatcima oglasa; zasebni testni API nije dostupan.

Referenca JSON polja

Koristite točne hrvatske nazive polja. API obrađuje samo sljedećih devet polja; proširena polja CSV/XML uvoza nisu dio ovog JSON ugovora.

PoljeTipObveznoPravila
naslovtekstDa5–120 znakova.
ponudatekstNeprodaja ili najam; zadano prodaja.
vrstatekstNestan, kuca, zemljiste ili poslovni; zadano stan.
cijenabrojDaVeće od 0 i manje od 1.000.000.000. EUR; kod najma mjesečni iznos.
povrsinabrojDaVeće od 0 i manje od 1.000.000 m².
sobebrojNe0–50 nakon zaokruživanja na cijeli broj; zadano 0.
gradtekstDaJedan od trenutačno podržanih gradova navedenih ispod.
adresatekstNeNajviše 200 znakova se sprema. Lokacija ostaje približna, na razini grada.
opistekstNeNajviše 5.000 znakova se sprema.

Brojevi: preporučeni su JSON brojevi s decimalnom točkom, bez oznaka EUR ili m². Ponuda i vrsta mogu biti i hrvatski nazivi (npr. Kuća), ali preporučene su gore navedene vrijednosti.

Trenutačno podržani gradovi za JSON API: Zagreb, Split, Rijeka, Osijek, Zadar, Pula, Dubrovnik, Šibenik, Varaždin, Karlovac, Slavonski Brod, Rovinj, Makarska i Opatija. Županija i približne koordinate preuzimaju se iz grada. Prepoznavanje zanemaruje velika/mala slova i dijakritičke znakove.

Važno za druge gradove: JSON API ne prosljeđuje polja zupanija, lat i lng. Zato slanje tih polja ne rješava nepoznat grad. Za takve lokacije koristite CSV/XML uvoz sa županijom i koordinatama ili kontaktirajte podršku.

Primjeri povezivanja

cURL
# ZELVOO_API_KEY postavite u sigurnom okruženju poslužitelja.
# oglasi.json sadrži JSON popis iz primjera ispod.
curl --request POST 'https://zelvoo.hr/api/public/import' \
  --header "Authorization: Bearer $ZELVOO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary '@oglasi.json'
JavaScript — poslužitelj
// Samo poslužiteljski kod; ključ nije za javni JavaScript.
const response = await fetch('https://zelvoo.hr/api/public/import', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.ZELVOO_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(oglasi), // popis do 200 oglasa
});
const result = await response.json();
if (!response.ok) throw new Error(result.error ?? 'API pogreška');
// HTTP 200 ne znači da je svaki oglas spremljen.
console.log({ saved: result.saved, errors: result.errors });
// Ne ponavljajte cijeli zahtjev ako je dio oglasa već spremljen.
Python — requests
import os
import requests

response = requests.post(
    "https://zelvoo.hr/api/public/import",
    headers={"Authorization": "Bearer " + os.environ["ZELVOO_API_KEY"]},
    json=oglasi,  # popis do 200 oglasa
    timeout=60,
)
response.raise_for_status()
result = response.json()
print({"saved": result["saved"], "errors": result["errors"]})
# Kod prekida veze prvo provjerite oglase u Zelvoo računu.
# Ponovni zahtjev može stvoriti duplikate.

Odgovori i pogreške

Odgovor je JSON. Uspješno obrađen zahtjev vraća saved (broj spremljenih nacrta) i errors (pogreške pojedinih zapisa). line koristi numeraciju tabličnog uvoza: prvi oglas je redak 2, drugi redak 3. Redak 1 označava zaglavlje, a 0 opće ograničenje.

Potpuno uspješan odgovor — HTTP 200
{
  "saved": 1,
  "errors": []
}
Djelomično uspješan odgovor — HTTP 200
{
  "saved": 1,
  "errors": [
    { "line": 3, "message": "naslov mora imati 5–120 znakova" }
  ]
}
Neispravan ključ — HTTP 401
{ "error": "Neispravan API ključ" }
HTTPZnačenjeSljedeći korak
200Zahtjev obrađenProvjerite saved i errors: moguća je djelomična uspješnost ili saved: 0.
400Neispravan zahtjevTijelo mora biti JSON; pošaljite neprazan popis ili objekt s poljem oglasi.
401Neispravan API ključProvjerite Bearer zaglavlje i je li ključ zamijenjen novim.
403API uvoz nije uključen u paketProvjerite trenutačna prava za tvrtkin API ključ.
404Tvrtka ne postojiKljuč mora pripadati postojećoj tvrtki.
413Zahtjev je prevelikTijelo zahtjeva smije imati najviše 2.000.000 bajtova.
500Spremanje nije uspjeloProvjerite paket, podatke i ograničenja u računu; po potrebi kontaktirajte podršku.

Neispravni zapisi ne spremaju se, a valjani se pokušavaju spremiti zajedno. Pogreška pri spremanju vraća HTTP 500 i može uključiti prethodne validacijske pogreške; nema popisa novostvorenih ID-ova u odgovoru.

Ograničenja i sigurno ponavljanje

  • Nema upserta ni idempotencije: svaki ponovni POST može stvoriti nove nacrte. Vanjski ID se u JSON API-ju ne obrađuje.
  • Nikada ne šaljite više od 200 oglasa: endpoint obrađuje samo prvih 200; ostatak može biti preskočen bez upozorenja u odgovoru.
  • Djelomični uspjeh: ispravite i ponovno pošaljite samo zapise iz errors, ne cijeli izvorni popis.
  • Prekid veze ili HTTP 500: prije ponavljanja provjerite nacrte u računu. Ne pretpostavljajte da zahtjev nije stigao.
  • Fotografije, video, novogradnja i dodatna polja: nisu podržani ovim JSON endpointom. Fotografije dodajte kroz Zelvoo ili ZIP uvoz; API koristi zamjensku naslovnu sliku.
  • Kvote i status: uvoz ne dodjeljuje pogodnosti, promocije ili automatsku objavu. Objavljivanje podliježe važećem paketu i pravilima računa.
  • Automatizacija: vaš sustav može poslati zahtjev, ali Zelvoo trenutačno ne dohvaća udaljene feedove niti provodi nenadziranu periodičnu sinkronizaciju.

Nije objavljen zaseban broj zahtjeva u minuti niti ugovorena propusnost. Šaljite serije redom i pratite svaki odgovor; ovaj API nije potvrđen kao rješenje za obradu 500 oglasa i 5.000 fotografija u pozadini.

CSV, XML i ZIP integracija

U Mojim oglasima i Mojoj tvrtki dostupan je odvojeni uvoz datoteka, prema osobnim pravima za CSV/XML. To nije drugi javni HTTP endpoint. U obrascu možete preuzeti predloške, pregledati podatke, mapirati stupce, spremiti konfiguraciju i pratiti izvještaj uvoza.

  • CSV: UTF-8, separator zarez, točka-zarez ili tabulator. Tekst sa separatorima stavite u dvostruke navodnike.
  • XML: ponavljajući elementi oglasa s poljima; DOCTYPE i vanjski entiteti nisu dopušteni.
  • ZIP: CSV/XML i lokalne fotografije. Polje fotografije navodi relativne putanje (npr. fotografije/stan-01.jpg|fotografije/stan-02.jpg). Fotografije se obrađuju u pregledniku i spremaju u privatnu pohranu; udaljene slike ne preuzimaju se.
  • Ponovljeni uvoz: za stabilni izvor koristite isti vanjski_id. Identitet je odvojen po vlasniku, izvoru i vanjskom ID-u. Neuspješan ili nepotpun uvoz ne smije ukloniti postojeću ponudu.
CSV — osnovni primjer
naslov;ponuda;vrsta;cijena;povrsina;sobe;grad;adresa;opis
"Trosobni stan u Zagrebu";prodaja;stan;245000;78.5;3;Zagreb;"Primjer adrese 12";"Zamijenite stvarnim opisom"
XML — osnovni primjer
<?xml version="1.0" encoding="UTF-8"?>
<oglasi>
  <oglas>
    <vanjski_id>CRM-001</vanjski_id>
    <naslov>Trosobni stan u Zagrebu</naslov>
    <ponuda>prodaja</ponuda>
    <vrsta>stan</vrsta>
    <cijena>245000</cijena>
    <povrsina>78.5</povrsina>
    <sobe>3</sobe>
    <grad>Zagreb</grad>
    <opis>Zamijenite stvarnim opisom</opis>
  </oglas>
</oglasi>

Proširena polja datoteka: vanjski_id, fotografije, zupanija, lat, lng, drzava, valuta, okucnica, kupaonice, kat, ukupno_katova, godina_izgradnje, godina_obnove, energetski_razred, grijanje, namjestenost, stanje, podvrsta, naselje, opcina, ulica, kucni_broj, video, video_2, virtualna_setnja, znacajke, udaljenost_mora, orijentacija, dostupno_od i novogradnja. Spremanje podliježe validaciji i pravima paketa.

Limiti naprednog uvoza: do 5.000 zapisa, 100 stupaca i 10.000 znakova po ćeliji, uz najviše 20 MB serijaliziranih podataka. Obrada ide u serijama po 20 oglasa; nastavak se pokreće iz preglednika. Pregled prikazuje do 20 valjanih zapisa. Jednostavni uvoz ograničen je na 200 oglasa, 30 stupaca i 2 MB podataka.

ZIP limiti: jedna CSV ili XML datoteka, najviše 100 MB arhive, 10.000 datoteka, ukupno 250 MB raspakirano i 20 MB po datoteci. Fotografije mogu biti JPEG, PNG ili WebP, do 10 MB i 40 megapiksela; pretvaraju se u WebP s najvećom dimenzijom 1.920 px. Broj spremljenih fotografija i videozapisa ograničen je paketom.

Identitet i izvještaji: bez vanjski_id novi odvojeni uvoz ne može pouzdano prepoznati prethodni oglas. Povijest prati processed, created, updated i failed te pogreške i upozorenja; izvor i posao moraju pripadati prijavljenom korisniku. Za izvoz odaberite 1–5.000 oglasa. Fotografije u izvozu imaju privremene poveznice, ne trajne javne URL-ove.

Za grad koji nije u ugrađenom popisu unesite grad, zupanija, lat i lng; koordinate moraju biti u Hrvatskoj. Za izvoz označite vlastite oglase i odaberite CSV ili XML ako vaš paket uključuje odgovarajući format. Izvoz nije dostupan kroz partnerski JSON API.

Moji oglasi i uvoz

Sigurnost integracije

  • Koristite HTTPS i čuvajte ključ isključivo na poslužitelju. Ne ugrađujte ga u aplikaciju preglednika, javni repozitorij, URL, e-poštu ili snimku zaslona.
  • Pri promjeni suradnika ili sumnji na otkrivanje odmah izradite novi ključ.
  • U zapisnicima ne bilježite Authorization zaglavlje ni nepotrebne osobne podatke. Evidentirajte vrijeme, broj poslanih oglasa, HTTP status, saved i errors.
  • Šaljite samo oglase i materijale koje smijete objavljivati. Ne pokušavajte slati owner_id, agency_id ili status: tvrtku i vlasnika određuje ključ, a status je draft.

Politika privatnosti · Opći uvjeti

Podrška za integraciju

Za pomoć pošaljite naziv tvrtke, format integracije, vrijeme zahtjeva, HTTP status i anonimizirani primjer pogreške. Nikada ne šaljite API ključ. Za udaljene feedove, dodatne gradove ili prilagođenu sinkronizaciju najprije provjerite mogućnosti s našim timom.

Kontaktirajte Zelvoo