Kolio REST API in webhooki

10.1Kaj Kolio REST API omogoča?

Kolio REST API je vmesnik HTTP/JSON pod osnovnim naslovom https://kolio.si/api/integrations/v1, prek katerega zunanji sistem bere in spreminja termine (koledar), CRM kontakte in naloge enega računa Kolio; avtenticira se z API ključem, ki hkrati določa račun (tenant) in dovoljeni obseg.

Vsi trije vhodi — vmesnik aplikacije, REST API in MCP strežnik — pišejo skozi ista poslovna jedra. Termin, ustvarjen prek API-ja, gre skozi isto preverjanje delovnega časa lokacije, prostih izvajalcev in prekrivanja kot termin, ki ga vaša ekipa vpiše v koledar; naloga dobi enako časovnico kot v CRM-ju. Integracija zato ne more ustvariti zapisa, ki ga aplikacija ne bi dovolila.

10.2Kako ustvarim API ključ?

API ključ ustvari član z dovoljenjem Nastavitve na strani Nastavitve → MCP viri in integracije, v razdelku API ključi; ključ se v celoti prikaže samo enkrat, v bazi pa ostane le njegov zgoščeni odtis (SHA-256) in vidna predpona.

10.3Kako se avtenticiram?

Ključ pošljete v glavi Authorization: Bearer kolio_sk_… ali v glavi X-API-Key: kolio_sk_…; račun (tenant) se vedno določi iz ključa in nikoli iz telesa ali URL-ja zahteve, zato en ključ ne more doseči podatkov drugega računa.

curl -s https://kolio.si/api/integrations/v1/ping \
  -H "Authorization: Bearer kolio_sk_…"

# odgovor
{
  "ok": true,
  "tenantId": "…",
  "scopes": ["contacts:read", "bookings:write"],
  "timestamp": "2026-09-15T08:12:03.512Z"
}

Vse ostale končne točke vrnejo ob uspehu objekt { "data": … }, ob napaki pa { "error": "koda", "message": "slovensko pojasnilo" }. Koda napake je stabilna in primerna za programsko obravnavo, sporočilo je namenjeno ljudem.

10.4Obsegi (scopes) in dovoljenja

Vsak obseg API ključa je preslikan v obstoječe dovoljenje člana v Koliu, zato ključ nikoli ne odpre področja, ki ga aplikacija sama ne pozna; obsegi so natančni nizi brez hierarhije — contacts:write ne vključuje contacts:read.

10.5Katere končne točke so na voljo?

Integrations API v1 ima osem poti: ping, locations ter po dve za termine, kontakte in naloge — zbirka (GET seznam, POST ustvarjanje) in posamezen zapis (GET, PATCH, DELETE); seznami so omejeni s parametrom limit (privzeto 50, največ 200).

Termini

curl -s -X POST https://kolio.si/api/integrations/v1/bookings \
  -H "Authorization: Bearer kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "slotStart": "2026-09-22T09:00",
    "serviceId": "<id storitve>",
    "contactId": "<id kontakta>",
    "locationId": "<id lokacije iz GET /locations>",
    "notes": "Rezervacija iz spletne trgovine"
  }'

# 201
{ "data": { "id": "…", "slotStart": "2026-09-22T07:00:00.000Z",
            "slotEnd": "2026-09-22T07:30:00.000Z", "status": "confirmed",
            "serviceId": "…", "contactId": "…", "locationId": "…", "locationName": "Ljubljana",
            "source": "api", "…": "…" } }

# 422 — izven delovnega časa lokacije, ni prostega izvajalca ali nosilec ni član
{ "error": "booking_rejected", "message": "Termin je izven delovnega časa lokacije." }

Seznam prostih terminov REST v1 ne ponuja; proste ure vrne orodje find_free_slots na MCP strežniku. Zasedenost lahko preverite tudi z GET /bookings?from=…&to=… in delovnim časom lokacij iz GET /locations, ki ga nastavite v koledarju in storitvah. Zapis prek API-ja je strog: termin izven delovnega časa lokacije ali brez prostega izvajalca vrne 422 booking_rejected; izjeme lahko vpiše samo ekipa v koledarju.

Kontakti

curl -s -X POST https://kolio.si/api/integrations/v1/contacts \
  -H "X-API-Key: kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ana",
    "lastName": "Novak",
    "email": "ana.novak@example.com",
    "phone": "+38640123456",
    "externalId": "erp-10482",
    "tags": ["spletna-trgovina"],
    "gdprConsent": true
  }'

