This text describes how to connect the Receiver 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 final Recipient side.

Prior to launching the production system, it is necessary to verify successful data exchange on Fina and Receiver test environments.

Definitions and Abbreviations

Communication conditions

Data exchange in the e-Invoice system for business users between the Recipient and Fina is done through the Internet. The transmission channel protection functions through the use of a two-way encrypted 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 as instructed in this technical specification.

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

• getB2BIncomingInvoiceList
  • GetB2BIncomingInvoiceListMsg

• getB2BIncomingInvoice
  • GetB2BIncomingInvoiceMsg

• GetB2BOutgoingInvoiceList
  • GetB2BOutgoingInvoiceListMsg

• GetB2BOutgoingInvoice
  • GetB2BOutgoingInvoiceMsg

• ChangeB2BIncomingInvoiceStatus
  • message ChangeB2BIncomingInvoiceStatusMsg

• GetReceiverList
  • message 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 of invoice,
• by the invoice 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 GetB2BIncomingInvoiceListMsg 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
  • B2BIncomingInvoiceList
    • DocumentCurrencyCode – true/false currency print of the partially paid invoice amount in the acknowledgment message (optional element)
    • Filter - Retrieval Filter
      • InvoiceStatus
        • StatusCode - Status in the e-Invoice system
      • DateRange
        • From - Date from
        • That - Date to
      • AmountRange
        • From - Amount from
        • To - Amount to
      • TextSearch
        • earchField - 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 GetB2BIncomingInvoiceListAckMsg elements

Synchronous response 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 GetB2BIncomingInvoiceListMsg
  • AckStatus - Reply status
  • AckStatusCode - System status code
  • AckStatusText - System status description
• B2BIncomingInvoiceList
  • B2BIncomingInvoice – Incoming invoice envelope
    • DocumentType - Document type
      • XMLStandard - Standard XML document (UBL)
      • 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
      • DocumentCurrencyCode – Currency of the partially paid invoice amount (optional element)
    • 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 B2B e-Invoice system
    • SupplierInvoiceID - Sender invoice identifier
    • DataInterchangeMethod - Invoice transfer method (PKI)
    • InvoiceIssueDate - Issue Date
    • InvoiceDate - Invoice Date
    • InvoiceTimestamp – Invoice timestamp in e-Invoice B2B system
    • InvoicePayableAmount - Invoice Amount
    • DocumentCurrencyCode – Currency of the invoice amount (optional element)
• 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 GetB2BIncomingInvoiceMsg 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
  • B2BIncomingInvoice – Envelope of query for retrieval of incoming invoice
    • InvoiceID - Invoice identifier in B2B e-Invoice system
    • DocumentCurrencyCode – true/false currency print of the partially paid invoice amount in the acknowledgment message (optional element)

Elements of GetB2BIncomingInvoiceAckMsg 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
• B2BIncomingInvoice
  • InvoiceID - Invoice identifier in B2B e-Invoice system
  • InvoiceTimestamp – Invoice timestamp in e-Invoice B2B system
  • DocumentType – Type of document for retrieval
    • XMLStandard - Standard XML document (UBL)
    • 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
    • DocumentCurrencyCode – Currency of the partially paid invoice amount (optional element)
  • DataInterchangeMethod - Invoice transfer method (PKI)
  • 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 business users" system, the initial status RECEIVED is automatically set. After entering the invoice into the system, the Recipient can send other available statuses.

If the recipient wants to reject the invoice because it was sent to the wrong business branch, he sets REJECTED as "StatusCode" and "190" as "CodeReason".

ChangeB2BIncomingInvoiceStatusMsg 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
  • B2BIncomingInvoiceStatus
  • InvoiceID - Invoice identifier in the B2B e-Invoice system
  • InvoiceStatus - Status to which you want to make changes in e-Invoice system
    • StatusCode - Status in the B2B e-Invoice system
    • CodeReason – Code reason („190“ for Wrong business branch) – optional element
    • Note - Status note (e.g., reason for rejection of invoice or partial payment)
    • PartialAmount - Partial payment amount
    • DocumentCurrencyCode – Currency of the partially paid invoice amount (optional element)

ChangeB2BIncomingInvoiceStatusAckMsg 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 ChangeB2BIncomingInvoiceStatusMsg
  • 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.

GetB2BOutgoingInvoiceListMsg 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
  • B2BOutgoingInvoiceList
    • DocumentCurrencyCode – true/false currency print of the partially paid invoice amount in the acknowledgment message (optional element)
    • Filter - Retrieval filter
      • InvoiceStatus
        • StatusCode - Status in the e-Invoice
      • 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 GetB2BOutgoingInvoiceListAckMsg 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 GetB2BOutgoingInvoiceListMsg
  • AckStatus - Reply status
  • AckStatusCode - System status code
  • AckStatusText - System status description
• B2BOutgoingInvoiceList
  • B2BOutgoingInvoice – Envelope of inbound invoice
    • DocumentType - Document type
      • XMLStandard - Standard XML Document (UBL)
      • 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
      • DocumentCurrencyCode – Currency of the partially paid invoice amount (optional element)
    • 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 B2B system
    • SupplierInvoiceID - Sender invoice identifier
    • DataInterchangeMethod - Invoice transfer method (PKI)
    • InvoiceIssueDate - Issue date
    • InvoiceDate - Invoice date
    • InvoiceTimestamp – Invoice timestamp in e-Invoice B2B system
    • InvoicePayableAmount - Invoice amount
    • DocumentCurrencyCode – Currency of the invoice amount (optional element)
• 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 GetB2BOutgoingInvoiceMsg 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
  • B2BOutgoingInvoice – Envelope of query for incoming invoice retrieval
    • InvoiceID - Invoice identifier in B2B e-Invoice system
    • DocumentCurrencyCode – true/false currency print of the partially paid invoice amount in the acknowledgment message (optional element)

Elements of GetB2ButgoingInvoiceAckMsg 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 GetB2BIncomingInvoiceMsg
  • AckStatus - Reply status
  • AckStatusCode - System status code
  • AckStatusText - System status description
• B2BOutgoingInvoice
  • InvoiceID - Invoice identifier in B2B e-Invoice system
  • InvoiceTimestamp – Invoice timestamp in e-Invoice B2B 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
    • DocumentCurrencyCode – Currency of the partially paid invoice amount (optional element)
  • DataInterchangeMethod - Invoice transfer method (PKI)
  • 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 business users" 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, ...)
  • ReceiptType - Document type received (1-UBL, 2-UBL EN, 3-CII)
  • 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:

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:

List of possible error codes when sending messages

Messages and web service definition

Message schema and web service definitions can be seen here.