1. Registracija

Prije slanja zahtjeva potrebno se registrirati u sustav.

TEST http://portal.test.ie-racuni.com/register PRODUKCIJA https://portal.ie-racuni.com/register

2. Adresa

U svim API zahtjevima, bazični dio URL-a je, ovisno o okruženju:

TEST http://api.test.ie-racuni.com/v4 PRODUKCIJA https://api.ie-racuni.com/v4

3. Zahtjev (REQUEST)

Svi zahtjevi u zaglavlju moraju imati:

ZAGLAVLJE (HEADER) VRIJEDNOST/PRIMJER OPIS
Content-Type application/json -
Authorization Basic dXNlcm5hbWU6cGFzc3dvcmQ=* https://en.wikipedia.org/wiki/Basic_access_authentication
OIB 78158722615* OIB korisnika u čije ime se šalju e-dokumenti putem API klijenta.
Token 191dc405-a779-4535-99df-94aa763369a3* Token u GUID formatu kojeg korisnik sustava daje API klijentu kako bi on u njegovo ime slao e-dokumente.

*Navedene vrijednosti su priložene kao primjer.

Paramteri username i password koji su potrebni za autentikaciju API klijenta (Authorization HEADER), dodjeljuju se nakon registracije i slanja zahtjeva za izadavanjem istih.

4. Odgovor (RESPONSE)


HTTP STATUS CODE OPIS
200 OK Uspješan odgovor u JSON formatu.
400 BAD REQUEST Klijentska greška pri slanju zahtjeva. Odgovor u JSON formatu (primjer ispod).

{
    "message": "Poruka s opisom greške"
}

401 UNAUTHORIZED Greška u autentikaciji API klijenta ili API korisnika. Opis u BODY TXT formatu.
404 NOT FOUND Traženi resurs nije pronađen. Provjeriti ID resursa.
500 INTERNAL SERVER ERROR Iznimna i rijetka greška u obradi zahtjeva. Po pojavljivanju smo obavješteni o istoj i radimo na rješavanju problema.

5. Import

e-računi (i svi ostali dokumenti) se obrađuju asinkrono.

Kada pozivate import, zapravo kreirate zahtjev za slanje računa i ukoliko je sve ok (dobar xml, validacija, potpisivanje itd) dobivate poruku kako je uspješno kreiran zahtjev za obradu dokumenta ili grešku kako bi odmah znali da nešto nije u redu i da slanje i daljnja obrada nemaju smisla.

Dokumenti se svako nekoliko minuta obrađuju redom kako su ušli u sustav i šalju primateljima (koji mogu imati pretinac u našem sustavu ili šaljemo prema drugim informacijskim posrendicima s kojima smo povezani).

Ukoliko je sve u redu, primatelj će biti obaviješten putem maila (ukoliko ima pretinac kod nas), a ukoliko je došlo do greške kod slanja putem maila biti će obaviješten pošiljatelj (korisnik, ne API klijent).

Dva računa s istim brojem u istoj godini nije moguće poslati i sustav će javiti grešku.

5.1. Slanje dokumenta

POST /import
PARAMETAR POZICIJA OPIS
type BODY DOCUMENT_TYPE
file BODY Base64 string XML dokumenta
PRIMJER ZAHTJEVA

{
    "type": "INVOICE",
    "file": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM..."
}

PRIMJER 200 OK

{
    "importId": int,
    "message": "string"
}

PRIMJER 400 BAD REQUEST

{
    "message": "string"
}


5.2. Pregled statusa importa

GET /import/{id}
PARAMETAR DATA TIP POZICIJA OPIS
id int PATH ID importa u sustavu
PRIMJER 200 OK
    
{
    "importId": 123,
    "documentType": "INVOICE",
    "created": "2021-07-22T17:18:39.4912151",
    "completed": true,
    "message": "Uspješno procesiran import.",
    "document": {
        "id": 456,
        "noAccountForReceiver": false,
        "statuses": [
            {
                "status": "DELIVERED",
                "timestamp": "2021-07-22T18:44:23.257541",
                "note": null
            }
        ]
    }
}
    

Polje completed je false sve dok je dokument u obradi. Nakod što obrada završi polje message biti će popunjeno, a ukoliko je slanje uspješno bit će popunjeno i polje document sa pripadajućim statusima dokumenta.

Pozivanje statusa impota (5.2) ne mijenja stanje u sustavu, već samo daje informaciju u kojem je statusu obrada.

Ukoliko je javljena greška, nakon što se otklone uzroci iste (bilo na strani IE Računa, treće strane ili korisnika) potrebno je ponovno pozvati metodu 5.1 i ponovno poslati račun.

Dokumenti kod kojih je prisutna greška u obradi ne obrađuju (šalju) se ponovno automatski od strane servisa IE Računi.

6. Računi UBL Invoice 2.1

https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd

6.1 Pregled svih računa

GET /invoices/{direction}
PARAMETAR DATA TIP POZICIJA OPIS
direction string PATH DOCUMENT_DIRECTION
branch string QUERY STRING Identifikator podružnice
page int QUERY STRING broj stranice
importDateFrom ISO 8601 date time QUERY STRING od datuma importa, uključivo taj datum i vrijeme (npr: 2024-12-08T12:13:16)
importDateTo ISO 8601 date time QUERY STRING do datuma importa, uključivo taj datum i vrijeme (npr: 2024-12-08T12:13:16)
issueDateFrom ISO 8601 date QUERY STRING od datuma izdavanja, uključivo taj datum
issueDateTo ISO 8601 date QUERY STRING do datuma izdavanja, uključivo taj datum
PRIMJER 200 OK

{
    "records": [
        {
            "id": 1,
            "name": "RACUN-001",
            "buyer": "AB d.o.o.",
            "supplier": "CD d.o.o.",
            "importDate": "2019-08-01T00:00:00",
            "issueDate": "2019-08-10T00:00:00",
            "dueDate": "2019-08-10T00:00:00",
            "payableAmount": 181.72,
            "currency": "EUR",
            "lastStatus": "DELIVERED"
        }
    ],
    "recordsFrom": 1,
    "recordsTo": 1,
    "recordsTotal": 1,
    "currentPage": 1,
    "maxPages": 1
}

6.2. Pregled pojedinačnog računa

GET /invoices/{id}
PARAMETAR DATA TIP POZICIJA OPIS
id int PATH ID dokumenta u sustavu
PRIMJER 200 OK

{
    "id": 1,
    "name": "NAZIV RAČUNA",
    "buyer": "DRUŠTVO d.o.o.",
    "supplier": "IE RAČUNI d.o.o.",
    "importDate": "2019-08-01T00:00:00",
    "issueDate": "2019-08-10T00:00:00",
    "dueDate": "2019-08-10T00:00:00",
    "payableAmount": 100.00,
    "currency": "EUR",
    "externalID": null,
    "lastStatus": "string",
    "statuses": [
        {
            "status": "DELIVERED",
            "timestamp": "2019-10-06T15:51:46.4134707",
            "note": null
        }
    ],
    "noAccountForReceiver": "bool"
}

6.3. Preuzimanje (download) računa

GET /invoices/{id}/download
PARAMETAR DATA TIP POZICIJA OPIS
id int PATH ID dokumenta u sustavu
PRIMJER 200 OK
    
{
    "name": "string",
    "xml": "string (base64 xml)"
}
    

6.4. Promjena statusa ulaznog računa

Status je moguće mijenjati samo za ulazne račune korisnika.

POST /invoices/{id}/status
PARAMETAR DATA TIP POZICIJA OPIS
id int PATH ID dokumenta u sustavu
status string BODY INVOICE_STATUS
note string BODY razlog stavljanja u status, samo za INVOICE_STATUS:REJECTED
partialAmount decimal BODY iznos djelomično plaćenog računa, samo za status INVOICE_STATUS:PAYMENTPARTIALLYFULFILLED
PRIMJER ZAHTJEVA

{
    "status": "RECEIVED",
    "note": null,
    "partialAmount": 0
}

PRIMJER 200 OK

{
    "status": "string"
}

7. Kreditna odobrenja UBL CreditNote 2.1

https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-CreditNote-2.1.xsd

7.1 Pregled svih (ulaznih/izlaznih) kreditinih odobrenja

GET /credit-notes/{direction}
PARAMETAR DATA TIP POZICIJA OPIS
direction string PATH DOCUMENT_DIRECTION
page int QUERY STRING broj stranice
importDateFrom ISO 8601 date time QUERY STRING od datuma importa, uključivo taj datum i vrijeme (npr: 2024-12-08T12:13:16)
importDateTo ISO 8601 date time QUERY STRING do datuma importa, uključivo taj datum i vrijeme (npr: 2024-12-08T12:13:16)
issueDateFrom ISO 8601 date QUERY STRING od datuma izdavanja, uključivo taj datum
issueDateTo ISO 8601 date QUERY STRING do datuma izdavanja, uključivo taj datum
PRIMJER 200 OK

