IE RAČUNI API v4
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). |
|
|
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
PARAMETAR | POZICIJA | OPIS |
---|---|---|
type | BODY | DOCUMENT_TYPE |
file | BODY | Base64 string XML dokumenta |
{
"type": "INVOICE",
"file": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM..."
}
{
"importId": int,
"message": "string"
}
{
"message": "string"
}
5.2. Pregled statusa importa
PARAMETAR | DATA TIP | POZICIJA | OPIS |
---|---|---|---|
id | int | PATH | ID importa u sustavu |
{
"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
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-10-04T09:28:59) |
importDateTo | ISO 8601 date time | QUERY STRING | do datuma importa, uključivo taj datum i vrijeme (npr: 2024-10-04T09:28:59) |
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 |
{
"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
PARAMETAR | DATA TIP | POZICIJA | OPIS |
---|---|---|---|
id | int | PATH | ID dokumenta u sustavu |
{
"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
PARAMETAR | DATA TIP | POZICIJA | OPIS |
---|---|---|---|
id | int | PATH | ID dokumenta u sustavu |
{
"name": "string",
"xml": "string (base64 xml)"
}
6.4. Promjena statusa ulaznog računa
Status je moguće mijenjati samo za ulazne račune korisnika.
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 |
{
"status": "RECEIVED",
"note": null,
"partialAmount": 0
}
{
"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
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-10-04T09:28:59) |
importDateTo | ISO 8601 date time | QUERY STRING | do datuma importa, uključivo taj datum i vrijeme (npr: 2024-10-04T09:28:59) |
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 |
{
"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
PARAMETAR | DATA TIP | POZICIJA | OPIS |
---|---|---|---|
id | int | PATH | ID dokumenta u sustavu |
{
"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
PARAMETAR | DATA TIP | POZICIJA | OPIS |
---|---|---|---|
id | int | PATH | ID dokumenta u sustavu |
{
"name": "string",
"xml": "string (base64 xml)"
}
7.4. Promjena statusa ulaznog kreditnog odobrenja
Status je moguće mijenjati samo za ulazna kreditna odobrenja korisnika.
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 |
{
"status": "RECEIVED",
"note": null
}
{
"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
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-10-04T09:28:59) |
importDateTo | ISO 8601 date time | QUERY STRING | do datuma importa, uključivo taj datum i vrijeme (npr: 2024-10-04T09:28:59) |
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 |
{
"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
PARAMETAR | DATA TIP | POZICIJA | OPIS |
---|---|---|---|
id | int | PATH | ID dokumenta u sustavu |
{
"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
PARAMETAR | DATA TIP | POZICIJA | OPIS |
---|---|---|---|
id | int | PATH | ID dokumenta u sustavu |
{
"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();
}
}
}