Tehnička specifikacija - Zaprimanje računa web servisom- asinkronom obradom
U ovom tekstu opisuje se način povezivanja sustava Primatelja sa sustavom Fine u svrhu zaprimanja ulaznog računa od Pošiljatelja prema Primatelju. Isti je namijenjen svim zainteresiranim stranama koje će sudjelovati u implementaciji rješenja na strani Primatelja.
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 sustavu e-Račun |
Primatelj | Primatelj računa iz sustava e-Račun |
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 poslovne subjekte 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 poslovne subjekte,
- 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 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:
- ReceiveB2BIncomingInvoiceMsg
- Šalje se samo strukturirani dokument (xml)
- ReceiveB2BIncomingInvoicePdfMsg
- 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 ReceiveB2BIncomingInvoiceMsg poruke (metoda receiveB2BIncomingInvoice):
- 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
- IncomingInvoiceEnvelope
- DocumentType
- XMLStandard - Standard XML dokumenta (UBL)
- 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
- InvoiceEnvelope – Omotač e-Računa po UBL shemiili
- CreditNoteEnvelope – Omotač e-Odobrenja po UBL shemi
Elementi ReceiveB2BIncomingInvoicePdfMsg poruke (metoda receiveB2BIncomingInvoicePdf):
- 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
- IncomingInvoicePdfEnvelope
- DocumentType - Tip dokumenta
- XMLStandard - Standard XML dokumenta (UBL)
- 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
- InvoiceEnvelope – Omotač e-Računa po UBL shemiili
- CreditNoteEnvelope – Omotač e-Odobrenja po UBL shemi
- PdfDocument - Pdf dokumenta (Invoice, CreditNote)
- DocumentType - Tip dokumenta
- IncomingInvoicePdfEnvelope
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".
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 | ReceiveB2BIncomingInvoiceMsg |
406 | Odgovor na primanje ulaznog računa bez PDF-a | ReceiveB2BIncomingInvoiceAckMsg |
411 | Primanje ulaznog računa s PDF-om | ReceiveB2BIncomingInvoicePdfMsg |
412 | Odgovor na primanje ulaznog računa s PDF-om | ReceiveB2BIncomingInvoicePdfAckMsg |