U ovom tekstu opisuje se način povezivanja sustava Primatelja (korisnika državnog proračuna) sa sustavom Fine u svrhu zaprimanja dolaznog 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

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 shemiili
  • CreditNoteEnvelope – 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 shemiili
  • CreditNoteEnvelope – Omotač e-Odobrenja po UBL shemiili
  • PdfDocument - 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: