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 primatelja u sustavu e-Račun
    • 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 shemi
      ili
    • 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 primatelja u sustavu e-Račun
    • 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 shemi
        ili
      • CreditNoteEnvelope – Omotač e-Odobrenja po UBL shemi
      • 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".
 

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