Slažem se

Hrvatskitelekom.hr poštuje vašu privatnost. Kolačiće (eng. 'cookies') koristimo u razne svrhe kao što su funkcionalnost web stranice, poboljšanje korisničkog doživljaja, osiguravanje integracije s društevnim mrežama i prikaz(ciljanih) reklamnih sadržaja. Nastavljajući svoju posjetu na našoj web stranici pristajete na to da koristite kolačiće.
Postavke kolačića možete promijeniti u bilo kojem trenutku.

E-Bill EDES REST sučelje


Sadržaj dokumenta

  1. Povijest promjena
  2. Uvod
    1. Korišteni dokumenti
    2. Podržane vrste dokumenata
  3. Slanje i primanje dokumenata
    1. Sigurnost
    2. Pristupne točke EDES platforme
    3. Vrste podataka pri pozivu REST servisa
    4. Ulazni dokumenti
    5. Izlazni dokumenti
  4. Dohvat povijesti promjena stanja firmi
  5. Dohvat podržanih dokumenata za pojedinu firmu
  6. Korištenje poslovnih jedinica
    1. Administracija poslovnih jedinica
    2. Adresiranje poslovnih jedinica firme
  7. FAQ
    1. Primanje ne podržanih dokumenata u inbox
    2. Vrijeme između provjera stanja inbox-a
    3. Asinkrona obrada ulaznih dokumenata
    4. Slanje grešaka od strane EDES platforme
    5. Slanje dokumenata s istim identifikatorom u pošiljateljevom sustavu
  8. Tipovi podataka
    1. DocumentInfo
    2. AttachmentInfo



Poglavlje 1. Povijest promjena

Verzija

Datum

Opis

1.0

20.06.2018

Inicijalna verzija.

1.1

31.07.2018

Dodana informacija o vrstama dokumenata; Dodani primjeri za opomenu i odobrenje; dodan FAQ.

1.2

10.12.2018

Dodano poglavlje "Dohvat povijesti promjena stanja firmi" i "Dohvat podržanih dokumenata za pojedinu firmu"

1.3

11.12.2018

Dokumentacija je ažurirana s EU normom EN16931

1.4

12.12.2018

Dodano poglavlje "Adresiranje poslovnih jedinica firme"

1.5

05.02.2019.

Poslovne jedinice grupirane po izlaznoj točki; Dodane šifre za različite tipove poslovnih jedinica; U dohvatu podržanih dokumenata dodana izlazna točka; Ispravljeni nazivi polja u dohvatu podržanih dokumenata

1.6

01.03.2019.

Ažurirano poglavlje adresiranje poslovnih jedinica firme. Ažurirana stanja u poglavlju promjena stanja dokumenta.

1.7

21.03.2019

Ažurirano poglavlje „Ažuriranje poslovnih jedinica firme“.



Poglavlje 2. Uvod

Svrha ovog dokumenta je definirati sučelje između Klijenta i E-Bill EDES platforme. Sučelje će se koristi za slanje ulaznih i izlaznih dokumenata od strane Klijenta prema partnerima i obrnuto.

Uz opis API-ja u ovome dokumentu postoji i Swagger definicija sučelja..

2.1. Korišteni dokumenti

• Swagger definicija namijenjena za alat na http://editor.swagger.io/ - link

2.2. Podržane vrste dokumenata

EDES platforma trenutno podržava dva formata za slanje i primanje računa, odobrenja i opomena:

  • HRInvoice - originalna specifikacija propisana od strane FINA-e,

  • EN16931 - specifikacija propisana od strane EU temeljena na ISO/IEC 19845 (UBL 2.1) standardu. Ova norma je ušla u upotrebu 01.12.2018.

2.2.1. HRInvoice

HRInvoice je specifikacija definirana od strane "Ministarstva gospodarstva, rada i poduzetništva Republike Hrvatske" 2009. godine.

Opis specifikacije možete pronaći u sljedećim privitcima:

Dokumenti (račun, odobrenje, opomena) se šalju kao XML dokumenti. XSD shema se nalazi u sljedećem privitku ubl-2_1-fina.zip.

Uz dokument korisnik može poslati jedan ili više privitaka. Preporuka jest da se uz račun ne šalju vizualizacije računa iz razloge što se ista može generirati na strani primatelja na temelju poslanog dokumenata. Privitak se mora poslati unutar omotača definiranog shemom maindoc/UBLAttachedDocument-2.1.xsd. Dodatno u AttachedDocument XML-u se mora popuniti polje DocumentType. Ovo polje je opcionalno po specifikaciji ali je obvezno prema FINA-inim preporukama.

Primjeri računa i privitaka su sljedeći:

◦ primjer slanja statusnog dokumenta od strane EDES platforme,

◦ primjer omotača privitka

◦ primjer poslanog računa

