This text describes how to connect the Receiver system to the Fina system for the purposes of receiving an incoming invoice from a Sender to a Recipient. It is intended for all interested parties that will participate in the implementation of the solution on the Receiver end.

This text describes all messages exchanged by systems, means of exchange, as well as levels 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.

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 link up to the web service for receiving invoices, the Recipient must meet the following prerequisites:

• Have an SSL certificate from a trusted issuer that must have the exact and verified name of the business entity to which it was issued, and must meet the requirements set out in the "Baseline Requirements Certificate Policy for the Issuance and Management of Publicly-Trusted Certificates" issued by the CA/Browser Forum, or higher level requirements (e.g., requirements prescribed for an EV certificate). The Recipient may also request from Fina a server SSL certificate to establish a secure connection between its ERP and the Fina e-Invoice system for business users,
• Request a Fina application certificate necessary for signing SOAP messages,
• Customize the system for receiving SOAP messages.

Integrity protection

Integrity protection is achieved by digitally signing the SOAP message with a Fina application 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 application 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

Receiving invoices via web services implies the fully automated downloading of invoices from the Fina System into the Recipient's system.

Via a web service on their side, the message recipient sends an incoming invoice by a standardized XML schema. In addition to an e-invoice, it is also possible to send an e-approval.

The Recipient's system synchronously responds with a confirmation message about receipt of the message. The recipient processes the message with the incoming document in his system. If there are changes in the status of an incoming invoice in the Recipient's system, the Recipient’s system sends a message via the Fina web service about changes in the incoming invoice’s status.

The recipient has two methods for receiving an invoice at their disposal:

• ReceiveB2BIncomingInvoiceMsg
  • Send only a structured document (xml)

• ReceiveB2BIncomingInvoicePdfMsg
  • Alongside a structured document (xml), a PDF document is also sent

Web service for receiving an incoming invoice on the Recipient side

On the Recipient end, web services must implement one of the following methods for receiving incoming invoices:

Elements of ReceiveB2BIncomingInvoiceMsg messages (receiveB2BIncomingInvoice method):

• HeaderBuyer
  • MessageID - Unique message number
  • BuyerID - OIB of the recipient in the e-Invoice system (e.g., 9934:12,345,678,901)
  • AdditionalBuyerID - Additional recipient identifier in the e-Invoice system
  • MessageType - Message type
    • 405 - Receiving an incoming e-Invoice
  • MessageAttributes - Message attribute
• Data
  • IncomingInvoiceEnvelope
    • DocumentType
      • XMLStandard - Standard XML document (UBL)
      • SpecificationIdentifier – Customized XML document (urn:cen.eu:en16931:2017 - fixed)
      • DocumentTypeCode - Document type
      • DocumentTypeText - Document type description
    • InvoiceID - Invoice identifier in e-Invoice system
    • InvoiceTimestamp - Time of receiving invoices in the system
    • InvoiceEnvelope - Envelope for e-Invoice by UBL schemaor
    • CreditNoteEnvelope – Envelope for e-Approval by UBL schema

Elements of ReceiveB2BIncomingInvoicePdfMsg messages (receiveB2BIncomingInvoicePdf method):

• HeaderBuyer
  • MessageID - Unique message number
  • BuyerID - OIB of the recipient in the e-Invoice system (e.g., 9934:12,345,678,901)
  • AdditionalBuyerID - Additional recipient identifier in the e-Invoice system
  • MessageType - Message type
    • 411 - Receiving an incoming e-Invoice
  • MessageAttributes - Message attributes
• Data
  • IncomingInvoicePdfEnvelope
    • DocumentType - Document type
      • XMLStandard - Standard XML document (UBL)
      • SpecificationIdentifier – Customized XML document (urn:cen.eu:en16931:2017 - fixed)
      • DocumentTypeCode - Document type
      • DocumentTypeText – Description of document type
    • InvoiceID - Invoice identifier in e-Invoice system
    • InvoiceTimestamp - Time of receiving invoices in the system
    • InvoiceEnvelope - Envelope for e-Invoice by UBL schemaor
    • CreditNoteEnvelope – Envelope for e-Approval by UBL schema
    • PdfDocument - Pdf document (Invoice, CreditNote)

Elements of ReceiveIncomingInvoiceAckMsg and ReceiveIncomingInvoicePdfAckMsg Messages:

• MessageAck
  • MessageID - Unique message number
  • MessageAckID - Unique message number to which the reply is addressed
  • MessageType - Message type
    • 406 - web service reply for an invoice without a PDF
    • 412 - web service reply for an invoice with a PDF
  • AckStatus - reply status
    • ACCEPTED or
    • MSG_NOT_VALID or
    • SYSTEM_ERROR
  • AckStatusCode - System status code - Default value '10' for successful receipt
  • AckStatusText - (Optional) - System status description

The Response message contains the "MessageAck" element where basic information about the web service reply is found. If the SOAP message is in accordance with the web service definition (wsdl) then ACCEPTED appears in the AckStatus element. If the SOAP message is not in accordance with the definition, MSG_NOT_VALID will appear in the reply. The SYSTEM_ERROR value indicates that there are larger problems in the Recipient system (e.g., runtime exception). In the case of SYSTEM_ERROR then the default value is AckStatusCode "99".

Message schema and web service definitions

Message schema and web service definition can be seen here.

Types of messages exchanged

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

The table below describes the types of messages and replies: