This text describes how to connect a Sender System with a Fina system for sending invoices from a Sender to a Recipient. It is intended for all interested parties that will participate in the implementation of the solutions on the Sender side.

This text 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 final Recipient side.

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 produce a production certificate.

Communication conditions

Data exchange in the e-Invoice system for business users 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 business users.

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 business users 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 (SendB2BOutgoingInvoice) 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 (2-way SSL),
• SOAP messages and documents in the message will be signed with Fina certificates,
• For each SOAP message there will be a SOAP acknowledgment message.

Sender has the following methods available:

• EchoMsg

• SendB2BOutgoingInvoiceMsg

• GetB2BOutgoingInvoiceStatusMsg

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 response message.

If the echo message has successfully been sent and Fina has responded with a response 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 responds with a message on the results of processing.

Message elements of EchoMsg

• 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

Message elements of EchoAckMsg

• MessageAck
  • MessageID - Unique message number
  • MessageAckID - Unique message number to which the response refers
  • MessageType - 10000 - Response to echo message
  • AckStatus - Response 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. The Sender can send the invoice to the Recipient registered within the e-Invoice system or to an external Recipient using the PEPPOL network. Therefore, the following values are used within the "SpecificationIdentifier" element:

• urn:cen.eu:en16931:2017 – to send an invoice to the Recipient within the e-Invoice system
• urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0 – to send an invoice to an external Recipient using the PEPPOL network.

When sending an invoice to an external Recipient using the PEPPOL network, the invoice must be created according to PEPPOL BIS 3 specification available here: https://docs.peppol.eu/poacc/billing/3.0/

Element of SendB2BOutgoingInvoiceMsg messages (SendB2BOutgoingInvoice method):

• HeaderSupplier
  • MessageID - Unique message number
  • SupplierID - Issuer identifier (OIB) - (9934:12345678909)
  • AdditionalSupplierID - Additional issuer identifier (GLN, JUS,...) - 0088:38545468711
  • ERPID – ERP provider identifier
  • MessageType - Message type: 9001 - Sending outgoing invoice
  • MessageAttributes - Message attributes
• Data
  • B2BOutgoingInvoiceEnvelope
    • XMLStandard - Standard XML document (UBL or CII)
    • SpecificationIdentifier – Customized XML document (urn:cen.eu:en16931:2017 or urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0)
    • SupplierInvoiceID - Invoice identifier in sender system
    • BuyerID – Invoice recipient identifier in the e-Invoice system (e.g. 9934:OIB) or recipient identifier in the PEPPOL system (PEPPOL ID)
    • 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 SendB2BOutgoingInvoiceAckMsg messages:

• MessageAck
  • MessageID - Unique message number
  • MessageAckID - Unique message number to which the response refers
  • MessageType - Message type: 9002 - Synchronous response to SendB2BOutgoingInvoiceMsg
  • AckStatus - Response status
    • ACCEPTED or
    • MSG_NOT_VALID or
    • SYSTEM_ERROR
  • AckStatusCode - System status code
  • AckStatusText - System status description
• B2BOutgoingInvoiceEnvelope
  • CorrectB2BOutgoingInvoice - Correct outgoing invoice
    • SupplierInvoiceID - Invoice identifier in sender system
    • InvoiceID - Invoice Identifier in B2B e-Invoice system
    • InvoiceTimestamp - Time of the invoice receipt in the system
  • IncorrectB2BOutgoingInvoice
    • SupplierInvoiceID - Invoice identifier in sender system.
    • ErrorCode – Error code of invalid outbound invoice separated by delimiter.
    • ErrorMessage – Error description of incorrect outgoing invoice.

A reply message consists of two parts:

• MessageAck
• B2BOutgoingInvoiceEnvelope

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

The status of a message may be as follows:

If the SOAP message is consistent with the web service definition (wsdl) then the MessageAck/AckStatus element always displays the ACCEPTED reply regardless of whether the data itself, e.g. the invoice, is correct. If the SOAP message does not comply with the definition, MSG_NOT_VALID will appear in the response. The SYSTEM_ERROR value shows that major system issues have occurred (e.g., a runtime exception) indicating that customer support should be contacted to verify the reason.

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

If the UBL document is valid, then the CorrectB2BOutgoingInvoice element appears with the invoice identifier data from the Sender system (invoice number), the invoice identifier under which it was received in the e-Invoice system and the timestamp of the receipt.

If the UBL document is invalid, then the IncorrectB2BOutgoingInvoice element appears with the invoice identifier data from the Sender system (invoice number), an error code, and description (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.

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.

Elements of GetB2BOutgoingInvoiceStatusMsg message (GetB2BOutgoingInvoiceStatus method):

• HeaderSupplier
  • MessageID - Unique message number
  • SupplierID - Issuer identifier (OIB) - (9934:12345678909)
  • AdditionalSupplierID - Additional issuer identifier (GLN, JUS, ...) - 0088:38545468711
  • ERPID – ERP provider identifier
  • MessageType - Message Type: 9011 – Retrieval status of outgoing invoice
  • MessageAttributes - Message attributes
• Data
  • B2BOutgoingInvoiceStatus
    • 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 GetB2BOutgoingInvoiceStatusAckMsg Message:

• MessageAck
  • MessageID - Unique message number
  • MessageAckID - Unique message number to which the response refers
  • MessageType - Message Type: 9012 - Synchronous Response to GetB2BOutgoingInvoiceStatusMsg
  • AckStatus - Response status
    • ACCEPTED or
    • MSG_NOT_VALID or
    • SYSTEM_ERROR
  • AckStatusCode - System status code
  • AckStatusText - System status description
• B2BOutgoingInvoiceStatus
  • SupplierID - Invoice sender identifier in the e-Invoice system
  • AdditionalSupplierID - Additional issuer identifier (GLN, JUS, ...) - 0088:38545468711
  • InvoiceID - Account Identifier in B2B e-Accounts
  • SupplierInvoiceID - Invoice identifier in the sender system
  • InvoiceTimestamp - Timestamp of invoice in the e-Invoice B2B system
  • DocumentStatus – System status of B2B e-Invoice
    • StatusCode - Status code in B2B e-Invoice system
    • StatusText - Description of status codes in the B2B e-Invoice system
    • StatusTimestamp - Timestamp status in the B2B 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)

Message schema and web service definition

Message schema 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 of them are required): 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 responses:

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.