{
    "records": [
        {
            "id": 1,
            "name": "ODOBRENJE-001",
            "buyer": "AB d.o.o.",
            "supplier": "CD d.o.o.",
            "importDate": "2019-08-01T00:00:00",
            "issueDate": "2019-08-10T00:00:00",
            "payableAmount": -181.72,
            "currency": "EUR",
            "lastStatus": "DELIVERED"
        }
    ],
    "recordsFrom": 1,
    "recordsTo": 1,
    "recordsTotal": 1,
    "currentPage": 1,
    "maxPages": 1
}

7.2. Pregled pojedinačnog kreditnog odobrenja

GET /credit-notes/{id}
PARAMETAR DATA TIP POZICIJA OPIS
id int PATH ID dokumenta u sustavu
PRIMJER 200 OK

{
    "id": 1,
    "name": "NAZIV KREDITNOG ODOBRENJA",
    "buyer": "DRUŠTVO d.o.o.",
    "supplier": "IE RAČUNI d.o.o.",
    "importDate": "2019-08-01T00:00:00",
    "issueDate": "2019-08-10T00:00:00",
    "payableAmount": -100.00,
    "currency": "EUR",
    "externalID": null,
    "lastStatus": "string",
    "statuses": [
        {
            "status": "DELIVERED",
            "timestamp": "2019-10-06T15:51:46.4134707",
            "note": null
        }
    ],
    "noAccountForReceiver": "bool"
}

7.3. Preuzimanje (download) kreditnog odobrenja

GET /credit-notes/{id}/download
PARAMETAR DATA TIP POZICIJA OPIS
id int PATH ID dokumenta u sustavu
PRIMJER 200 OK
    
{
    "name": "string",
    "xml": "string (base64 xml)"
}
    

7.4. Promjena statusa ulaznog kreditnog odobrenja

Status je moguće mijenjati samo za ulazna kreditna odobrenja korisnika.

POST /credit-notes/{id}/status
PARAMETAR DATA TIP POZICIJA OPIS
id int PATH ID dokumenta u sustavu
status string BODY CREDIT_NOTE_STATUS
note string BODY razlog stavljanja u status, samo za CREDIT_NOTE_STATUS:REJECTED
PRIMJER ZAHTJEVA

{
    "status": "RECEIVED",
    "note": null
}

PRIMJER 200 OK

{
    "status": "string"
}

8. Narudžbe UBL Order 2.1

https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-CreditNote-2.1.xsd

8.1. Pregled svih (ulaznih/izlaznih) narudžbi

GET /orders/{direction}
PARAMETAR DATA TIP POZICIJA OPIS
direction string PATH DOCUMENT_DIRECTION
page int QUERY STRING broj stranice
importDateFrom ISO 8601 date time QUERY STRING od datuma importa, uključivo taj datum i vrijeme (npr: 2024-12-08T12:13:16)
importDateTo ISO 8601 date time QUERY STRING do datuma importa, uključivo taj datum i vrijeme (npr: 2024-12-08T12:13:16)
issueDateFrom ISO 8601 date QUERY STRING od datuma izdavanja, uključivo taj datum
issueDateTo ISO 8601 date QUERY STRING do datuma izdavanja, uključivo taj datum
PRIMJER 200 OK

{
    "records": [
        {
            "id": 123,
            "name": "NAZIV",
            "buyer": "DRUŠTVO d.o.o.",
            "supplier": "IE RAČUNI d.o.o.",
            "importDate": "2019-08-01T00:00:00",
            "issueDate": "2019-08-10T00:00:00",
            "currency": "EUR",
            "status": "DELIVERED",
            "deletedOn": "2019-08-02T00:00:00"(nullable)
        }
    ],
    "recordsFrom": 1,
    "recordsTo": 1,
    "recordsTotal": 1,
    "currentPage": 1,
    "maxPages": 1
}

8.2. Pregled pojedinačne narudžbe

GET /orders/{id}
PARAMETAR DATA TIP POZICIJA OPIS
id int PATH ID dokumenta u sustavu
PRIMJER 200 OK

