U ovom tekstu opisuje se 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 nastavku su opisane sve poruke koje sustavi razmjenjuju, načini razmjene te razine sigurnosti, odnosno zaštite prijenosa.

Podaci će se razmjenjivati korištenjem XML poruka putem SOAP 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

PKI Public Key Infrastructure – Infrastruktura javnog ključa
EV  Extended Validation – postupak provjere poslovnog subjekta prilikom izdavanja SSL certifikata
SSL  Secure Sockets Layer – protokol koji omogućava zaštitu komunikacijskog kanala
Pošiljatelj  Pošiljatelj računa prema sustavu Fine
Primatelj  Krajnji primatelj računa
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 podataka u SOAP poruci ostvaruje se digitalnim potpisivanjem SOAP poruke digitalnim certifikatom korištenjem WS-Security standarda. Zaštita integriteta podataka u XML-u računa ostvaruje se digitalnim potpisivanjem XML-a u skladu s UBL specifikacijom korištenjem digitalnog certifikata. Kako bi se ostvarila kontrola elektroničkog potpisa, Fina radi provjeru je li OIB broj naveden u XML-u računa jednak OIB broju na koji je izdan certifikat kojim je račun potpisan. U slučaju da OIB brojevi nisu jednaki, poruka se odbija i ne ulazi u Finin sustav.

Za potrebe testiranja, Pošiljatelj može koristiti Finin DEMO certifikat, a za produkciju produkcijski certifikat.

 

Komunikacijski uvjeti

Razmjena podataka u sustavu e-Račun za poslovne subjekte 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 subjekte.

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 ovog dokumenta.

 

Web servis

Fina je sa svoje strane izradila web servis za zaprimanje podataka prema standardiziranoj XML shemi.

Dokumenti koji se mogu slati web servisom sustava e-Račun  za poslovne korisnike su:

  • Račun (s popratnom dokumentacijom kao prilogom),
  • Odobrenje (s popratnom dokumentacijom kao prilogom).

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 s metodama za slanje poruke s izlaznim e-računom i e-odobrenjem (SendB2BOutgoingInvoice) te s metodama za slanje poruke za dohvat statusa izlaznog računa i probne, echo poruke,
  • prilikom poziva  web servisa Fine uspostavljat će se SSL veza s klijentskom autentifikacijom (2-way SSL),
  • SOAP poruke i dokumenti u poruci će se potpisivati Fininim certifikatom,
  • za svaku SOAP poruku postojat će potvrdna SOAP poruka (acknowledgement message).

 

Pošiljatelj ima na raspolaganju korištenje nekoliko metoda za slanje računa:

  • EchoMsg

  • SendB2BOutgoingInvoiceMsg

  • GetB2BOutgoingInvoiceStatusMsg

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 ili odobrenja, 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 - Identifikator izdavatelja (OIB) – (9934:12345678909)
    • AdditionalSupplierID - Dodatni identifikator izdavatelja ("Interna šifra", JUS,...) - "HR99:123456"
    • ERPID - Identifikator ERP providera
    • MessageType - Tip poruke: 9999 – echo poruka
    • MessageAttributes – Atributi poruke
  • Data
    • EchoData
      • Echo -  Sadržaj teksta

 

Elementi EchoAckMsg poruke

  • MessageAck
    • MessageID - Jedinstveni broj poruke
    • MessageAckID - Jedinstveni broj poruke na koju se odnosi odgovor
    • 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

Metoda za slanje izlaznih poruka (račun, odobrenje)

Nakon uspješnog slanja echo SOAP poruke, Pošiljatelj kreira SOAP poruku za slanje dokumenta:

Elementi SendB2BOutgoingInvoiceMsg poruke (metoda SendB2BOutgoingInvoice)

  • HeaderSupplier
    • MessageID - Jedinstveni broj poruke
    • SupplierID - Identifikator izdavatelja (OIB) – (9934:12345678909)
    • AdditionalSupplierID - Dodatni identifikator izdavatelja ("Interna šifra", JUS,...) - "HR99:123456"
    • ERPID - Identifikator ERP providera
    • MessageType - Tip poruke: 9001 – slanje izlaznog računa
    • MessageAttributes – Atributi poruke
  • Data
    • B2BOutgoingInvoiceEnvelope
      • XMLStandard - Standard XML dokumenta (UBL ili CII)
      • SpecificationIdentifier - Prilagodba XML dokumenta (fiksno - urn:cen.eu:en16931:2017)
      • SupplierInvoiceID – Identifikator računa u sustavu pošiljatelja
      • BuyerID – Identifikator primatelja računa u sustavu (OIB) – (9934:12345678909)
      • AdditionalBuyerID - Dodatni identifikator primatelja računa u sustavu ("Interna šifra", JUS, ...) – ("HR99:123456")
      • InvoiceEnvelope – Omotač e-Računa po UBL shemi
      • CreditNoteEnvelope – Omotač e-Odobrenja po UBL shemi

