Mercurius platform - Simpl.ePRIOR service - technical documentation

Contents

Business context, purpose, scope and target audience

As layed out in the article Mercurius: the electronic mail room for our public entities, the Mercurius platform operates as a main/central mailroom for Belgian government entities, in the context of e-Invocing and e-Procureent. Such entities, and more generally, any Belgian Contracting Authority, can take advantage of teh services offered by the Mercurius platform to ease, improve, and/or boost its transition towards standardized, interoperable e-Procurement. The article Contracting Authorities : how to integrate your accounting software with the Mercurius platform? introduces the technical side of the Mercurius platform for such Belgian contracting authorities, eligible to use the Mercurius platform.

This guide provides the additional technical information required to understand and use the simpl.ePRIOR web service in this context. What it does consist of, what are the usage patterns. It contains practical information needed to integrate the web service into the users' software.

Other services offered by the Mercurius platform to support and boost e-invoicing adoption, such as conversion to human readable equivalents, Portal services (for suppliers not yet able to send structured electronic invoices, or for the sake of tracking the exchanges), are out of scope . Also, the non-technical aspects of the integration of simpl.ePRIOR, such as registering on the platform - and thereby obtaining access to the test environment and to the production environment, or the technical support through the lifecycle of use of the services, are not covered here. For such questions please contact Mercurius support by either filling out a support request (cf section D. of Contracting Authorities : how to integrate your accounting software with the Mercurius platform?)

Notice also that the Private sector-side of Mercurius is not discussed here. Technically speaking, private sector entities do not even need to know about Mercurius, they only need to know about Peppol (which Mercurius is aligned with, offering Business-to-Government interoperability).

simpl.ePRIOR is mainly available through the network of the service integrators of the Belgian public sector. Therefore, its use requires the ability to connect to such a service service integrator (FSB, Magda/VSB, FIDUS, BCED/eWBS, ...). The present document does not provide information covering this aspect, for it is not specific to the service. See also the section B of article mentioned above.

Another possibility to access simpl.ePRIOR is offered by the subcontractor operating the Mercurius platform. Such direct technical access can be considered when the Contracting Authority does not fall in the scope of any Public sector integrator (and thereby cannot be serviced by any of them), or when the disadvantages of using the network of the service integrators of the Belgian public sector are higher than the benefits. This is typically the case for organisations operating accross mutiple regions, or for entities services by IT service providers operating accross multiple regions. The technical information available in this guide, also applies to such direct access mode. On the other hand, such direct access requires (a) a direct agreement with the subcontractor operating the Mercurius platform, and (b) a registration

The target audience is software developers, analysts and architects charged with the integration of the systems of eligible Belgian Contracting Authorities with Mercurius - at connectivity level and at business logic level.

Prerequisites

To be able to fully understand the concept and technologies used in this document, you need to first get knowledge about the following :

• SOAP

  • SOAP with Attachment ( MIME )

  • WS-* Policies : X509

  • WSDL : XSD, namespace, ...

• eProcurement

  • Peppol High-level architecture and interoperability framework

  • 4 corners model

  • UBL data type : Peppol BIS, CEN BII , EN 16931, ...

Failing at understanding those principles and technologies 'll be a serious impediment to the implementation of this service in your solution.

Also please note that the endpoints exposed by the different integrators are secured and may require an on-boarding process, that is driven by the integrators. Without a completed on-boarding you won't be able to get access to the Simpl.ePRIOR web service.

This document is not describing how to integrate with the web service exposed by an integrators but more as a technical guide on how the Simpl.ePRIOR interface works independently from the integrator.

Also it doesn't provide any support for particular technology to integrate with the web service. We only provide a sample CXF for reference only.

Introduction

When you send a document to someone through the postal services, you just put it in an envelope, put the address on it, stamp it (if required) ... and that's it. Basically, Peppol is the solution for doing the same, but between computers. This is however quite a different, more complex challenge to solve in the world of computers than in the world of paper, because the ultimate goal - automation of invoice processing -  is much more sophisticated, and due to the inherent nature of computer systems - programs can hardly cope with deviations. Therefore, achieving such a universal, fully inter-operable exchange system, is a challenge. Peppol is (a) a framework that enables this universal "new way of posting", and (b) a global, open ecosystem into which the interoperability framework is respected by all actors.

SRC https://Peppol.eu/about-openPeppol/

The solution setup in Belgium for the business to government exchanges is composed of the following keyline elements:

1. Mercurius: it is the centralized mailroom for reception and routing of all e-Procurement related electronic and structured documents to and from the public sector. Mercurius thereby serves the public sector in their automation projects, and ensures consistency throughout all public sector entities.