{
    "id": 123,
    "name": "NAZIV",
    "buyer": "DRUŠTVO d.o.o.",
    "supplier": "IE RAČUNI d.o.o.",
    "importDate": "2019-08-01T00:00:00",
    "issueDate": "2019-08-10T00:00:00",
    "currency": "EUR",
    "physicalDeliveryTerms": "string",
    "physicalDeliveryRequestedPeriodFrom": "2019-08-01T00:00:00"(nullable),
    "physicalDeliveryRequestedPeriodTo": "2019-08-01T00:00:00"(nullable),
    "status": "DELIVERED",
    "statuses": [
        {
            "status": "DELIVERED",
            "timestamp": "2019-08-01T15:51:46.4134707",
            "note": null
        }
    ],
    "deletedOn": "2019-08-02T00:00:00"(nullable)
}

8.3. Preuzimanje (download) narudžbe

GET /orders/{id}/download
PARAMETAR DATA TIP POZICIJA OPIS
id int PATH ID dokumenta u sustavu
PRIMJER 200 OK
    
{
    "name": "string",
    "xml": "string (base64 xml)"
}
    

9. Šifrarnik

DOCUMENT_TYPE INVOICE, CREDITNOTE, ORDER
DOCUMENT_DIRECTION INCOMING, OUTGOING
INVOICE_STATUS DELIVERED, RECEIVED, ACCEPTED, REJECTED, PAYMENTPARTIALLYFULFILLED, PAYMENTFULFILLED
CREDIT_NOTE_STATUS DELIVERED, RECEIVED, ACCEPTED, REJECTED
ORDER_STATUS DELIVERED, RECEIVED

10. Popis testnih kompanija

Za promjene statusa poslanih B2B računa i slanje e-dokumenata prema Vašem pretincu, molimo Vas kontaktirajte nas na info@ie-racuni.com.

Slanje B2G računa FINANCIJSKA AGENCIJA (OIB: 85821130368)
Slanje B2B računa IE-RAČUNI (OIB: 78158722615)

11. API klijent

Primjeri klijenata za slanje dokumenata putem API-a ovisno o tehnologiji:

    
using System;
using System.IO;
using System.Net;
using System.Text;

namespace IERacuni.ApiClient
{
    enum DocumentType
    {
        INVOICE,
        CREDITNOTE,
        ORDER
    }

    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var endpoint = "http://api.test.ie-racuni.com/v3/import";

                var accountOIB = ""; // OIB korisnika za kojeg se šalju e-dokumenti
                var accountApiToken = ""; // API token korisnika za kojeg se šalju e-dokumenti

                var apiClientUsername = ""; // Username od API klijenta
                var apiClientPassword = ""; // Password od API klijenta
                    
                var testXmlFilePath = "putanja_do_xml_datoteke.xml";
                var testXmlFileContent = File.ReadAllText(testXmlFilePath);
                var testXmlFileContentBytes = Encoding.UTF8.GetBytes(testXmlFileContent);
                var testXmlFileContentAsBase64 = Convert.ToBase64String(testXmlFileContentBytes);

                var documentType = DocumentType.INVOICE; // promijeniti ovisno o tipu dokumenta koji se šalje

                var svcCredentialsBytes = Encoding.ASCII.GetBytes(apiClientUsername + ":" + apiClientPassword);
                var svcCredentials = Convert.ToBase64String(svcCredentialsBytes);

                var request = (HttpWebRequest)WebRequest.Create(endpoint);
                request.Method = "POST";
                request.ContentType = "application/json";
                request.Headers.Add("Authorization", "Basic " + svcCredentials);
                request.Headers.Add("OIB", accountOIB);
                request.Headers.Add("TOKEN", accountApiToken);

                var data = new
                {
                    type = documentType,
                    file = testXmlFileContentAsBase64
                };

                var json = Newtonsoft.Json.JsonConvert.SerializeObject(data);

                var byteData = Encoding.UTF8.GetBytes(json);

                var requestStream = request.GetRequestStream();
                requestStream.Write(byteData, 0, byteData.Length);

                var response = request.GetResponse();

