Tehnilčka specifikcija opisuje način povezivanja sustava Pošiljatelja s Fininim sustavom u svrhu slanja računa od Pošiljatelja prema Primatelju koji je korisnik državnog proračuna. Namijenjena je 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.

Podatci se razmjenjuju 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

Zaštita integriteta

Zaštita integriteta podataka u SOAP poruci ostvaruje se elektroničkim potpisivanjem SOAP poruke, korištenjem digitalnog certifikata te WS-Security standarda. Zaštita integriteta podataka u XML-u računa ostvaruje se elektroničkim potpisivanjem XML-a, korištenjem digitalnog certifikata te u skladu s UBL specifikacijom. 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. Ukoliko Pošiljatelj ne koristi Finine digitalne certifikate, nužno je da na testnoj okolini ne koristi isti certifikat kao na produkcijskoj okolini.

Komunikacijski uvjeti

Razmjena podataka u sustavu e-Račun za državu između Fine i Pošiljatelja obavlja 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 državu.

Za ovakvo automatizirano slanje računa Pošiljatelj treba:

• Zatražiti od Fine demo i produkcijski certifikat za potrebe potpisivanja SOAP poruka
• Prilagoditi ERP za kreiranje i slanje SOAP poruka

Web servis

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

Putem servisa e-Račun za državu se mogu slati:

• Računi (s popratnom dokumentacijom kao prilogom)
• Odobrenja (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). Podatci (Data) su definirani za svaku poruku posebno, a unutar elementa se nalazi specifična XML struktura, 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 (SendB2GOutgoingInvoice) te s metodama za slanje poruke za dohvat statusa izlaznog računa i probne, echo poruke
• Prilikom poziva web servisa Fine uspostavlja se SSL veza s klijentskom autentifikacijom
• SOAP poruke i dokumenti u poruci se potpisuju Fininim certifikatom
• Za svaku SOAP poruku postoji 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 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 (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja)
  • 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 SendB2GOutgoingInvoiceMsg poruke (metoda SendB2GOutgoingInvoice)

• HeaderSupplier
  • MessageID - Jedinstveni broj poruke
  • SupplierID - Identifikator izdavatelja (OIB) – (9934:12345678909)
  • AdditionalSupplierID - Dodatni identifikator izdavatelja (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja)
  • MessageType - Tip poruke: 9001 – slanje izlaznog računa
  • MessageAttributes – Atributi poruke
• Data
  • B2GOutgoingInvoiceEnvelope
    • 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 kupca (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru primatelja)
    • InvoiceEnvelope – Omotač e-Računa po UBL shemi
    • CreditNoteEnvelope – Omotač e-Odobrenja po UBL shemi

Elementi SendB2GOutgoingInvoiceAckMsg poruke

• MessageAck
  • MessageID - Jedinstveni broj poruke
  • MessageAckID - Jedinstveni broj poruke na koju se odnosi odgovor
  • MessageType - Tip poruke: 9002 – sinkroni odgovor na SendB2GOutgoingInvoiceMsg
  • AckStatus – status odgovora
    • ACCEPTED ili
    • MSG_NOT_VALID ili
    • SYSTEM_ERROR
  • AckStatusCode – Šifra statusa iz sustava
  • AckStatusText – (opcinalno) – Opis statusa iz sustava
• B2GoutgoingInvoiceEnvelope
  • CorrectB2GOutgoingInvoice - Ispravan izlazni račun
    • SupplierInvoiceID - Identifikator računa u sustavu Pošiljatelja
    • InvoiceID - Identifikator računa u sustavu e-RačunB2G
    • InvoiceTimestamp - Vrijeme zaprimanja računa u sustav
  • IncorrectB2GOutgoingInvoice
    • 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.

Povratna poruka se sastoji od dva dijela:

• MessageAck
• B2GOutgoingInvoiceEnvelope

U MessageAck dijelu se nalaze osnovni podaci o samoj SOAP poruci, dok se u dijelu B2GoutgoingInvoiceEnvelope nalaze podaci o obradi poslanog računa.

Statusi poruka

Ako je SOAP poruka u skladu s definicijom web servisa (wsdl), tada se u elementu MessageAck / AckStatus uvijek pojavljuje odgovor ACCEPTED bez obzira jesu li podatci, npr. računa, ispravni. Ako 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 B2GoutgoingInvoiceEnvelope 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 B2GoutgoingInvoiceEnvelope ne pojavljuje u povratnoj poruci.

Ako je UBL dokument ispravan, tada se pojavljuje element CorrectB2GOutgoingInvoice s podatcima o identifikatoru računa iz sustava pošiljatelja (broj računa), identifikatorom računa pod kojim je zaprimljen u sustav e-Račun, te vremenskom oznakom zaprimanja.

Ako je UBL dokument neispravan, tada se pojavljuje element IncorrectB2GOutgoingInvoice s podatcima o identifikatoru računa iz sustava pošiljatelja (broj računa), šifrom greške i opisom (odvojeni delimiterom, ako ima više grešaka). U tom slučaju potrebno je ispraviti greške te ponovno poslati poruku u sustav.

Slanje povratne potvrdne poruke sustava

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 GetB2GOutgoingInvoiceStatusMsg poruke (metoda GetB2GOutgoingInvoiceStatus)

• HeaderSupplier
  • MessageID - Jedinstveni broj poruke
  • SupplierID - Identifikator izdavatelja (OIB) – (9934:12345678909)
  • AdditionalSupplierID - Dodatni identifikator izdavatelja (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja)
  • MessageType - Tip poruke: 9011 – dohvat statusa izlaznog računa
  • MessageAttributes – Atributi poruke
• Data
  • B2GOutgoingInvoiceStatus
    • SupplierInvoiceID - Identifikator računa u sustavu pošiljatelja
    • InvoiceYear - Godina računa u sustavu pošiljatelja
    • DocumentCurrencyCode - true/false ispis valute iznosa djelomičnog plaćanja u odgovornoj poruci (neobavezan element)

Elementi GetB2GOutgoingInvoiceStatusAckMsg poruke

• MessageAck
  • MessageID - Jedinstveni broj poruke
  • MessageAckID - Jedinstveni broj poruke na koju se odnosi odgovor
  • MessageType - Tip poruke: 9012 – sinkroni odgovor na GetB2GOutgoingInvoiceStatusMsg
  • AckStatus – status odgovora
    • ACCEPTED ili
    • MSG_NOT_VALID ili
    • SYSTEM_ERROR
  • AckStatusCode – Šifra statusa iz sustava
  • AckStatusText – (opcinalno) – Opis statusa iz sustava
• B2GOutgoingInvoiceStatus
  • SupplierID - Identifikator pošiljatelja računa u sustavu e-Račun
  • AdditionalSupplierID - Dodatni identifikator izdavatelja (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja)
  • 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čunB2G
  • 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čunB2G
    • Note - Napomena statusa (npr. razlog odbijanja računa)
    • PartialAmount - Iznos djelomično plaćenog računa
    • DocumentCurrencyCode - Valuta iznosa djelomičnog plaćanja (neobavezan element)

Metoda za dohvat registra Primatelja

Ova se poruka koristi za dohvat liste Primatelja iz registra sustava "e-Račun za državu".

Filtriranje je moguće prema OIB broju, nazivu poslovnog subjekta ili datumu. Ako se želi dohvatiti kompletni registar, kao vrijednosti polja "SearchField" i "SearchValue" se upisuje "ALL". Ukoliko se pretraživanje radi prema OIB broju, kao vrijednosti polja "SearchField" se upisuje "OIB", a u polje "SearchValue" se upisuje OIB broj s "HR" prefiksom, npr. "HR01234567890". Ako se pretraživanje radi prema nazivu poslovnog subjekta, kao vrijednosti polja "SearchField" se upisuje "NAZIV", a u polje "SearchValue" se upisuje dio i kompletan naziv poslovnog subjekta. Kod pretraživanja prema datumu upisuju se datumi u formatu GGGG-MM-DD.

Kod dohvata kompletnog registra i kod filtriranja prema nazivu i OIB broju, u odgovoru se šalju samo podatci aktivnih korisnika. U slučaju filtriranja prema datumu, u odgovoru se šalju podatci o aktivnim i neaktivnim korisnicima, za navedeno razdoblje.

Elementi GetReceiverListMsg poruke

• HeaderSupplier - Zaglavlje poruke
  • MessageID - Jedinstveni broj poruke
  • SupplierID - OIB izdavatelja (npr. 9934:12345678901)
  • AdditionalSupplierID - Dodatni identifikator izdavatelja (poslovne jedinice, npr. HR99:12345 gdje je 12345 šifra poslovne jedinice koja je navedena u registru izdavatelja)
  • MessageType – Tip poruke: 50041 – dohvat registra primatelja
  • MessageAttributes - Atribut poruke
• Data
  • ReceiverList - Dohvat liste primatelja iz registra
    • Filter - Filter za dohvat
      • DateRange
        • From - Datum od
        • To - Datum do
      • TextSearch
        • SearchField - Polje za pretragu ("ALL", "OIB" ili "NAZIV")
        • SearchValue – Vrijednost polja ("ALL" OIB broj ili naziv)

Elementi GetReceiverListAckMsg poruke

• MessageAck
  • MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
  • MessageAckID - Jedinstveni broj poruke odgovora
  • MessageType - Tip poruke: 50042– sinkroni odgovor na GetReceiverListMsg
  • AckStatus - Status odgovora
  • AckStatusCode - Šifra statusa iz sustava
  • AckStatusText - Opis statusa iz sustava
• ReceiverList - Omotač upita za dohvat liste primatelja iz registra
  • Receiver
    • RegistrationName - Naziv tvrtke primatelja računa
    • ISOCode - ISO kod države (HR)
    • CompanyID – OIB
    • PostalAddress
      • StreetName - Ulica
      • BuildingNumber - Kućni broj
      • PostalCode - Poštanski broj
      • CityName – Grad
      • Country – Država
      • AddressLine – Adresa u jednoj liniji
    • BusinessBranch - Poslovna jedinica
      • EndpointID - Identifikator poslovne jedinice
      • EndpointIDSchemeID - Identifikator shema (CEF lista)
      • PartyIdentificationID - Identifikator poslovne jedinice (npr. 9934:OIB::HR99:1234)
      • PartyIdentificationIDSchemeID - Identifikator shema (ISO 6523 npr. 0088->GLN)
      • BusinessBranchName - Naziv poslovne jedinice
      • PostalAddress – Adresa
        • StreetName - Ulica
        • BuildingNumber - Kućni broj
        • PostalCode - Poštanski broj
        • CityName – Grad
        • Country – Država
        • AddressLine – Adresa u jednoj liniji
      • Activity - Aktivnost poslovne jedinice

Sheme poruka i definicija web servisa

Sheme poruka i definicija web servisa (WSDL) nalaze 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

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 te je potrebno detaljno dokumentirati komponente razmjene podataka.