API dokumentacija

Osnovno

• Base URL (produkcija): https://www.poiscisidom.si/api/v1
• Base URL (razvoj): http://localhost:3000/api/v1
• Format odgovora: application/json, UTF-8

API ključ ustvarite v nadzorni plošči agencije (zavihek »API Ključi«).

Avtentikacija

Vsak zahtevek mora vsebovati glavo Authorization: Bearer <api_key>.

Authorization: Bearer psd_live_<64 hex znakov>

V bazi se shrani le SHA-256 hash ključa. Polni ključ je viden samo enkrat ob ustvarjanju — shranite ga v varni shrambi. Ob preklicu ključ takoj preneha delovati (vse zahteve vrnejo 401).

Omejitve hitrosti

100 zahtev na minuto na API ključ (drseče 60-sekundno okno). Ob preseženju:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Preveč zahtev. Počakajte in poskusite znova."
}

Glava Retry-After pove število sekund do naslednje dovoljene zahteve. Implementirajte eksponentni backoff.

Format napak

{
  "code": "STRING_KODA",
  "message": "Človeku berljivo sporočilo v slovenščini."
}

Oglasi

GET /api/v1/listings — seznam oglasov

Vrne oglase vaše agencije. Query parametri: status (osnutek/aktiven/prodan/arhiviran), limit (privzeto 50, najv. 100), offset.

curl -H "Authorization: Bearer $POISCISIDOM_API_KEY" \
  "https://www.poiscisidom.si/api/v1/listings?status=aktiven&limit=20"

{
  "data": [
    {
      "id": "1111…5555",
      "title": "Stanovanje 3-sobno z balkonom",
      "slug": "stanovanje-3-sobno-z-balkonom-ljubljana-12345678",
      "listing_type": "prodaja",
      "property_type": "stanovanje",
      "status": "aktiven",
      "price": 245000,
      "size_m2": 78,
      "rooms": 3,
      "city": "Ljubljana",
      "reference_no": "VAŠA-REF-001",
      "published_at": "2026-04-12T08:30:00Z",
      "listing_images": [
        { "id": "…", "url": "https://…/img.jpg", "is_primary": true, "sort_order": 0 }
      ]
    }
  ],
  "meta": { "limit": 20, "offset": 0 }
}

POST /api/v1/listings — ustvari oglas

Obvezna polja: title, listing_type, property_type, city. Ostala podprta polja: description, size_m2, rooms, bedrooms, bathrooms, floor, total_floors, year_built, energy_class, heating_type, has_parking, has_balcony, has_elevator, is_furnished, price, monthly_rent, address, municipality, post_code, reference_no, lat, lng.

curl -X POST -H "Authorization: Bearer $POISCISIDOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lepa hiša s pogledom",
    "listing_type": "prodaja",
    "property_type": "hisa",
    "city": "Bled",
    "price": 450000,
    "size_m2": 180,
    "rooms": 5,
    "energy_class": "B",
    "has_parking": true,
    "lat": 46.3683, "lng": 14.1146,
    "reference_no": "BLED-2026-001",
    "status": "aktiven"
  }' \
  https://www.poiscisidom.si/api/v1/listings

GET / PUT / DELETE /api/v1/listings/{id}

GET vrne posamezen oglas (403, če ne pripada vaši agenciji). PUT je delna posodobitev — pošljite samo polja, ki se spreminjajo. DELETE ne briše zapisa, ampak nastavi status na arhiviran (izgine iz javnega iskanja, ostane v vaših statistikah).

curl -X PUT -H "Authorization: Bearer $POISCISIDOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "price": 425000, "status": "aktiven" }' \
  https://www.poiscisidom.si/api/v1/listings/1111…

Slike oglasa

POST /api/v1/listings/{id}/images

Dva načina nalaganja:

A) URL-uvoz (application/json) — URL mora biti HTTPS in javno dostopen; strežnik prenese sliko v Supabase Storage. Lokalni/zasebni IP-ji so blokirani (SSRF zaščita), maks. 20 MB, samo image/*.

curl -X POST -H "Authorization: Bearer $POISCISIDOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://cdn.agencija.si/photo.jpg", "is_primary": true, "sort_order": 0 }' \
  https://www.poiscisidom.si/api/v1/listings/1111…/images

B) Multipart upload (multipart/form-data):

curl -X POST -H "Authorization: Bearer $POISCISIDOM_API_KEY" \
  -F "file=@./photo.jpg" -F "is_primary=true" -F "sort_order=0" \
  https://www.poiscisidom.si/api/v1/listings/1111…/images

DELETE /api/v1/listings/{id}/images/{imageId} odstrani sliko iz shrambe in baze.

Webhooki

Konfigurirajte URL-je, na katere POST-amo dogodke. Dostava poteka asinhrono prek Upstash QStash, do 3 ponovni poskusi z eksponentnim backoffom (1, 5, 25 minut).

Registracija (url mora začeti s https://, events neprazen seznam, secret neobvezen):

curl -X POST -H "Authorization: Bearer $POISCISIDOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://crm.vasa-agencija.si/poiscisidom/webhook",
    "events": ["lead.created"],
    "secret": "moj-skrivni-niz-za-hmac"
  }' \
  https://www.poiscisidom.si/api/v1/webhooks

Če nastavite secret, telo podpišemo s HMAC-SHA256 in pošljemo glavo X-Poiscisidom-Signature: sha256=<hex>. GET /api/v1/webhooks vrne aktivne, DELETE /api/v1/webhooks/{id} mehko izbriše.

Telo dostavljenega dogodka:

{
  "event": "lead.created",
  "agency_id": "…",
  "occurred_at": "2026-05-09T14:23:11Z",
  "data": {
    "lead_id": "…",
    "listing_id": "…",
    "listing_title": "Stanovanje 3-sobno z balkonom",
    "name": "Janez Novak",
    "email": "janez@primer.si",
    "phone": "+386 40 123 456",
    "message": "Pozdravljeni, kdaj je možen ogled?"
  }
}

Preverjanje podpisa (priporočeno):

import crypto from 'crypto'

function verify(rawBody: string, signatureHeader: string, secret: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
}

Pričakovan odgovor: HTTP 2xx v 10 sekundah. Po 3 neuspehih dostavo zabeležimo kot neuspešno.

OpenImmo XML uvoz

Standardni format za nepremičninske CRM-je (Flowfact, onOffice idr.). Pošljite XML kot telo z Content-Type: application/xml (ali application/json z { "xml": "…" }).

• Ujemanje obstoječih oglasov po verwaltung_objekt.objektnr_extern → reference_no (re-uvoz posodobi, ne podvaja).
• Slike se prenesejo s strežnika — samo HTTPS URL-ji.
• Uvoženi oglasi dobijo status aktiven.
• DOCTYPE/ENTITY/CDATA so blokirani (XXE zaščita).

curl -X POST -H "Authorization: Bearer $POISCISIDOM_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @export.xml \
  https://www.poiscisidom.si/api/v1/import/openimmo

{ "created": 3, "updated": 12, "skipped": 1,
  "errors": ["BLED-2026-005: Manjka obvezno polje city"] }

GET /api/v1/import/openimmo/status vrne rezultat zadnjega uvoza.

OpenAPI specifikacija

Strojno berljiva OpenAPI 3.1 specifikacija celotnega /api/v1 vmesnika je na voljo na spodnjem naslovu (brez ključa — vsebuje le obliko vmesnika, ne podatkov). Uvozite jo v Postman, Insomnia, generator odjemalcev ali AI orodje.

curl https://www.poiscisidom.si/api/v1/openapi.json

Zahtevni podatki oglasov v specifikaciji so izpeljani neposredno iz istih validacijskih shem, ki jih uporablja API — zato se opis ne more razhajati z dejanskim vedenjem.

MCP (Model Context Protocol)

Za AI asistente in agentska orodja ponujamo samo-bralni MCP vmesnik na POST /api/v1/mcp. Uporablja isto avtentikacijo z API ključem, iste omejitve hitrosti in isti obseg agencije kot REST — in ne razkriva nobene poti za pisanje ali brisanje. Na voljo so tri orodja: list_listings, get_listing in import_status.

# Seznam razpoložljivih orodij (JSON-RPC 2.0)
curl -X POST -H "Authorization: Bearer $POISCISIDOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }' \
  https://www.poiscisidom.si/api/v1/mcp

# Klic orodja
curl -X POST -H "Authorization: Bearer $POISCISIDOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
        "params": { "name": "list_listings", "arguments": { "status": "aktiven", "limit": 20 } } }' \
  https://www.poiscisidom.si/api/v1/mcp

Orodja za pisanje in širši MCP nabor so načrtovani kot naslednja faza.

Najboljše prakse

• Idempotenca: vedno nastavite reference_no na svoj stabilni interni ID — tako PUT in OpenImmo upsert ne podvajata.
• Slike kot zadnji korak: najprej ustvarite oglas (status: "osnutek"), naložite slike, šele nato status: "aktiven".
• Webhook idempotenca: vsak data.lead_id je enoznačen — hranite ga in zavrnite duplikate.
• Preslikava izrazov: če vaš CRM uporablja angleške izraze, jih preslikajte v naše enum vrednosti pred POST-om.

Podpora

Prijava napak in vprašanja: api-support@poiscisidom.si. Spremembe pogojev sporočimo 30 dni vnaprej po e-pošti.