Tehnička specifikacija za spajanje putem sinkronih web servisa - Zaprimanje i ostale metode (stari način razmjene)
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.