                using (var reader = new StreamReader(response.GetResponseStream(), Encoding.UTF8))
                {
                    var responseText = reader.ReadToEnd();

                    dynamic jsonResult = Newtonsoft.Json.JsonConvert.DeserializeObject(responseText);

                    Console.WriteLine($"{responseText}");
                }
            }
            catch (WebException e)
            {
                using (var response = e.Response)
                {
                    if (response != null)
                    {
                        var httpResponse = (HttpWebResponse)response;
                        using (var data = response.GetResponseStream())
                        {
                            if (data != null)
                            {
                                using (var reader = new StreamReader(data))
                                {
                                    var text = reader.ReadToEnd();
                                    Console.WriteLine("Greška:" + text);
                                }
                            }
                        }
                    }
                    else
                    {
                        Console.WriteLine("Greška:" + e.Message);
                    }
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("Greška:" + ex.Message + ex.InnerException?.Message);
            }

            Console.ReadLine();
        }
    }
}
    
            
$endpoint = "http://api.test.ie-racuni.com/v3/import";
$accountOIB = ""; // OIB korisnika za kojeg se šalju e-dokumenti
$accountApiToken = ""; // API token korisnika za kojeg se šalju e-dokumenti
$apiClientUsername = ""; // Username od API klijenta
$apiClientPassword = ""; // Password od API klijenta
$testXmlFilePath = "invoice.xml";

$testXmlFileContent = file_get_contents($testXmlFilePath);
$testXmlFileContentAsBase64 = base64_encode($testXmlFileContent);
$documentType = 'INVOICE'; // promijeniti ovisno o tipu dokumenta koji se šalje
$svcCredentials = base64_encode($apiClientUsername . ":" . $apiClientPassword);
// use key 'http' even if you send the request to https://...

$data = array('type' => $documentType, 'file' => $testXmlFileContentAsBase64);

$options = array(
  'http' => array(
    'method'  => 'POST',
    'content' => json_encode( $data ),
    'header'=>  "Content-Type: application/json\r\n" .
    			"Accept: */*\r\n" .
                'Authorization: Basic '.$svcCredentials."\r\n".
                'OIB:'.$accountOIB."\r\n".
        		'TOKEN:'.$accountApiToken."\r\n"
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($endpoint, false, $context);
$response = json_decode( $result );
    

import java.nio.file.Paths;
import java.nio.file.Files;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.net.URL;
import java.net.HttpURLConnection;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.Reader;

public class Program {
    enum DocumentType {
        INVOICE,
        CREDITNOTE,
        ORDER
    }

    public static void main(String[] args) {
        try {
            String endpoint = "http://api.test.ie-racuni.com/v3/import";

            String accountOIB = ""; // OIB korisnika za kojeg se šalju e-dokumenti
            String accountApiToken = ""; // API token korisnika za kojeg se šalju e-dokumenti

            String apiClientUsername = ""; // Username od API klijenta
            String apiClientPassword = ""; // Password od API klijenta

            String testXmlFilePath = "putanja_do_xml_datoteke.xml";
            byte[] testXmlFileContentBytes = Files.readAllBytes(Paths.get(testXmlFilePath));
            String testXmlFileContentAsBase64 = Base64.getEncoder().encodeToString(testXmlFileContentBytes);

            DocumentType documentType = DocumentType.INVOICE; // promijeniti ovisno o tipu dokumenta koji se šalje

            String apiClinetCredentials = apiClientUsername + ":" + apiClientPassword;
            byte[] svcCredentialsBytes = apiClinetCredentials.getBytes(StandardCharsets.US_ASCII);
            String svcCredentials = Base64.getEncoder().encodeToString(svcCredentialsBytes);

            URL url = new URL(endpoint);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setRequestProperty("Authorization", "Basic " + svcCredentials);
            connection.setRequestProperty("OIB", accountOIB);
            connection.setRequestProperty("TOKEN", accountApiToken);

            String jsonParameters = "{\"type\": \"" + documentType + "\", \"file\": \"" + testXmlFileContentAsBase64 + "\"}";
            byte[] postDataBytes = jsonParameters.getBytes("UTF-8");

            connection.setDoOutput(true);
            connection.setRequestProperty("Content-Length", String.valueOf(postDataBytes.length));
            connection.getOutputStream().write(postDataBytes);

            Reader streamReader = null;
            if (connection.getResponseCode() < 400) {
                streamReader = new InputStreamReader(connection.getInputStream());
            } else {
                streamReader = new InputStreamReader(connection.getErrorStream());
            }

            BufferedReader in = new BufferedReader(streamReader);
            String inputLine;
            StringBuffer responseText = new StringBuffer();
            try {
                while ((inputLine = in.readLine()) != null) {
                    responseText.append(inputLine);
                }
            } finally {
                in.close();
            }

            connection.disconnect();

            System.out.println(responseText.toString());
        } catch (Exception e) {
            System.out.println("Greška: " + e.getMessage());
            e.printStackTrace();
        }
    }
}