Mercurius platform - Simpl.ePRIOR service - technical documentation

version

2.0

published

Apr 9, 2021 

comment

Readers are welcome to send questions and/or provide comments by email to mercurius@bosa.fgov.be 

 

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.

 

For the avoidance of doubt:

The present guide makes abstraction of the technical architecture at the side of the consumer application. It is not unfrequent that the customer - the user of the consumer application -, operates within a technical context that involves intermediate services such as central middelware and service bussses or any other infrastructure services. This guide cannot provide information that would meet the specific needs and constraints of all such possible contexts. It is up to the reader to properly include such context in the reading of the guide.

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

Context of this document



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.



Scope covered by 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.

Example: to receive an invoice and return a business response, the following 3-phases sequence applies to the simpl. ePRIOR consumer application:

  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 BIS Invoice

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

    3. the consumer performs a markRequest 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 post 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 BIS v2 MessageLevelResponse (MLR). Note: Apr 9, 2021 the Peppol BIS Invoice Response (IMR) is being introduced. IT will replace the MLR (for more info see later in the Guide).

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.

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.

soapenv:Envelope/soapenv:Header/head:fsbHeader/head:messageId

UUID, unique ID for the message

soapenv:Envelope/soapenv:Body/.../v1:receiverId

Identifier of the receiving party

soapenv:Envelope/soapenv:Body/.../v1:senderId

Identifier of the sender party

soapenv:Envelope/soapenv:Body/.../v1:documentType

Type of the document, 

soapenv:Envelope/soapenv:Body/.../v1:docId

Id of the document as provided by the sender

soapenv:Envelope/soapenv:Body/.../v1:DocumentFormatIdentifier

identifier of the document format on the Peppol transport infrastructure [NB: the use of uppercase for the first caracter is not consistent with applicable conventions and with other elements --> we might change by documentFormatIdentifier at a later stage]

soapenv:Envelope/soapenv:Body/.../v1:document

UBL Document. NB: the binary is not inline in the message but transmitted as an attachment. See SOAP with Attachment for further information.

soapenv:Envelope/soapenv:Body/.../v1:receivedDate

Date at which the document has been processed by the Mercurius platform

soapenv:Envelope/soapenv:Body/.../v1:ackIndicator

Boolean indicating the status of the operation

  • True : Request successfully processed

  • False : An exception occurred and the process failed

In the upcoming sections, the elements listed above are further referenced by means of the bold part of their name in the above table.

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

Input

Output

Exception (*)

Input

Output

Exception (*)

  • receiverId ( mandatory )

  • senderId

  • documentType

  • DocumentFormatIdentifier 

  • list of the unmarked documents ( 0..N ):

    • docId

    • receiverId

    • senderId

    • documentType

    • DocumentFormatIdentifier

  • No access allowed to inbox

(*) See SOAP Fault section for more details

submitInboxRequest

1 2 3 4 5 6 7 8 9 10 11 12 13 <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>9397cbe5-174f-479f-941d-2371129acb05</head:messageId> </head:fsbHeader> </soapenv:Header> <soapenv:Body> <v1:submitInboxRequest> <v1:receiverId>?</v1:receiverId> <v1:senderId>?</v1:senderId> </v1:submitInboxRequest> </soapenv:Body> </soapenv:Envelope>

Response

submitInboxRequestResponse

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 <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.

Parameters

Input (all mandatory)

Output

Exception(*)

Input (all mandatory)

Output

Exception(*)

  • receiverId

  • senderId

  • documentType

  • docId

  • reception date

  • Document

  • Document doesn't exist or is not accessible (unauthorized)

(*) See SOAP Fault section for more details

 

Request 

retrieveDocument

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 <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:retrieveDocument> <v1:receiverId>?</v1:receiverId> <v1:senderId>?</v1:senderId> <v1:documentType>?</v1:documentType> <v1:documentId>?</v1:documentId> </v1:retrieveDocument> </soapenv:Body> </soapenv:Envelope>

Response

retrieveDocumentResponse

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 <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

Input (all mandatory)

Output

Exception(*)

Input (all mandatory)

Output

Exception(*)

  • receiverdId

  • senderId

  • documentType

  • docId

  • ackIndicator = True

  • Document doesn't exist or is not accessible (unauthorized)

(*) See SOAP Fault section for more details

Request