2. Peppol: it is the "new way of posting", suited to structured electronic documents. Mercurius is fully aligned with the Peppol model. It is exclusively connected through a Peppol accesspoint

3. Simpl.ePRIOR: interface with the public sector entities, suited to their context, and more specifically aligned with the technology in use on the public sector integrators.

4. Mercurius portal: provides track and trace function to staff of entities using Mercurius platform. the portal reuses the Network infrastructure (proxy) and the Authentication and Authorization service

Open

This document is about the Simpl.ePRIOR interface defined on the right side of the schema : it describes the interaction between the Mercurius platform and the Public sector, the customers. The other flows aren't part of this document.

The simpl.ePRIOR interface is defined by a WSDL as it's a SOAP based service. This service is exposed by the Federal integrators for federal customers and by Regional integrators for regional customers. 

How does it work? - Keyline-principles

The Simpl.ePRIOR webs service defines the following four operations : submitDocument, submitInboxRequest, retrieveDocument, and markDocument. Each operation is  explained later in appropriate details.

Any consumer of the simpl.ePRIOR service can send valid documents (of a supported document format, see later)  through Mercurius, on behalf of any business entity (no control of representation by Mercurius).

Once properly configured in Mercurius,

• any business entity (=enterprise belonging to the Belgian public sector) can receive documents through Mercurius. It is identified with an inbox, where the documents are dropped, for collection by the receiver.

• any consumer of the simpl.ePRIOR can collect the documents received by all business entities it represents

As explained above, to perform meaningful business exchanges, the operations must (a) be performed using the appropriate document format (BIS INVOICE, BIS ORDER, BIS MLR, ...) and (b) be combined appropriately.

Sequences of operations

Document conformance

Documents flowing through Mercurius and simpl.ePRIOR always comply with (a) syntax and (b) semantic rules:

• the integrators validate the conformance to the syntax, ie the applicable UBL xsd (*), and

• additionally, Mercurius (ie, the backend service), validates the conformance to the semantic standard, hereafter referred to as "document format". (**)

(*) The service supports (a) the transport of UBL 2.1 documents ( syntax for Peppol BIS documents), and (b) the transport of the UNCEFACT / CII invoice compliant with the EN 16931 specifications

(**) Notice that:

• Outbound documents are validated at runtime: if a non-conformant document is submitted, the submit will fail (the service consumer will get a false ack indicator - and a SOAP fault describing format violations encountered in the document.

• Inbound document validation is performed asynchronously:

  • Upon fatal error in the validation process, Mercurius attempts to return an MLR to the document sender, notifying him that the document cannot be processed further due to non conformance. Such MLR can only be return if document sender has published MLR receiving capabilities.

  • This aspect (asynchonous validation and MLR feedback) does not affect the interface with the Public sector. thisinformation is only provided to add context to the end-to-end business exchanges with business correspondents, which the user, our service consumer, must be aware of, to properly drive their end-to-end projects.

How to test the service?

To familiarise yourself with the web service, you can use SOAPUI.

See for download : https://www.soapui.org/downloads/soapui.html

See here for documentation : https://www.soapui.org/soapui-projects/soapui-projects.html

Hereunder is a document about how to configure SOAPUI to integrate with the FSB ( Federal Service Bus - Federal integrator ) in the case you represent a federal customer.

Open

You can repeat the same with the WSDL for Simpl.ePRIOR .

Testing your development

When you start development or wish to validate your logic, you can exchange information with "sparring partners" : the fakeCustomer and fakeSupplier. In an upcoming version of this guide, this section will elaborate on this service, that is not completely finalized yet.

In the meantime, we recommend you:

• develop your own mock or use SOAPUI as a sparring partner, using your favorite integrator's wsdl, and the information in this document.

• when the development is sufficiently advanced, test the service by sending documents to yourself through simpl.ePRIOR. You can also use the Mercurius portal to generate incoming documents - however this does not guarantee that you will see all possible document patterns.

• When this is OK, test the service in combination with other public sector entities

• eventually, organize tests involving private sector entities.

Detailed presentation of the service

Overview

The following elements are used in the Simpl.ePRIOR interface. This is part of the required transmission items, on top of that the payload needs to contain a valid xml (UBL in most cases) document ( retrieve and submit document ). The Mercurius platform validates the UBL is correct based on the document type defined : this is a schematic and format validation - against XSD and Schematron. The business content like PO, price, ... is not validated and must be checked by the consumer.

See UBL document definition and UBL document Validation for reference.

Submit Inbox

Description

This operation accesses the inbox on Mercurius for a particular receiverID. Note that you need to have a contractual obligation before you can access a receiver's inbox ( to be configured with your integrator ).

Parameters

submitInboxRequest