This text describes how to connect the Receiver (payer to public procurement) system to the Fina system for the purposes of communication from the Recipient to Fina. It is intended for all interested parties that will participate in the implementation of the solution on the receiving end.

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.