markDocument

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 <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>

Response

MarkDocumentResponse

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 <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>

Inbound Documents that can’t be picked up - conversion to a human-readable equivalent and out-of-band transmission (per eMail)

The following information does not affect the technical integration, but is nevertheless useful to understand the overall flow of documents.

In the happy flow, any document that is received by Mercurius and posted in the inbox of the destination entity, is also retrieved and marked by the simpl.ePRIOR consumer application. Unfortunately, more than often the consumer can’t retrieve and mark some document because of some data problem or technical limitation. On the other hand, (a) many public sector entities haven’t found yet a suitable tool to receive and process documents, and (b) adoption of eProcurement involves many other documents than the incoming invoice, that each public sector entity integrate at their own rythm.

This 3 scenarios cause the same result: a document keeps hanging in the inbox of the destination entity. Therefore, Mercurius responds to these 3 scenarios in one single effective way: any document that hasn’t been picked up after a certain delay (called the pick-up delay), is systematically (a) converted into a human readable equivalent and (b) transmitted by email at a central functional email address communicated by the destination entity at mercurius registration.

Notice that the original document remains available for retrieve - until expiration of the retention delay. That way, should the problem be temporary, the structured electronic document can still be picked up and processed by the consumer application.

Most of the entities choose to configure the pick-up delay between 1 hour and 5 days, depending on the consumer application. The retention delay is 30 days.

Submit Document

Description

This operation allows to send a document type to a receiver (in the case of the invoice response, the receiver is the supplier who issued the invoice).

The format of the document must be supported by Mercurius (and, thereby, by simpl.ePRIOR), which involves an onboarding 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 SMP. To overcome that limitation, Mercurius provides services that convert the structured electronic document into a human-readable equivalent, and transmits it per email to the receiver, provided that the sender commnicates such email address in the original document. This strategy is gradually rolled out accross inbound and outbound flows. The availability of such additionnal service is documented flow per flow, in the next main section.

 

Parameters

Input

Output

Exception

Input

Output

Exception

valid UBL Document

ackIndicator = True

  • unsupported document format

  • document format violation (list of errors found)

(*) See SOAP Fault section for more details

Request

submitDocument

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 <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>

Response

submitDocumentResponse

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 <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:submitDocumentResponse> <!—When successful ackIndicator is true--> <v1:ackIndicator>true</v1:ackIndicator> <!—When an exception occurred ackIndicator is false--> <v1:ackIndicator>false</v1:ackIndicator> --> </v1:submitDocumentResponse> </soapenv:Body> </soapenv:Envelope>



SOAP with attachments

In order to keep the size of xml documents small enough for middleware processing, Simpl.ePrior is using SOAP with attachments when exchanging UBL documents.

It is required to remove any embedded attachment present in the UBL tag <EmbeddedDocumentBinaryObject> and to move it to a content part of the SOAP with attachments. The 'Content-ID' of the mime part must correspond to the value of the <ID> element of the parent of the <EmbeddedDocumentBinaryObject> element.

Note: in case you submit an outbound document to the relevant schematron validation before sending it, the document must contain the base64 encoded attachment in the UBL tag <EmbeddedDocumentBinaryObject>.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 ------=_Part_20_1065051393.1568991070704 Content-Type: text/xml; charset=UTF-8 Content-ID: <rootpart@babelway.net> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">  <soap:Header/>  <soap:Body>   <v1:retrieveDocumentResponse xmlns:v1="http://fsb.belgium.be/einvoicing/simpleprior/v1_00">    <receivedDate xmlns="http://fsb.belgium.be/einvoicing/simpleprior/v1_00">2019-09-20</receivedDate>    <document xmlns="http://fsb.belgium.be/einvoicing/simpleprior/v1_00">     <inv:Invoice xmlns:inv="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"          xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"          xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">     <cbc:UBLVersionID>2.1</cbc:UBLVersionID> ...     <cac:AdditionalDocumentReference>      <cbc:ID>file1</cbc:ID>      <cac:Attachment>       <cbc:EmbeddedDocumentBinaryObject filename="file1.txt" mimeCode="application/octet-stream"/>      </cac:Attachment>     </cac:AdditionalDocumentReference>     <cac:AdditionalDocumentReference>      <cbc:ID>file2</cbc:ID>      <cac:Attachment>       <cbc:EmbeddedDocumentBinaryObject filename="file2.log" mimeCode="application/octet-stream"/>      </cac:Attachment>     </cac:AdditionalDocumentReference>     <cac:AdditionalDocumentReference>      <cbc:ID>file3</cbc:ID>      <cac:Attachment>       <cbc:EmbeddedDocumentBinaryObject filename="file3.txt" mimeCode="application/octet-stream"/>      </cac:Attachment>     </cac:AdditionalDocumentReference> ...    </inv:Invoice>   </document>       </v1:retrieveDocumentResponse>    </soap:Body> </soap:Envelope> ------=_Part_20_1065051393.1568991070704 Content-Type: application/octet-stream Content-Transfer-Encoding: binary Content-ID: <file1> Content-Disposition: attachment; filename=file1.txt file1 ------=_Part_20_1065051393.1568991070704 Content-Type: application/octet-stream Content-Transfer-Encoding: binary Content-ID: <file2> Content-Disposition: attachment; filename=file2.log file2 ------=_Part_20_1065051393.1568991070704 Content-Type: application/octet-stream Content-Transfer-Encoding: binary Content-ID: <file3> Content-Disposition: attachment; filename=file3.txt file3 ------=_Part_20_1065051393.1568991070704—

 

SOAP Fault

Simpl.ePrior uses standard SOAP fault, without defining substructures.

The Fault code [soap:Client Or soap:Server] is defining where is the probable system responsible for the error.

The fault string is the normalized definition of the error code. Hereunder you can find a list of all  SOAP fault triggered by the simpl.ePrior backend.

Please note that this list can be augmented with the error thrown by the FSB or the integrator layer.



Error

Fault code

Fault string

Description

Error

Fault code

Fault string

Description

UnauthorizedAccess

soap:Client

Unauthorized Access

This error is returned when any security issues is encountered. This includes authentication, signature validation, authorization to a receiver or a sender…

InvalidRequest

soap:Client

Invalid request

The document included in the message is not parsable or doesn’t contains information.

InvalidCustomizationId

soap:Client

CustomizationId not supported

The document included in the message has an unsupported <CustomizationID> and <ProfileID>.

InvalidDocumentValidationFailed

soap:Client

Validation failed

The document included in the message has validation errors.

UnsupportedIncomingMessage

soap:Client

Unsupported incoming message

The type of the document included in the message is not configured in the list of accepted documents in the Mercurius gateway configuration.

InvalidAttachments



soap:Client

Invalid attachments

The attachment defined in the document and in the SOAP with attachments do not match.

More specifically:

  • <EmbeddedDocumentBinaryObject> are empty

  • All <EmbeddedDocumentBinaryObject> parent node have an <ID> element. This <ID> is not null and unique in the document. It matches a MIME part 'Content-ID' attribute of the SOAP attachments.

ServerError

soap:Server

Server Error

Any other error.



Endpoint URL

This remark only applies to users of the Belgian public sector integrators.

The endpoint URLs are defined by the integrator. Once you start your on-boarding process those 'll be communicated by the integration team plus the necessary security/authorization artifacts ( certificate, credentials, ... ).

Detailed explanations of the document exchange patterns supported by Mercurius and simpl.ePRIOR and their composing flows

As explained above, Mercurius supports business transactions consisting in exchange of documents, according to a preliminary defined exchange Profile. The 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 scope of such transactions supported by Mercurius and its simpl.ePRIOR interface, grow according to its users community needs and expectations. This section keeps track of, and provides details over the supported document flows.

Inbound Invoicing

This exchange pattern starts with an inbound flow: the reception of an invoice or a credit note, with 0..n attachments (supporting documents). It can be followed by and outbound flow: the transmission of a business response.

(a) Reception of invoice/creditNote

supported formats

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

  • Peppol BIS INVOICE (EN 16931-conformant) : mandatory since Apr 18, 2019 due to Directive 2014/55. 

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

See "defined Document formats" for detailed format specifications

Remark: Directive 2014/55 also imposes European Contracting Authorities to receive and process the European Norm in the UN CEFACT Cross Industry Invoice (CII) syntax. Mercurius converts such documents into their Peppol BIS Invoice (UBL-based) equivalent, before transmitting them to the receiver. Therefore, this format is not listed above.

Sequence of simpl.ePRIOR operations to apply

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

sequence

comment

sequence

comment

  1. submitInboxRequest

  • the receiverId is the only mandatory parameter.

  • you can filter the documents per sender, per document Type, per documentFormat

  1. For each document listed in the response,

    2.a. retrieveRequest

Mercurius returns the document in the payload.

attached files are provided using SWA protocol, instead of inline encoding (see applicable section)

    2.b. mark Request

the markRequest is the confirmation that the document was duly retrieved, and the command to remove the document from the inboxRequestResponse

(b) Response to an Invoice/CN

supported formats:
  • Peppol BIS (2.0) MLR (CENBII-conformant) - in phase out - deadline: 30/03/2022 - starting a project to send responses to an invoice using the MLR is strongly discouraged, and not supported by BOSA. This part of the documentation is only available for current users.

  • Peppol BIS InvoiceResponse (IMR) - not yet supported: in phase in - availability : October 2021

See "defined Document formats" for detailed format specifications.

Remarks:

  • The use of old BIS (2.0) MLR by the Belgian Public sector for responding to invoices, originates from the fact that when we adopted Peppol, there was no Invoice Response document type available. The introduction of the Invoice Response took several years to schedule, also due to the many other changes that needed to be performed.

  • in phase 1, the IMR will be used only for business scenarios limited to approval and rejection. Other scenarios will be introduced later, depending on the progress of the user community. Mercurius will support the exchange of Invoice Responses beyond this limitation, however the information displayed on the Mercurius Portal may not be fully aligned with the other possible statusses.

Sequence of simpl.ePRIOR operations to apply

The transmission of the Response is optional. Nevertheless its use is recommended because it creates consistency through the community.

It is performed in one single step:

sequence

comments

sequence

comments

submitDocumentRequest

1/ for a functional explanation of the Invoice response, please refer to the applicable documentation (see table below)

2/ Use of old BIS (2.0) MLR involves meeting the following additionnal specification, for the sake of meeting the ePRIOR response codes specifications: the UBL Data Element DocumentResponse/Response/Description must contain:

  • the following codes:

    • invoice approved: 380:1

    • invoice Rejected: 380:2

    • credit note approved: 81:1

    • credit note rejected: 81:2

  • in case of a rejection, the code must be followed by the explanation of rejection reason.

 

Outbound invoicing

This pattern currently consists only one outbound flow : submission of an invoice /CN.

sending an Invoice/CN

supported formats:
  • Peppol BIS INVOICE (EN-conformant )

  • Peppol BIS CREDIT NOTE (EN-conformant )

See "defined Document formats" for detailed format specifications

Sequence of simpl.ePRIOR operations to apply

This exchange is performed in one single step:

sequence

comments

sequence

comments

submitDocumentRequest

  • if the receiver does not support the document format, then Mercurius posts an MLR (2.0) in the inbox of the sender to notify the failure of the transmission.
    NB: (a) it is not supposed to happen, as senders are supposed to use that flow only if they know that it will work; (b) see below information

  • documents may contain attachments. in this case attachment must be transmitted using SWA protocol (cf appropriate section of this document)

Since december 2020, in the context of the Hermes project, any entreprise registered in the Belgian Crossroad Bank of Enterprises can receive a Peppol BIS invoice. This enables invoice senders on Peppol to reach all their Belgian Customers, under the conditin that such senders agree with the Hermes terms and conditions. all Public sector entities using the services of Mercurius can also agree with the Hermes Terms and conditions, and thereby also benefit of the bigger reach enabled by Hermes.

In the happy flow (when the sending meets all Hermes terms and conditions), the use of Hermes is already supported.

Both Hermes and Mercurius need to be adjusted to cope with the error flow (if the sending does not meet the terms and condition). The adjustment works are ongoing. support of the error flow is expected to be available in october 2021.

Upcoming changes (update: Apr 9, 2021 )

  • add a invoice response reception flow: this is part of the introduction of the Invoice Response (IMR), see section “(b) response to an invoice” above. This is in development. Target availability date: October 2021.

  • see above: support of the Hermes error flow is expected to be available in October 2021.

Outbound e-Ordering

Outbound e-Ordering involves (a) issuing an Order, and (b) receiving an OrderResponse

(a) issuing an Order

supported formats:

Peppol BIS ORDER

See "defined Document formats" for detailed format specifications

Sequence of simpl.ePRIOR operations to apply

