Tehnička specifikacija slanja računa web servisima prema državi primjenom ostalih metoda
U nastavku su opisane sve poruke koje sustavi razmjenjuju, načini razmjene te razine sigurnosti, odnosno zaštite prijenosa.
Podaci će se razmjenjivati korištenjem XML poruka putem SOAP web servisa. Ovakvim načinom razmjene podataka nema ovisnosti o tehnologiji koja se koristi na strani Pošiljatelja, ni o tehnologiji na strani Fine kao informacijskog posrednika, a ni na strani proračunskog korisnika kao krajnjeg Primatelja.
Definicije i skraćenice
SSL | Secure Sockets Layer – protokol koji omogućava zaštitu komunikacijskog kanala |
EV | Extended Validation – postupak provjere poslovnog subjekta prilikom izdavanja SSL certifikata |
Pošiljatelj | Pošiljatelj računa prema korisniku državnog proračuna |
Primatelj | Korisnik državnog proračuna |
ERP | Enterprise Resource Planning – Poslovni sustav na strani Pošiljatelja |
SOAP | Simple Object Access Protocol – protokol koji se koristi za razmjenu podataka između dva sustava web servisima |
Zaštita integriteta
Zaštita integriteta ostvaruje se procesnim kontrolama na strani Pošiljatelja. Pošiljatelj mora moći internim procesnim kontrolama utvrditi podrijetlo računa i cjelovitost sadržaja.
Komunikacijski uvjeti
Razmjena podataka u sustavu e-Račun za državu između Fine i Pošiljatelja vrši se putem internetske mreže. Slanje računa web servisima podrazumijeva potpuno automatizirano slanje računa iz ERP sustava Pošiljatelja prema sustavu Primatelja kroz Finin sustav e-Račun za državu.
Za ovakvo automatizirano slanje računa Pošiljatelj treba sljedeće:
- utvrditi procesne kontrole kojima će moći dokazati podrijetlo računa, odnosno tko je račun izdao, te procesne kontrole kojima će moći dokazati cjelovitost sadržaja,
- posjedovati SSL certifikat povjerljivog izdavatelja koji mora imati naveden točan i provjeren naziv poslovnog subjekta kojem je izdan te mora zadovoljiti zahtjeve navedene u dokumentu "Baseline Requirements Certificate Policy for the Issuance and Management of Publicly-Trusted Certificates" kojeg izdaje CA/Browser Forum, ili zahtjeve više razine (kao npr. zahtjeve propisane za EV certifikat). Korisnik može zatražiti i od Fine poslužiteljski SSL certifikat za uspostavu sigurne veze između svog ERP-a i Fininog sustava e-Račun za državu,
- prilagoditi ERP za kreiranje i slanje SOAP poruka prema uputi iz poglavlja 4 ovog dokumenta.
Web servis
Fina je sa svoje strane izradila web servis za zaprimanje podataka prema standardiziranoj XML shemi.
Dokumenti koji se mogu slati web servisom sustava e-Račun za državu su:
- račun (s popratnom dokumentacijom kao prilogom),
- odobrenje (s popratnom dokumentacijom kao prilogom).
Sve poruke koje se šalju web servisom su identičnog osnovnog izgleda. Sastoje se od zaglavlja (HeaderSupplier) i podataka (Data).
Podaci (Data) su definirani za svaku poruku posebno i unutar elementa se nalazi XML struktura različita ovisno o poruci. Poruke koje sadrže samostalne XML strukture (npr. xml e-računa) se ugrađuju u "omotnice" (npr. InvoiceEnvelope) tipa base64binary u kojem se nalazi originalni XML enkodiran u Base64.
Osnovne postavke koncepta:
- Fina je izradila web servis s metodama za slanje poruke s izlaznim e-računom i e-odobrenjem (SendB2GOutgoingInvoice) te s metodama za slanje poruke za dohvat statusa izlaznog računa i probne, echo poruke,
- prilikom poziva web servisa Fine uspostavljat će se SSL veza s klijentskom autentifikacijom,
- prije korištenja Fininog sustava e-Račun za državu, moraju biti utvrđene procesne kontrole na strani Pošiljatelja za dokazivanje podrijetla računa i cjelovitost sadržaja,
- za svaku SOAP poruku postojat će potvrdna SOAP poruka (acknowledgement message).
Slanje echo poruke
Slanje izlaznog računa
Provjera rada web servisa (Echo metoda)
Pošiljatelj kreira echo SOAP poruku, potpisuje je i šalje prema Fininom web servisu radi testiranja dostupnosti. Fina sinkrono odgovara povratnom porukom.
Ukoliko je slanje echo poruke uredno prošlo i Fina je odgovorila povratnom porukom, pošiljatelj kreira SOAP poruku za slanje izlaznog računa ili odobrenja, potpisuje SOAP poruku te poziva web servis na strani Fine. Fina sinkrono odgovara na poruku s rezultatima obrade.
Elementi EchoMsg poruke
HeaderSupplier
MessageID - Jedinstveni broj poruke
SupplierID - Identifikator izdavatelja (OIB) – (9934:12345678909)
AdditionalSupplierID - Dodatni identifikator izdavatelja (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja)
MessageType - Tip poruke: 9999 – echo poruka
MessageAttributes – Atributi poruke
Data
EchoData
Echo - Sadržaj teksta
Elementi EchoAckMsg poruke
MessageAck
MessageID - Jedinstveni broj poruke
MessageAckID - Jedinstveni broj poruke na koju se odnosi odgovor
MessageType – 10000 - Odgovor na echo poruku
AckStatus - Status odgovora
AckStatusCode - Šifra statusa iz sustava
AckStatusText - Opis statusa iz sustava
EchoData
Echo - Sadržaj teksta
Slanje Echo i Echo potvrdne poruke
Metoda za slanje izlaznih dokumenata (račun ili odobrenje)
Nakon uspješnog slanja echo SOAP poruke, Pošiljatelj kreira SOAP poruku za slanje dokumenta:
Elementi SendB2GOutgoingInvoiceMsg poruke (metoda SendB2GOutgoingInvoice)
HeaderSupplier
MessageID - Jedinstveni broj poruke
SupplierID - Identifikator izdavatelja (OIB) – (9934:12345678909)
AdditionalSupplierID - Dodatni identifikator izdavatelja (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja)
MessageType - Tip poruke: 9001 – slanje izlaznog računa
MessageAttributes – Atributi poruke
Data
B2GOutgoingInvoiceEnvelope
XMLStandard - Standard XML dokumenta (UBL ili CII)
SpecificationIdentifier - Prilagodba XML dokumenta (fiksno - urn:cen.eu:en16931:2017)
SupplierInvoiceID – Identifikator računa u sustavu pošiljatelja
BuyerID – Identifikator primatelja računa u sustavu (OIB) – (9934:12345678909)
AdditionalBuyerID - Dodatni identifikator kupca (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru primatelja)
InvoiceEnvelope – Omotač e-računa po UBL shemi
CreditNoteEnvelope – Omotač e-odobrenja po UBL shemi
Elementi SendB2GOutgoingInvoiceAckMsg poruke
MessageAck
MessageID - Jedinstveni broj poruke
MessageAckID - Jedinstveni broj poruke na koju se odnosi odgovor
MessageType - Tip poruke: 9002 – sinkroni odgovor na SendB2GOutgoingInvoiceMsg
AckStatus – status odgovora
ACCEPTED ili
MSG_NOT_VALID ili
SYSTEM_ERROR
AckStatusCode – Šifra statusa iz sustava
AckStatusText – (opcinalno) – Opis statusa iz sustava
B2GoutgoingInvoiceEnvelope
CorrectB2GOutgoingInvoice - Ispravan izlazni račun
SupplierInvoiceID - Identifikator računa u sustavu Pošiljatelja
InvoiceID - Identifikator računa u sustavu e-RačunB2G
InvoiceTimestamp - Vrijeme zaprimanja računa u sustav
IncorrectB2GoutgoingInvoice
SupplierInvoiceID - Identifikator računa u sustavu Pošiljatelja.
ErrorCode - Šifre grešaka neispravnog izlaznog računa odvojene delimiterom.
ErrorMessage - Opis grešaka neispravnog izlaznog računa.
Odgovorna poruka sastoji se od dva dijela:
- MessageAck
- B2GOutgoingInvoiceEnvelope
U MessageAck dijelu se nalaze osnovni podaci o samoj SOAP poruci, dok se u dijelu B2GoutgoingInvoiceEnvelope nalaze podaci o obradi poslanog računa.
Statusi poruka
AckStatus | AckStatusCode | AckStatusText |
ACCEPTED | 10 | Poruka zaprimljena |
MSG_NOT_VALID | 90 | XML poruka nije ispravna |
MSG_NOT_VALID | 91 | Potpis poruke nije ispravan |
SYSTEM_ERROR | 99 | Sistemska greška na strani web servisa + opis |
Ukoliko je SOAP poruka u skladu s definicijom web servisa (wsdl), tada se u elementu MessageAck / AckStatus uvijek pojavljuje odgovor ACCEPTED bez obzira da li su sami podaci, npr. računa, ispravni. Ukoliko SOAP poruka nije u skladu s definicijom, tada se u odgovoru pojavljuje MSG_NOT_VALID. Vrijednost SYSTEM_ERROR pokazuje da je došlo do većih problema u sustavu (npr. runtime exception) te je pokazatelj da se treba javiti korisničkoj podršci kako bi se provjerio razlog.
U B2GoutgoingInvoiceEnvelope dijelu se nalaze podaci o obrađenom dokumentu (računu, odobrenju…) i cijeli element se pojavljuje isključivo ako je MessageAck / AckStatus ACCEPTED. Ukoliko je AckStatus MSG_NOT_VALID ili SYSTEM_ERROR, tada se element B2GoutgoingInvoiceEnvelope ne pojavljuje u odgovornoj poruci.
Ukoliko je UBL dokument ispravan, tada se pojavljuje element CorrectB2GOutgoingInvoice s podacima o identifikatoru računa iz sustava pošiljatelja (broj računa), identifikator računa pod kojim je zaprimljen u sustav e-Račun te vremenske oznake zaprimanja.
Ukoliko je UBL dokument neispravan, tada se pojavljuje element IncorrectB2GOutgoingInvoice s podacima o identifikatoru računa iz sustava pošiljatelja (broj računa), šifra greške i opis (odvojeni delimiterom ukoliko je više grešaka). U tom slučaju potrebno je ispraviti greške te poslati poruku ponovno u sustav.
Slanje povratne potvrdne poruke sustava
Metoda za dohvat statusa izlaznog računa
Ova metoda služi za provjeru statusa određenog izlaznog računa. Kao identifikatori se koriste broj računa iz sustava pošiljatelja i godina izdavanja računa.
Elementi GetB2GOutgoingInvoiceStatusMsg poruke (metoda GetB2GOutgoingInvoiceStatus)
HeaderSupplier
MessageID - Jedinstveni broj poruke
SupplierID - Identifikator izdavatelja (OIB) – (9934:12345678909)
AdditionalSupplierID - Dodatni identifikator izdavatelja (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja
MessageType - Tip poruke: 9011 – dohvat statusa izlaznog računa
MessageAttributes – Atributi poruke
Data
B2GOutgoingInvoiceStatus
SupplierInvoiceID - Identifikator računa u sustavu pošiljatelja
InvoiceYear - Godina računa u sustavu pošiljatelja
DocumentCurrencyCode - true/false ispis valute iznosa djelomičnog plaćanja u odgovornoj poruci (neobavezan element)
Elementi GetB2GOutgoingInvoiceStatusAckMsg poruke
MessageAck
MessageID - Jedinstveni broj poruke
MessageAckID - Jedinstveni broj poruke na koju se odnosi odgovor
MessageType - Tip poruke: 9012 – sinkroni odgovor na GetB2GOutgoingInvoiceStatusMsg
AckStatus – status odgovora
ACCEPTED ili
MSG_NOT_VALID ili
SYSTEM_ERROR
AckStatusCode – Šifra statusa iz sustava
AckStatusText – (opcinalno) – Opis statusa iz sustava
B2GOutgoingInvoiceStatus
SupplierID - Identifikator pošiljatelja računa u sustavu e-Račun
AdditionalSupplierID - Dodatni identifikator izdavatelja (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja
InvoiceID - Identifikator računa u sustavu e-Račun
SupplierInvoiceID - Identifikator računa u sustavu pošiljatelja
InvoiceTimestamp - Timestamp računa u sustavu e-RačunB2G
DocumentStatus - Status u sustavu e-Račun
StatusCode - Šifra statusa u sustavu e-Račun
StatusText - Opis šifre statusa u sustavu e-Račun
StatusTimestamp - Timestamp statusa u sustavu e-RačunB2G
Note - Napomena statusa (npr. razlog odbijanja računa)
PartialAmount - Iznos djelomično plaćenog računa
DocumentCurrencyCode - Valuta iznosa djelomičnog plaćanja (neobavezan element)
Metoda za dohvat registra Primatelja
Ova se poruka koristi za dohvat liste Primatelja iz registra sustava "e-Račun za državu".
Filtriranje je moguće prema OIB broju, nazivu poslovnog subjekta ili datumu. Ukoliko se želi dohvatiti kompletni registar, kao vrijednosti polja "SearchField" i "SearchValue" se upisuje "ALL". Ukoliko se pretraživanje radi prema OIB broju, kao vrijednosti polja "SearchField" se upisuje "OIB", a u polje "SearchValue" se upisuje OIB broj s "HR" prefiksom, npr. "HR01234567890".Ukoliko se pretraživanje radi prema nazivu poslovnog subjekta, kao vrijednosti polja "SearchField" se upisuje "NAZIV", a u polje "SearchValue" se upisuje dio i kompletan naziv poslovnog subjekta. Kod pretraživanja prema datumu upisuju se datumi u formatu GGGG-MM-DD.
Kod dohvata kompletnog registra i kod filtriranja prema nazivu i OIB broju, u odgovoru se šalju samo aktivni korisnici. U slučaju filtriranja prema datumu, u odgovoru se šalju aktivni i neaktivni korisnici za navedeno razdoblje.
Elementi GetReceiverListMsg poruke
HeaderSupplier - Zaglavlje poruke
MessageID - Jedinstveni broj poruke
SupplierID - OIB izdavatelja (npr. 9934:12345678901)
AdditionalSupplierID - Dodatni identifikator izdavatelja (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja
MessageType – Tip poruke: 50041 – dohvat registra primatelja
MessageAttributes - Atribut poruke
Data
ReceiverList - Dohvat liste primatelja iz registra
Filter - Filter za dohvat
DateRange
From - Datum od
To - Datum do
TextSearch
SearchField - Polje za pretragu ("ALL", "OIB" ili "NAZIV")
SearchValue – Vrijednost polja ("ALL" OIB broj ili naziv)
Elementi GetReceiverListAckMsg poruke
MessageAck
MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
MessageAckID - Jedinstveni broj poruke odgovora
MessageType - Tip poruke: 50042– sinkroni odgovor na GetReceiverListMsg
AckStatus - Status odgovora
AckStatusCode - Šifra statusa iz sustava
AckStatusText - Opis statusa iz sustava
ReceiverList - Omotač upita za dohvat liste primatelja iz registra
Receiver
RegistrationName - Naziv tvrtke primatelja računa
ISOCode - ISO kod države (HR)
CompanyID – OIB
PostalAddress
StreetName - Ulica
BuildingNumber - Kućni broj
PostalCode - Poštanski broj
CityName – Grad
Country – Država
AddressLine – Adresa u jednoj liniji
BusinessBranch - Poslovna jedinica
EndpointID - Identifikator poslovne jedinice
EndpointIDSchemeID - Identifikator shema (CEF lista)
PartyIdentificationID - Identifikator poslovne jedinice (npr. 9934:OIB::HR99:1234)
PartyIdentificationIDSchemeID - Identifikator shema (ISO 6523 npr. 0088->GLN)
BusinessBranchName - Naziv poslovne jedinice
PostalAddress – Adresa
StreetName - Ulica
BuildingNumber - Kućni broj
PostalCode - Poštanski broj
CityName – Grad
Country – Država
AddressLine – Adresa u jednoj liniji
Activity - Aktivnost poslovne jedinice
Sheme poruka i definicija web servisa
Sheme poruka i definicija web servisa (WSDL) nalazi se ovdje.
UBL sheme
Invoice: https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd
Credit Note: https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-CreditNote-2.1.xsd
Common sheme (potrebne su sve): https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/common/
Tipovi i opisi poruka u razmjeni
Slijedi tablica s opisima tipova poruka i odgovornih poruka:
Tip poruke | Opis | Poruka/metoda |
9999 | Echo | EchoMsg |
10000 | Sinkroni odgovor na Echo | EchoAckMsg |
9001 | Slanje izlaznog računa | SendB2GOutgoingInvoiceMsg |
9002 | Sinkroni odgovor na slanje izlaznog računa | SendB2GOutgoingInvoiceAckMsg |
9011 | Dohvat statusa izlaznog računa | GetB2GOutgoingInvoiceStatusMsg |
9012 | Sinkroni odgovor na dohvat statusa izlaznog računa | GetB2GOutgoingInvoiceStatusAckMsg |
Postupci prije produkcije
Prije puštanja na produkcijski sustav nužna je verifikacija uspješne razmjene podataka na testnim okruženjima Fine i Pošiljatelja.
Ne može se napraviti iznimka izostajanja testiranja razmjene, na testnim okruženjima Fine i Pošiljatelja. Jednako tako je potrebno detaljno dokumentirati komponente razmjene podataka.