Ovim se tekstom opisuje način povezivanja sustava Pošiljatelja sa sustavom Fine u svrhu interakcije s korisničkim pretincom na Fininom sustavu putem Web servisa.
Korisnik u sustav može poslati sljedeće poruke:
- Poruka za dohvat liste ulaznih računa,
- Poruka za dohvat pojedinog ulaznog računa, 
- Poruka za dohvat statusa izlaznog računa,
- Poruka za promjenu statusa ulaznog računa.

Isti je namijenjen svim zainteresiranim stranama koje će sudjelovati u implementaciji rješenja na strani Korisnika.

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 Korisnika.

 

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
Korisnik Svaki korisnik Fininog 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

 

Zaštita integriteta

Zaštita integriteta ostvaruje se digitalnim potpisivanjem SOAP poruke Fininim digitalnom certifikatom. Prije slanja odgovora, Fina provjerava da li certifikat koji se koristi ima prava nad korisničkim pretincem na kojem se želi napraviti akcija. Ukoliko potpisni certifikat nema prava nad pretincom, poruka se odbija.

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.

Korisnik ima mogućnost korištenja Fininog aplikacijskog certifikata ili certifikata na kripto uređaju, ovisno o implementacijskom rješenju na strani ERP sustava Korisnika.

 

Komunikacijski uvjeti

Razmjena podataka u sustavu e-Račun za poslovne korisnike između Fine i Korisnika vrši se putem internetske mreže. Prilikom pozivanja Web servisa uspostavlja se SSL veza radi zaštite komunikacijskog kanala.

Za korištenje Web servisa Korisnik treba sljedeće:

  • zatražiti od Fine Demo i produkcijski certifikat za potrebe potpisivanja SOAP poruka,
  • prilagoditi ERP za kreiranje, potpisivanje i slanje SOAP poruka prema uputi iz narednih poglavlja.

 

Poruka za dohvat liste ulaznih računa

Ova se poruka koristi za dohvaćanje ulaznih računa. Korisnik za dohvaćanje računa koristi filter kojim određuje kriterije po kojima želi dohvatiti račune. Omogućeno je sljedeće filtriranje:

  • po statusu računa,
  • po datumu,
  • po iznosu,
  • po tekstu u računu.

Elementi GetB2BIncomingInvoiceListMsg poruke

  • HeaderBuyer - Zaglavlje poruke
    • MessageID - Jedinstveni broj poruke
    • BuyerID - Jedinstveni identifikator primatelja u sustavu e-Račun
    • MessageType - Tip poruke: 1101 – dohvat liste ulaznih računa
    • MessageAttributes - Atribut poruke
  • Data
    • B2BIncomingInvoiceList - Omotač upita za dohvat liste ulaznih računa
      • BuyerID - Identifikator primatelja računa u sustavu e-RačunB2B
      • DocumentType
        • DocumentTypeCode - Tip dokumenta
        • DocumentTypeText - Opis tipa dokumenta
      • Filter
        • InvoiceStatus
          • StatusCode - Šifra statusa u sustavu e-Račun
          • StatusText - Opis šifre statusa u sustavu e-Račun
          • Note - Napomena statusa (npr. razlog odbijanja računa)
        • DateRange
          • From - Datum od
          • To - Datum do
        • AmountRange
          • From - Iznos od
          • To - Iznos do
        • TextSearch
          • SearchField - Polje za pretragu (default ALL)
          • SearchValue - Tekst za pretragu

 

Dohvat liste ulaznih računa

Elementi GetB2BIncomingInvoiceListAckMsg poruke

