IE RAČUNI API v3

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/v3 PRODUKCIJA https://api.ie-racuni.com/v3

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)

Svaki odgovor može se pojaviti u dva oblika: uspješan i neuspješan. Uspješan odgovor sadrži tražene podatke unutar polja data. Primjeri odgovora dani su za uspješne odgovore.

PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "data": { }
}

PRIMJER NEUSPJEŠNOG ODGOVORA 

{
    "success": false,
    "message": "Poruka s opisom greške"
}

5. Slanje dokumenata

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

{
    "type": "INVOICE",
    "file": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM..."
}
PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "data": {
        "success": true,
        "importId": 1,
        "message": "string",
        "documentType": "string",
        "documentId": 1,
        "documentName": "string",
        "noAccountForReceiver": false
    }
}
PRIMJER NEUSPJEŠNOG ODGOVORA 

{
    "success": true,
    "data": {
        "success": false,
        "importId": 1,
        "message": "string"
    }
}

Ukoliko primatelj dokumenta (računa, odobrenja...) nema korisnički pretinac, polje noAccountForReceiver biti će true.

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 POZICIJA OPIS
direction PATH DOCUMENT_DIRECTION
page QUERY STRING broj stranice (int)
issueDateFrom QUERY STRING od tog datuma izdavanja, uključivo taj datum (date)
issueDateTo QUERY STRING do tog datuma izdavanja, uključivo taj datum (date)
PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "data": {
        "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": "HRK",
                "lastStatus": "DELIVERED"
            }
        ],
        "recordsFrom": 1,
        "recordsTo": 1,
        "recordsTotal": 1,
        "currentPage": 1,
        "maxPages": 1
    }
}

6.2. Pregled pojedinačnog računa

GET /invoices/{id}
PARAMETAR POZICIJA OPIS
id PATH ID dokumenta u sustavu (int)
PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "data": {
        "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": "HRK",
        "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 POZICIJA OPIS
id PATH ID dokumenta u sustavu (int)
PRIMJER USPJEŠNOG ODGOVORA 
    
{
    "success": true,
    "data": {
        "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 POZICIJA OPIS
id PATH ID dokumenta u sustavu (int)
status BODY INVOICE_STATUS
note BODY razlog stavljanja u status, samo za INVOICE_STATUS:REJECTED (string)
partialAmount BODY iznos djelomično plaćenog računa, samo za status INVOICE_STATUS:PAYMENTPARTIALLYFULFILLED (decimal)
PRIMJER ZAHTJEVA 

{
    "status": "RECEIVED",
    "note": null,
    "partialAmount": 0
}
PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "message": "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 POZICIJA OPIS
direction PATH DOCUMENT_DIRECTION
page QUERY STRING broj stranice (int)
issueDateFrom QUERY STRING od tog datuma izdavanja, uključivo taj datum (date)
issueDateTo QUERY STRING do tog datuma izdavanja, uključivo taj datum (date)
PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "data": {
        "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": "HRK",
                "lastStatus": "DELIVERED"
            }
        ],
        "recordsFrom": 1,
        "recordsTo": 1,
        "recordsTotal": 1,
        "currentPage": 1,
        "maxPages": 1
    }
}

7.2. Pregled pojedinačnog kreditnog odobrenja

GET /credit-notes/{id}
PARAMETAR POZICIJA OPIS
id PATH ID dokumenta u sustavu (int)
PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "data": {
        "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": "HRK",
        "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 POZICIJA OPIS
id PATH ID dokumenta u sustavu (int)
PRIMJER USPJEŠNOG ODGOVORA 
    
{
    "success": true,
    "data": {
        "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 POZICIJA OPIS
id PATH ID dokumenta u sustavu (int)
status BODY CREDIT_NOTE_STATUS
note BODY razlog stavljanja u status, samo za CREDIT_NOTE_STATUS:REJECTED (string)
PRIMJER ZAHTJEVA 

{
    "status": "RECEIVED",
    "note": null
}
PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "message": "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 POZICIJA OPIS
direction PATH DOCUMENT_DIRECTION
page QUERY STRING broj stranice (int)
issueDateFrom QUERY STRING od tog datuma izdavanja, uključivo taj datum (date)
issueDateTo QUERY STRING do tog datuma izdavanja, uključivo taj datum (date)
PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "data": {
        "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": "HRK",
                "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 POZICIJA OPIS
id PATH ID dokumenta u sustavu (int)
PRIMJER USPJEŠNOG ODGOVORA 

{
    "success": true,
    "data":  {
        "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": "HRK",
        "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 POZICIJA OPIS
id PATH ID dokumenta u sustavu (int)
PRIMJER USPJEŠNOG ODGOVORA 
    
{
    "success": true,
    "data": {
        "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();
        }
    }
}
    

    
// USKORO
    

    
// USKORO