...

version

...

1.1

...

published

...

27 Sep 2019 

...

comment

...

This page is still the subject of additional validation cycles. Readers are welcome to send questions and/or provide comments by email to mercurius@bosa.fgov.be 

Contents

Purpose and target Audience

The purpose of this guide is to explain the web service simpl.ePRIOR to its users. what it does consist of, what are the usage patterns, how to use it to accelerate its adoption path towards e-invoicing and e-Procurement for Belgian public sector entities. It contains practical information needed to integrate the web service into the users' (potentially multiple) software affected by e-Invoicing and e-Procurement.

...

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 . 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 is not specific to the serviceare 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 :

...

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 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 Peppol offers a framework that enables this universal "new way of posting". 

...

...

SRC https://peppolPeppol.eu/about-openpeppolopenPeppol/

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. PEPPOLPeppol: it is the "new way of posting", suited to structured electronic documents. Mercurius is fully aligned with the PEPPOL Peppol model. It is exclusively connected through a PEPPOL 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

...

1. the consumer collects incoming invoice:

   1. the consumer performs a submitInboxRequest on behalf of the target business entity→ in return he gets the list of new documents available in his inbox.

      1. we assume that an invoice is waiting to be picked up

      2. we also assume that it is a PEPPOL Peppol BISv3 Invoice  (see later form more explanations over document formats, BISv2 and BIS v3)

   2. the consumer performs a retrieveRequest to pick up the invoice

   3. the consumer performs a mark request to notify Mercurius that it successfully retrieved the invoice, and that the invoice can be removed from the business entity's inbox

2. The consumer performs the appropriate business processing. This phase is out of scope of the current process. It ends up with a possible response to the original document sender

3. The consumer performs a submitDocument Request to posts a response to the original document sender, notifying him of the results of the processing by the business entity. It uses the following document format: PEPPOL Peppol BIS v2 MessageLevelResponse (MLR).

...

• 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 [Cmt 10 May 2019: hasn't yet been checked] ).

• Inbound document validation is performed asynchronously - due to a lack of consensus to exploit the PEPPOL Peppol transport protocol (AS2/AS4), to send non-conformance feedback (it is questionable whether this belongs to the transport layer). Fatal validation errors on inbound documents are handled as breaches against the PEPPOL Peppol agreements. Therefore the documents are intercepted and propped with no further follow up. This aspect does not affect the interface with the Public sector. Howver, it adds context to the end-to-end business exchanges with business correspondents, which our service consumer must be aware of to properly drive their end-to-end projects.

...

...

1. Submit Inbox

2. Retrieve Document

3. Mark document

4. Submit Document

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 ).

...

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://fsb.belgium.be/einvoicing/simpleprior/v1_00>
   <soapenv:Header>
      <wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsu:Timestamp wsu:Id="Timestamp-HvumButHp993jGDym7t89Q22" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsu:Created>2018-10-03T10:07:55Z</wsu:Created>
            <wsu:Expires>2018-10-03T10:12:55Z</wsu:Expires>
         </wsu:Timestamp>
	<!—More elements on security and signature:-->
      </wsse:Security>    </soapenv:Header>
   <soapenv:Body>
      <v1:submitInboxRequestResponse>
         <v1:documentGroup>
            <!--Zero or more repetitions:-->
            <v1:documentReference>
               <v1:documentId>?</v1:documentId>
               <v1:documentTypeCode>?</v1:documentTypeCode>
               <v1:receiverId>?</v1:receiverId>
               <v1:senderId>?</v1:senderId>
            </v1:documentReference>
         </v1:documentGroup>
      </v1:submitInboxRequestResponse>
   </soapenv:Body>
</soapenv:Envelope>

Retrieve Document

Description

This operation retrieves a document from the inbox of a defined receiver.

...