Sinkroni odgovor na poruku za dohvat liste ulaznih račun.

  • MessageAck
    • MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
    • MessageAckID - Jedinstveni broj odgovorne poruke
    • MessageType - Tip poruke: 1102 – sinkroni odgovor na GetB2BIncomingInvoiceListMsg
    • AckStatus - Status odgovora
    • AckStatusCode - Šifra statusa iz sustava
    • AckStatusText - Opis statusa iz sustava
  • B2BIncomingInvoiceList
    • BuyerID - Identifikator primatelja računa u sustavu e-RačunB2B
    • B2BIncomingInvoice - Omotač ulaznog računa
      • DocumentType - Tip dokumenta
        • DocumentTypeCode - Tip dokumenta
        • DocumentTypeText - Opis tipa dokumenta
      • InvoiceStatus - Status dokumenta
        • StatusCode - Šifra statusa u sustavu e-Račun
        • StatusText - Opis šifre statusa u sustavu e-Račun
        • Note - Napomena statusa (npr. razlog odbijanja računa)
      • SupplierID - Identifikator pošiljatelja računa u sustavu
      • SupplierRegistrationName - Naziv pošiljatelja računa u sustavu
      • SupplierCompanyID - OIB pošiljatelja računa u sustavu
      • InvoiceID - Identifikator računa u sustavu e-RačunB2B
      • SupplierInvoiceID - Identifikator računa pošiljatelja
      • InvoiceIssueDate - Datum izdavanja
      • InvoicePayableAmount - Iznos računa

 

Sinkroni odgovor na poruku dohvat liste ulaznih računa

Poruka za dohvat ulaznog računa

Ova se poruka koristi za dohvaćanje određenog ulaznog računa. Za dohvat računa, korisnik treba navesti ID računa kojeg želi dohvatiti i podatke o tipu dokumenta.

Elementi GetB2BIncomingInvoiceMsg poruke

  • HeaderBuyer - Zaglavlje poruke
    • MessageID - Jedinstveni broj poruke
    • BuyerID - Jedinstveni identifikator primatelja u sustavu e-Račun
    • MessageType - Tip poruke: 1103 – dohvat ulaznog računa
    • MessageAttributes - Atribut poruke
  • Data - XML s podacima
    • B2BIncomingInvoice - Omotač upita za dohvat ulaznog računa
      • BuyerID - Identifikator primatelja računa u sustavu e-RačunB2B
      • InvoiceID - Identifikator računa u sustavu e-RačunB2B
      • DocumentType - Tip dokumenta za dohvat
        • DocumentTypeCode - Tip dokumenta
        • DocumentTypeText - Opis tipa dokumenta

 

Dohvaćanje određenog ulaznog računa

Elementi GetB2BIncomingInvoiceAckMsg poruke

Sinkroni odgovor na poruku za dohvat ulaznog računa.

  • MessageAck
    • MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
    • MessageAckID - Jedinstveni broj odgovorne poruke 
    • MessageType - Tip poruke: 1104 – sinkroni odgovor na GetB2BIncomingInvoiceMsg
    • AckStatus - Status odgovora
    • AckStatusCode - Šifra statusa iz sustava
    • AckStatusText - Opis statusa iz sustava
  • B2BIncomingInvoice
    • BuyerID - Identifikator primatelja računa u sustavu e-RačunB2B
    • InvoiceID - Identifikator računa u sustavu e-RačunB2B
    • DocumentType - Tip dokumenta za dohvat
      • DocumentTypeCode - Tip dokumenta
      • DocumentTypeText - Opis tipa dokumenta
    • InvoiceStatus - Status dokumenta za dohvat
      • StatusCode - Šifra statusa u sustavu e-Račun
      • StatusText - Opis šifre statusa u sustavu e-Račun
      • Note - Napomena statusa (npr. razlog odbijanja računa)
    • IncomingInvoiceEnvelope - Omotnica ulaznog računa
      • InvoiceEnvelope - Omotač e-Računa po UBL shemi
      • CreditNoteEnvelope - Omotač e-Odobrenja po UBL shemi
      • ReminderEnvelope - Omotač e-Opomene po UBL shemi
      • PdfDocument - PDF dokument
      • UtilityStatementEnvelope - Omotač specifikacije računa
      • AttachedDocumentEnvelope - Omotač privitaka računa

 

Sinkroni odgovor na poruku za dohvat određenog ulaznog računa

Poruka za dohvat statusa izlaznog računa

Ova se poruka koristi za dohvaćanje statusa pojedinog izlaznog računa, odnosno je li neki izlazni račun prihvaćen, plaćen ili odbijen od strane primatelja. Za dohvat statusa pojedinog računa Korisnik treba navesti podatke o računu.

Elementi GetB2BOutgoingInvoiceStatusMsg poruke

  • HeaderSupplier - Zaglavlje poruke
    • MessageID - Jedinstveni broj poruke
    • SupplierID - Jedinstveni identifikator izdavatelja u sustavu e-Račun
    • MessageType - Tip poruke: 1007
    • MessageAttributes - Atribut poruke
  • Data - XML s podacima
    • B2BOutgoingInvoiceStatus - Omotač upita za dohvat statusa izlaznog računa
      • SupplierID - Identifikator pošiljatelja računa u sustavu
      • SupplierInvoiceID - Identifikator računa u sustavu pošiljatelja
      • InvoiceID - Identifikator računa u sustavu e-RačunB2B

 

Elementi GetB2BOutgoingInvoiceStatusAckMsg poruke

  • MessageAck
    • MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
    • MessageAckID - Jedinstveni broj odgovorne poruke
    • MessageType - Tip poruke: 1008
    • AckStatus - Status odgovora
    • AckStatusCode - Šifra statusa iz sustava
    • AckStatusText - Opis statusa iz sustava
  • B2BOutgoingInvoiceStatus - Omotač upita za dohvat statusa izlaznog računa
    • SupplierID - Identifikator pošiljatelja računa u sustavu e-RačunB2B
    • InvoiceID - Identifikator računa u sustavu pošiljatelja
    • InvoiceStatus - Status u sustavu e-Račun
      • StatusCode - Šifra statusa u sustavu e-Račun
      • StatusText - Opis šifre statusa u sustavu e-Račun
      • Note - Napomena statusa (npr. razlog odbijanja računa)

 

Poruka za promjenu statusa ulaznog računa

Ova se poruka koristi za promjenu statusa pojedinog ulaznog računa. Za promjenu statusa Korisnik mora navesti ID računa i podatke o statusu koji se želi postaviti.

Elementi ChangeB2BIncomingInvoiceStatusMsg poruke

  • HeaderBuyer - Zaglavlje poruke
    • MessageID - Jedinstveni broj poruke
    • BuyerID - Identifikator primatelja računa u sustavu e-RačunB2B
    • MessageType - Tip poruke: 1105 – promjena statusa ulaznog računa
    • MessageAttributes - Atribut poruke
  • Data - XML s podacima
    • B2BIncomingInvoiceStatus
      • BuyerID - Identifikator primatelja računa u sustavu e-RačunB2B
      • InvoiceID - Identifikator računa u sustavu e-RačunB2B
      • InvoiceStatus - Status u koji se želi napraviti promjena u sustavu e-Račun
        • StatusCode - Šifra statusa u sustavu e-Račun
        • StatusText - Opis šifre statusa u sustavu e-Račun
        • Note - Napomena statusa (npr. razlog odbijanja računa)

 

Poruka za promjenu statusa ulaznog računa

Elementi ChangeB2BIncomingInvoiceStatusAckMsg poruke

Sinkroni odgovor na poruku za promjenu statusa ulaznog računa.

  • MessageAck
    • MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
    • MessageAckID - Jedinstveni broj odgovorne poruke
    • MessageType - Tip poruke: 1106 – sinkroni odgovor na ChangeB2BIncomingInvoiceStatusMsg
    • AckStatus - Status odgovora
    • AckStatusCode - Šifra statusa iz sustava
    • AckStatusText - Opis statusa iz sustava
  • Error
    • ErrorCode - Šifra greške odvojene delimiterom
    • ErrorMessage - Opis greške odvojene delimiterom
    • ErrorText - Dodatni tekst greške

 

Sinkroni odgovor na poruku za promjenu statusa ulaznog računa

Poruka za dohvat registra Primatelja servisa e-Račun

Ova se poruka koristi za dohvat liste Primatelja iz registra sustava Fina e-Račun za poslovne korisnike.

Filtriranje je moguće prema OIB broju, nazivu poslovnog subjekta ili datumu. Ukoliko 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". Ukoliko 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 aktivni korisnici. U slučaju filtriranja prema datumu, u odgovoru se šalju aktivni i neaktivni korisnici za navedeno razdoblje.
 

Elementi GetReceiverListMsg poruke

  • HeaderSupplier - Zaglavlje poruke
    • MessageID - Jedinstveni broj poruke
    • SupplierID - Jedinstveni identifikator izdavatelja u sustavu e-Račun
    • MessageType – Tip poruke: 1201 – 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)

 

Poruka za dohvat Primatelja iz registra korisnika sustava

