Page Comparison

version	2.0
published	09 Apr 2021
comment	Readers are welcome to send questions and/or provide comments by email to mercurius@bosa.fgov.be

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

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

...

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 (*)
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

Code Block

language	xml

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

...

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

Parameters

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

Code Block

language	xml

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

...

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(*)
receiverdId senderId documentType docId	ackIndicator = True	Document doesn't exist or is not accessible (unauthorized)
(*) See SOAP Fault section for more details

Request

...

markDocument

Code Block

language	xml

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

...

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
valid UBL Document	ackIndicator = True	unsupported document format document format violation (list of errors found)
(*) See SOAP Fault section for more details

Request

...

submitDocument

Code Block

language	xml

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

...

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

...

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

sequence	comment
submitInboxRequest	the receiverId is the only mandatory parameter. you can filter the documents per sender, per document Type, per documentFormat
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

...

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 2021starting : March 2022

See "defined Document formats" for detailed format specifications.

...

It is performed in one single step:

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.

...

This exchange is performed in one single step:

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)

Info

Since december 2020, in the context of the Hermes project, any entreprise company 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 condition that such senders agree with the Hermes terms and conditions. all All Public sector entities using the services of Mercurius can also agree with the Hermes Terms 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 Support of the error flow is expected to be available in october 2021.

Upcoming changes (update: 09 Apr 2021 )

add a an 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 2021March 2022.
see above: support of the Hermes error flow is expected to be available in October 2021.

...

This exchange is performed in one single step:

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

...

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

sequence	comment
submitInboxRequest	the receiverId is the only mandatory parameter. you can filter the documents per sender, per document Type, per documentFormat
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: 09 Apr 2021 )

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

Legacy flows (decommissioned)

...

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

Format specifications

Document format	UBL DocumentTypeCode	syntax (XSD)	semantic	status, remarks
BIS Invoice	multiple, cf http://docs.Peppol.eu/poacc/billing/3.0/codelist/UNCL1001-inv/	UBL-Invoice-2.1.xsd	http://docs.Peppol.eu/poacc/billing/3.0/	EN-compliant list of authorized identification schemes for party identifiers (enpointID): cf Electronic Address Scheme code list (EAS)
BIS Credit Note	multiple, cf https://docs.Peppol.eu/poacc/billing/3.0/codelist/UNCL1001-cn/	UBL-CreditNote-2.1.xsd	http://docs.Peppol.eu/poacc/billing/3.0/
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

March 2022

Peppol Format identifiers

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
PEPPOL Invoice Response transaction 3.0	busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1	cenbii-procid-ubl::urn:fdc:peppol.eu:poacc:bis:invoice_response: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.

...

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.

View file

name	simpleprior_CXF.zip

FAQ

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.

Links

Description	Link
wsdl of the backend service (for info)	http://fe1.babelway.net/simpleprior/simpleprior?WSDL
Peppol.eu page about the Belgian Peppol authority (PA)	http://Peppol.eu/what-is-Peppol/Peppol-country-profiles/belgium-country-profile/?rel=tab664
official webpage of the Belgian Peppol authority	https://openPeppol.atlassian.net/wiki/spaces/Belgium
Mercurius platform, portal-site homepage	https://digital.belgium.be/e-invoicing/MercuriusLogin.html
list of Peppol receivers registered in smp.belgium.be	https://digital.belgium.be/e-invoicing/PeppolinBelgium.html
simpl.ePRIOR relevant documentation on FSB (access, proxy-service)	https://dtservices.bosa.be/fr/services/fsb/demande-dun-service-web-fsb-ou-dun-certificat-fsb/je-demande-dacceder-un-service-web http://dtservices.bosa.be/fr/services/fsb/catalogue/eprocurementservices-s294/documentation-eprocurementservices-s294#S331-MercuriusService%20(Simpl.ePRIOR)
sources of diagrams shown on the page	Simpl.ePRIOR technical documentation
list of authorized identification schemes for party identifiers (enpointID)	cf page: https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/Code+lists, select Electronic Address Scheme code list (EAS)

Versions Compared

Old Version 27

New Version 28

Key

Contents

Parameters

Parameters

Request

Parameters

Request

Parameters

Request

Endpoint URL

(b) Response to an Invoice/CN

Outbound invoicing

Upcoming changes (update: 09 Apr 2021 )

(b) receving an OrderResponse

Upcoming changes (update: 09 Apr 2021 )

Legacy flows (decommissioned)

Format specifications

Peppol Format identifiers

Definitions

References

Sample Code

FAQ

Links