Tehnička spec. za spajanje putem sinkronih web servisa - Slanje računa (stari način razmjene)
Ovim se tekstu opisuje način povezivanja sustava Pošiljatelja sa sustavom Fine u svrhu slanja računa od Pošiljatelja prema Primatelju. Isti je namijenjen svim zainteresiranim stranama koje će sudjelovati u implementaciji rješenja na strani Pošiljatelja.
U ovom se tekstu opisuju 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 krajnjeg Primatelja.
Definicije i skraćenice
PKI | Public Key Infrastructure – Infrastruktura javnog ključa |
SSL | Secure Sockets Layer – protokol koji omogućava zaštitu komunikacijskog kanala |
Pošiljatelj | Pošiljatelj računa kroz Finin sustav e-Račun |
Primatelj | Primatelj računa kroz Finin sustav e-Račun |
RDC | Registar za digitalne certifikate |
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 digitalnim potpisivanjem SOAP poruke Fininim digitalnom certifikatom. Kako bi se ostvarila kontrola elektroničkog potpisa, Fina radi provjeru je li OIB broj naveden u poruci jednak OIB broju na koji je izdan certifikat. U slučaju da ovi OIB brojevi nisu jednaki, poruka se odbija i ne ulazi u Finin sustav.
Za potrebe testiranja, Pošiljatelj dobavlja Finini DEMO certifikat, a za produkciju produkcijski certifikat. U testnoj okolini nije dozvoljeno slanje SOAP poruka potpisanih produkcijskim certifikatom, ni obrnuto.
Komunikacijski uvjeti
Razmjena podataka u sustavu e-Račun za poslovne korisnike 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 poslovne korisnike.
Za ovakvo automatizirano slanje računa Pošiljatelj treba sljedeće:
- zatražiti od Fine Demo i produkcijski certifikat za potrebe potpisivanja SOAP poruka
- 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 koje se mogu slati Web servisom sustava E-račun za poslovne korisnike su:
- račun,
- odobrenje,
- opomena,
- specifikacija računa,
- prilozi dokumentu.
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 za slanje izlaznih e-računa (SendB2BOutgoingInvoice) i slanje probne, echo poruke,
- prilikom poziva Web servisa Fine uspostavljat će se SSL veza,
- SOAP poruke će se potpisivati Fininim certifikatom,
- za svaku SOAP poruku postojat će potvrdna SOAP poruka (acknowledgement message).
Slanje Echo poruke
Slanje izlaznog računa
Provjera rada Web servisa
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, odobrenja ili opomene, 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 - Jedinstveni identifikator izdavatelja u sustavu e-Račun
- MessageType - Tip poruke: 9999 – echo poruka
- MessageAttributes – Atributi poruke
- Data
- EchoData
- Echo - Sadržaj teksta
- EchoData
Elementi EchoAckMsg poruke
- MessageAck
- MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
- MessageAckID - Jedinstveni broj odgovorne poruke
- 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
Web servis za slanje izlaznih poruka
Nakon uspješnog slanja echo SOAP poruke, Pošiljatelj kreira SOAP poruku za slanje:
Elementi SendB2BOutgoingInvoiceSyncMsg poruke (metoda SendB2BOutgoingInvoice):
- HeaderSupplier
- MessageID - Jedinstveni broj poruke
- SupplierID - Jedinstveni identifikator izdavatelja u sustavu e-Račun
- MessageType - Tip poruke: 1001 – slanje izlaznog računa
- MessageAttributes – Atributi poruke
- Data
- B2BOutgoingInvoiceEnvelope
- SupplierInvoiceID – Identifikator računa u sustavu pošiljatelja
- BuyerID – Identifikator primatelja računa u sustavu.
- InvoiceEnvelope – Omotač e-Računa po UBL shemi
- CreditNoteEnvelope – Omotač e-Odobrenja po UBL shemi
- ReminderEnvelope – Omotač e-Opomene po UBL shemi
- UtilityStatementEnevelope – Omotač specifikacije računa
- AttachedDocumentEnvelope – Omotač privitaka računa
- B2BOutgoingInvoiceEnvelope
Slanje poruke izlaznog računa
Elementi SendB2BOutgoingInvoiceSyncAckMsg poruke:
- MessageAck
- MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
- MessageAckID - Jedinstveni broj odgovorne poruke
- MessageType - Tip poruke: 1002 – sinkroni odgovor na SendB2BOutgoingInvoiceMsg
- AckStatus – status odgovora
- ACCEPTED ili
- MSG_NOT_VALID ili
- SYSTEM_ERROR
- AckStatusCode – Šifra statusa iz sustava
- AckStatusText – (opcinalno) – Opis statusa iz sustava
- B2BoutgoingInvoiceEnvelope
- CorrectB2BOutgoingInvoice - Ispravan izlazni račun
- SupplierInvoiceID - Identifikator računa u sustavu Pošiljatelja
- InvoiceID - Identifikator računa u sustavu e-RačunB2B
- InvoiceTimestamp - Vrijeme zaprimanja računa u sustav
- IncorrectB2BOutgoingInvoice
- 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.
- CorrectB2BOutgoingInvoice - Ispravan izlazni račun
Odgovorna poruka sastoji se od dva dijela:
- MessageAck
- B2BoutgoingInvoiceEnvelope
U MessageAck dijelu se nalaze osnovni podaci o samoj SOAP poruci, dok se u dijelu B2BoutgoingInvoiceEnvelope nalaze podaci o obradi poslanog računa.
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 B2BoutgoingInvoiceEnvelope dijelu se nalaze podaci o obrađenom dokumentu (računu, odobrenju, opomeni,…) i cijeli element se pojavljuje isključivo ako je MessageAck / AckStatus ACCEPTED. Ukoliko je AckStatus MSG_NOT_VALID ili SYSTEM_ERROR, tada se element B2BoutgoingInvoiceEnvelope ne pojavljuje u odgovornoj poruci.
Ukoliko je UBL dokument ispravan, tada se pojavljuje element CorrectB2BOutgoingInvoice 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 IncorrectB2BOutgoingInvoice 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
Sheme poruka i definicija Web servisa
Sheme poruka i definicija Web servisa nalazi se ovdje.
UBL sheme
UBL sheme nalaze se ovdje.
Opis statusa i grešaka 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 |
1001 | Slanje izlaznog računa | SendB2BOutgoingInvoiceMsg |
1002 | Sinkroni odgovor slanje izlaznog računa | SendB2BOutgoingInvoiceAckMsg |
Slijede tablice s opisima statusa odgovornih poruka za opisane Web servise:
Na strani Pošiljatelja (prima promjenu statusa)
AckStatus | AckStatusCode | AckStatusText |
ACCEPTED | 10 | Poruka zaprimljena |
MSG_NOT_VALID | 90 | XML poruka nije ispravan |
MSG_NOT_VALID | 91 | Potpis poruke nije ispravan |
SYSTEM_ERROR | 99 | Sistemska greška na strani web servisa + opis |
Slijede tablice s opisima statusa izlaznih računa u razmjeni za opisane web servise:
Na strani Pošiljatelja (prima promjenu statusa)
Status | Opis |
1 | Obavijest o plaćanju |
2 | Odbijen |
3 | Odobren (prihvaćen) |
4 | Neobrađen (automatski iz sustava e-račun) |
6 | Plaćen u Internet bankarstvu (automatski iz sustava e-račun) |
Na strani Primatelja (šalje promjenu statusa)
Status | Opis |
1 | Obavijest o plaćanju |
2 | Odbijen |
3 | Odobren (prihvaćen) |
Slijedi tablica s opisima statusa grešaka u razmjeni za opisane Web servise:
Šifra greške | Opis greške | Poruka |
E000151 | Identifikator poslovnog subjekta iz zaglavlja poruke nije definiran u sustavu e-Račun kao aktivni korisnik | Nepoznat ID poslovnog subjekta |
E000322 | Greška se javlja ako e-račun ne odgovara XML shemi e-računa | e-račun ne odgovara xml schemi |
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.
Specifikacija e-računa (UBL-Invoice)
Nacrti specifikacije e-računa Ministarstva gospodarstva, rada i poduzetništva RH, Povjerenstva za e-račun.