This exchange is performed in one single step:

sequence

comments

sequence

comments

submitDocumentRequest

  • if the receiver does not support the document format, then Mercurius posts an MLR in the inbox of the sender to notify the failure of the transmission.
    NB: (a) it is not supposed to happen, as senders are supposed to use that flow only if they know that it will work; (b) see "upcoming changes"

  • documents may contain attachments. in this case attachment must be transmitted using SWA protocol (cf appropriate section of this document)

(b) receving an OrderResponse

supported formats:

Peppol BIS order Response

See "defined Document formats" for detailed format specifications

Sequence of simpl.ePRIOR operations to apply

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

sequence

comment

sequence

comment

  1. submitInboxRequest

  • the receiverId is the only mandatory parameter.

  • you can filter the documents per sender, per document Type, per documentFormat

  1. For each document listed in the response,

    2.a. retrieveRequest

Mercurius returns the document in the payload.

attached files are provided using SWA protocol, instead of inline encoding (see applicable section)

    2.b. mark Request

the markRequest is the confirmation that the document was duly retrieved, and the command to remove the document from the inboxRequestResponse

Upcoming changes (update: Apr 9, 2021 )

  • Conversion of Order into human-readable equivalent in case destination entity is not yet able to process structured electronic order: in development - target imeframe: summer 2021

  • Conversion or orderResponse into human-readable equivalent in case destination entity is not yet able to process structured electronic order - target imeframe: summer 2021

Legacy flows (decommissioned)

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

ePRIOR is also a suite of CEN-BII-, UBL2.0-based document formats (invoice, credit note, application response, attached document ...). Based on these documents formats, several flows were set up and kept alive until ePRIOR interface is completely stopped.

Additionally, in the context of the BIS BILLING migration, the old BIS (2.0) Invoice and credit note was also phased out, after due migration towards the new Peppol BIS invoice and credit note.

Here is the list of decommissioned flows

  • inbound ePRIOR Invoice

  • inbound ePRIOR CreditNote

  • inbound ePRIOR Attached Document

  • outbound ePRIOR Application Response

  • inbound Peppol old BIS (2.0) Invoice

  • inbound Peppol old BIS (2.0) CreditNote

Document formats specifications

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

  • defining the detailed semantics of the documents, and

  • mapping the semantics into the (UBL) Syntax.

The semantic layer are defined by standardization teams. The new Peppol BIS Invoice format is an implementation of the European Norm for electronic invoicing, that provides the semantic specification and the syntax binding. Peppol teams only add implementation-level specifications.

Defined document formats

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

Format specifications

Document format

UBL DocumentTypeCode

syntax (XSD)

semantic

status, remarks

Document format

UBL DocumentTypeCode

syntax (XSD)

semantic

status, remarks

BIS Invoice

UBL-Invoice-2.1.xsd

http://docs.Peppol.eu/poacc/billing/3.0/

BIS Credit Note

UBL-CreditNote-2.1.xsd

old BIS 2.0 Message Level Response (MLR)

301

UBL-ApplicationResponse-2.1.xsd

Peppol BIS 36A Message Level Response

  • in phase out - Deadline 30/03/2022

  • only supported for outbound traffic

BIS Order

220 (supported variant: 227)

UBL-Order-2.1.xsd

https://docs.peppol.eu/poacc/upgrade-3/profiles/28-ordering/

 

Order Response

231

UBL-OrderResponse-2.1.xsd

 

Invoice Response

23

UBL-ApplicationResponse-2.1.xsd

https://docs.peppol.eu/poacc/upgrade-3/profiles/63-invoiceresponse/

bidirectional support - in development - target date: October 2021


Peppol Format identifiers

format

Document Format Id /Document identifier/ customisationID  

Process ID / Profile ID

format

Document Format Id /Document identifier/ customisationID  

Process ID / Profile ID

BIS INVOICE

busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:Peppol.eu:2017:poacc:billing:3.0::2.1

urn:fdc:Peppol.eu:2017:poacc:billing:01:1.0

BIS CN

busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:Peppol.eu:2017:poacc:billing:3.0::2.1

 

urn:fdc:Peppol.eu:2017:poacc:billing:01:1.0

CII EN-compliant INVOICE (*)

busdox-docid-qns::urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100::CrossIndustryInvoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::D16B

