This document describes how to connect a Sender System with a Fina system for sending invoices from a Sender to a Recipient (users of the government budget). The document is intended for all interested parties that will participate in the implementation of the solutions on the Sender side.

This document describes all messages exchanged by systems, means of exchange, as well as levels of security, e.g., protection of transmissions.

Data will be exchanged using XML messages via the SOAP 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.

Definitions and abbreviations

Integrity protection

Data integrity protection in a SOAP message is achieved by digitally signing a SOAP message with a digital certificate using the WS-Security standard. Data integrity protection in an XML account is achieved by digitally signing XML in accordance with UBL specifications using a digital certificate. In order to gain control of the electronic signature, Fina checks to see if the OIB number specified in the XML account is identical to the OIB number assigned to the certificate with which the account was signed. If the OIB numbers are not the same, the message is rejected and does not enter the Fina system.

For the purposes of testing, the Sender may use Fina’s DEMO certificate and a production certificate when in production. If the Sender is not using a Fina digital certificate, it is essential that they do not use the same certificate in the test environment as in the production environment.

Communication conditions

Data exchange in the e-Invoice system for the government between Fina and a Sender is done through the Internet. Sending invoices via web services implies the fully automated sending of invoice from an ERP Sender system to a Recipient system through the Fina e-Invoice system for the government.

For this type of automated invoice sending, the Sender must do the following:

• request a Fina Demo and a production certificate for signing SOAP messages,
• adjust the ERP to create and send a SOAP message.

Web service

For its part, Fina has created a web service for receiving data via a standardized XML schema.

Documents that can be sent through this e-Invoice web service for the government are:

• Invoice (with accompanying documentation attached),
• Approval (with accompanying documentation attached).

All messages sent through the web service have the same basic layout. It consists of headers (HeaderSupplier) and Data.

Information (data) is defined for each message separately and differ within the element of the XML structure depending on the message. Messages that contain standalone XML structures (such as xml e-invoices) are embedded in a "envelope" (e.g., InvoiceEnvelope) of the base64binary type that contains the original XML encoded in Base64.

Basic settings concept:

• Fina has created a web service with methods for sending outgoing e-invoice and e-approval (SendB2GOutgoingInvoice) messages, and methods for sending a message to retrieve the status of the outgoing invoice and trial run, echo message,
• when a web service is called, Fina will establish an SSL connection with client authentication,
• SOAP messages and documents in the message will be signed with Fina certificates,
• for each SOAP message there will be a SOAP acknowledgment message.

Sending Echo message

Sending outgoing invoice

Checking web service function

The Sender creates an echo SOAP message, signs it and sends it to the Fina web service to test its availability. Fina synchronously answers with a reply message.

If the echo message has successfully been sent and Fina has responded by a reply message, the sender creates a SOAP message for sending the outgoing invoice or approval, signs the SOAP message, and calls the web service on the Fina side. Fina synchronously replies with a message on the results of processing.

Elements of EchoMsg messages

• HeaderSupplier
  • MessageID - Unique message number
  • SupplierID - Issuer identifier (OIB) - (9934:12345678909)
  • AdditionalSupplierID - Additional Issuer Identifier (GLN, JUS, ...) - 0088:38545468711
  • MessageType - Message type: 9999 - echo message
  • MessageAttributes - Message attributes
• Data
  • EchoData
    • Echo - Text content

Elements of EchoAckMsg 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

Sending an Echo and Echo confirmation message

Method for sending outgoing messages (invoice, approval)

After successfully sending echo SOAP messages, the sender creates a SOAP message to send the document:

Element of SendB2GOutgoingInvoiceMsg messages (SendB2GOutgoingInvoice method):

• HeaderSupplier
  • MessageID - Unique message number
  • SupplierID - Issuer identifier (OIB) - (9934:12345678909)
  • AdditionalSupplierID - Additional issuer identifier (GLN, JUS,...) - 0088:38545468711
  • MessageType - Message type: 9001 - Sending outgoing invoice
  • MessageAttributes - Message attributes
• Data
  • B2GOutgoingInvoiceEnvelope
    • XMLStandard - Standard XML document (UBL or CII)
    • SpecificationIdentifier – Customized XML document (fixed - urn:cen.eu:en16931:2017)
    • SupplierInvoiceID - Invoice identifier in sender system
    • BuyerID – Invoice recipient identifier in the system (OIB) - (9934:12345678909)
    • AdditionalBuyerID - Additional invoice recipient identifier in system (GLN, JUS, ...) - (0088:38545468711)
    • InvoiceEnvelope – Envelope of e-Invoice according to UBL schema
    • CreditNoteEnvelope - Envelope of e-Approval according to UBL schema

Elements of SendB2GOutgoingInvoiceAckMsg messages:

• MessageAck
  • MessageID - Unique message number
  • MessageAckID - Unique message number to which the reply relates
  • MessageType - Message type: 9002 - Synchronous reply to SendB2GOutgoingInvoiceMsg
  • AckStatus - reply status
    • ACCEPTED or
    • MSG_NOT_VALID or
    • SYSTEM_ERROR
  • AckStatusCode - System status code
  • AckStatusText - System status description