<soapenv:Envelope xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/  xmlns:v1="http://fsb.belgium.be/einvoicing/simpleprior/v1_00>
   <soapenv:Header>
      <wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsu:Timestamp wsu:Id="Timestamp-HvumButHp993jGDym7t89Q22" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsu:Created>2018-10-03T10:07:55Z</wsu:Created>
            <wsu:Expires>2018-10-03T10:12:55Z</wsu:Expires>
         </wsu:Timestamp>
	<!—More elements on security and signature:-->
      </wsse:Security>    </soapenv:Header>
   <soapenv:Body>
      <v1:retrieveDocumentResponse>
         <v1:receivedDate>yyyy-MM-dd</v1:receivedDate>
         <v1:document>
            <!--Valid UBL document returned-->
         </v1:document>
      </v1:retrieveDocumentResponse>
   </soapenv:Body>
</soapenv:Envelope>

Mark document

Description

This operation marks a document when it has been processed at the customer side. Once it has been marked, it isn't accessible anymore from the entity's inbox, via the submit inbox request or the retrieveDocument request.

Parameters

Request

...

markDocument

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:head=”http://fsb.belgium.be/header”  xmlns:v1="http://fsb.belgium.be/einvoicing/simpleprior/v1_00">
   <soapenv:Header>
      <head:fsbHeader>
         <head:messageId>692da97e-e4a0-4ed0-b0bd-6e3f01e1e601</head:messageId>
      </head:fsbHeader>
   </soapenv:Header>
   <soapenv:Body>
      <v1:markDocument>
         <v1:receiverId>?</v1:receiverId>
         <v1:senderId>?</v1:senderId>
         <v1:documentType>?</v1:documentType>
         <v1:documentId>?</v1:documentId>
      </v1:markDocument>
   </soapenv:Body>
</soapenv:Envelope>

...

<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” 
xmlns:v1="http://fsb.belgium.be/einvoicing/simpleprior/v1_00">
         <soapenv:Header>
            <wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
               <wsu:Timestamp wsu:Id="Timestamp-HvumButHp993jGDym7t89Q22" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
                  <wsu:Created>2018-10-03T10:07:55Z</wsu:Created>
                  <wsu:Expires>2018-10-03T10:12:55Z</wsu:Expires>
               </wsu:Timestamp>
	      <!—More elements on security and signature:-->
            </wsse:Security>          </soapenv:Header>
   <soapenv:Body>
      <v1:markDocumentResponse>
		<!—When successful ackIndicator is true-->
         <v1:ackIndicator>true</v1:ackIndicator>
		<!—When an exception occurred ackIndicator is false-->
		<v1:ackIndicator>false</v1:ackIndicator>
		-->
      </v1:markDocumentResponse>
   </soapenv:Body>
</soapenv:Envelope>

Submit Document

Description

This operation allows to send a document type to a supplier. The format of the document must be supported by Mercurius/simpl.ePRIOR, which involves an intake of the format (see supported document flows). Additionally, the receiver must support that document format, meaning he must have published the receiving capability in a PEPPOL Peppol SMP. NB: to increase interoperability, Mercurius will soon add a default conversion to human readable of the documents whose receivers do not yet support the document format used by the sender. This echoes the already existing conversion for inbound documents, that was implemented to accelerate regularisation of Belgian public sector towards directive 2014/55.

Parameters

Request

...

submitDocument

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:head=”http://fsb.belgium.be/header”   xmlns:v1="http://fsb.belgium.be/einvoicing/simpleprior/v1_00">
   <soapenv:Header>
      <head:fsbHeader>
         <head:messageId>692da97e-e4a0-4ed0-b0bd-6e3f01e1e601</head:messageId>
      </head:fsbHeader>
   </soapenv:Header>
   <soapenv:Body>
      <v1:submitDocument>
         <v1:document>
            <!--You may enter ANY valid UBL document at this point-->
         </v1:document>
      </v1:submitDocument>
   </soapenv:Body>
</soapenv:Envelope>