◦ primjer odobrenja od strane FINA-e

◦ primjer računa od strane FINA

◦ primjer vizualizacije od strane FINA

Kod slanja ove vrste dokumenta molimo koristiti sljedeće:

  • mainDocument[].documentType: INVOICE, CREDIT_NOTE ili REMINDER,

  • mainDocument[].documentFormat: UBL-2.1-HR,

  • attachmentss[].documentFormat: application/vnd.ubl-2-1.attached-document+xml,

  • attachments[].documentName: <ime datoteke>.xml.

Potpisivanje dokumenata/računa aplikacijskim certifikatom od FINA-e može se vršiti na dva načina:
1. Putem ERP-a u kojem se implementira software za potpisivanje
2. Putem HT EDI platforme na koju se učita certifikat (jednostavnija integracija)


HT EDI Platforma vrši potpisivanje dokumenata ukoliko je certifikat učitan na platformu pod "skladište ključeva" i na Korisničkom portalu je označena kvačica u postavkama na sljedećim poljima: 
- "Potpiši račune poslane u formatu UBL-2.1-EN16931"
- "Potpiši račune poslane u formatu UBL-2.1-HR"

Platforma također omogućava konverziju izlaznih dokumenata iz UBL-2.1-EN16931 u UBL-2.1-HR normu, a za aktivaciju te mogućnosti na Korisničkom portalu je potrebno staviti kvačicu u postavkama na "Konvertiraj račune iz formata UBL-2.1-EN16931 u UBL-2.1-HR".

Svi dokumenti moraju biti potpisani XML-DSig elektroničkim potpisom. Privitci mogu biti potpisani ukoliko to pošiljatelj želi. Za potpisivanje se mora koristiti aplikacijski certifikat za eračun izdan od strane FINA-e. Pravila potpisa je odredila FINA.

U privitku ubl-signature-examples.zipdodan je primjer generiranja potpisa u programskom jeziku Java. Projekt pokazuje koji elementi moraju biti prisutni kako bi potpis bio prihvaćen od strane FINA-e kao validan.

EDES sustav većinu operacija odrađuje asinkrono. Pri slanju dokumenata u EDES sustav sinkrono se odrađuju samo provjere validacije zahtjeva i sigurnosne provjere. Sve ostale provjere kao i slanje dokumenata prema primatelju odrađuje se asinkrono. Kako bi omogućili uvid u stanje poslanog dokumenta te potvrdu uspješnog ili neuspješnog slanja EDES platforma koristi APPLICATION_RESPONSE tip dokumenta. Struktura ovog dokumenta definirana je UBL 2.1 maindoc/UBL-ApplicationResponse-2.1.xsd shemom. Primjer ovog dokumenta možete pronaći u privitku application-response.xml. Ovaj dokument sadrži dvije važne informacije. Informacije o greški ili uspjeha (Note) te status dokumenta (DocumentResponse).

Status dokumenta može biti sljedeći:

  • SUCCESS - ukoliko je dokument uspješno poslan,

  • FAILURE - ukoliko dostava dokumenta nije bila uspješna.

U budućnosti su mogući i drugi statusi. Ukoliko vaš sustav ne prepoznaje primljeni status može ga slobodno zanemariti. Dokument će biti dostavljen u vaš inbox.

2.2.2. EN16931

Ova norma definirana je od strane Europske Unije te se koristi na cijelom području EU. Od 01.12.2018. korištenje ove norme je obvezno ukoliko se računi šalju prema državnim institucijama Republike Hrvatske.

Specifikacija računa za tržište Republike Hrvatske nalazi se u sljedećem privitku (zadnja izmjena 13.06.2019) EN-UBL-HR-Specifikacija upotrebe.pdf.

Dokumenti (račun i odobrenje) se šalju kao XML dokumenti prema UBL 2.1 specifikaciji. XSD Shema se nalazi u sljedećem privitku UBL-2.1.zip.

Uz račun se može poslati jedan ili više privitaka. Privitci su sastavni dio računa. Preporuka jest da se uz račun ne šalju vizualizacije računa iz razloga što se ista može generirati na strani primatelja na temelju poslanog dokumenta.

Primjer računa možete pronaći u sljedećem privitku fina-invoice-examples.xmlKod slanja ove vrste dokumenta molimo koristiti sljedeće:

  • mainDocument[].documentType: INVOICE ili CREDIT_NOTE,

  • mainDocument[].documentFormat: UBL-2.1-EN16931

Svi dokumenti moraju biti potpisani XAdES elektroničkim potpisom. Za potpisivanje se mora koristiti aplikacijski certifikat za e-račun izdan od strane FINA-e. Primjer potpisa u programskom jeziku Java možete pronaći u našem službenom GIT repositoriju https://bitbucket.org/ingemark/ edes-fina-signatures.

EDES sustav većinu operacija odrađuje asinkrono. Pri slanju dokumenata u EDES sustav sinkrono se odrađuju samo provjere validacije zahtjeva i sigurnosne provjere. Sve ostale provjere kao i slanje dokumenata prema primatelju odrađuje se asinkrono. Kako bi omogućili uvid u stanje poslanog dokumenta te potvrdu uspješnog ili neuspješnog slanja EDES platforma koristi EDES_RESPONSE tip dokumenta. Struktura ovog dokumenta definirana je XSD shemom edesresponse.xsd. Primjer ovog dokumenta možete pronaći u privitku edes-response-v1-valid.xml.

Status dokumenta može biti sljedeći:

  • SENT - Dokument je uspješno dostavljen informacijskom posredniku ili u pretinac na EDES platformi,

  • SEND_FAILED - Dokument nije moguće dostaviti,

  • RECEIVER_READ - Primatelj je pročitao dokument ali ga još nije obradio,

  • RECEIVER_PROCESSED - Primatelj je prihvatio dokument,

  • RECEIVER_REJECTED - Primatelj je odbio dokument,

  • RECEIVER_PARTIALLY_PAID - Primatelj je djelomično platio iznos troška,

  • RECEIVER_PAID - Primatelj je platio iznos troška.

U budućnosti su mogući i drugi statusi. Ukoliko vaš sustav ne prepoznaje primljeni status može ga slobodno zanemariti. Dokument će biti dostavljen u vaš inbox.

Poglavlje 3. Slanje i primanje dokumenata

Za slanje odnosno primanje dokumenata od strane Klijenta koristiti će se REST sučelje definirano od strane e-Bill EDES platforme.

Svaki korisnik EDES platforme imati će na raspolaganju vlastiti inbox i outbox. Inbox će sadržati sve dokumente poslane prema Klijentu. Dokumenti mogu biti računi (documentType = "INBOX"), opomene (documentType = "REMINDER"), odobrenje (documentType = "CREDIT_NOTE") ali i potvrde primitka poslanih računa (documentType = "APPLICATION_RESPONSE"). Outbox će sadržati sve dokumente koje Klijent šalje prema vlastitim partnerima.

3.1. Sigurnost

Zaštita podataka u transportu između Klijentske platforme i EDES platforme provoditi će se korištenjem TLS 1.2 protokola uz poznate certifikate poslužitelja. Autorizacija pristupa pojedinim servisima provoditi će se korištenjem HTTP Basic Authentication mehanizma.

3.2. Pristupne točke EDES platforme

E-bill EDES platforma biti će raspoloživa na sljedećim URL-ovima:

3.3. Vrste podataka pri pozivu REST servisa

Ukoliko nije drugačije navedeno EDES platforma očekuje "Content-Type: application/json" u svim pozivima web servisa. Odgovor od platforme također će biti u "application/json" mime tipu.

3.4. Ulazni dokumenti

Proces primanja ulaznih dokumenata odvija se u 3 koraka:

  • Klijentska platforma periodički provjera stanje vlastitog inbox-a. Ukoliko postoje novi dokumenti u inbox-u EDES platforma vratiti će metapodatke o primljenim dokumentima

  • Klijentska platforma će na temelju dobivenih metapodataka dohvaćati dokumente iz vlastitog inbox-a te ih interno obraditi

  • Nakon obrade dokumenta Klijentska platforma javiti će stanje obrade dokumenta EDES platformi

3.4.1. Provjera stanje inbox-a

Stanje pretinca provjerava se slanjem HTTP POST poruke na sljedeći endpoint:

/api/v1/clients/inbox/documents. Unutar tijela poruke nalazi se element tipa InboxDocumentSearchRequest koji sadrži sljedeće parametre:

Naziv

Tip

Obvezan

Opis

Primjer

identifier

string

Da

Identifikator vlasnika pretinca u formatu HR0<OIB>

HR0-02854892746

documentStatus

string

Ne

Status dokumenta

UNREAD, READ,

PROCESSED,

REJECTED

timestampFrom

string

Ne

Vrijeme formatirano prema ISO-8601 standardu. Opisuje donju granicu (uključeno) pretrage

2017-01-

01T00:00:30+01:00

timestampTo

string

Ne

Vrijeme formatirano prema ISO-8601 standardu. Opisuje gornju granicu (isključeno) pretrage

2017-01-

01T00:00:30+01:00

Na primjer:

Također je moguće definirati broj stranice te broj elemenata po stranici korištenjem parametara page i size. Pozivom URL-a /api/v1/clients/inbox/documents?page=0&size=5 dohvatiti će te stranicu broj 0 te će vam sustav vratiti 5 rezultata po stranici. Maksimalan broj rezultata je 20.

Ukoliko HTTP poslužitelj vrati HTTP status "200 OK" rezultat izvršavanja će biti lista elemenata tipa InboxDocumentSearchResponse koji sadrži sljedeće parametre:

Naziv

Tip

Obvezan

Opis

Primjer

documents[]. documentId

string

Da

Identifikator dokumenta na EDES platformi

e5db2893-b5f84642-8a8c7f55a53ec608

documents[]. receivedAt

string

Da

Vrijeme primitka prema ISO-8601 standardu

2017-01-

01T00:00:00+01:00

Naziv

Tip

Obvezan

Opis

Primjer

documents[]. documentType

string

Da

Vrsta dokumenta

INVOICE,

REMINDER,

CREDIT_NOTE,

APPLICATION_RES

PONSE

documents[].

documentFormat

string

Da

Format dokumenta

UBL-2.1-HR

documents[].

documentEncodin g

string

Da

Encoding documenta

Base64

documents[]. documentStatus

string

Da

Status dokumenta na EDES platformi

UNREAD, READ,

PROCESSED,

REJECTED

documents[].

senderIdentifier

string

Da

Identifikator pošiljatelja u formatu HR0<OIB>

HR0-02854892746

documents[].

receiverIdentifier

string

Da

Identifikator primatelja u formatu HR0<OIB>

HR0-02854892746

maxResults

int

Da

Traženi maksimalan broj rezultata po stranici

20

pageNumber

int

Da

Trenutni broj stranice

0

Na primjer:

3.4.2. Dohvat pojedinačnog dokumenta

Dokument se dohvaća pozivom HTTP POST metode na URL: /api/v1/clients/inbox/documents/download. Unutar tijela poruka nalazi se element tipa InboxDocumentDownloadRequest sa sljedećim parametrima:

Naziv

Tip

Obvezan

Opis

Primjer

identifier

string

Da

Identifikator

Klijenta u formatu HR0-<OIB>

HR0-02854892746

documentId

string

Da

Identifikator dokumentu u sustavu EDES

e5db2893-b5f84642-8a8c7f55a53ec608

Na primjer

Ukoliko je rezultat izvršavanje poziva HTTP status code "200 OK" rezultat izvršavanje će biti element tipa InboxDocumentDownloadResponse s sljedećim parametrima

Naziv

Tip

Obvezan

Opis

Primjer

mainDocument

DocumentInfo

Da

Glavni dokument


attachments

Array

AttachmentInfo

Ne

Privitci glavnog dokumenta


Na primjer:

3.4.3. Dohvat pojedinačnog računa korištenjem XML omotača

Uz JSON prikaz računa platforma može vratiti račun u obliku XML omotača:

Za dohvat XML omotača potrebno je pozvati servis na url-u /api/v1/clients/wrapper/inbox/documents metodom HTTP POST, Content-Type poljem vrijednosti application/json i Accept poljem vrijednosti application/xml. Zahtjev mora sadržavati element tipa InboxDocumentDownloadRequest (kao i kod JSON prikaza).

Rezultat izvršavanje će biti uspješan ukoliko servis vrati status HTTP 200. U HTTP tijelu nalaziti će se XML omotač.

Schema omotača nalazi se u attachments/tht-xml-wrapper/THT-OutgoingInvoicesData.xsd. Primjer omotača se nalazi u attachments/tht-xml-wrapper/THT-OutgoingInvoicesData.xml.

3.4.4. Promjena stanja dokumenta

Stanje ulaznog dokumenta može se promijeniti pozivom HTTP POST metode na URL: /api/v1/clients/inbox/documents/status. Unutar tijela nalazi se element tipa InboxDocumentStatusRequest sa sljedećim parametrima:

Naziv

Tip

Obvezan

Opis

Primjer

identifier

string

Da

Identifikator vlasnika pretinca u formatu HR0<OIB>

HR0-02854892746

documentId

string

Da

Identifikator dokumenta u sustavu EDES

e5db2893-b5f84642-8a8c7f55a53ec608

status

string

Da

Status obrade dokumentu U ERPu primatelja

READ,

PROCESSED,

REJECTED

statusCode

string

Da

Status kod rezultata obrade u

ERP-u primatelja.

200

statusText

string

Da

Localizirani opis greške

Primljeni dokument ne sadrži validan UBL e-račun

Na primjer:

Ukoliko je zahtjev uspješno obrađen poslužitelj vraća HTTP Status Code "204 No Content". Sustav trenutno podržava sljedeća stanja:

  • READ - koristi se ukoliko je potrebna asinkrona obrada dokumenta. Korisnička platforma mora naknadno postaviti stanje u jedno od sljedećih stanja,

  • PROCESSED - korisnička platforma ovim stanje potvrđuje da je dokument uspješno obrađen,

  • REJECTED - koristi se ukoliko dokument nije moguće obraditi,

  • PAYMENT_PARTIALLY_FULFILLED – koristi se u situacijama kada je račun djelomično plaćen,

  • PAID – ovim stanje korisnik potvrđuje da je račun plaćen.

