Za razvijalce

Tvoji podatki, tvoj API.

Paketa Podjetje in Računovodstvo vključujeta MCP strežnik za AI asistente in bralni REST API: potni nalogi, evidenca delovnega časa, odsotnosti in mesečni obračuni — vprašaš Clauda ali povežeš ERP. Brez skritih pravil: vse, kar dostop zmore in česa ne, piše na tej strani.

MCP strežnik za AI asistente ključ = samo tvoja organizacija dostop je izključno bralni 120 zahtev/min na ključ uporaba iz brskalnika je blokirana

Začetek v dveh minutah

1 · Ustvari ključ — v aplikaciji: Nastavitve podjetja → API za razvijalce (lastnik ali admin). Ključ nalog_live_… se prikaže samo enkrat; hranimo zgolj njegov SHA-256.
2 · Pošlji zahtevo — ključ sodi v glavo Authorization: Bearer … in živi izključno na strežniku. Klici z brskalniškimi glavami (Sec-Fetch, Origin) so zavrnjeni, ključ pa označen kot razkrit.
3 · Določi podjetje — organizacije z enim podjetjem parameter ?company= lahko izpustijo; računovodski servisi ga podajo za vsako stranko (seznam: /v1/companies).

MCP strežnik — nalog.si v tvojem AI asistentu

Poleg REST API-ja je na isti ključ vezan tudi MCP strežnik (Model Context Protocol, Streamable HTTP). Poveži ga s Claude ali katerim koli MCP odjemalcem in vprašaj kar po slovensko: »koliko nadur je imela ekipa maja?« — asistent sam pokliče prava orodja.

Claude Code / CLI

claude mcp add --transport http nalog https://api.staging.nalog.si/mcp \
  --header "Authorization: Bearer $NALOG_KEY"

Drugi MCP odjemalci (JSON konfiguracija)

{
  "mcpServers": {
    "nalog": {
      "type": "http",
      "url": "https://api.staging.nalog.si/mcp",
      "headers": { "Authorization": "Bearer nalog_live_…" }
    }
  }
}

Orodje	Kaj vrne
list_companies	podjetja organizacije (servisi: vse stranke)
list_members	člani z vlogami in userId-ji
list_trips / get_trip	potni nalogi z relacijo, km in zneski
list_time_entries	evidenca delovnega časa
list_absences	dopusti in bolniške
monthly_summary	mesečni zbir po osebah: ure, nadure, km, EUR, nalogi — iste deterministične številke kot obračun

MCP dostop je bralni in podvržen istim pravilom kot REST: isti ključi, ista izolacija organizacije, ista zaščita pred razkritjem v brskalniku in ista omejitev 120 zahtev/min.

REST končne točke

Vsi datumi so YYYY-MM-DD in se, tako kot v aplikaciji, razlagajo po slovenskem (stenskem) času. V primerih je $NALOG_KEY tvoj ključ.

GET /v1/companies

Podjetja organizacije. Računovodski servis tu dobi seznam vseh svojih strank.

Zahteva

curl "https://api.staging.nalog.si/v1/companies" -H "Authorization: Bearer $NALOG_KEY"

Primer odgovora

{
  "data": [
    {
      "id": "9b2f1c4e-…",
      "name": "TermoFin d.o.o.",
      "address": "Obrtna ulica 5, Celje",
      "taxId": "SI12345678",
      "createdAt": "2026-01-12T09:30:00.000Z"
    }
  ]
}

Polja odgovora

Polje	Tip	Pomen
data[].id	`string · uuid`	identifikator podjetja — uporabi ga kot ?company=
data[].name	`string`	naziv podjetja
data[].address	`string \| null`	naslov sedeža
data[].taxId	`string \| null`	davčna številka
data[].createdAt	`string · ISO 8601`	kdaj je bilo podjetje dodano

GET /v1/members

Člani z dostopom do podjetja. Parameter ?company= je obvezen, kadar ima organizacija več podjetij.

Zahteva

curl "https://api.staging.nalog.si/v1/members?company=9b2f1c4e-…" -H "Authorization: Bearer $NALOG_KEY"

Primer odgovora

{
  "data": [
    {
      "userId": "71ac9d02-…",
      "name": "Ana Kovačič",
      "email": "ana@termofin.si",
      "role": "employee"
    }
  ]
}

Polja odgovora

Polje	Tip	Pomen
data[].userId	`string · uuid`	identifikator osebe — uporabi ga kot ?member=
data[].name	`string`	ime in priimek
data[].email	`string`	prijavni e-naslov
data[].role	`"owner" \| "admin" \| "manager" \| "employee" \| "accountant"`	vloga v organizaciji

GET /v1/trips

Potni nalogi po datumu izdaje (from/to, YYYY-MM-DD, vključujoče; privzeto tekoči mesec; največ 500 zapisov). Neobvezno: &status=draft|submitted|approved|issued.

Zahteva

curl "https://api.staging.nalog.si/v1/trips?from=2026-06-01&to=2026-06-30&status=issued" -H "Authorization: Bearer $NALOG_KEY"

Primer odgovora

{
  "data": [
    {
      "id": "d41e7a55-…",
      "status": "issued",
      "sequenceNumber": 42,
      "createdBy": "71ac9d02-…",
      "issuedAt": "2026-06-08T14:02:11.000Z",
      "nalog": {
        "issueDate": "2026-06-08",
        "purpose": "Sestanek pri stranki",
        "travelMeans": "own_vehicle",
        "basis": "kilometrina",
        "country": "SI"
      },
      "itinerary": { "startAt": "…", "endAt": "…", "roundTrip": true, "legs": [] },
      "calc": {
        "totalKm": 256,
        "kilometrinaEur": 110.08,
        "dnevniceEur": 13.88,
        "totalEur": 123.96
      },
      "createdAt": "2026-06-08T07:55:00.000Z",
      "updatedAt": "2026-06-08T14:02:11.000Z"
    }
  ],
  "count": 1
}

Polja odgovora

Polje	Tip	Pomen
data[].id	`string · uuid`	identifikator naloga
data[].status	`"draft" \| "submitted" \| "approved" \| "issued" \| …`	stanje v poteku odobritve
data[].sequenceNumber	`number \| null`	zaporedna številka (brez vrzeli); null pred izdajo
data[].createdBy	`string · uuid \| null`	avtor (glej /v1/members)
data[].issuedAt	`string · ISO 8601 \| null`	trenutek izdaje
data[].nalog	`object`	glava naloga: issueDate, purpose, travelMeans, basis, country
data[].itinerary	`object`	pot: startAt, endAt, roundTrip, legs[] (from/to/distanceKm)
data[].calc	`object`	izračun: totalKm, kilometrinaEur, dnevniceEur, stroški, totalEur
count	`number`	število vrnjenih zapisov

GET /v1/trips/{id}

En nalog v celoti — enak objekt kot v seznamu, ovit v { data }.

Zahteva

curl "https://api.staging.nalog.si/v1/trips/d41e7a55-…" -H "Authorization: Bearer $NALOG_KEY"

Primer odgovora

{ "data": { "id": "d41e7a55-…", "status": "issued", "nalog": { … }, "calc": { … } } }

Polja odgovora

Polje	Tip	Pomen
data	`object`	isti objekt kot element seznama /v1/trips

GET /v1/time-entries

Evidenca delovnega časa (privzeto zadnjih 31 dni; največ 2000 zapisov). Neobvezno: &member=<userId>.

Zahteva

curl "https://api.staging.nalog.si/v1/time-entries?from=2026-06-01&to=2026-06-07" -H "Authorization: Bearer $NALOG_KEY"

Primer odgovora

{
  "data": [
    {
      "id": "ab21f6e8-…",
      "userId": "71ac9d02-…",
      "startedAt": "2026-06-01T06:00:00.000Z",
      "endedAt": "2026-06-01T14:00:00.000Z",
      "breaks": [
        { "start": "2026-06-01T10:00:00.000Z", "end": "2026-06-01T10:30:00.000Z" }
      ],
      "homeOffice": false,
      "note": null
    }
  ],
  "count": 1
}

Polja odgovora

Polje	Tip	Pomen
data[].id	`string · uuid`	identifikator zapisa
data[].userId	`string · uuid`	kdo je delal (glej /v1/members)
data[].startedAt	`string · ISO 8601`	prihod
data[].endedAt	`string · ISO 8601 \| null`	odhod; null = izmena še teče
data[].breaks	`{ start, end \| null }[]`	malice/premori znotraj izmene
data[].homeOffice	`boolean`	delo od doma
data[].note	`string \| null`	opomba

GET /v1/absences

Dopusti, bolniške in druge odsotnosti, ki se prekrivajo z obdobjem from/to.

Zahteva

curl "https://api.staging.nalog.si/v1/absences?from=2026-06-01&to=2026-06-30" -H "Authorization: Bearer $NALOG_KEY"

