Tehnička specifikacija - razmjena podataka web servisima asinkronom obradom
U ovom tekstu opisane su sve poruke koje sustavi razmjenjuju, načini razmjene te razine sigurnosti, odnosno zaštite prijenosa.
Podaci će se razmjenjivati korištenjem XML poruka putem 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 | Obveznik javne nabave |
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 |
Komunikacijski uvjeti
Razmjena podataka u sustavu e-Račun za državu između Primatelja i Fine vrši se putem internetske mreže. Zaštita prijenosnog kanala se radi korištenjem dvosmjernog kriptiranja kanala (2-way ssl) što znači da se pri uspostavljanju sigurne veze klijent predstavlja aplikacijskim certifikatom, a web server serverskim certifikatom.
Preduvjeti potrebni za uspostavu web servisa za zaprimanje računa Primatelj treba sljedeće:
- 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). Primatelj 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,
- zatražiti od Fine aplikacijski certifikat za potrebe potpisivanja SOAP poruka,
- prilagoditi sustav za zaprimanje SOAP poruka prema uputi iz ovog teksta.
Zaštita integriteta
Zaštita integriteta ostvaruje se digitalnim potpisivanjem SOAP poruke Fininim aplikacijskim certifikatom. Standard koji se koristi za izvedbu potpisa SOAP poruke je WS-Security (https://www.oasis-open.org/standards#wssv1.0).
Za potrebe testiranja, Primatelj dobavlja Finin aplikacijski DEMO certifikat, a za produkciju produkcijski certifikat. U testnoj okolini nije dozvoljeno slanje SOAP poruka potpisanih produkcijskim certifikatom, ni obrnuto.
Koncept razmjene podataka
Zaprimanje računa web servisima podrazumijeva potpuno automatizirano preuzimanje računa iz Fininog sustava u sustavu Primatelja.
Primatelju poruka (Korisniku državnog proračuna) se putem web servisa na njegovoj strani šalje ulazni račun po standardiziranoj XML shemi. Osim e-računa, moguće je poslati i e-Odobrenje.
Sustav Primatelja sinkrono odgovara potvrdnom porukom o primitku poruke. Primatelj obrađuje poruku s ulaznim dokumentom u svom sustavu. Ovisno o promjenama statusa ulaznog računa u sustavu Primatelja, Primateljev sustav šalje poruku na web servis Fine o promjeni statusa ulaznog računa.
Primatelj ima na raspolaganju korištenje dvije metode za zaprimanje računa:
- ReceiveB2GIncomingInvoiceMsg
- Šalje se samo strukturirani dokument (xml)
- ReceiveB2GIncomingInvoicePdfMsg
- Uz strukturirani dokument (xml), šalje se i dokument u PDF formatu
Web servis za zaprimanje ulaznog računa na strani Primatelja
Web servis na strani Primatelja treba implementirati jednu od sljedećih metoda za zaprimanje ulaznih računa:
Elementi ReceiveB2GIncomingInvoiceMsg poruke (metoda receiveB2GIncomingInvoice):
HeaderBuyer
MessageID - Jedinstveni broj poruke
BuyerID - OIB primatelja u sustavu e-Račun (npr. 9934:12345678901)
AdditionalBuyerID - Dodatni identifikator kupca (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru primatelja)
MessageType - Tip poruke
405 – primanje ulaznog e-računa
MessageAttributes – atribut poruke
Data
DocumentType
XMLStandard - Standard XML dokumenta (UBL ili CII)
SpecificationIdentifier - Prilagodba XML dokumenta (urn:cen.eu:en16931:2017 - fiksno)
DocumentTypeCode – Tip dokumenta
DocumentTypeText – Opis tipa dokumenta
InvoiceID – Identifikator računa u sustavu e-Račun
InvoiceTimestamp - Vrijeme zaprimanja računa u sustav
DataInterchangeMethod – Moguće vrijednosti „PKI“, „EDI“ ili „OTHER“
InvoiceEnvelope – Omotač e-Računa po UBL shemi
iliCreditNoteEnvelope – Omotač e-Odobrenja po UBL shemi
Elementi ReceiveB2GIncomingInvoicePdfMsg poruke (metoda receiveB2GIncomingInvoicePdf):
HeaderBuyer
MessageID - Jedinstveni broj poruke
BuyerID - OIB primatelja u sustavu e-Račun (npr. 9934:12345678901)
AdditionalBuyerID - Dodatni identifikator kupca (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru primatelja)
MessageType - Tip poruke
411 – primanje ulaznog e-računa
MessageAttributes – atributi poruke
Data
DocumentType - Tip dokumenta
XMLStandard - Standard XML dokumenta (UBL ili CII)
SpecificationIdentifier - Prilagodba XML dokumenta (urn:cen.eu:en16931:2017 - fiksno)
DocumentTypeCode – Tip dokumenta
DocumentTypeText – Opis tipa dokumenta
InvoiceID – Identifikator računa u sustavu e-Račun
InvoiceTimestamp - Vrijeme zaprimanja računa u sustav
DataInterchangeMethod – Moguće vrijednosti „PKI“, „EDI“ ili „OTHER“
InvoiceEnvelope – Omotač e-Računa po UBL shemi
iliCreditNoteEnvelope – Omotač e-Odobrenja po UBL shemi
iliPdfDocument - Pdf dokumenta (Invoice, CreditNote)
Elementi ReceiveIncomingInvoiceAckMsg i ReceiveIncomingInvoicePdfAckMsg poruke:
MessageAck
MessageID - Jedinstveni broj poruke
MessageAckID - Jedinstveni broj poruke na koju se odnosi odgovor
MessageType - Tip poruke
406 – odgovor web servisa za račun bez PDF-a
412 – odgovor web servisa za račun s PDF-om
AckStatus – status odgovora
ACCEPTED ili
MSG_NOT_VALID ili
SYSTEM_ERROR
AckStatusCode – Šifra statusa iz sustava – Default vrijednost '10' za uspješno zaprimanje
AckStatusText – (opcionalno) – Opis statusa iz sustava
Odgovorna poruka sadrži "MessageAck" element gdje se nalaze osnovni podaci o odgovoru web servisa. Ukoliko je SOAP poruka u skladu s definicijom web servisa (wsdl), tada se u elementu AckStatus pojavljuje odgovor ACCEPTED. 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 Primatelja (npr. runtime exception). U slučaju "SYSTEM_ERROR" tada je defaultna vrijednost AckStatusCode "99".
Slanje povratne potvrdne poruke
Sheme poruka i definicija web servisa
Sheme poruka i definicija web servisa (WSDL) nalazi se ovdje.
Tipovi poruka u razmjeni
Prije puštanja na produkcijski sustav nužna je verifikacija uspješne razmjene podataka na testnim okruženjima Fine i Primatelja.
Slijedi tablica s opisima tipova poruka i odgovornih poruka:
Tip poruke | Opis | Poruka/metoda |
405 | Primanje ulaznog računa bez PDF-a | ReceiveB2GIncomingInvoiceMsg |
406 | Odgovor na primanje ulaznog računa bez PDF-a | ReceiveB2GIncomingInvoiceAckMsg |
411 | Primanje ulaznog računa s PDF-om | ReceiveB2GIncomingInvoicePdfMsg |
412 | Odgovor na primanje ulaznog računa s PDF-om | ReceiveB2GIncomingInvoicePdfAckMsg |