3.5. Izlazni dokumenti

Process slanja izlaznih dokumenata odvija se u dva koraka:

  • Klijenska platforma šalje dokument koristeći EDES REST sučelje

  • Potvrda primitka od strane primatelja dostaviti će se u inbox pretinac kao poseban dokument tipa APPLICATION_RESPONSE.

Klijentska platforma šalje račune prema svojim partnerima pozivom HTTP POST metode na URL: /api/v1/clients/outbox/documents. U tijelu poruke nalazi se element tipa OutboxDocumentRequest s sljedećim parametrima:

Naziv

Tip

Obvezan

Opis

Primjer

senderIdentifier

string

Da

Identifikator pošiljatelja u formatu HR0<OIB>

HR0-02854892746

senderDocumentI d

string

Da

Identifikator dokumenta u ERP-

u pošiljatelja

1799/200/1

receiverIdentifier

string

Da

Identifikator primatelja u formatu HR0<OIB>

HR0-02854892746

receiverBusinessU nitCode

string

Ne

Identifikator poslovne jedinice

205

mainDocument

DocumentInfo

Da

Dokument koji se šalje


Naziv

Tip

Obvezan

Opis

Primjer

attachments

Array

AttachmentInfo

Ne

Privitci koji se šalju


Poziv je uspješan ukoliko HTTP poslužitelj vrati HTTP Status Code "202 OK". Tijelo će sadržati element OutboxDocumentResponse s sljedećim parametrima:

Naziv

Tip

Obavezan

Opis

Primjer

documentId

string

Da

Identifikator dokumenta u sustavu EDES

6c16ce36-ee56-

46d8-84053048f0235bca

correlationId

string

Da

Identifikator

procesa u sustavu EDES

6c16ce36-ee56-

46d8-84053048f0235bca

submittedAt

string

Da

Vrijeme primitka dokumenta u sustav EDES po ISO-8601 standardu

2017-01-

01T00:00:00+01:00

3.5.1. Izlazni računi korištenjem XML omotača

Izlazni računi se osim u JSON formatu mogu slati preko platforme i korištenjem XML omotača. Schema XML omotača se nalazi u attachments/tht-xml-wrapper/THT-OutgoingInvoicesData.xsd.

Primjer omotača se nalazi u attachments/tht-xml-wrapper/THT-OutgoingInvoicesData.xml.

XML omotač se sastoji od sljedećih tipova:

Naziv

Tip

Obavezan

Opis

Primjer

SupplierID

string

Da

OIB pošiljatelja

85821130368

BuyerID

string

Da

OIB primatelja

85821130368

InvoiceType

integer

Da

Vrsta doumenta. Ovaj tip je dodao radi

kompatibilnosti platforme s drugim sustavima

i ne koristi se

0 za B2G; 1 za B2B

SupplierInvoiceID

string

Da

Identifikator dokumenta u ERP-

u pošiljatelja

2017/1/1

Format

string

Da

format poslanog računa

HR_INVOICE_UBL_ 2_1_V0.2

Content

string

Da

Base64 enkodirani račun u odgovarajućem formatu


DocumentName

string

Da

Naziv dokumenta u privitku


DocumentFormat

string

Da

MIME type dokumenta u privitku

application/pdf

DocumentContent

string

Da

Base64 enkodirani privitak u odgovarajućem formatu


Za slanje računa korištenjem XML omotaća potrebno je ispravan omotač poslati pozivom HTTP POST metode na url /api/v1/clients/wrapper/outbox/documents. HTTP servis očekuje Content-Type application/xml i vraća dokument s Content-Type application/json.

Poziv je uspješan ukoliko HTTP poslužitelj vrati HTTP Status Code "202 Accepted". Tijelo će sadržati element OutboxDocumentResponse s sljedećim parametrima:

Naziv

Tip

Obavezan

Opis

Primjer

documentId

string

Da

Identifikator dokumenta u sustavu EDES

6c16ce36-ee56-

46d8-84053048f0235bca

correlationId

string

Da

Identifikator

procesa u sustavu EDES

6c16ce36-ee56-

46d8-84053048f0235bca


Naziv

Tip

Obavezan

Opis

Primjer

submittedAt

string

Da

Vrijeme primitka dokumenta u sustav EDES po ISO-8601 standardu

2017-01-

01T00:00:00+01:00



Poglavlje 4. Dohvat povijesti promjena stanja firmi

Za dohvat podataka o promjenama stanja firmi potrebno je poslati zahtjev tipa HTTP GET na sljedeći url /api/v1/clients/exports/company/history. Servis prihvaća dva obvezna parametra timestampFrom i timestampTo. Parametar timestampFrom definira donju vremensku granicu (inkluzivno) vremenskog raspona povijesti dok timestampTo definira gornju granicu (ekskluzivno) raspona. Vremena moraju biti definirana prema ISO 8601 standardu. Sljedeći zapis pokazuje primjer jednog zahtjeva:

Servis će vratiti odgovor s Content-Type-om text/csv (s kodiranjem tipa UTF-8) i sadržajem kojeg definira sljedeći primjer:

Sadržaj odgovora definiran je CSV standardom uz korištenje znaka ’;’ kao separatora. Prva linija predstavlja zaglavlje izvoza te će biti definirana i u slučaju praznog odgovora. Ostale linije predstavljaju zapis pojedine stavke povijesti firme. Svaki zapis se sastoji od sljedećih polja:

  • Naziv tvrtke - predstavlja službeno ime firme prema podacima iz ICT Marketplace-a ili posrednika u razmijeni,

  • Tip - Označava vrstu identifikator (HR0 je oznaka za HR OIB),

  • Identifikator tvrtke - predstavlja identifikator firme,

  • Stanje - definira razlog promjene. Moguće opcije su: Dodana (u slučaju dodavanja zapisa u bazu), Obrisana (u slučaju brisanja firme iz baze) i Promijenjena (u slučaju promjene podataka o firmi),

  • Datum promjene - odnosi se na datum promjene stanja firme (u formatu YYYY-MM-dd).

Poglavlje 5. Dohvat podržanih dokumenata za pojedinu firmu

Za dohvat podataka o dokumentima koje firma može primiti potrebno je poslati HTTP GET zahtjev na sljedeći URL /api/v1/clients/contracts/company/{company-identifier}/supported-documents gdje je company-identifier identifikator firme na EDES platformi.

Ukoliko firma postoji na EDES platformi sustav će vratit "HTTP 200 OK" s Content-Type "application/json". Tijelo će sadržavati element tipa CompanySupportedDocumentTypes s sljedećim parametrima:

Naziv

Tip

Obavezan

Opis

Primjer

companyIdentifier

string

Da

Identifikator firme na EDES platformi

HR0-57663938873

types[]

array

Da

List podržanih dokumenata


types[].documenttType

string

Da

Vrsta dokumenta

INVOICE

types[].documentfFormat

string

Da

Format dokumenta

UBL-2.1-HR, UBL-

2.1-EN16931

types[].endpoint

string

Da

Izlazna točka

fina-adapter, fina-adapter-b2g, internal

Primjer jednog odgovora je sljedeći:

"companyIdentifier": "HR0-81793146560",

"types": [

{

"documentType": "INVOICE",

"documentFormat": "UBL-2.1-HR",

"endpoint": "internal"

},

{

"documentType": "INVOICE",

"documentFormat": "UBL-2.1-EN16931",

"endpoint": "internal"

},

{

"documentType": "REMINDER",

"documentFormat": "UBL-2.1-HR",

"endpoint": "internal"

},

{

"documentType": "CREDIT_NOTE",

"documentFormat": "UBL-2.1-HR",

"endpoint": "internal"

}

]

}

Poglavlje 6. Korištenje poslovnih jedinica

6.1 Administracija poslovnih jedinica

Svaka firma na EDES platformi može uz osnovni pretinac definirati i dodatne poslovne jedinice. Pošiljatelj dokumenta pri tome može odabrati da li želi dokument poslati na osnovni pretinac ili na poslovnu jedinicu. Za ažuriranje poslovnih jedinica potrebno je poslati "HTTP POST" zahtjev na URL /api/v1/clients/company/business-units s Content-Type "application/json". Ako je zahtjev uredno obrađen sustav vraća "HTTP 204 No Content" odgovor. U zahtjevu se uvijek šalju sve informacije o poslovnim jedinicama. Tijelo zahtjeva mora sadržavati element tipa *BusinessUnitsUpdateRequest* sa sljedećim parametrima:

Naziv

Tip

Obavezan

Opis

Primjer

identifier

string

Da

Identifikator firme na EDES platformi

HR0-57663938873

businessUnits []

array

Da

Skup informacija o poslovnim jedinicama

 

businessUnits [].identifierType

string

Da

Vrsta identifikatora poslovne jedinice

PEPPOL_GLN, PEPPOL_DUNS, PEPPOL_HR_VAT

businessUnits [].code

string

Da

Vrijednost šifre poslovne jedinice

3850157000000

businessUnits [].name

string

Da

Naziv poslovne jedinice

Poslovnica Zagreb

businessUnits [].addressStreet

string

Da

Adresa poslovne jedinice

Trg Bana Jelačića bb

businessUnits [].zipCode

string

Da

Poštanski broj

10000

businessUnits [].addressCity

string

Da

Grad u kojoj se nalazi poslovna jedinica

Zagreb

businessUnits [].country

string

Da