...

Endpoint URL

...

As explained above, Mercurius supports business transactions consisting in exchange of documents, according to a preliminary defined exchange Profile. The PEPPOL Peppol specifications for the Document types and exchange Profiles are re-used. Only the connectivity is customised to the specificity of the service integrators operating in the Belgian public sector.

...

The initial, inbound flow of this pattern currently handles four possible formats:

• PEPPOL Peppol BISv2 INVOICE (CENBII-conformant) : optional since 18 Apr 2019 .  In practice all current users do support this format and need to maintain it, to preserve business continuity

• PEPPOL Peppol BISv2 CREDIT NOTE (CENBII-conformant ): optional since 18 Apr 2019 .  In practice all current users do support this format and need to maintain it, to preserve business continuity

• PEPPOL Peppol BIS v3 INVOICE (EN 16931-conformant) : mandatory since 18 Apr 2019 due to Directive 2014/55.  In practice current users are still finalizing the intake of this format

• PEPPOL Peppol BIS v3 CREDIT NOTE (EN 16931-conformant): mandatory since 18 Apr 2019 due to Directive 2014/55. In practice current users are still finalizing the intake of this format

...

Each time a new processing cycle starts, the collection of incoming documents takes three steps:

(b) Response to an Invoice/CN

supported formats:

PEPPOL Peppol BISV2 MLR (CENBII-conformant)

...

Upcoming changes (update: 27 Apr 2019 )

• generalization of PEPPOL Peppol BISv3 INVOICE and CREDIT NOTE: support of PEPPOL Peppol BISv3  invoice and credit note is active on Mercurius; however the activation of this format in Production must still happen. This step takes various test and coordnation activities. It is expected to be over in the coming weeks.

• phase out of PEPPOL Peppol BIS v2 MLR , phase-in of PEPPOL Peppol BIS v3 IMR:

  • The MLR is not the most suitable format to exchange business information between business entities. This document format was chosen for historical reasons.

  • Now there is a new document format available, BIS IMR. Mercurius will be configured soon to support the BIS IMR v3. 

  • this configuration has not yet been scheduled. additionally, the proper introduction of IMR requires coordination with suppliers actually using MLR. This is a significant piece of work  that must be duly analyzed and planned together with the configuration

...

For Mercurius staff, see also page 201 - Simpl.ePRIOR: Outbound Invoicing - Implementation (secured page)

sending an Invoice/CN

supported formats:

• PEPPOL Peppol BISv2 INVOICE (CENBII-conformant )

• PEPPOL Peppol BISv2 CREDIT NOTE (CENBII-conformant )

...

Upcoming changes (update: 27 Apr 2019 )

• add PEPPOL Peppol BISv3 INVOICE and CREDIT NOTE document formats:

  • This capability will enable G2G exchanges of EN-conformant invoices. It requires configuration on the simpl.ePRIOR flow.

  • It is a high-priority requirement. It is planned, target date 15 May 2019 .

  • For Mercurius staff only: see page 219 - Outbound (G2B) Invoicing - BIS3 support (secured page).

• add a response reception flow: this involves configuring inbound PEPPOL Peppol BIS IMR support, and may also require more configuration and more preparation.

• adding a PDF plan B to the main flow:

  • the current situation generates a lot of burden to the public sector entity that sends the documents: the entity must know in advance for each receiver  if he is capable of receiving the PEPPOL Peppol BIS format, and find other ways to handle the sendings to other receivers

  • to improve this, Mercurius will soon generalize a logic that converts the document and sends it via pdf/email if the receiver does not have suitable receiing capabilities. this way the public sector entities are freed from the cumbersome process described above, and can plan massive use of the outbound flows.

...

sending an Invoice/CN

supported formats:

PEPPOL Peppol BISv2 ORDER (CENBII-conformant )

...

• adding the response reception flow: order response. This is currently not being planned yet.

