Integracijski API i webhookovi

Osnovna adresa i autentikacija

https://<organizacija>.komunalio.hr/api/v1
X-API-Key: kom_...

Ključ se izdaje u Admin panelu, Integracije, API ključevi. Prikazuje se samo jednom.
Opseg: read (samo GET) ili read,write (i POST/PATCH).
Ograničenje: 300 zahtjeva u minuti po ključu.
Greške vraćaju JSON { "error": "..." } sa statusima 400, 401, 403, 404 ili 429.

Tiketi (prijave)

GET/tickets	Popis prijava. Parametri: `status`, `category_id`, `district_id`, `since`, `updated_since`, `page`, `limit` (do 200). Odgovor `{ total, page, limit, items[] }`.
GET/tickets/:id	Prijava s javnim porukama i nalozima.
POST/tickets	Nova prijava: `subject`, `body` (obavezno), `from_name`, `from_email`, `from_phone`, `category_id`, `district_id`, `address`, `latitude`, `longitude`, `priority`, `external_ref`. Odgovor `{ id, number, sla_deadline }`. Izvor prijave je `api`.
PATCH/tickets/:id	Promjena statusa: `{ "status": "resolved" }`. Vrijednosti: new, open, in_progress, forwarded, waiting_info, resolved, closed.
POST/tickets/:id/messages	Interna bilješka u ime vanjskog sustava: `{ "body": "..." }`.

Polja prijave: id, number, subject, status, priority, source, from_name, from_email, from_phone, address, latitude, longitude, created_at, updated_at, resolved_at, sla_deadline, category, department, district. Anonimizirane prijave (GDPR) se ne vraćaju.

Ostalo (samo čitanje)

GET/work-orders	Terenski nalozi. Parametri: `status`, `updated_since`, `page`, `limit`.
GET/categories	Vrste posla organizacije.
GET/districts	Mjesni odbori.
GET/roadworks	Radovi i prekopi.

Webhookovi

Postavljaju se u Admin panelu, Integracije, Webhookovi: URL (https) i događaji ticket.created i ticket.status_changed. Komunalio šalje POST s JSON tijelom:

{
  "event": "ticket.status_changed",
  "tenant_id": 3,
  "sent_at": "2026-10-09T08:00:00.000Z",
  "data": {
    "id": 42, "number": "KOM-2026-00042",
    "status": "resolved", "previous_status": "in_progress",
    "...": "ista polja kao GET /tickets/:id"
  }
}

Zaglavlja: X-Komunalio-Event i X-Komunalio-Signature: sha256=<HMAC-SHA256(tijelo, tajna)>. Tajna se prikazuje jednom pri kreiranju.
Jedan pokušaj slanja, vremensko ograničenje 8 s. Zadnji status i greška vidljivi su u Admin panelu; gumb „Probni događaj" šalje testni poziv.

Provjera potpisa (Node.js)

const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));

Primjer

curl -H "X-API-Key: kom_..." \
  "https://organizacija.komunalio.hr/api/v1/tickets?status=new&limit=20"

curl -H "X-API-Key: kom_..." -H "Content-Type: application/json" \
  -d '{"subject":"Rupa na kolniku","body":"Ulica 1, velika rupa","from_email":"[email protected]","category_id":12}' \
  https://organizacija.komunalio.hr/api/v1/tickets

API i webhookovi dio su paketa Enterprise ili se uključuju kao zaseban modul.