Technical specifications - e-Invoice web service system for the government with synchronized processing
Brzi linkovi
Technical specification
Method for checking web service function
Method for retrieving incoming invoice lists
Method for retrieving an incoming invoice
Method for changing the status of an incoming invoice
Method for retrieving outbound Invoice lists
Method for retrieving an outgoing invoice
Message for receipt of registry from e-Invoice service
Status codes of invoices in exchange
This text describes all the messages exchanged by the systems, the modes of exchange, and the level of security, i.e., protection of transmissions.
The data will be exchanged using XML messages via the web service. This kind of data exchange does not depend on the technology used on the Sender side, or on Fina as an information intermediary, or on the part of budget users such as the final Recipient.
Prior to launching the production system, it is necessary to verify successful data exchange on Fina and Receiver test environments.
Definitions and Abbreviations
SSL | Secure Sockets Layer - a protocol that enables communication channel protection |
Sender | Invoice Sender to a government budget user |
Recipient | Payer to public procurement |
ERP | Enterprise Resource Planning - Business system on the Sender side |
SOAP | Simple Object Access Protocol - a protocol used to exchange data between two web service systems |
Communication conditions
Data exchange in the e-Invoice system for the government between the Recipient and Fina is done through the Internet. The transmission channel protection functions through the use of a two-way encrypted channel (2-way SSL), which means that before establishing a secure connection the client presents an application certificate, and the web server with a server certificate (SSL).
In order for the Recipient to successfully link to the Fina web service, the following prerequisites must be met:
- The recipient should request a Fina certificate for the need to sign SOAP messages and authentication on the system. For the purpose of testing, the Recipient must use a demo certificate, and for the purpose of linking to the production system, a production certificate should be used.
- The recipient needs to customize his ERP system to send SOAP messages
Integrity protection
Integrity protection is achieved by digitally signing the SOAP message with the Fina Certificate. The standard used to execute the SOAP message signature is WS-Security (https://www.oasis-open.org/standards#wssv1.0).
For testing purposes, the Recipient will receive the Fina DEMO certificate, and a production certificate for producing. In the testing environment, SOAP messages signed with production certificates are not allowed, and vice versa.
Data exchange concept
The recipient system depends on the operation it wishes to execute at the Fina service web site, sending a message by standardized XML schema. In the web service response, the Fina System synchronously sends the processing results, or an error if anything is wrong.
Reply messages contain a "MessageAck" element where basic information about web service response is found. If the SOAP message is consistent with the Web Services Definition (WSDL), ACCEPTED is displayed in the AckStatus element. If the SOAP message is not in accordance with the definition, MSG_NOT_VALID will appear in the response. The SYSTEM_ERROR value indicates that there are larger problems in the Fina system (e.g., runtime exception). In the case of "SYSTEM_ERROR", then the default value is AckStatusCode "99".
The recipient has the following methods available:
- EchoBuyer
- EchoBuyerMsg
- getB2GIncomingInvoiceList
- GetB2GIncomingInvoiceListMsg
- getB2GIncomingInvoice
- GetB2GIncomingInvoiceMsg
- GetB2GOutgoingInvoiceList
- GetB2GOutgoingInvoiceListMsg
- GetB2GOutgoingInvoice
- GetB2GOutgoingInvoiceMsg
- ChangeB2GIncomingInvoiceStatus
- poruka ChangeB2GIncomingInvoiceStatusMsg
- GetReceiverList
- poruka GetReceiverListMsg
Method for checking web service function (Echo method)
The Echo method can be used for checking the availability of web service.
Elements of EchoBuyerMsg messages
HeaderBuyer
MessageID - Unique message number
BuyerID - Buyer identifier (OIB) - (9934:12345678909)
AdditionalBuyerID - Additional buyer identifier (GLN, JUS, ...) - 0088:12345678901
MessageType - Message type: 9999 - echo message
MessageAttributes - Message attribute
Data
EchoData
Echo - Text content
Elements of EchoBuyerAckMsg messages
MessageAck
MessageID - Unique message number
MessageAckID - Unique message number to which the reply is addressed
MessageType - 10000 - Reply to echo message
AckStatus - Reply status
AckStatusCode - System status code
AckStatusText - System status description
EchoData
Echo - Text content
Method for retrieving incoming invoice lists
This method is used for retrieval of incoming invoice lists. To retrieve the invoice list, the recipient uses a filter that specifies the criteria by which they want to retrieve the invoices. The following filtering is enabled:
- by invoice status,
- by date,
- by amount,
- by the registered name of the sender.
The invoice list that you want to retrieve can also be filtered by entering the ID of the invoice to which and from which you want to retrieve it.
Elements of GetB2GIncomingInvoiceListMsg messages
HeaderBuyer
MessageID - Unique message number
BuyerID – Buyer OIB (e.g.9934:12,345,678,901)
AdditionalBuyerID - Additional buyer identifier (GLN, DUNS, ... e.g., 0088:123,456,789)
MessageType - Message type 9101 - status change of the incoming e-Invoice
MessageAttributes - Message attribute
Data
B2GIncomingInvoiceList
Filter - Retrieval Filter
InvoiceStatus
StatusCode - Status in the e-Invoice system (according to the table in Chapter 8)
Note - Status note (e.g., reason for rejection of invoice or partial payment)
PartialAmount - Partial payment amount
DateRange
From - Date from
That - Date to
AmountRange
From - Amount from
To - Amount to
TextSearch
SearchField - Search field (default ALL)
SearchValue - Search text (registered sender name)
InvoiceIDRange - The range for invoice retrieval through Fina InvoiceID
From - Invoice ID (not including this ID, greater than)
To - Invoice ID to (including that ID, less or equal to)
Elements of GetB2GIncomingInvoiceListAckMsg messages
Synchronous reply to an incoming invoice retrieval list message.
MessageAck
MessageID - Unique message number to which the answer relates
MessageAckID - Unique message reply number
MessageType - Message type: 9102 - synchronous response to GetB2GIncomingInvoiceListMsg
AckStatus - Reply status
AckStatusCode - System status code
AckStatusText - System status description
B2GIncomingInvoiceList
B2GIncomingInvoice – Incoming invoice envelope
DocumentType - Document type
XMLStandard - Standard XML document (UBL or CII)
SpecificationIdentifier - Customized XML document (urn:cen.eu:en16931:2017) - fixed
DocumentTypeCode - Document type
DocumentTypeText - Document type description
InvoiceStatus - Status document
StatusCode - Status in e-Invoice system
Note - Status note (e.g., reason for rejection of invoice or partial payment)
PartialAmount - Partial payment amount
SupplierID - Supplier identifier (OIB, e.g., 99 34:12345678901)
AdditionalSupplierID - Additional supplier identifier (GLN, e.g., 0088:12,345,678,901)
SupplierRegistrationName - Name of the invoice sender in the system
SupplierCompanyID - MB invoice sender in system
InvoiceID - Invoice identifier in the B2G e-Invoice system
SupplierInvoiceID - Sender invoice identifier
DataInterchangeMethod - Invoice transfer method (PKI, EDI, OTHER)
InvoiceIssueDate - Issue Date
InvoiceTimestamp – Invoice timestamp in e-Invoice B2G system
InvoicePayableAmount - Invoice Amount
Error
ErrorCode - Error codes separated by delimiter
ErrorMessage - Error description separated by a delimiter
ErrorText - Additional error text
Method for retrieving an incoming invoice
This method is used to retrieve a specific incoming invoice. To receive an invoice, the recipient should enter the invoice ID he wants to retrieve.
Elements of GetB2GIncomingInvoiceMsg messages
HeaderBuyer - Message header
MessageID - Unique message number
BuyerID – Buyer OIB (e.g.9934:12345678901)
AdditionalBuyerID - Additional buyer identifier (GLN, DUNS, ... e.g., 0088:123,456,789)
MessageType - Message Type: 9103 – Retrieval of incoming invoice
MessageAttributes - Message attributes
Data - XML with data
B2GIncomingInvoice – Envelope of query for retrieval of incoming invoice
InvoiceID - Invoice identifier in B2G e-Invoice system
Elements of GetB2GIncomingInvoiceAckMsg message
Synchronous reply to retrieval messages for incoming invoices.
MessageAck
MessageID - Unique message number to which the answer relates
MessageAckID - Unique message response number
MessageType - Message type: 9104 - synchronous response to GetB2BIncomingInvoiceMsg
AckStatus - Reply status
AckStatusCode - System status code
AckStatusText - System status description
B2GIncomingInvoice
InvoiceID - Invoice identifier in B2G e-Invoice system
InvoiceTimestamp – Invoice timestamp in e-Invoice B2G system
DocumentType – Type of document for retrieval
XMLStandard - Standard XML document (UBL or CII)
SpecificationIdentifier - Customized XML document (urn:cen.eu:en16931:2017) - fixed
DocumentTypeCode - Document type
DocumentTypeText - Document type description
InvoiceStatus - Status of document for retrieval
StatusCode – System status of an e-Invoice
Note - Status note (e.g., reason for rejection of invoice or partial payment)
PartialAmount - Partial payment amount
DataInterchangeMethod - Invoice transfer method (PKI, EDI, OTHER)
IncomingInvoiceEnvelope - Envelope for incoming document
InvoiceEnvelope - e-Invoice envelope by UBL schema
CreditNoteEnvelope – e-Approval envelope by UBL schema
PdfDocument - PDF document (e-Invoice or e-Approval)
Error
ErrorCode - Error codes separated by delimiter
ErrorMessage - Error description separated by a delimiter
ErrorText - Additional error text
Method for changing the status of an incoming invoice
This message is used to change the status of a specific incoming invoice. To change the status, the Recipient must specify the invoice ID and status information that they want to set.
After entering the "e-Invoice for the government" system, the initial status "RECEIVED" is automatically set. After entering the invoice into the system, the Recipient must download the invoice and confirm receipt of the invoice by submitting the status "RECEIVING_CONFIRMED". Only after the aforementioned status is set is it possible to send other available statuses.
ChangeB2GIncomingInvoiceStatusMsg elements
HeaderBuyer - Message header
MessageID - Unique message number
BuyerID - Buyer OIB (e.g., 9934:12345678901)
AdditionalBuyerID - Additional buyer identifier (GLN, DUNS, ... e.g., 0088:123,456,789)
MessageType - Message type: 107 - changing inbound invoice status
MessageAttributes - Message attributes
Data - XML with data
B2GIncomingInvoiceStatus
InvoiceID - Invoice identifier in the B2G e-Invoice system
InvoiceStatus - Status to which you want to make changes in e-Invoice system
StatusCode - Status in the B2G e-Invoice system (according to the table in Chapter 8)
Note - Status note (e.g., reason for rejection of invoice or partial payment)
PartialAmount - Partial payment amount
ChangeB2GIncomingInvoiceStatusAckMsg elements
Synchronous reply to a message for changing the status of an incoming invoice.
MessageAck
MessageID - Unique message number to which the answer relates
MessageAckID - Unique number of the reply message
MessageType - Message type: 108 - Synchronous response to ChangeB2GIncomingInvoiceStatusMsg
AckStatus - Reply status
AckStatusCode - System status code
AckStatusText - System status description
Error
ErrorCode - Error code separated by delimiter
ErrorMessage - Description of the error separated by a delimiter
ErrorText - Additional error text
Method for retrieving outbound Invoice lists
This method is used to retrieve a list of outgoing invoices. The invoice list retrieval uploader uses a filter that specifies the criteria by which it wants to retrieve the invoices. The following filtering is enabled:
By invoice status
By date
By amount
The invoice list that you want to retrieve can be filtered by entering the ID of the invoice to which and from which you want to retrieve it.
GetB2GOutgoingInvoiceListMsg elements
HeaderSupplier
MessageID - Unique message number
SupplierID – Supplier OIB (eg.9934:12,345,678,901)
AdditionalSupplierID - Additional supplier identifier (GLN, DUNS, ... e.g., 0088:123,456,789)
MessageType - Message type 9105 - Changing the incoming e-Invoice status
MessageAttributes - Message attribute
Data
B2GOutgoingInvoiceList
Filter - Retrieval filter
InvoiceStatus
StatusCode - Status in the e-Invoice system (according to the table in Chapter 8)
Note - Status note (e.g., reason for rejection of invoice or partial payment)
PartialAmount - Partial payment amount
DateRange
From - Date From
That - Date to
AmountRange
From - Amount from
To - Amount to
InvoiceIDRange - The range of the invoice within Fina InvoiceID
From - Invoice ID from (not including this ID, greater than)
To - Invoice ID to (including this ID, less than or equal to)
Elements of GetB2GOutgoingInvoiceListAckMsg messages
Synchronous reply to a message to get a list of outgoing Invoices.
MessageAck
MessageID - Unique message number to which the answer relates
MessageAckID - Unique message reply number
MessageType - Message type: 9106 - synchronous reply to GetB2GOutgoingInvoiceListMsg
AckStatus - Reply status
AckStatusCode - System status code
AckStatusText - System status description
B2GOutgoingInvoiceList
B2GOutgoingInvoice – Envelope of inbound invoice
DocumentType - Document type
XMLStandard - Standard XML Document (UBL or CII)
SpecificationIdentifier - Customized XML Document (urn:cen.eu:en16931:2017) - fixed
DocumentTypeCode - Document type
DocumentTypeText - Document type description
InvoiceStatus - Status of document
StatusCode - Status in e-Invoice system
Note - Status note (e.g., reason for rejection of invoice or partial payment)
PartialAmount - Partial payment amount
BuyerID - Buyer Identifier (OIB, e.g., 9934:12345678901)
AdditionalBuyerID - Additional buyer identifier (GLN, e.g., 0088:12,345,678,901)
BuyerRegistrationName - Name of the buyer invoice in the system
BuyerCompanyID - MB buyer invoice in the system
InvoiceID - Invoice identifier in e-Invoice B2G system
SupplierInvoiceID - Sender invoice identifier
DataInterchangeMethod - Invoice transfer method (PKI, EDI, OTHER)
InvoiceIssueDate - Issue date
InvoiceTimestamp – Invoice timestamp in e-Invoice B2G system
InvoicePayableAmount - Invoice amount
Error
ErrorCode - Error codes separated by a delimiter
ErrorMessage - Error description separated by a delimiter
ErrorText - Additional error text
Method for retrieving an outgoing invoice
This method is used to retrieve a specific outgoing invoice. To retrieve an invoice, the sender should enter the ID of the invoice which they want to retrieve.
Elements of GetB2GOutgoingInvoiceMsg messages
HeaderSupplier - Message header
MessageID - Unique message number
SupplierID – Supplier OIB (eg.9934:12345678901)
AdditionalSupplierID - Additional supplier identifier (GLN, DUNS, ... e.g., 0088:123,456,789)
MessageType - Message type: 9107 - retrieving incoming invoice
MessageAttributes - Message attribute
Data - XML with data
B2GOutgoingInvoice – Envelope of query for incoming invoice retrieval
InvoiceID - Invoice identifier in B2G e-Invoice system
Elements of GetB2GOutgoingInvoiceAckMsg messages
Synchronous reply to a message for outgoing invoice retrieval.
MessageAck
MessageID - Unique message number to which the answer relates
MessageAckID - Unique reply message number
MessageType - Message Type: 9108 - Synchronous Response to GetB2GIncomingInvoiceMsg
AckStatus - Reply status
AckStatusCode - System status code
AckStatusText - System status description
B2GOutgoingInvoice
InvoiceID - Invoice identifier in B2G e-Invoice system
InvoiceTimestamp – Invoice timestamp in e-Invoice B2G system
DocumentType - Retrieval document type
XMLStandard - Standard XML document (UBL or CII)
SpecificationIdentifier - Customized XML document (urn:cen.eu:en16931:2017) - fixed
DocumentTypeCode - Document type
DocumentTypeText - Document type description
InvoiceStatus - Retrieval status of document
StatusCode - Status in e-Invoice system
Note - Status note (e.g., reason for rejection of invoice or partial payment)
PartialAmount - Partial payment amount
DataInterchangeMethod - Invoice transfer method (PKI, EDI, OTHER)
OutgoingInvoiceEnvelope – Envelope for incoming document
InvoiceEnvelope – Envelope of e-invoice by UBL schema
CreditNoteEnvelope – Envelope of e-approval by UBL schema
PdfDocument - PDF document (e-invoice or e-approval)
Error
ErrorCode - Error codes separated by a delimiter
ErrorMessage - Error description separated by a delimiter
ErrorText - Additional error text
Message for receipt of registry from e-Invoice service
This message is used to retrieve a Recipient list from the registry of the "e-Invoice for the government" system.
Filtering is possible by OIB number, business name, or date. If you want to retrieve a complete registry, enter the search value “ALL” into the "SearchField" and "SearchValue" fields. If the search is done based on an OIB number, enter “OIB” into the "SearchField" field, and into the “SearchValue" element, enter the OIB number beginning with the "HR" prefix, e.g., "HR01234567890". If the search is done based on the business name, enter “NAME” into the "SearchField" field, and enter the complete or partial name of the business entity into the "SearchValue" field. When searching based on a date, enter the date in the YYYY-MM-DD format.
Upon receiving the complete registry and when filtering by name and OIB number, replies are sent only to active users. In the case of filtering by date, active and inactive users are sent a reply for the specified period.
Elements of GetReceiverListMsg messages
HeaderSupplier - Message header
MessageID - Unique message number
SupplierID - OIB issuer (eg.9934: 12,345,678,901)
AdditionalSupplierID - Additional issuer identifier (GLN, DUNS, ... eg.0088: 123,456,789)
MessageType - Message type: 50041 - retrieve the recipient's registry
MessageAttributes - Message attribute
Data
ReceiverList - Provides a list of receivers from the registry
Filter - Retrieval filter
DateRange
From - Date From
To - Date to
TextSearch
SearchField - Search field ("ALL", "OIB" or "NAME")
SearchValue - Field value ("ALL" OIB number or name)
Elements of GetReceiverListAckMsg messages
MessageAck
MessageID - Unique message number to which the answer relates
MessageAckID - Unique message reply number
MessageType - Message type: 50042 - synchronized response to GetReceiverListMsg
AckStatus - Reply status
AckStatusCode - System status code
AckStatusText - System status description
BusinessBranch - Data on the business entity
BuyerID - Organizational unit identifier (BuyerID)
SchemeName - Organizational unit schema type (GLN, JUS, RKP, ...)
BusinessBranchCode - Organizational unit code
BusinessBranchName - Name of the organizational unit
PostalAddress - Address of a business entity
StreetName - Street
BuildingNumber - Building number
PostalCode - Postal code
CityName - City
Country - Country
AddressLine - Address on one line
Activity - Activity
Receiver - Receiver
RegistrationName - The name of the recipient
ISOCode - ISO Country Code (HR)
CompanyID - OIB
PostalAddress - Address of the organizational unit
StreetName - Street
BuildingNumber - Building number
PostalCode - Postal code
CityName - City
Country - Country
AddressLine - Address on one line
Status codes of invoices in exchange
Incoming invoices may have the following status values:
Status | Description |
RECEIVED | Received. The initial status of the invoice after being received in the system |
RECEIVING_CONFIRMED | Receipt confirmation |
APPROVED | Approved |
REJECTED | Rejected |
PAYMENT_FULFILLED | Fully paid |
PAYMENT_PARTIALLY_FULFILLED | Partially paid |
In case of refusal or partial payment it is necessary to enter the reason for the refusal or the partial payment in the "Note" element. Also, in case of partial payment, it is necessary to enter the partial payment amount into the "PartialAmount" element.
Types of messages exchanged
The table below describes the types of messages and the replies:
Message Type | Description | Message/methods |
9999 | Echo message | EchoBuyerMsg |
10000 | Reply to echo message | EchoBuyerAckMsg |
9101 | Receipt of incoming lists | GetB2GIncomingInvoiceListMsg |
9102 | Reply to retrieval of incoming invoice list | GetB2GIncomingInvoiceListAckMsg |
9103 | Receipt of incoming invoice | GetB2GIncomingInvoiceMsg |
9104 | Reply to retrieval of incoming invoice | GetB2GIncomingInvoiceAckMsg |
107 | Change of incoming invoice status | ChangeB2GIncomingInvoiceStatusMsg |
108 | Reply to change of incoming invoice status | ChangeB2GIncomingInvoiceStatusAckMsg |
9105 | Retrieve list of outgoing invoice | GetB2GOutgoingInvoiceListMsg |
9106 | Reply to retrieval of outgoing invoices list | GetB2GOutgoingInvoiceListAckMsg |
9107 | Retrieve outgoing invoice | GetB2GOutgoingInvoiceMsg |
9108 | Reply to retrieval of outgoing invoice | GetB2GOutgoingInvoiceAckMsg |
50041 | Retrieve the registry of the recipient | GetReceiverListMsg |
50042 | Reply to the retrieval of the recipient’s registry | GetReceiverListAckMsg |
List of possible error codes when sending messages
Error code | Description of error | Message |
E000100 | Nonexistent user | Nonexistent user ''{DN user}'' |
E000101 | User has no rights | User ''{User ID}'' no rights ''{name of the right}'' |
E000200 | Nonexistent document | There is no document ID={ID document} recipient ID={Orderer ID} |
E000201 | A status change is not possible because the document is of an unauthorized status | Document ID={Document ID} is of an unauthorized status ''{status description}''. Cannot change status |
E000202 | Unable to change document status | Document ID={Document ID} type={Document type (380 Invoice ...)} cannot change status. |
E000999 | Other mistakes | Error: {0} |
Messages and web service definition
Message schema and web service definitions can be seen here.