• adding a PDF plan B to the main flow:

  • the current situation generates a lot of burden to the public sector entity that sends the documents: the entity must know in advance for each receiver  if he is capable of receiving the PEPPOL Peppol BIS format, and find other ways to handle the sendings to other receivers

  • to improve this, Mercurius will soon generalize a logic that converts the document and sends it via pdf/email if the receiver does not have suitable receiing capabilities. this way the public sector entities are freed from the cumbersome process described above, and can plan massive use of the outbound flows.

...

This list is maintained for the sake of completeness. ePRIOR is the legacy system that was re-used during the pilot B2G e-invoicing project. After the pilot project the ePRIOR interface with the private sector was phased-out (and replaced by PEPPOL Peppol interface), but the interface with public sector was maintained. Only in 2018 this interface phase-out became necessary, due to introduction of European Norm and new exchange patterns such as eOrdering.

...

The document in the payload are based on specificatiosn available on : http://peppolPeppol.eu/downloads/post-award/. These specifications provide strong business interoperability by

...

The semantic layer are defined by standardization teams. The new PEPPOL Peppol BIS 3 Invoice format is an implementation of the european standard for electronic invoice, that provides the semantic specification and the syntaxt binding. PEPPOL Peppol teams only add implementation-level specifications.

...

The following 2 tables summarize the key information about the supported document formats.

Format specifications

( * ) the codes shown in this table were historicaly used with ePRIOR to qualify the invoice and credit note. They are also reflected in the status codes that were used then (confer the table in section Inbound Invoicing). All invoice and credit notes receivers are supposed to be able to handle the documents with these UBL Document Type Codes. NB: due to the alignment of Mercurius to the Peppol framework, other codes can be used in teh invoices and credit notes. to see the full list, please consult these documents : Invoice type code (UNCL1001 subset) and Credit note type code (UNCL1001 subset). It is up to each document receiver to decide how to handle these patterns.

...

Peppol Format identifiers

...

curl -X GET --header 'Accept: application/xml' 'http://smp.belgium.be/{identifierscheme}::{id}

id					Identifier of PEPPOLPeppol participant
identifierscheme	Scheme under which the identifier is registered

...

• https://vefa.difi.no/validator/

• https://peppolPeppol.helger.com/public/menuitem-validation-bis2

...

Develop your own validation tool via :

• https://github.com/difi/vefa-validator

• https://peppolPeppol.helger.com/public/locale-en_US/menuitem-validation-ws2

...

Mercurius was aligned with the PEPPOL Peppol model in 2016Q1, to enable massive onboarding of suppliers - in fact, get rid of onboarding activites since alle participants adhering to the PEPPOL Peppol model are supposed to inter-operate directly, thereby eliminating the need for preliminary bilateral negociation and tests and associated costs. To  minimize the amount of simultaneous changes, the ePRIOR documents formats and interface to the public sector were preserved: the ePRIOR and the PEPPOL Peppol BIS v2 semantics were both coformant implementation of CENBII works-results, and the syntaxes were close (UBL2.0 and UBL 21 respectively), making this approch straightforward.

...

• Both interfaces are available in parallel.

• The legacy invoices and CNs, sent by (5) suppliers still using the interface implemented during the Pilot-phase (not yet PEPPOLPeppol), are only accessible through the ePRIOR interface.

• All portal invoices (and CN), all BIS2 Invoices (and CN), and all EDIFACT-pilot invoices are accessible through both interfaces.

• Only simpl.ePRIOR gives access to BIS3 and UNCEFACT/CII invoices and CNs.

• Only simpl.ePRIOR enables outbound flows.

...

It is recommended to encourage pilot suppliers to migrate to PEPPOLPeppol. If a few weeks is needed, it is recommended to use following pattern at each invoice collection cycle:

...

References

Sample Code

This example is provided without any guarantee or support. It's only to help you and show you how to generate code based on the WSDL definition.

...