API-first

API za obračun plata i kadrovsku evidenciju

Salario je od početka građen oko ugovora: OpenAPI 3.1 specifikacija je izvor istine, a web aplikacija koristi isti API kao i vaši sistemi.

# spisak aktivnih zaposlenih (sesija poslije OIDC prijave)
curl -b "$SESIJA" -H "X-Institution-Id: $USTANOVA" \
  "https://vasa-instanca/api/v1/employees?status=active"

# fajl sa satima za uvoz (CSV, shema salario-mock/1; pregled prije upisa)
curl -X POST -b "$SESIJA" -H "X-Institution-Id: $USTANOVA" \
  -H "X-CSRF-Token: $CSRF" -F file=@sati-novembar.csv \
  https://vasa-instanca/api/v1/time/imports/files

# pregled obračuna za jednog zaposlenog
curl -X POST -b "$SESIJA" -H "X-Institution-Id: $USTANOVA" \
  -H "X-CSRF-Token: $CSRF" -H "Content-Type: application/json" \
  -d '{"employeeId":"…"}' \
  https://vasa-instanca/api/v1/payroll/runs/{runId}/preview

REST + OpenAPI 3.1

Verzionisan /api/v1, JSON šeme, greške po RFC 9457, paginacija i filteri. Tipizirani klijenti se generišu iz specifikacije.

Uvoz sa provjerom

Sati iz CSV fajla: provjera fajla, pregled grešaka prije upisa, primjena tek nakon potvrde. Formati vaše ustanove uz potvrđen uzorak.

Izvozi (u izradi)

Izvozi za Poresku upravu i trezor nosiće SHA-256 kontrolni zbir, zapis u reviziji i statuse od izrade do predaje — uključuju se uz zvaničnu specifikaciju.

Sigurnost API-ja

OIDC prijava (Keycloak) i serverska sesija, CSRF zaštita izmjena, provjera ustanove na serveru, optimistična konkurentnost (ETag / If-Match) i revizorski trag.

Događaji domena (planirano)

Obavještenja o promjenama (zaposleni, odobreni sati, zaključan obračun) za sinhronizaciju sa drugim sistemima — u planu razvoja.

Adapteri (planirano)

Poreska uprava, trezor, banke, računovodstvo, evidencija prisustva — verzionisani adapteri, uključuju se uz zvaničnu specifikaciju i potvrđen uzorak.

Najvažnije rute

OblastPrimjeri ruta
ZaposleniGET/POST /employees, GET/PATCH /employees/{employeeId}, …/account-changes, …/documents, …/deductions
Organizacija/institution, /org-units, /positions, /engagements
Radno vrijeme i odsustva/time/timesheets, POST /time/imports/files → /time/imports → /time/imports/apply, /time/punches, /leave/cases
ObračunPOST /payroll/runs, …/validate, …/calculate, …/preview, …/submit, …/review, …/approve, …/lock, …/employees/{employeeId}/trace
Konfiguracija/configuration/parameters, /configuration/versions (…/diff, …/submit, …/activate), /calendar/non-working-days
RevizijaGET /audit/events, POST /audit/chain/verify

Sve rute su pod /api/v1. Izvozi za Poresku upravu i trezor dobijaju rute kad se njihovi formati zvanično potvrde. Kompletnu specifikaciju i testno okruženje dobijate uz projekat integracije.

Česta pitanja o API-ju

Da li web aplikacija koristi isti API?

Da. Web aplikacija Salaria radi isključivo preko javnog REST API-ja opisanog OpenAPI 3.1 specifikacijom, uz iste dozvole, provjere i revizorski trag. Koje rute i načine pristupa koristi vaša integracija dogovaramo u projektu.

Kako se API autentifikuje?

Prijava ide preko OIDC-a (Keycloak) u serversku sesiju; izmjene traže CSRF token, a izabrana ustanova se šalje zaglavljem X-Institution-Id, koje server uvijek provjerava prema članstvima korisnika. Način pristupa za mašinske integracije dogovaramo u projektu.

Postoji li uvoz iz fajla?

Postoji kontrolisan uvoz sati iz CSV fajla po zadatoj šemi: fajl se provjeri, prikaže se pregled sa greškama, a upis ide tek nakon potvrde. Formate izvoza vaše ustanove (npr. Excel) uključujemo uz potvrđen uzorak.

Mogu li se povezati evidencija prisustva i računovodstvo?

Mogu, kroz API. Za specifične sisteme (banka, trezor, računovodstvo, evidencija prisustva) dogovaramo integraciju u okviru projekta.

Pogledajte Salario uživo

Zakažite demo od 30 minuta. Proći ćemo kroz mjesečni obračun, evidenciju zaposlenih i izvještaje i odgovoriti na pitanja vašeg računovođe — na demo podacima, bez slanja vaših platnih lista.