Elementi SendB2BOutgoingInvoiceAckMsg poruke

  • MessageAck
    • MessageID - Jedinstveni broj poruke
    • MessageAckID - Jedinstveni broj poruke na koju se odnosi odgovor
    • MessageType  - Tip poruke: 9002 – sinkroni odgovor na SendB2BOutgoingInvoiceMsg
    • AckStatus – status odgovora
      • ACCEPTED ili
      • MSG_NOT_VALID ili
      • SYSTEM_ERROR
    • AckStatusCode – Šifra statusa iz sustava
    • AckStatusText – 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čun B2B
      • 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.

 

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.

 

Statusi poruka

AckStatus AckStatusCode AckStatusText
ACCEPTED     10     Poruka zaprimljena
MSG_NOT_VALID     90     XML poruka nije ispravna
MSG_NOT_VALID     91     Potpis poruke nije ispravan
SYSTEM_ERROR     99     Sistemska greška na strani web servisa + opis

 

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…) 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.

 

Metoda za dohvat statusa izlaznog računa

Ova metoda služi za provjeru statusa određenog izlaznog računa. Kao identifikatori se koriste broj računa iz sustava pošiljatelja i godina izdavanja računa.

Elementi GetB2BOutgoingInvoiceStatusMsg poruke (metoda GetB2BOutgoingInvoiceStatus)

  • HeaderSupplier
    • MessageID - Jedinstveni broj poruke
    • SupplierID - Identifikator izdavatelja (OIB) – (9934:12345678909)
    • AdditionalSupplierID - Dodatni identifikator izdavatelja ("Interna šifra", JUS,...) - "HR99:123456"
    • ERPID - Identifikator ERP providera
    • MessageType - Tip poruke: 9011 – dohvat statusa izlaznog računa
    • MessageAttributes – Atributi poruke
  • Data
    • B2BOutgoingInvoiceStatus
      • SupplierInvoiceID - Identifikator računa u sustavu pošiljatelja
      • InvoiceYear - Godina računa u sustavu pošiljatelja

Elementi GetB2BOutgoingInvoiceStatusAckMsg poruke

  • MessageAck
    • MessageID - Jedinstveni broj poruke
    • MessageAckID - Jedinstveni broj poruke na koju se odnosi odgovor
    • MessageType  - Tip poruke: 9012 – sinkroni odgovor na GetB2BOutgoingInvoiceStatusMsg
    • AckStatus – status odgovora
      • ACCEPTED ili
      • MSG_NOT_VALID ili
      • SYSTEM_ERROR
    • AckStatusCode – Šifra statusa iz sustava
    • AckStatusText – (opcinalno) – Opis statusa iz sustava
  • B2BOutgoingInvoiceStatus 
    • SupplierID - Identifikator pošiljatelja računa u sustavu e-Račun
    • AdditionalSupplierID - Dodatni identifikator izdavatelja ("Interna šifra", JUS,...) - "HR99:123456"
    • InvoiceID - Identifikator računa u sustavu e-Račun
    • SupplierInvoiceID - Identifikator računa u sustavu pošiljatelja
    • InvoiceTimestamp - Timestamp računa u sustavu e-Račun B2B
    • DocumentStatus - Status u sustavu e-Račun
      • StatusCode - Šifra statusa u sustavu e-Račun
      • StatusText - Opis šifre statusa u sustavu e-Račun
      • StatusTimestamp - Timestamp statusa u sustavu e-Račun B2B
      • Note - Napomena statusa (npr. razlog odbijanja računa)
      • PartialAmount - Iznos djelomično plaćenog računa

 

Sheme poruka i definicija web servisa

Sheme poruka i definicija web servisa (WSDL) nalazi se ovdje.

 

UBL sheme

Invoice: https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd

Credit Note: https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-CreditNote-2.1.xsd

Common sheme (potrebne su sve): https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/common/

 

Tipovi i opisi poruka 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
9001     Slanje izlaznog računa SendB2BOutgoingInvoiceMsg
9002     Sinkroni odgovor slanje izlaznog računa SendB2BOutgoingInvoiceAckMsg
9011     Dohvat statusa izlaznog računa GetB2BOutgoingInvoiceStatusMsg
9012     Sinkroni odgovor na dohvat statusa izlaznog računa GetB2BOutgoingInvoiceStatusAckMsg

 

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.