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.

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 (env: 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 tokena 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
Izlaz
{
    "creationTime":  "2018-02-23T21:00:30.5262037+01:00",
    "accessToken":   "eyJ1ba1A3jdeC0....",
    "refreshToken":  "eyJ1bmlxdWVfbm...."
}

Napomenе

  • Pristup korisniku se blokira na 1 minut ukoliko 3 puta uzastopno pošalje pogrešnu lozinku.
  • Pristupni token zastareva nakon 20 minuta.

API

Verzija: 1.1

Funcija Opis
invoice/<idf> Detalji konkretne fakture
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,
              ...
            }

/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 [string]
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.
Primer poziva u PowerShell-u

Prikuzuje 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

  • Rate limit: max 1 request/s.
  • Invoice limit: max 1000 invoices/request

/api/invoice/assign

Kreiranje asigancije.

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 [string]
Iznos izmene
comments [string]
Komentar
Rezultat
id [integer]
Identifikator izmene iznosa

/api/invoice/revert-amount

Otkaz izmene iznosa konkretne fakture

Metod
Post
Atributi
id [string]
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 [string]
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)