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.
{
"success": true,
"data": { }
}
{
"success": false,
"message": "Poruka s opisom greške"
}
5. Slanje dokumenata
PARAMETAR | POZICIJA | OPIS |
---|---|---|
type | BODY | DOCUMENT_TYPE |
file | BODY | Base64 string XML dokumenta |
{
"type": "INVOICE",
"file": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM..."
}
{
"success": true,
"data": {
"success": true,
"importId": 1,
"message": "string",
"documentType": "string",
"documentId": 1,
"documentName": "string",
"noAccountForReceiver": false
}
}
{
"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
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) |
{
"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
PARAMETAR | POZICIJA | OPIS |
---|---|---|
id | PATH | ID dokumenta u sustavu (int) |
{
"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
PARAMETAR | POZICIJA | OPIS |
---|---|---|
id | PATH | ID dokumenta u sustavu (int) |
{
"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.
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) |
{
"status": "RECEIVED",
"note": null,
"partialAmount": 0
}
{
"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
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) |
{
"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
PARAMETAR | POZICIJA | OPIS |
---|---|---|
id | PATH | ID dokumenta u sustavu (int) |
{
"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
PARAMETAR | POZICIJA | OPIS |
---|---|---|
id | PATH | ID dokumenta u sustavu (int) |
{
"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.
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) |
{
"status": "RECEIVED",
"note": null
}
{
"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
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) |
{
"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
PARAMETAR | POZICIJA | OPIS |
---|---|---|
id | PATH | ID dokumenta u sustavu (int) |
{
"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
PARAMETAR | POZICIJA | OPIS |
---|---|---|
id | PATH | ID dokumenta u sustavu (int) |
{
"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();
}
}
}