Integracija↵
Integracija funkcionalnost CRF servisa u druge informacione sisteme postiže se upotrebom CRF REST servisa (RCRF).
Napomena
Ciljna grupa za informacije iz ovog dokumenta su IT profesionalci. Informacije nisu od značaja za ostale učesnike sistema.
Napomena
U svrhu implementacije i lakšeg testiranja eksternih integrativnih servisa, podignuto je i stavljeno u funkciju javno testno okruženje CRF REST servisa, dostupno na adresi
https://crfrtest.trezor.gov.rs
. Servisi javnog testnog okruženja su funkcionalno identični produkcionim servisima (što ne uljučuje korisničke podatke) i potrebno ih je
koristiti u ranim fazama integracije, obzirom da je masovan unos testnih podataka na produkcione servise zabranjen.
JSON Standardizacija↵
Napomena
Nakon nadogradnje servisa za 2020, prestala je podrška za stari tip serijalizacije JSON objekata.
Podrška za implicitnu konverziju tekstualnih tipova u okviru JSON objekta više nije omogućena. Stoga je neohpodno doslovce pratiti specifikaciju o integraciji kada se radi o tipovima podataka prosleđenim servisu.
Primer nevalidnog zahteva
$invoices = @( @{ DebtorCompanyNumber = '10523' InvoiceNumber = 'Racun 18/01' Amount = '1001' IssueDate = '2018-02-28' Comments = 'Komentar 1' } @{ DebtorCompanyNumber = '10523' InvoiceNumber = 'Racun 18/02' Amount = '1002.33' IssueDate = '2018-02-28' Comments = 'Komentar 2' Lifetime = '88' } ) | ConvertTo-Json irm "https://rcrf.trezor.gov.rs/api/invoice/register" @params -Body $invoices
Stara instanca JSON serijalizacije je u ovom slučaju propuštala zahtev, obzirom da je implicitna konverzija tekstualnih tipova prevodila vrednosti Amount
i Lifetime
iz
string
tipa u očekivane decimal
, odnosno integer
vrednosti. Aktuelna verzija servisa u ovom zahtevu eksplicitno očekuje tipove decimal
i integer
i vratiće odgovarajuću grešku o
serijalizaciji, ukoliko taj kriterijum nije ispunjen.
Primer validnog zahteva
$invoices = @( @{ DebtorCompanyNumber = '10523' InvoiceNumber = 'Racun 18/01' Amount = 1001 IssueDate = '2018-02-28' Comments = 'Komentar 1' } @{ DebtorCompanyNumber = '10523' InvoiceNumber = 'Racun 18/02' Amount = 1002.33 IssueDate = '2018-02-28' Comments = 'Komentar 2' Lifetime = 88 } ) | ConvertTo-Json irm "https://rcrf.trezor.gov.rs/api/invoice/register" @params -Body $invoices
Pristup↵
API funkcijama se pristupa preko adrese https://rcrf.trezor.gov.rs
. Svaki poziv ima prefiks api
i opciono verziju u putanji vX.Y
:
/api/invoice/register
Poziva poslednju verziju funkcije./api/v1.1/invoice/register
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.
Primer validnog zahteva:
curl "https://rcrf.trezor.gov.rs/api/login/ping" # CLI
Invoke-RestMethod "https://rcrf.trezor.gov.rs/api/login/ping" # Powershell
PowerShell napomena
U Microsoft PowerShell (do verzije 5), curl
je alijas na Invoke-WebRequest
koji nema iste parametre kao i curl.exe
, native CLI aplikacija.
U ovom kontekstu potrebno je dodati ekstenziju prilikom poziva - curl.exe
.
API koristi JSON format za razmenu podatka i osim ako je drugačije napomenuto, ContentType za svaki request je application/json
. Većina funkcija vraća rezultat kao atribute payload
objekta.
Upozorenje
Postoji maksimalna frekvencija upotrebe svake konkretne funkcije RCRF servisa (eng: Rate Limiter).
Na primer, neke funkcije je moguće koristiti maksimalno jednom u sekundi.
Navedeni primeri korišćenja zahtevaju minimalno PowerShell 3+ (provera lokalne verzije: $host.Version.Major -gt 3
) koji dolazi preinstaliran na Windows 10 operativnom sistemu a može se instalirati i na Unix-like sistemima.
Autentikacija i autorizacija↵
Pristup sistemu zahteva autentikaciju. Pristup funkcionalnostima zahteva odgovarajuća aplikativna prava (autorizaciju).
RCRF koristi JWT1 standard za autentikaciju i autorizaciju. Pristup se ostvaruje preuzimanjem access tokena pozivom /api/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 autentikacije ili autorizacije su:
Code | Message | Opis |
---|---|---|
401 |
Unauthenticated |
Korisnik nije autentikovan |
403 |
Unauthorized |
Korisnik nema odgovarajuće ovlašćenje za korišćenje funkcionalnosti |
/api/login↵
Preuzimanje pristupnog token koristeći korisnički nalog i lozinku.
- Metod
POST
- Atributi
-
login [string]
- Korisnički nalog
password [string]
- Korisnička lozinka
- Rezultat
{creationTime, accessToken, refreshToken}
Primer poziva u PowerShell-u
$params = @{ Method = 'Post' Uri = "https://rcrf.trezor.gov.rs/api/login" ContentType = 'application/json' Body = @{ login = 'foo'; password = 'bar' } | ConvertTo-Json } Invoke-RestMethod @params
{ "creationTime": "2018-02-23T21:00:30.5262037+01:00", "accessToken": "eyJ1ba1A3jdeC0....", "refreshToken": "eyJ1bmlxdWVfbm...." }
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 |
API↵
Verzija: 1.1
Funcija | Opis |
---|---|
invoice/<idf> | Detalji konkretne fakture |
invoice/paged-liabilities | Grupni pregled faktura |
invoice/register | Registrovanje jedne ili više faktura |
invoice/assign | Kreiranje asigancije |
invoice/cancel | Otkazivanje jedne ili više faktura |
invoice/cancel-assign | Otkazivanje asignacije |
invoice/change-amount | Izmena iznosa |
invoice/revert-amount | Otkaz izmene iznosa |
invoice/validate | Testiranje izmirenja fakture |
/api/invoice/<idf>↵
Detalji konkretne fakture.
- Metod
GET
- Rezultat
-
invoice [object]
- JSON objekat koji sadrži sve detalje fakture
Primer poziva u PowerShell-u
irm "https://rcrf.trezor.gov.rs/api/invoice/285F" -Headers @{Authorization = "Bearer $accessToken"}
{ "status": { "message": "Success", "code": 0 }, "liability": { "id": 2309, "createdId": 2550, "invoiceId": "285F", "creditorId": 1618, "creditorName": "Specijalna bolnica za ...", "creditorCompanyNumber": "17512579", "creditorTaxIdNumber": "103079070", "debtorName": "MF-UPRAVA ZA TREZOR", "debtorCompanyNumber": "10523", "invoiceNumber": "Racun 18/02", "issueDate": "2018-02-23T12:48:00", "creationDate": "2018-02-23T12:48:56.5633333", "importDate": "2018-02-26T12:48:56.5633333", "dueDate": "2018-04-27T12:48:56.5633333", "amount": 1000.00, "settledAmount": 0.00, "status": 1, "settled": false, ... }
Statusi fakture
Vrednost | Status | Opis |
---|---|---|
1 | Aktivna | Aktivna registrovana faktura |
2 | Nevalidna | Faktura je odbijena od strane dužnika - dostupno samo za eFakture |
3 | Otkazana | Fakturu je otkazao poverilac |
4 | Delimično izmirena | Faktura je delimično izmirena u parcijalnom iznosu |
5 | Izmirena | Faktura je izmirena |
6 | Asignirana | Dužnik je asignirao fakturu drugom dužniku |
7 | Profaktura | Profaktura |
/api/invoice/paged-liabilities↵
Grupni pregled faktura sa paginacijom, filtriranjem i sortiranjem. Zahtev implementira standardizovan query
parametarski model pretrage. Odgovor je niz invoice
objekata.
- Metod
Get
- Parametri
-
debtorCompanyNumber [string]
- JBKJS dužnika
creditorName [string]
- Naziv poverioca
debtorName [string]
- Naziv dužnika
side [string]
- Pretraga dužnika/poverilaca, vrednosti
debtor
,creditor
formattedInvoiceNumber [string]
- Broj fakture
amount [decimal]
- Iznos
settledAmount [decimal]
- Izmireni iznos
status [int]
- Status fakture
creationDate [string]
- Datum kreiranja,
YYYY-MM-DD
format dueDate [string]
- Zakonski rok izmirenja,
YYYY-MM-DD
format currentPageSize [int]
- Broj faktura po paginaciji
currentPage [int]
- Strana paginacije
Napomena
Obavezno je navesti parametar side
, kako bi se utvrdila strana pretrage. Za datumske i parametre sa iznosima, neophodno je dodati sufiks -from
ili -to
‚ kako bi se označio početak odnosno kraj opsega, npr. settledAmount-from
.
- Rezultat
-
invoice [object]
- Niz JSON objekata sa informacijama o fakturi.
Primer poziva u PowerShell-u
$Page = 1 $PerPage = 5 $Side = 'debtor' $QueryParams = @{ debtorCompanyNumber = '10523' "amount-From" = 10 "amount-To" = 1000 } $query = $QueryParams.GetEnumerator() | % { 'filter[{0}]={1}' -f $_.Key, $_.Value } $params = @{ Uri = "https://rcrf.trezor.gov.rs/api/invoice/paged-liabilities?$($query -join '&')&page=$Page&perPage=$PerPage&side=$Side" Headers = @{Authorization = "Bearer $accessToken"} } Invoke-RestMethod @params
Primer sirovog query upita
invoice/paged-liabilities?filter%5Bside%5D=creditor&filter%5BdebtorCompanyNumber%5D=10523&perPage=5&side=creditor
Ograničenja
Ograničenje | Vrednost | Komentar |
---|---|---|
currentPageSize | 50 | Maksimalni broj faktura po upitu |
/api/invoice/register↵
Registrovanje jedne ili više faktura. Telo zahteva je niz invoice
objekata.
- Metod
Post
- Atributi fakture
-
DebtorCompanyNumber [string]
- JBKJS dužnika
InvoiceNumber [string]
- Broj fakture
Amount [decimal]
- Iznos
IssueDate [string]
- Datum izdavanja,
YYYY-MM-DD
format Comments [string]
- Komentar (opciono)
Lifetime [integer]
- Rok važenja profakture (opciono - ako postoji objekat se tretira kao profaktura)
- Rezultat
-
- v1.0 -
IDFList [string[]]
- Niz IDF brojeva u istom redosledu kao i ulazne fakture
- v1.0 -
-
- v1.1 -
Result [object[]]
- Niz JSON objekata od kojih svaki sadrži 2 JSON objekta -
liability
iliabilityError
pri čemu je druginull
ukoliko faktura nema grešaka.
- v1.1 -
Primer poziva u PowerShell-u
Prikazuje registrovanje jedne fakture i jedne profakture.
$invoices = @( @{ DebtorCompanyNumber = '10523' InvoiceNumber = 'Racun 18/01' Amount = 1001 IssueDate = '2018-02-28' Comments = 'Komentar 1' } @{ DebtorCompanyNumber = '10523' InvoiceNumber = 'Racun 18/02' Amount = 1002.33 IssueDate = '2018-02-28' Comments = 'Komentar 2' Lifetime = 88 } ) | ConvertTo-Json irm "https://rcrf.trezor.gov.rs/api/invoice/register" @params -Body $invoices
Ograničenja
Ograničenje | Vrednost | Komentar |
---|---|---|
Request limit per second | 1 | |
Invoice limit per request | 1000 | |
Invoice limit per month | 30.000 | podrazumevani, veći se može dobiti po zahtevu UT |
/api/invoice/assign↵
Kreiranje asignacije.
- Metod
Post
- Atributi
-
InvoiceID [string]
- IDF fakture
AssignmentContractNumber [string]
- JBKJS asignatora
DebtorCompanyNumber [string]
- JBKJS asignanta (novog dužnika)
/api/invoice/cancel↵
Otkazivanje jedne ili više faktura. Telo zahteva je niz objekata otkaza.
- Metod
Post
- Atributi otkaza
-
invoiceId [string]
- IDF fakture koju treba otkazati
cancelComments [string]
- Komentar otkaza
/api/invoice/cancel-assign↵
Otkazivanje asignacije.
- Metod
Post
- Atributi
-
invoiceId [string]
- IDF asignirane fakture za koju treba otkazati asignaciju
/api/invoice/change-amount↵
Izmena iznosa konkretne fakture
- Metod
Post
- Atributi
-
invoiceId [string]
- IDF fakture
amount [decimal]
- Iznos izmene
comments [string]
- Komentar
- Rezultat
-
id [integer]
- Identifikator izmene iznosa
/api/invoice/revert-amount↵
Otkaz izmene iznosa konkretne fakture
- Metod
Post
- Atributi
-
id [integer]
- Identifikator izmene iznosa
cancelComments [string]
- Komentar
/api/invoice/validate↵
Testiranje izmirenja jedne ili više faktura koristeći elemente naloga za prenos. Telo zahteva je niz settlement
objekata.
Izmirenje se ne smatra validnim ako bilo šta od navedenih stavki nije zadovoljeno:
- nije moguće identifikovati fakturu koja se odnosi na datog poverioca (MB,PIB) i dužnika (JBKJS) sa datim pozivom na broj odobrenja (PBO) (set ovih atributa jednoznačno određuje fakturu i može se koristiti umesto IDF-a); KJS se može identifikovati upotrebom MB/PIB kombinacije ako je jedinstvena odnosno JBKJS/PIB kombinacijom. Ukoliko prosleđeni MB/PIB odgovara više KJS
- atribut
settledAmount
(sr: Izmireni iznos) premašuje preostali iznos na fakturi - faktura je već zatvorena (izmirena ili otkazana)
Ukoliko je testiranje izmirenja uspešno, korisnik među podacima dobija IDF odgovarajuće fakture.
Atributi identifikacije poverioca - PIB i MB - moraju da budu asocirani sa računom odobrenja u RIR NBS. Funkcija ne radi ovu kontrolu i odgovornost korisnika je da ovo proveri - ukoliko se prilikom obrade naloga u platnom prometu UT ispostavi da nije tako, nalog će biti odbijen.
- Metod
Post
- Atributi izmirenja
-
debtorCompanyNumber [string]
- Identifikator dužnika - JBKJS
creditorCompanyNumber [string]
- Identifikator poverioca - MB ili JBKJS
creditorTaxIdNumber [string]
- Poreski identifikator poverioca - PIB
invoiceNumber [string]
- Broj fakture, ne mora biti prečišćen od simbola već kao na nalogu za prenos u polju PBO
settledAmount [decimal]
- Iznos izmirenja koji se testira
bank [string]
- Broj banke, trenutno jedino
840
- Rezultat
-
Result [object]
- Rezultat sadrži 2 objekta,
settlement
isettlementError
. Validacija je uspešna akosettlementError == null
, inače objekatsettlement
sadrži IDF (invoiceId
)
Ograničenja:
Ograničenje | Vrednost |
---|---|
Request limit per second | 10 |
Invoice limit per request | 1000 |