Elementi GetReceiverListAckMsg poruke

  • MessageAck
    • MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
    • MessageAckID - Jedinstveni broj odgovorne poruke
    • MessageType - Tip poruke: 1202 – sinkroni odgovor na GetReceiverListMsg
    • AckStatus - Status odgovora
    • AckStatusType
    • 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 – Adresa
        • StreetName – Ulica
        • BuildingNumber - Kućni broj
        • PostalCode - Poštanski broj
        • CityName – Mjesto
        • Country – Država
        • AddressLine - Adresa u jednoj liniji
      • BusinessBranch - Poslovna jedinica
        • BuyerID - Identifikator poslovne jedinice (BuyerID)
        • SchemeName - Vrsta sheme poslovne jedinice (GLN, JUS, RKP,...)
        • BusinessBranchCode - Šifra poslovne jedinice
        • BusinessBranchName - Naziv poslovne jedinice
        • PostalAddress – Adresa poslovne jedinice
          • StreetName – Ulica
          • BuildingNumber - Kućni broj
          • PostalCode - Poštanski broj
          • CityName – Mjesto
          • Country – Država
          • AddressLine - Adresa u jednoj liniji
        • Activity - Aktivnost. 1-aktivan, 0-neaktivan

 

Sinkroni odgovor na poruku za dohvat liste Primatelja iz registra korisnika sustava

Poruka za dohvat izlaznog računa

Ova se poruka koristi za dohvaćanje određenog izlaznog računa. Za dohvat računa, korisnik treba navesti ID računa kojeg želi dohvatiti i podatke o tipu dokumenta.

Elementi GetB2BOutgoingInvoiceMsg poruke

  • HeaderBuyer 
    • MessageID - jedinstveni ID poruke, to može biti UUID ili neki drugi jedinstveni broj
    • SupplierID - ID pretinca pošiljatelja, odnosno ID pretinca do kojeg imamo pravo pristupa i sa kojeg želimo preuzeti izlazni račun
    • MessageType - Tip poruke: 1005 – dohvat izlaznog računa
    • MessageAttributes 
  • Data
    • B2BIncomingInvoice 
      • SupplierID - ID pretinca pošiljatelja, odnosno ID pretinca do kojeg imamo pravo pristupa i sa kojeg želimo preuzeti izlazni račun
      • InvoiceID – ID računa kojeg želimo preuzeti
      • DocumentType
        • DocumentTypeCode - Tip dokumenta (Primjerice 380 za račun)
        • DocumentTypeText - Opis tipa dokumenta (Primjerice „Račun“)

 

Elementi GetB2BOutgoingInvoiceAckMsg poruke

Sinkroni odgovor na poruku za dohvat ulaznog računa.

  • MessageAck
    • MessageID - Jedinstveni broj poruke na koju se odnosi odgovor
    • MessageAckID - Jedinstveni broj odgovorne poruke 
    • MessageType - Tip poruke: 1006 – sinkroni odgovor na GetB2BIncomingInvoiceMsg
    • AckStatus - Status odgovora
    • AckStatusCode - Šifra statusa iz sustava
    • AckStatusText - Opis statusa iz sustava
  • B2BIncomingInvoice
    • SupplierID - Identifikator pošiljatelja računa u sustavu e-RačunB2B
    • InvoiceID - Identifikator računa u sustavu e-RačunB2B
    • DocumentType - Tip dokumenta za dohvat
      • DocumentTypeCode - Tip dokumenta
      • DocumentTypeText - Opis tipa dokumenta
    • InvoiceStatus - Status dokumenta za dohvat
      • StatusCode - Šifra statusa u sustavu e-Račun
      • StatusText - Opis šifre statusa u sustavu e-Račun
    • OutgoingInvoiceEnvelope - Omotnica izlaznog računa
      • InvoiceEnvelope - Omotač e-Računa po UBL shemi (Base64)
      • CreditNoteEnvelope - Omotač e-Odobrenja po UBL shemi (Base64)
      • ReminderEnvelope - Omotač e-Opomene po UBL shemi (Base64)
      • PdfDocument - PDF dokument (Base64)
      • UtilityStatementEnvelope - Omotač specifikacije računa (Base64)
      • AttachedDocumentEnvelope - Omotač privitaka računa (Base64)

 

Sheme poruka i definicija web servisa

Sheme poruka i definicija Web servisa nalazi se ovdje.