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.

Method

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.

Method: 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 Methode obavezno imaju sledeće parametre podešene, te oni nisu navođeni eksplicitno:

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

Sve API funkcije vraćaju rezultat u obliku:

  "status": {
    "code": "...",
    "message": "..."
  },
  "payload": {
    ...
  }

Atribut status sadrži kod greške (code - jedna reč) i opis greške (message) dok payload sadrži objekat koji je specifičan za pozvanu funkciju.

Prilikom kreiranja entiteta, API gotovo uvek gde je to moguće koristi niz objekata kao ulaz, obrađuje sve što je moguće, dok za ostale entitete prijavljuje greške. Pozivi koji su uspešni ali imaju validacione greške smatraju se uspešnim (imaju statusni HTTP kod 200) obzirom da su podaci uspešno obrađeni dok se greške individualnih elemenata vraćaju u okviru atributa error.

Bank Accounts↵

Sekcija sadrži istaknute funkcije za rad sa računima.

Objekat računa sadrži značajan broj atributa od kojih su izdvojeni sledeći:

Atribut	Značenje	Primer
organizationId	JBKJS organizacije kojoj je dodeljen račun	10523
organizationName	Naziv organizacije kojoj je dodeljen račun	MF-UPRAVA ZA TREZOR
organizationType	Tip KJS organizacije kojoj je dodeljen račun	1
bank	Banka računa	840
number	Partija računa	0000000001624
controlNumber	Kontrolni broj računa	09
ownerOrganizationId	JBKJS organizacije koja je nosilac računa	59027
ownerOrganizationType	Tip KJS organizacije koja je nosilac računa	6
ownerOrganizationName	Naziv organizacije koja je nosilac računa	FOND ZA RAZVOJ REPUBLIKE SRBIJE
requestStatus	Status zahteva za račun	2
name	Naziv računa	FOND ZA RAZVOJ REPUBLIKE SRBIJE
localName	Lokalno ime računa
activity	Aktivnost računa u platnom prometu	1
status	Status računa u platnom prometu	0
organizationalUnitNumber	Šifra OJ UT koja vodi račun	40200
treasury	Šifra trezora računa	601
permission	Dozvola računa	2
type	Tip računa	1
maxAmount	Maksimalni iznos naloga koji zadužuju račun	10000000

Koriste se sledeće enumeracije:

requestStatus
- 1 u toku odobrenje
- 2 odobren
- 3 otkazan
- 4 u toku otkaz
- 5 odbijen
type
- 1 organizacioni
- 2 sintetički
- 3 analitički
- 4 evidencioni
- 5 konsolidovani
permission
- 1 plaćanje
- 2 pregled
activity
- 1 aktivan
- 5 ugašen
status
- 0 ukljucen u PP
- 4 dozvoljena izdavanja
- 5 dozvoljena primanja
- 8 blokiran
- 9 iskljucen iz PP

`GET bank-accounts`↵

Paginator bankovnih računa.

Method

GET

Query parametri

PerPage: Broj računa po stranici

Page: Stranica

SortBy: Atribut po kome je niz sortiran

SortDesc: Način sortiranja: desc ili asc

Filter: Niz izraza kojim se sprovodi filtriranje računa oblika filter[<atribut>]=<vrednost>. Ukoliko atribut podržava raspon, ime uključuje sufikse -from za donju granicu vrednosti, odnosno -to za gornju.; Podržani su sledeći atributi: Number, Name, OrganizationId, OrganizationalUnitNumber, RequestStatus, RequestPermission, Type

Primer paginacije računa

Primer prikazuje listanje druge stranice računa sa 10 računa po stranici uz filter RequestStatus = 2 (Status zahteva je odobren):

$params = @{
    Method  = 'Get'
    Uri     = "https://epp-rest.trezor.gov.rs/api/bank-accounts/filter[RequestStatus]=2&perPage=10&page=2"
    Headers = @{ Authorization = "Bearer <token>" }
}
$result = Invoke-RestMethod @params

`GET bank-accounts/<BankAccountNumber>`↵

Detalji konkretnog računa sa partijom BankAccountNumber.

Method

GET

URL parametri

BankAccountNumber: Partija računa od 13 karaktera

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

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

Method

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.

Response

url: Link za download izvoda

expiredDate: Datum i vreme do koga link važi

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 skriptu 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

Payment Orders↵

Sekcija sadrži istaknute funkcije za rad sa nalozima za prenos.

Objekat računa sadrži značajan broj atributa od kojih su izdvojeni sledeći:

Atribut	Značenje	Primer
id	Id naloga	319877
paymentBasis	Svrha	Uplata poreza
paymentCode	Šifra plaćanja	221
amount	Iznos	17139.66
debtorBankAccountNumber	Partija računa zaduženja	0000001156804
debtorBankAccount	Račun zaduženja	840000000115680485
debtorBankAccountName	Naziv računa zaduženja	MF-UPRAVA ZA TREZOR-DEPOZITNI RACUN
debtorCodeModel	Model PBZ	97
debtorName	Naziv organizacije zaduženja	MF-UPRAVA ZA TREZOR
debtorAddress	Adresa organizacije zaduženja	POP LUKINA 7-9
debtorPlace	Mesto organizacije zaduženja	BEOGRAD
debtorCode	PBZ	86004934268220007912
creditorName	Naziv računa odobrenja	Slobodan Spasić
creditorAddress	Adresa računa odobrenja	Zetska 26/47, (Niš)
creditorBankAccount	Račun odobrenja	840000000115680485
creditorCodeModel	Model PBO
creditorCode	PBO	3965040
urgentPayment	Hitno plaćanje	False
expectedPaymentDate	Očekivani datum plaćanja	2022-12-01
externalId	Eksterni Id naloga
transactionReference	Referenca izvršenja naloga	EPP319877
transactionMessage	Greška izvršenja naloga	dupli ključ radne;fieldName;7
transactionId	ID izvršenja naloga u PP	609
transactionStartDate	Datum pokretanja transakcije u PP	2024-06-13T13:40:35
transactionEndDate	Datum kraja transakcije u PP	2024-06-13T13:40:36
createdDate	Datum kreiranja	13.6.2024T12:16:46
createdUserLogin	Korisnički nalog korisnika koji je kreirao nalog	spasic6
createdUserName	Ime i prezime korisnika koji je kreirao nalog	Слободан Спасић
modifiedDate	Datum poslednje modifikacije
modifiedUserLogin	Ime i prezime korisnika koji je modifikovao nalog
modifiedUserName	Korisnički nalog korisnika koji je modifikovao nalog
paymentDate	Datum slanja na plaćanje	2024-06-13T13:39:29
paymentUserLogin	Korisnički nalog korisnika koji je pokrenuo plaćanje	spasic6
paymentUserName	Ime i prezime korisnika koji je pokrenuo plaćanje	Слободан Спасић
userGroupId	Id korisničke grupe	183
userGroupName	Naziv korisničke grupe	Grupa za fakture
comment	Komentar
userTags	Korisnički tagovi	tag1
systemTags	Sistemski tagovi	п-798nj неизвршен

JSON šema

Za detalje o tipovima, dužini polja, obaveznim atributima itd. pogledajte JSON šemu.

Validacija grupe naloga za prenos se može sprovesti upotrebom opcije servisa Validacija.

`GET payment-orders`↵

Paginator naloga za prenos.

Method

GET

Query parametri

PerPage: Broj računa po stranici

Page: Stranica

SortBy: Atribut po kome je niz sortiran

SortDesc: Način sortiranja: desc ili asc

Filter: Niz izraza kojim se sprovodi filtriranje računa oblika filter[<atribut>]=<vrednost>. Ukoliko atribut podržava raspon, ime uključuje sufikse -from za donju granicu vrednosti, odnosno -to za gornju.; Podržani su sledeći atributi: DebtorBankAccount, PaymentCode, AmountFrom, AmountTo, CreditorName, CreditorBankAccount, CreditorCode, CreatedDateFrom, CreatedDateTo, PaymentDateFrom, PaymentDateTo, SystemTag, UserTag, IdFrom, IdTo,

`GET payment-orders/<id>`↵

Detalji konkretnog naloga za prenos sa identifikatorom <id>.

Method: GET

`POST payment-orders`↵

Kreiranje jednog ili više (do 5000) naloga za prenos. Funkcija kreira naloge za prenos koji nemaju greške, dok vraća greške za one koji ih imaju.

Method

POST

Body

Payment Orders Niz naloga za prenos.

Response

model/error: Niz objekata koji sadrže objekte model i error. Objekat model sadrži poslati nalog za prenos, dok error sadrži eventualnu grešku za predmetni nalog. Ukoliko je error objekat null, greška ne postoji i nalog je kreiran, inače nalog nije kreiran zbog navedenog razloga.

Primer kreiranja dva naloga za prenos

U ovom primeru prikazan je pokušaj kreiranja 2 naloga za prenos od kojih 1 ima grešku u atributu eksterni broj naloga (ExternalId) koji prevazilazi maksimalnu dužinu. Prvi nalog je kreiran dok je za drugi vraćen popunjen objekat error:

$jsonPaymentOrders = '
[
    {
        "PaymentBasis": "Testiranje automatizacije plaćanja 1",
        "PaymentCode": 270,
        "Amount": 3.21,
        "DebtorBankAccount": "840000000010284941",
        "DebtorCodeModel": 97,
        "DebtorCode": "28070794239110001820",
        "CreditorName": "Test Poverioc",
        "CreditorAddress": "Adresa poverioca 1",
        "CreditorBankAccount": "840000000023566472",
        "CreditorCodeModel": null,
        "CreditorCode": "220216",
        "UrgentPayment": false,
        "ExpectedPaymentDate": "2024-03-05T09:17:57",
        "UserGroupName": "",
        "UserTags": [
            "test",
            "testni-nalog1"
        ],
        "Comment": "Testno plaćanje putem Powershell skripte"
    },
    {
        "PaymentBasis": "Testiranje automatizacije plaćanja 2",
        "PaymentCode": 270,
        "Amount": 3.21,
        "DebtorBankAccount": "840000000010284941",
        "DebtorCodeModel": 97,
        "DebtorCode": "28070794239110001820",
        "CreditorName": "Test Poverioc",
        "CreditorAddress": "Adresa poverioca 1",
        "CreditorBankAccount": "840000000023566472",
        "CreditorCodeModel": null,
        "CreditorCode": "220216",
        "UrgentPayment": false,
        "ExpectedPaymentDate": "2024-03-05T09:17:57",
        "ExternalId": "invalid payment order id to demonstrate test error",
        "UserGroupName": "",
        "UserTags": [
            "test",
            "testni-nalog2"
        ],
        "Comment": "Testno plaćanje putem Powershell skripte"
    }
]'
$params = @{
    Method  = 'POST'
    Uri     = "https://epp-rest.trezor.gov.rs/api/payment-orders"
    Headers = @{ Authorization = "Bearer <token>" }
    Body    = $jsonPaymentOrders
}
$result = Invoke-RestMethod @params
$result | ConvertTo-Json
<#
[
    {
        "model": {
            "id": 0,
            "paymentBasis": "Testiranje automatizacije plaćanja 1",
            "paymentCode": 270,
            "amount": 3.21,
            ...
        },
        "error": null
    },
    {
        "model": {
            "id": 0,
            "paymentBasis": "Testiranje automatizacije plaćanja 2",
            "paymentCode": 270,
            "amount": 3.21,
            "externalId": "invalid payment order id to demonstrate test error",
            ...
        },
        "error": {
            "code": "ValidationError",
            "message": "InvalidExternalIdValidation.",
            "type": 1
        }
    }
]
#>

Detaljna PowerShell skripta

Korisnici mogu koristiti cross-platform skriptu invoke-payment-totp da bi testirali kreiranja i plaćanja naloga za prenos. Skripta se može koristiti kao detaljni primer upotrebe ili u okviru integracije.

`POST payments`↵

Pokretanje plaćanja za jedan ili više (do 5000) naloga za prenos.

Pozivom ove funkcije pokreće se brojač sekundi za unos OTP tokena. Dok ovaj brojač traje, poslati nalozi za prenos su zaključani za bilo kakve aktivnosti sem pregleda od strane drugih korisnika organizacije.

Method

POST

Body

PaymentOrderIds: Niz identifikatora naloga za prenos

TwoFactorAuthenticationChannel

Id kanala za 2FA autentifikaciju (default: podrazumevani kanal). Kanal koji se koristi mora biti uključen u profilu korisnika i podešen:

Postal - Email Server 1
Zimbra - Email Server 2
Nth - SMS (zahteva podešen broj telefona korisnika)
Authenticator - Autentifikator (zahteva inicijalizovan autentifikator)

Response

paymentOrders: Niz naloga za prenos čiji su identifikatori poslati

paymentIdTagName: Tag pokušaja plaćanja (pa- tag)

totalAmounts: Ukupni iznos poslatih naloga za prenos

totalCount: Ukupni broj poslatih naloga za prenos

`PUT payments`↵

Konfirmacija OTP tokena pokrenutog plaćanja.

Nakon što je OTP token uspešno potvrđen, nalozi za prenos su zaključani za dalje izmene.

Method

PUT

Body

PaymentIdTagName: Tag pokušaja plaćanja (pa- tag)

Token: OTP token za odabrani kanal

Response

paymentTagName: Tag uspešnog plaćanja (p- tag)

paymentIdTagName: Tag pokušaja plaćanja (pa- tag)

totalAmounts: Ukupni iznos poslatih naloga za prenos

totalCount: Ukupni broj poslatih naloga za prenos

Error Codes

InvalidToken: Token nije ispravan

UsedToken: Token je već korišćen (samo za autentifikator)

`POST payment-orders/validate`↵

Validacija jednog ili više (do 5000) naloga za prenos. Funkcija ne kreira naloge već ih isključivo validira i vraća eventualne greške.

Method

POST

Body

Payment Orders Niz naloga za prenos.

Response

model/error: Niz objekata koji sadrže objekte model i error. Objekat model sadrži poslati nalog za prenos, dok error sadrži eventualnu grešku za predmetni nalog.

✏️ Poslednja promena: 26.06.2024 10:37

📖 Datum izdanja: 18.11.2024 22:07

https://jwt.io ↩

Integracija sa ePP↵

Okruženja↵

Autentifikacija i autorizacija↵

login↵

login/refresh↵

API↵

Bank Accounts↵

GET bank-accounts↵

GET bank-accounts/<BankAccountNumber>↵

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

Payment Orders↵

GET payment-orders↵

GET payment-orders/<id>↵

POST payment-orders↵

POST payments↵

PUT payments↵

POST payment-orders/validate↵

`login`↵

`login/refresh`↵

`GET bank-accounts`↵

`GET bank-accounts/<BankAccountNumber>`↵

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

`GET payment-orders`↵

`GET payment-orders/<id>`↵

`POST payment-orders`↵

`POST payments`↵

`PUT payments`↵

`POST payment-orders/validate`↵