Integracija↵

Integracija funkcionalnost CRF servisa u druge informacione sisteme postiže se upotrebom CRF REST servisa (RCRF).

JSON Standardizacija↵

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

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.

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 JWT¹ 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:

/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}

$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

API↵

Verzija: 1.1

/api/invoice/<idf>↵

Detalji konkretne fakture.

Metod

GET

Rezultat

invoice [object]

JSON objekat koji sadrži sve detalje fakture

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

/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

Rezultat

invoice [object]

Niz JSON objekata sa informacijama o fakturi.

$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

invoice/paged-liabilities?filter%5Bside%5D=creditor&filter%5BdebtorCompanyNumber%5D=10523&perPage=5&side=creditor

Ograničenja

/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.1 - Result [object[]]

Niz JSON objekata od kojih svaki sadrži 2 JSON objekta - liability i liabilityError pri čemu je drugi null ukoliko faktura nema grešaka.

$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

/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:

1. 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
2. atribut settledAmount (sr: Izmireni iznos) premašuje preostali iznos na fakturi
3. 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 i settlementError. Validacija je uspešna ako settlementError == null, inače objekat settlement sadrži IDF (invoiceId)

Ograničenja: