Technical specification - eInvoice web service for receiving incoming invoices with asynchronous processing
This document 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 part of budget users such as the final Recipient.
Definitions and Abbreviations
SSL | Secure Sockets Layer - a protocol that enables communication channel protection |
EV | Extended Validation - The process of checking a business entity when issuing an SSL certificate |
Sender | Sender of invoices to government budget users |
Recipient | Government budget users |
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 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 the government,
- 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 (government budget user) 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:
- ReceiveB2GIncomingInvoiceMsg
- Send only a structured document (xml)
- ReceiveB2GIncomingInvoicePdfMsg
- 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 ReceiveB2GIncomingInvoiceMsg messages (receiveB2GIncomingInvoice 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
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
DataInterchangeMethod – Possible values “PKI”, “EDI” or “OTHER”
InvoiceEnvelope - Envelope for e-Invoice by UBL schema
orCreditNoteEnvelope – Envelope for e-Approval by UBL schema
Elements of ReceiveB2GIncomingInvoicePdfMsg messages (receiveB2GIncomingInvoicePdf 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
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
DataInterchangeMethod – Possible values “PKI”, “EDI” or “OTHER”
InvoiceEnvelope - Envelope for e-Invoice by UBL schema
orCreditNoteEnvelope – Envelope for e-Approval by UBL schema
orPdfDocument - 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
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".
Sending a confirmation reply message
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:
Message Type | Description | Message/methods |
105 | Receiving incoming invoice without a PDF | ReceiveB2GIncomingInvoiceMsg |
106 | Reply to receiving incoming invoice without a PDF | ReceiveB2GIncomingInvoiceAckMsg |
111 | Receiving an incoming invoice with a PDF | ReceiveB2GIncomingInvoicePdfMsg |
112 | Reply to receiving an incoming invoice with a PDF | ReceiveB2GIncomingInvoicePdfAckMsg |