Integracija sa ePP↵

Integracija sa funkcionalnostima ePP servisa u druge informacione sisteme postiže se upotrebom ePP REST servisa. Obzirom da kompletan ePP API sadrži stotine funkcija, u ovom dokumentu su prikazane samo one koje su do sada korisnicima bile značajne za integraciju.

Ciljna grupa

Ciljna grupa za informacije iz ovog dokumenta su IT profesionalci. Informacije nisu od značaja za ostale učesnike sistema.

Testno okruženje

U svrhu implementacije i lakšeg testiranja eksternih integrativnih servisa, postoji javno testno okruženje ePP servisa dostupno na adresi https://epp-test.trezor.gov.rs/. Testno okruženje je funkcionalno identično produkcionom (što ne uključuje podatke) i potrebno ga je koristiti u ranim fazama integracije, obzirom da je masovan unos testnih podataka na produkcioni servis zabranjen.

Pristup testnom okruženju ostvaruje se registracjom organizacije na produkcionom okruženju. Za više detalje pogledajte sekciju pristup servisu.

Okruženja↵

Sve funkcije navedene u ovom dokumentu se prefiksuju URL-om okruženja:

Produkcija: https://epp-rest.trezor.gov.rs/api
Test: https://repp-test.trezor.gov.rs/api

Na primer, poziv ping funkciji:

curl "https://epp-rest.trezor.gov.rs/api/login/ping"

Invoke-RestMethod "https://epp-rest.trezor.gov.rs/api/login/ping"

Autentifikacija i autorizacija↵

Pristup sistemu zahteva autentifikaciju. Pristup funkcionalnostima zahteva odgovarajuća aplikativna prava (autorizaciju).

ePP REST servis koristi JWT¹ standard za autentifikaciju i autorizaciju. Pristup se ostvaruje preuzimanjem access tokena pozivom login funkcije. Poziv svih drugih funkcija 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 autentifikacije ili autorizacije su:

Code	Message	Opis
`401`	`Unauthenticated`	Korisnik nije autentifikovan
`403`	`Unauthorized`	Korisnik nema odgovarajuće ovlašćenje za korišćenje funkcionalnosti

`login`↵

Preuzimanje pristupnih tokena - accessToken i refreshToken - koristeći korisnički nalog i lozinku.

Metod

POST

Atributi

login [string]: Korisnički nalog

password [string]: Korisnička lozinka

Rezultat

JSON objekat

{
    "properties": {
        "status": {
            "properties": {
                "message": { "type": "string" },
                "code":    { "type": "string" }
            }
        },
        "payload": {
            "properties": {
                "creationTime": { "type": "string" },
                "accessToken":  { "type": "string" },
                "refreshToken": { "type": "string" }
            }
        }
    }
}

Primer poziva koristeći PowerShell

$params = @{
    Method      = 'POST'
    Uri         = "https://epp-rest.trezor.gov.rs/api/login"
    ContentType = 'application/json'
    Body        = @{ login = 'foo'; password = 'bar' } | ConvertTo-Json
}
Invoke-RestMethod @params

Rezultat:

{
"status": {
    "message": "Success",
    "code": "Success"
},
"payload": {
    "creationTime": "2024-04-25T12:56:38.4460154+02:00",
    "accessToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
}

Ograničenja

Ograničenje	Vrednost	Komentar
Maksimalni broj neuspelih prijava	3	Pristup korisniku se blokira na 1 minut
*Vreme trajanja accessToken-a u minutima*	20

Konstantno logovanje pre svakog API poziva pristupa nije dozvoljeno

Ukoliko integrator kontinuirano pristupa ePP okruženju u kratkim vremenskim intervalima, ne sme koristiti login API pre svakog poziva. U tom slučaju, potrebno je da osveži accessToken upotrebom refresh API funkcije. Osvežavanje se sprovodi isključivo kada dobije grešku 401 - Unauthorized, što se dešava nakon što accessToken istekne.

`login/refresh`↵

Osvežavanje pristupnog tokena - accessToken - koristeći refreshToken.

Metod: GET
Headers: Authorization: Bearer <refreshToken>
Rezultat: JSON objekat, identičan kao kod login funkcije

Primer poziva koristeći PowerShell

$params = @{
    Method  = 'GET'
    Uri     = "https://epp-rest.trezor.gov.rs/api/login/refresh"
    Headers = @{ Authorization = "Bearer <RefreshToken>" }
}
Invoke-RestMethod @params

Rezultat:

{
"status": {
    "message": "Success",
    "code": "Success"
},
"payload": {
    "creationTime": "2024-04-25T12:56:38.4460154+02:00",
    "accessToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
}

API↵

Sve metode obavezno imaju sledeće parametre podešene, te oni nisu navođeni eksplicitno:

ContentType: application/json
Headers:
- Authorization: Bearer <RefreshToken>

`bank-accounts/<BankAccountNumber>/statement-url`↵

Preuzimanje linka za izvod računa. Nakon što je link preuzet, potrebno je eksplicitno pokrenuti download. Izvodi su dostupni u više formata.

Metod

GET

URL parametri

BankAccountNumber: Partija računa od 13 karaktera

Query parametri

type

Tip izvoda:

statement - dnevni izvod
specialStatement - specijalni izvod

format: Jedan od raspoloživih formata dnevnog izvoda: PDF, XML, JSON. Ne koristi se za specijalni izvod.

date: Datum izvoda u ISO8601 formatu yyyy-MM-dd

name: Ime specijalnog izvoda. Ne koristi se za dnevni izvod.

Headers

Referer: Za download se postavlja na https://epp.trezor.gov.rs/ na produkcionom okruženju, odnosno https://epp-test.trezor.gov.rs/ za testno okruženje. NAPOMENA: Završni / karakter je obavezan.

Primer preuzimanja dnevnog izvoda koristeći PowerShell

Sledeći primer prikazuje preuzimanje dnevnog izvoda za dan 2024-04-24 za račun 0000001185804 u json formatu:

$params = @{
    Method  = 'Get'
    Uri     = "https://epp-rest.trezor.gov.rs/api/bank-accounts/0000001185804/statement-url?type=statement&format=json&date=2024-04-24"
    Headers = @{ Authorization = "Bearer <token>" }
}
$result = Invoke-RestMethod @params
Invoke-WebRequest -Uri $result.payload.url -OutFile "0000001185804.json.zip" -Headers @{ Referer = 'https://epp.trezor.gov.rs/' }

Rezultat:

{
    "status": {
        "message": "Success",
        "code": "Success"
    },
    "payload": {
        "url": "https://epp.trezor.gov.rs/izvodi/2024-04-24/ePP/<jbkjs1>/<username>/<jbkjs2>/0000001185804.json.zip?md5=Kc6KrmV-86JXPPBCExBrZg&expires=1714061756",
        "expiredDate": "2024-04-25T18:15:56.8571103+02:00",
        "error": null
    }
}

NAPOMENA: URL delovi <јbkjs> i <username> imaju vrednosti koje zavise od prijavljenog korisnika i nosioca računa.

Primer preuzimanja specijalnog izvoda koristeći PowerShell

Sledeći primer prikazuje preuzimanje specijalnog izvoda pod imenom <JBKJS>_sve-partije za dan 2024-04-24:

$params = @{
    Method  = 'Get'
    Uri     = "https://epp-rest.trezor.gov.rs/api/bank-accounts/<jbkjs>/statement-url?type=specialStatement&date=2024-04-24&name=<jbkjs>_sve-partije"
    Headers = @{ Authorization = "Bearer <token>" }
}
$result = Invoke-RestMethod @params
Invoke-WebRequest -Uri $result.payload.url -OutFile "sve-partije.zip" -Headers @{ Referer = 'https://epp.trezor.gov.rs/' }

NAPOMENA: URL deo <јbkjs> ima vrednost koja zavisi od organizacije prijavljenog korisnika.

Detaljna PowerShell skripta

Korisnici mogu koristiti cross-platform skritpu download-statement da bi preuzeli izvod. Skripta se može koristiti kao detaljni primer upotrebe ili u okviru integracije.

Ograničenja

Generisani link, dostupan putem payload.url, zastareva nakon vremena dobijenog u payload.expiredDate (trenutno 60s); pokušaj preuzimanja izvoda nakon isticanja tog vremena rezultuje porukom 410 Gone
Download se mora pokrenuti sa iste IP adrese koja je korišćena za preuzimanje linka

✏️ Poslednja promena: 26.04.2024 09:48

📖 Datum izdanja: 26.04.2024 07:50

https://jwt.io ↩

Integracija sa ePP↵

Okruženja↵

Autentifikacija i autorizacija↵

login↵

login/refresh↵

API↵

bank-accounts/<BankAccountNumber>/statement-url↵

`login`↵

`login/refresh`↵

`bank-accounts/<BankAccountNumber>/statement-url`↵