• B2GOutgoingInvoiceEnvelope
  • CorrectB2GOutgoingInvoice - Correct outbound invoice
    • SupplierInvoiceID - Invoice identifier in sender system
    • InvoiceID - Invoice Identifier in B2G e-Invoice system
    • InvoiceTimestamp - Time of receiving invoices in the system
  • IncorrectB2GOutgoingInvoice
    • SupplierInvoiceID - Invoice identifier in sender system.
    • ErrorCode – Error code of invalid outbound invoice separated by delimiter.
    • ErrorMessage – Error description of incorrect outbound invoice.

A reply message consists of two parts:

• MessageAck
• B2GOutgoingInvoiceEnvelope

The MessageAck section contains basic information about the SOAP message itself, while in the B2GOutgoingInvoiceEnvelope section is found the processing data of the invoice that was sent.
 

Message Status

If the SOAP message is consistent with the web service definition (wsdl) then the Message Accept / AckStatus element always displays the ACCEPTED reply regardless of whether the data itself, e.g. the invoice, is correct. If the SOAP message is not in accordance with the definition, MSG_NOT_VALID will appear in the response. The SYSTEM_ERROR value shows that there are major system issues (e.g., a runtime exception) and an indication that user support should be notified to verify the reason.

The B2GoutgoingInvoiceEnvelope section contains data on a processed document (invoice, approval...), and the entire element appears only if MessageAck / AckStatus ACCEPTED. If AckStatus is MSG_NOT_VALID or SYSTEM_ERROR then the B2GoutgoingInvoiceEnvelope element does not appear in the reply message.

If the UBL document is correct, then the CorrectB2GOutgoingInvoice element appears with the invoice identifier data from the sender's system (invoice number), the invoice identifier under which it was sent via the e-Invoice system and the timestamp of receipt appears.

If the UBL document is incorrect, then the IncorrectB2GOutgoingInvoice element appears with the invoice identifier data from the sender's system (invoice number), an error code, and description appears (separated by a delimiter if there are multiple errors). In this case, it is necessary to correct the errors and send the message back through the system.

Sending confirmation reply message in the system

Method for retrieving outgoing invoice status

This method is used to check the status of a specific outgoing invoice. The invoice number from the sender's system and the year of issue of the invoice are used as identifiers.

Message elements GetB2GOutgoingInvoiceStatusMsg (method GetB2GOutgoingInvoiceStatus):

• HeaderSupplier
  • MessageID - Unique message number
  • SupplierID - Issuer identifier (OIB) - (9934:12345678909)
  • AdditionalSupplierID - Additional issuer identifier (GLN, JUS, ...) - 0088:38545468711
  • MessageType - Message Type: 9011 – Retrieval status of outbound invoice
  • MessageAttributes - Message attributes
• Data
  • B2GOutgoingInvoiceStatus
    • SupplierInvoiceID - Invoice identifier in sender system
    • InvoiceYear - The year of the invoice in the sender's system
    • DocumentCurrencyCode - true/false currency print of the partially paid invoice amount in the acknowledgment message (optional element)

Elements GetB2GOutgoingInvoiceStatusAckMsg Message:

• MessageAck
  • MessageID - Unique message number
  • MessageAckID - Unique message number to which the reply is addressed
  • MessageType - Message Type: 9012 - Synchronous Response to GetB2GOutgoingInvoiceStatusMsg
  • AckStatus - Reply status
    • ACCEPTED or
    • MSG_NOT_VALID or
    • SYSTEM_ERROR
  • AckStatusCode - System status code
  • AckStatusText - System status description
• B2GOutgoingInvoiceStatus
  • SupplierID - Invoice sender identifier in the e-Invoice system
  • AdditionalSupplierID - Additional issuer identifier (GLN, JUS, ...) - 0088:38545468711
  • InvoiceID - Account Identifier in e-Invoice
  • SupplierInvoiceID - Invoice identifier in the sender system
  • InvoiceTimestamp - Timestamp of invoice in the B2G e-Invoice system
  • DocumentStatus – System status of B2G e-Invoice
    • StatusCode - Status code in B2G e-Invoice system
    • StatusText - Description of status codes in the B2G e-Invoice system
    • StatusTimestamp - Timestamp status in the B2G e-Invoice system
    • Note - Status note (e.g., reason for rejection)
    • PartialAmount - Amount of partially paid invoice
    • DocumentCurrencyCode - Currency of the partially paid invoice amount (optional element)

Messages and web service definition

Messaging and web services definition (WSDL) schema can be seen here.

UBL schema

The UBL schema can be downloaded from the Oasis site:

Invoice: https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd

Credit Note: https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-CreditNote-2.1.xsd

Common Schema (all are needed): https://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/common/

Types and descriptions of messages exchanged

The table below describes the types of messages and replies:

Procedures before production

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

No exceptions can be made for a lack of exchange testing, on the test environments of Fina and Sender. Likewise, it is necessary to document the data exchange components in detail.