Grad u kojoj se nalazi poslovna jedinica

Republika Hrvatska

businessUnits [].active

string

Da

Da li je poslovna jedinica aktivna

true | false

 

Primjer zahtjeva je sljedeći:

{
"identifier" : "HR0-XXXXXXXXXXX",
"businessUnits" : [ {
"identifierType" : "PEPPOL_GLN",
"code" : "3850157000000",
"name" : "Poslovnica Zagreb",
"addressStreet" : "Trg Bana Jelačića bb",
"zipCode" : "10000",
"addressCity" : "Zagreb",
"country" : "Republika Hrvatska",
"active" : true
}, {
"identifierType" : "PEPPOL_DUNS",
"code" : "15-048-3782",
"name" : "Poslovnica Rijeka",
"addressStreet" : "Zvonimirova ulica bb",
"zipCode" : "52100",
"addressCity" : "Rijeka",
"country" : "Republika Hrvatska",
"active" : false
}, {
"identifierType" : "PEPPOL_HR_VAT",
"code" : "38267045036",
"name" : "Poslovnica Osijek",
"addressStreet" : "Šetalište kardinala Franje Šepara bb",
"zipCode" : "31000",
"addressCity" : "Osijek",
"country" : "Republika Hrvatska",
"active" : false
} ]
}

6.2 Adresiranje poslovnih jedinica firme

Prilikom slanja dokumenata pošiljatelj ima mogućnost adresirati "glavni pretinac" ili pojedinu poslovnu jedinicu unutar primatelja. U slučaju da se želi adresirati "glavni pretinac" potrebno je polje receiverBusinessUnitCode kod slanja izlaznog dokumenta ostaviti prazno odnosno null. Ukoliko se želi adresirati poslovna jedinica potrebno je u polje postaviti šifru poslovne jedinice.

Vrijednost šifre poslovne jedinice ovisi o pružatelju usluge na kojem se nalazi primatelj. Na EDES platformi trenutno su podržani sljedeći tipovi poslovne jedinice:

  • PEPPOL_GLN - 0088,
  • PEPPOL_DUNS - 0060
  • PEPPOL_HR_VAT - 9934

Na FINA platformi su definirani sljedeći tipovi poslovnih jedinica:

  • gln - 0088
  • jus - HR01
  • “Interna šifra“ - HR99
  • “Osnovni pretinac“- 9934
  • rkp - HR02
  • osobni - 9934
  • duns – 0060

Šifra poslovne jedinice je definirana u formatu <sifra tipa poslovne jedinice>:<interna šifra poslovne jedinice - code polje>.

U odgovoru na ovaj upit nalazi se polje completeCode. Ovo polje sadrži automatski izračunatu vrijednosti šifre poslovne jedinice. Vrijednost se izračunava na samoj platformu na temelju dostupnih pravila. Ukoliko je vrijednost coompleteCode polja null navedena poslovna jedinica služi za interne potrebe pružatelja usluge te se ne može adresirati.

Za dohvat svih poslovnih jedinica pojedine firme potrebno je napraviti "HTTP GET" upit na URL: /api/v1/clients/exports/company/business-units. U slučaju uspješnog odgovora servis će vratiti sljedeće informacije:

Naziv

Tip

Obavezan

Opis

Primjer

units[]

map

Da

Lista s informacija o poslovnim jedinicama (grupirano po izlanoj točki)

 

units.[<endpoint>].[].identifierTy pe

string

Da

Vrsta interne šifre. Ovo polje je slobodni unos

GLN

units.[<endpoint>].[].localCode

string

Da

Šifra poslovne jedinice kod pružatelja usluge

205

units.[<endpoint>].[].code

string

Da

Interna šifra poslovne jedinice kod primatelja

HR55

units.[<endpoint>].[].name

string

Da

Naziv poslovne jedinice

Poslovnica Zagreb

units.[<endpoint>].[] .addressStre et

string

Da

Adresa poslovne jedinice

Trg bana Jelačića 1

units.[<endpoint>].[].zipCode

string

Da

Poštanski broj poslovne jedinice

10000

units.[<endpoint>].[] .addressCity

string

Da

Grad poslovne jedinice

Zagreb

units.[<endpoint>].[].country

string

Da

Zemlja poslovne jedinice

Republika Hrvatska

units.[<endpoint>].[].active

Boolean

Da

Da je je poslovna jedinica aktivna

True|false

units.[<endpoint>].[].completeCode

String

Ne

Automatski izračunata vrijednosti šifre poslovne jedinica

HR2:1001

