Idi na tekst

Model integracije

Pristup↵

API funkcijama se pristupa preko adrese http://gbs-stage.mfin.trezor.rs:2282. Svaki poziv ima prefiks api i opciono verziju u putanji vX.Y:

  • /api/login
    Poziva poslednju verziju funkcije.
  • /api/v1.1/login
    Poziva verziju 1.1 funkcije.

Zaglavlje rezultata svakog poziva sadrži atribut api-supported-versions koji lista sve raspoložive verzije funkcije. Poslednja verzija API-ja je dodatno označena sufiksom current, npr. 1.1-current.

Neaktuelne verzije API-ja zastarevaju (eng: deprecation) i biće uklonjene. Uklanjanje se neće vršiti ranije od 3 meseca od trenutka raspoloživosti nove verzije.

API koristi JSON format za razmenu podatka i osim ako je drugačije napomenuto, ContentType za svaki request je application/json.

Upozorenje

Postoji maksimalna frekvencija upotrebe svake konkretne funkcije SPIRI servisa (eng: Rate Limiter).

Na primer, neke funkcije je moguće koristiti maksimalno jednom u sekundi.

Model povratnog paketa↵

Sve API funkcije servisa SPIRI imaju standardizovanu formu povratnog paketa (payload). Povratni paket sadrži sledeći set polja:

  • status - statusni kod i opis greške - u slučaju neuspelog poziva, inače Success
  • payload - poslovni podaci konkretnog endpoint-a kao rezultat izvršenja funkcije
  • additionalInformation - dodatni poslovni podaci, ukoliko je neophodno
Primer uspešnog povratnog paketa 
{
    "status": {
        "message": "Success",
        "code": "Success"
    },
    "payload": {
        "creationTime": "2022-05-07T18:58:04.193788+02:00",
        "accessToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
        "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
        "applicationStateId": 1
    },
    "additionalInformation": null
}
Primer povratnog paketa sa greškom 
{
    "status": {
        "message": "Failed to generate access token with submitted credentials",
        "code": "GenerateAccessToken"
    },
    "payload": null,
    "additionalInformation": null
}

Autentikacija i autorizacija↵

Pristup zaštićenim pristupnim tačkama servisa zahteva autentikaciju. Pristup konkretnim funkcionalnostima zahteva odgovarajuća aplikativna prava (autorizaciju).

SPIRI koristi JWT standard za autentikaciju i autorizaciju.

Pristup se ostvaruje preuzimanjem access tokena (accessToken) pozivom /api/login javne pristupne tačke. Poziv zaštićenih pristupnih tačaka zahteva da u zaglavlju (eng: Headers) postoji Authorization atribut sa vrednošću Bearer <accessToken>.

Poruke o greškama koje se javljaju kod pristupa API funkcijama usled neodgovarajuće autentikacije ili autorizacije su:

Code Message Opis
401 Unauthorized Korisnik nije autentikovan
403 Forbidden Korisnik nema odgovarajuće ovlašćenje za korišćenje funkcionalnosti

Workflow autentikacije↵

Kako bi se krajnjem korisniku obezbedio nesmetan rad na servisu, kao i smanjio nepotreban broj poziva ka servisu, JWT pristup obezbeđuje mehanizam kontinualnog pristupa zaštićenim funkcijama upotrebom refresh workflow-a.

Inicijalnim pozivom pozivom /api/login javne pristupne tačke, sadržaj povratnog paketa uspešnog zahteva će sadržati polja:

  • accessToken - pristupni token kratkoročne validnosti - 20 minuta,
  • refreshToken - dugoročni token

Pristupni access token omogućava neposredno pozivanje zaštićenih funkcija u toku trajanja access sesije (20 minuta). Nakon isteka sesije, pozivi zaštićenih funkcija servisa sa istim access tokenom će rezultovati greškom 401 - Unauthorized.

Kako bi se izbegla potreba za ponovnim slanjem korisničkih kredencijala, postavljanjem Authorization atributa na vrednost Bearer <refreshToken> i pozivom refresh funkcije, omogućeno je pribavljanje novog aktivnog access tokena i time nastavljen neometan rad krajnjeg korisnika u trajanju nove access sesije.

Rezime workflow-a

  1. Pribavljanje access i refresh tokena pozivom login funkcije sa korisničkim kredencijalima,
  2. Rad sa zaštićenim funkcijama servisa upotrebom access tokena u trajanju kratkoročne sesije,
  3. Nakon isteka kratkoročne sesije, poziv zaštićene funkcije rezultuje greškom 401 - Unauthorized,
  4. Pribavljanje validnog access tokena pozivom refresh funkcije upotrebom refresh tokena,
  5. Nastavak rada sa zaštićenim funkcijama servisa upotrebom novog validnog access tokena

SPIRI JWT token↵

Pored standardnih sigurnosnih elemenata, JWT token servisa SPIRI sadrži i određeni broj polja koja se odnose na poslovnu logiku samog servisa.

  • unique_name - jedinstveno korisničko ime u sistem login
  • user_name - puno ime korisnika,
  • user_id - identifikator korisnika,
  • organization_id - identifikator organizacije korisnika,
  • budget_user_id - JBKJS korisnika,
  • budget_user_name - naziv budžetskog korisnika,
  • budget_user_type - tip budžetskog korisnika,
  • urgent_payment - da li korisnik može da kreira hitno plaćanje,
  • treasury - šifra trezora,
  • treasury_branch - šifra filijale trezora

Sekcija security_claims sadrži niz aplikativnih prava koja odgovaraju poslovnim funkcionalnostima servisa, a kojima korisnik ima omogućen pristup.

Nazivi aplikativnih prava se formiraju prema pravilu resurs_akcija, pri čemu resurs označava funkcionalnu celinu (aproprijacija, kvota, itd.), dok akcija predstavlja omogućenu radnju nad datim resursom (čitanje, izmena, odobravanje itd.)

Primer JWT tokena 
{
    "unique_name": "min_odbrane",
    "user_name": "Korisnik ministarstva odbrane",
    "user_id": "11",
    "organization_id": "4",
    "budget_user_id": "61040",
    "treasury": "601",
    "treasury_branch": "40200",
    "budget_user_name": "MINISTARSTVO ODBRANE",
    "budget_user_type": "1",
    "urgent_payment": "True",
    "security_claims": [
        "user_notification_view",
        "user_session_invoke",
        "appropriation_request_view",
        "appropriation_request_manage",
        "appropriation_request_user_approve",
        "appropriation_request_cancel",
        "appropriation_view",
        "appropriation_manage",
        "quota_request_view",
        "quota_request_manage",
        "quota_view",
        "recording_account_request_view",
        "recording_account_request_manage",
        "recording_account_view",
        "datatable_view",
        "document_type_view",
        "budget_year_view",
        "calendar_view",
        "sub_economic_classification_view",
        "sub_economic_classification_manage",
        "economic_classification_payment_code_view",
        "exchange_rate_view",
        "enforced_collection_view",
        "budget_structure_view"
    ],
    "nbf": 1651950725,
    "exp": 1651952525,
    "iat": 1651950725,
    "iss": "TreasurySecurityIssuer",
    "aud": "TreasurySecurityAudience"
}
✏️ Poslednja promena: 11.05.2026 15:14
📖 Datum izdanja: 11.05.2026 13:15