Primer odgovora

{
  "data": [
    {
      "id": "5fc38b91-…",
      "userId": "71ac9d02-…",
      "kind": "dopust",
      "fromDate": "2026-06-22",
      "toDate": "2026-06-26",
      "hoursPerDay": null,
      "note": null
    }
  ],
  "count": 1
}

Polja odgovora

Polje	Tip	Pomen
data[].kind	`"dopust" \| "bolniska" \| "drugo"`	vrsta odsotnosti
data[].fromDate	`string · YYYY-MM-DD`	prvi dan
data[].toDate	`string · YYYY-MM-DD \| null`	zadnji dan; null = do nadaljnjega
data[].hoursPerDay	`number \| null`	delna bolniška (ure/dan); null = cel dan

GET /v1/obracun/{YYYY-MM}

Mesečni obračun kot .xlsx — bajtno enak izvozu iz aplikacije (nalogi + evidenca ur + zbir po osebah). En klic na mesec in plače so pokrite.

Zahteva

curl -OJ "https://api.staging.nalog.si/v1/obracun/2026-06?company=9b2f1c4e-…" -H "Authorization: Bearer $NALOG_KEY"

Primer odgovora

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="obracun-2026-06.xlsx"

<binarni xlsx>

Polja odgovora

Polje	Tip	Pomen
—	`binary · xlsx`	trije listi: Obračun (nalogi), Evidenca ur, Obračun skupaj (po osebah)

Napake — vse, brez izjem

Telo napake je vedno { "error": "koda" }:

HTTP	Koda	Pomen
401	`unauthorized`	ključ manjka, je napačen ali preklican
403	`plan_without_api`	paket organizacije ne vključuje API-ja (Podjetje/Računovodstvo)
403	`browser_blocked`	zahteva je prišla iz brskalnika (glave Sec-Fetch/Origin) — ključ je razkrit v javni kodi; zahteva je zavrnjena, ključ pa v aplikaciji označen za zamenjavo
400	`company_required`	organizacija ima več podjetij — dodaj ?company=
404	`company_not_found`	podjetje ne obstaja ali ne pripada tvoji organizaciji
400	`bad_date / bad_month`	datum ni YYYY-MM-DD oziroma mesec ni YYYY-MM
404	`not_found`	zapis ne obstaja (ali pripada drugi organizaciji — namerno ista koda)
429	`rate_limited`	več kot 120 zahtev/min na ključ; glej glavo Retry-After

Varnost ključev

• Ključ vidiš samo enkrat. Pri nas je shranjen izključno kot SHA-256 — nihče (niti mi) ga ne more prebrati nazaj. Izgubljen ključ prekličeš in ustvariš novega.
• Zaščita pred razkritjem v brskalniku. Brskalniki vsaki zahtevi samodejno dodajo glave Sec-Fetch-* (JavaScript jih ne more odstraniti) in Origin. Če katera od njih prispe na /v1, ključ očitno živi v javni kodi — zahteva je zavrnjena s browser_blocked, ključ pa v aplikaciji označen z opozorilom za zamenjavo. Strežniških integracij (curl, Node, Python …) to nikoli ne prizadene.
• Zaščito je mogoče izklopiti (Nastavitve podjetja → API za razvijalce) — z dvojno potrditvijo, ker je smiselna le za interne kioske ali Electron aplikacije. Ne priporočamo.
• Vsaka uporaba pušča sled — čas zadnje uporabe je viden ob vsakem ključu.

Pošteno o omejitvah

• v1 je bralni. Ustvarjanje nalogov, ur ali odsotnosti prek API-ja še ni mogoče — če ga potrebuješ, se oglasi, gradimo po dejanskih potrebah.
• Brez webhookov (zaenkrat). Spremembe pridobivaš s poizvedovanjem; za mesečne obračune zadošča en klic na mesec.
• 120 zahtev/min na ključ. Pri prekoračitvi dobiš 429 z glavo Retry-After; trajna prekoračitev ne vodi v blokado, samo v upočasnitev.
• Do 10 aktivnih ključev na organizacijo; vsak se prekliče z enim klikom in neha veljati takoj.
• Seznami so omejeni (nalogi 500, ure/odsotnosti 2000 zapisov) — oži obdobje, če zadaneš mejo.

Manjka končna točka?

API širimo po potrebah strank — napiši nam, kaj integriraš, in povemo, kdaj (ali zakaj ne).

Piši razvojni ekipi