cenbii-procid-ubl::urn:fdc:peppol.eu:2017:poacc:billing:01:1.0

old BIS 2.0 MLR

busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:www.cenbii.eu:transaction:biitrns071:ver2.0:extended:urn:www.Peppol.eu:bis:Peppol36a:ver1.0::2.1

cenbii-procid-ubl::urn:www.cenbii.eu:profile:bii36:ver2.0

BIS order

busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Order-2::Order##urn:fdc:peppol.eu:poacc:trns:order:3::2.1

cenbii-procid-ubl::urn:fdc:peppol.eu:poacc:bis:ordering:3

BIS orderResponse

busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2::OrderResponse##urn:fdc:peppol.eu:poacc:trns:order_response:3::2.1

cenbii-procid-ubl::urn:fdc:peppol.eu:poacc:bis:ordering:3

(*) Support of this format is only mentioned for the sake of completeness: mercurius converts such documents into their UBL equivalent to make them available to the simpl.ePRIOR consumer application.

The message type you have to support are the one defined for your organisation in the SMP. See http://smp.belgium.be.

1 2 3 4 curl -X GET --header 'Accept: application/xml' 'http://smp.belgium.be/{identifierscheme}::{id} id Identifier of Peppol participant identifierscheme Scheme under which the identifier is registered

 

Documents Format Validation

You can validate that your message contain documents that respect format specifications with the following tools :

NB: the tools allowing to use different rules set, it is important to use the correct rules set, ie the latest version of the rules set that contains the exact format denomination (example : BISV2 INVOICE 4A).

Develop your own validation tool via :

BOSA doesn't support those tools, for question please direct them to their respective developers.

Definitions

Mercurius

Mail-room from the Belgian Public sector, for e-Procurement related structured electronic documents

Peppol

Pan-European Public Procurement Online, Peppol enables businesses across Europe and beyond to communicate electronically with public buyers in various stages of the procurement process

OpenPeppol

OpenPeppol is a non-profit international association under Belgian law (Association Internationale Sans But Lucratif – AISBL) and consists of both public sector and private members. The association has assumed full responsibility for the development and maintenance of the Peppol specifications, building blocks and its services and implementation across Europe.

Integrators

Integrators allow service consumers to access the simpl.ePRIOR service exposed by the Mercurius platform. The service on the Mercurius platform is only accessible to integrators : Federal ( FSB ) or regional ( Magda, ... )

Portal

Also known as the Mercurius portal, it allows customers and suppliers to monitor (track and trace) the documents received and sent. It provides business information (sender, receiver, business status, date, ...) and access to technical information (messages exchanged, technical status, ...)

FAS

Federal Authentication Service authenticates authorises users to access the Mercurius Portal

Supplier

A supplier is an enterprise that contributes goods or services. Generally, a supply chain vendor manufactures inventory/stock items and sells them to the next link in the chain. Today, these terms refer to a supplier of any good or service.

See https://en.wikipedia.org/wiki/Supplier

The Peppol definition is the following :

The supplier is the legal person or organization who provides a product and/or service.
Examples of supplier roles: seller, consignor, creditor, economic operator.

Customer

In sales, commerce and economics, a customer (sometimes known as a client, buyer, or purchaser) is the recipient of a good, service, product or an idea - obtained from a seller, vendor, or supplier via a financial transaction or exchange for money or some other valuable consideration.

See https://en.wikipedia.org/wiki/Customer

The Peppol definition is the following :

The customer is the legal person or organization who is in demand of a product and/or service.
Examples of customer roles: buyer, consignee, debtor, contracting authority.





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.

FAQ

Question

Response

Question

Response

I can find the attached document in the SOAP Response

The document is transmitted using SOAP with Attachment ( SWA ) and it's part of the MIME part of the message. Most JAVA libraries can handle SWA without problem.

There are no URL to test the service defined on this page

The URLs exposing the service implementation are defined by the integrators, please contact yours.

Do you support REST

No, only SOAP.

Can you review my code?

No, we don't have the resource to review code. We can help you in case of integration issues but it's on a best effort only.

Do the different integrators expose the same WSDL

In 99.9% it's the same WSDL. The most differences are related to WS-Security policies implemented and enforced by the integrators.

Do you provide test cases?

Yes, but it's not part of this document. Test cases are provided with the integrators on-boarding kit.

Description

Link