{

    "units":  {

        "fina-adapter": [

            {

                "identifierType": "Osnovni pretinac",

                "localCode": "205",

                "code": "1111111111111",

                "name": "AGENCIJA",

                "addressStreet": "Aleja Testera bb ",

                "zipCode": "10000",

                "addressCity": "ZAGREB",

                "country": "REPUBLIKA HRVATSKA",

                "active": false,

              "completeCode": "HR2:1001“

            },

            {

                "identifierType": "Interna šifra",

                "localCode": "206",

                "code": "50101",

                "name": "PODRUŽNICA ZAGREB",

                "addressStreet": "Aleja Testera 1",

                "zipCode": "10000",

                "addressCity": "ZAGREB",

                "country": "REPUBLIKA HRVATSKA",

                "active“: true,

                "completeCode": "HR2:2002"

            }

        ]

    }

}

Poglavlje 7. FAQ

7.1. Primanje ne podržanih dokumenata u inbox

Na web portalu EDES platforme korisnik može definirati koje dokumente on može primiti odnosno slati. Trenutno je ova postavka informacijske prirode. Prema pravilima FINA-e EDES platforma ne smije odbiti dokument bez obzira da li korisnik taj document može automatski obraditi ili ne. Ukoliko u inbox primite dokument koji vaš sustav ne može automatski obraditi potrebno je isti dokument poslati na ručnu obradu. Dokument je moguće preuzeti i na web portalu EDES platforme

7.2. Vrijeme između provjera stanja inbox-a

Kako ne bi preopteretili EDES platformu s velikim brojem upita molimo da podesite vaše sustave da provjeravaju stanje Vašeg inbox svakih sat vremena.

7.3. Asinkrona obrada ulaznih dokumenata

Ovisno o arhitekturi Vašeg sustava moguće su situacije u kojima niste u mogućnosti odmah vratiti stanje obrade dokumenata. U ovim situacijama stanje dokumenta u inbox-u će i dalje biti UNREAD. Sljedeći upit prema inboxu može vratiti dokumente koje ste već primili u Vaš sustav. Za ove situacije predvidili smo stanje READ. Ovo stanje EDES platformi dojavljuje da ste dokument primili ali ne i obradili. Nakon obrade dokumenta možete naknadno postaviti finalno stanje (PROCESSED ili REJECTED).

7.4. Slanje grešaka od strane EDES platforme

Kod slanja dokumenata na EDES platformu potrebno je znati da se velik broj operacija izvodi asinkrono te vam nismo u mogućnosti istog trena u odgovoru vratiti sve greške. EDES platforma kod primanje dokumenta provjerava osnovne informacije:

  • Da li su autentikacijske informacije ispravne,

  • Da li korisnik ima pravo slati dokumente za firmu navedenu u dokumentu,

  • Da li je firma aktivna,

  • Da li je format zahtjeva ispravan,

  • Da li je veličina poslanog dokumenta ispod maksimalne podržane granice,

  • Da li je već poslan dokument s navedenim brojem dokumenta na strani pošiljatelja.

Sve ostale greške dostavljamo u obliku dokumenta tipa APPLICATION_RESPONSE. Ovaj dokument generira se od strane EDES platforme te se dostavlja u Vaš inbox.

7.5. Slanje dokumenata s istim identifikatorom u pošiljateljevom sustavu

Prilikom slanja dokumenata na EDES platformu pošiljatelj mora navesti identifikator dokumenta u svome internom sustavu (senderDocumentId u json zahtjevu te SupplierInvoiceID u XML zahtjevu). Ovaj identifikator mora biti jedinstven u sustavu pošiljatelja. Ukoliko EDES platforma detektira da navedeni identifikator već postoji na EDES platformi zahtjev će se smatrati retransmisijom. U odgovoru na zahtjev poslati ćemo informacije o prvom primljenom dokumentu dok će svaki sljedeći biti ignoriran.

Na web portalu biti će vidljiv samo inicijalno poslan dokument.

Poglavlje 8. Tipovi podataka

8.1. DocumentInfo

Naziv

Tip

Obavezan

Opis

Primjer

documentType

string

Da

Vrsta dokumenta

INVOICE,

APPLICATION_RES PONSE

documentFormat

string

Da

Format dokumenta

UBL-2.1-HR

documentEncodin g

string

Da

Encoding documenta

Base64

documentContent

string

Da

enkodirani dokument


8.2. AttachmentInfo

Naziv

Tip

Obavezan

Opis

Primjer

documentName

string

Da

Naziv dokumenta

invoice.pdf

documentFormat

string

Da

format dokumenta

application/pdf

documentEncodin g

string

Da

Encoding dokumenta

Base64

documentContent

string

Da

sadržaj dokumenta




ŽELITE LI DA VAS KONTAKTIRAMO?

Ostavite nam svoje podatke kako bismo Vas mogli kontaktirati i odgovoriti na vaša pitanja

Osobne podatke prikupljamo radi kontaktiranja korisnika. Zato je važno da su točno napisani. Detaljnije o zaštiti osobnih podataka pogledajte u
Politici zaštite privatnosti korisnika HT-a.