# 201
{ "data": { "id": "…", "firstName": "Ana", "lastName": "Novak",
            "email": "ana.novak@example.com", "externalId": "erp-10482", "…": "…" } }

# 422
{ "error": "missingFields",
  "message": "Kontakt potrebuje vsaj eno od polj: ime, priimek, telefon ali e-pošta." }

Pred ustvarjanjem preverite, ali kontakt že obstaja: GET /contacts?email=…, ?phone=… ali ?externalId=… vrnejo točno ujemanje, ?q=… išče po imenu, priimku, e-pošti, telefonu in podjetju. Polje externalId je namenjeno id-ju stranke v vašem sistemu (ERP, spletna trgovina).

Naloge

# POST — nova naloga
curl -s -X POST https://kolio.si/api/integrations/v1/tasks \
  -H "Authorization: Bearer kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pokliči stranko glede ponudbe 2026-118",
    "contactId": "<id kontakta>",
    "assigneeEmail": "prodaja@vase-podjetje.si",
    "priority": 2,
    "dueAt": "2026-09-18T12:00"
  }'

# 201
{ "data": { "id": "tsk_…", "title": "Pokliči stranko …", "status": "nova",
            "priority": 2, "dueAt": "2026-09-18T10:00:00.000Z", "…": "…" } }

# PATCH — zaključi nalogo s komentarjem
curl -s -X PATCH https://kolio.si/api/integrations/v1/tasks/tsk_… \
  -H "Authorization: Bearer kolio_sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "zakljucena", "comment": "Stranka je ponudbo potrdila." }'

# 422 — neznan nosilec
{ "error": "unknownAssignee", "message": "…" }

10.6Kako API razume čas?

Vsi časi vhoda so ISO 8601; niz z odmikom ali Z se vzame dobesedno, niz brez odmika (2026-09-22T09:00) pa se razume kot lokalni čas v časovnem pasu vašega računa (Nastavitve → Splošno, privzeto Europe/Ljubljana), sam datum (2026-09-22) pa kot polnoč tega dne v istem pasu.

Odgovori vračajo čase kot UTC instant s končnico Z (npr. 2026-09-22T07:00:00.000Z). Strežnik teče v UTC; brez tega pravila bi se termin, poslan kot 09:00 brez odmika, tiho premaknil za eno ali dve uri. Pravilo velja za slotStart, slotEnd, from, to in dueAt.

10.7Kako delujejo webhooki?

Webhook je HTTP POST, ki ga Kolio ob dogodku pošlje na vaš URL z JSON ovojnico { event, tenantId, timestamp, data }, podpisano s HMAC-SHA256 (RFC 2104) v glavi X-Kolio-Signature (oblika sha256= + šestnajstiški HMAC); čas dogodka je v glavi X-Kolio-Timestamp in v polju timestamp telesa, zato je podpis vezan na čas. Pošiljanje je enkratno in po načelu najboljšega truda (brez ponovnih poskusov).

POST /webhook HTTP/1.1
Content-Type: application/json
X-Kolio-Event: booking.created
X-Kolio-Timestamp: 2026-09-15T08:14:22.318Z
X-Kolio-Signature: sha256=3f1a9c…

{
  "event": "booking.created",
  "tenantId": "…",
  "timestamp": "2026-09-15T08:14:22.318Z",
  "data": {
    "bookingId": "…",
    "contactId": "…",
    "serviceId": "…",
    "slotStart": "2026-09-22T07:00:00.000Z",
    "slotEnd": "2026-09-22T07:30:00.000Z",
    "status": "confirmed"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyKolioSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

10.8Omejitve in dobra praksa

Kolio REST API v1 nima idempotenčnega ključa in nima ponovnih poskusov webhookov, zato mora integracija sama preprečevati podvojene zapise — s preverjanjem obstoja pred ustvarjanjem in s shranjevanjem id-jev, ki jih Kolio vrne.

• Za vsako integracijo uporabite ločen ključ z lastnim imenom — v časovnici boste videli, katera integracija je posegla, in jo lahko preklicali, ne da bi ustavili druge.
• Pred POST /contacts poiščite kontakt po email, phone ali externalId; pred POST /bookings preberite zasedenost obdobja in pri več lokacijah podajte locationId.
• Za preklic termina uporabite PATCH { "status": "cancelled" }, za konec naloge PATCH { "status": "arhivirana" }; DELETE je trajen in briše tudi časovnico.
• Pošiljajte čase z odmikom in shranjujte id-je iz odgovorov (data.id) — to je edini zanesljiv ključ za kasnejši PATCH.
• Napake obravnavajte po polju error, ne po besedilu message, ki je namenjeno ljudem in se lahko spremeni.