version | 2.0 |
---|---|
published |
|
comment | Readers are welcome to send questions and/or provide comments by email to mercurius@bosa.fgov.be |
Contents
Table of Contents | ||||||
---|---|---|---|---|---|---|
|
...
The solution setup in Belgium for the business to government exchanges is composed of the following keyline elements:
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.
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
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.
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.
...
Example: to receive an invoice and return a business response, the following 3-phases sequence applies to the simpl. ePRIOR consumer application:
the consumer collects incoming invoice:
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.
we assume that an invoice is waiting to be picked up
we also assume that it is a Peppol BIS Invoice
the consumer performs a retrieveRequest to pick up the invoice
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
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
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: 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
...
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 |
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
|
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 (*) |
---|---|---|
|
|
|
(*) See SOAP Fault section for more details |
...
submitInboxRequest
Code Block | ||
---|---|---|
| ||
<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(*) |
---|---|---|
|
|
|
(*) See SOAP Fault section for more details |
Request
...
retrieveDocument
Code Block | ||
---|---|---|
| ||
<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(*) |
---|---|---|
|
|
|
(*) See SOAP Fault section for more details |
Request
...
markDocument
Code Block | ||
---|---|---|
| ||
<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 |
|
(*) See SOAP Fault section for more details |
Request
...
submitDocument
Code Block | ||
---|---|---|
| ||
<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:
|
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 |
---|---|
|
|
| |
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 InvoiceResponse (IMR) - In production as of March 2022
Peppol BIS (2.0) MLR (CENBII-conformant) - in phase out - deadline: Decommissioned as of 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.
...
It is performed in one single step:
sequence | comments |
---|---|
submitDocumentRequest |
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.
...
Outbound invoicing
This pattern currently consists only one outbound flow : submission of an invoice /CN.
(a) Sending an Invoice/CN
supported formats:
Peppol BIS INVOICE (EN-conformant )
Peppol BIS CREDIT NOTE (EN-conformant )
...
This exchange is performed in one single step:
sequence | comments |
---|---|
submitDocumentRequest |
|
|
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 2021March 2022. |
...
(b) Receiving Response
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.
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
...
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)
...
March 2022.
Sequence of simpl.ePRIOR operations to apply
Each time a new processing cycle starts, the collection of incoming documents takes three steps:
sequence | comment |
---|---|
|
|
| |
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 |
Outbound Ordering
Outbound 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 |
---|---|
submitDocumentRequest |
|
(b) Receiving an Order Response
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 |
---|---|
|
|
| |
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:
...
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
...
)
None
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/ |
|
| |||
BIS Credit Note | multiple, cf https://docs.Peppol.eu/poacc/billing/3.0/codelist/UNCL1001-cn/ | ||
old BIS 2.0 Message Level Response (MLR) | 301 |
|
| ||||
BIS Order | 220 (supported variant: 227) | https://docs.peppol.eu/poacc/upgrade-3/profiles/28-ordering/ | ||
Order Response | 231 | |||
Invoice Response | 23 | https://docs.peppol.eu/poacc/upgrade-3/profiles/63-invoiceresponse/ | bidirectional support |
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.
...
https://Peppolecosio.helger.com/public/menuitem-validation-bis2en/peppol-and-xml-document-validator/
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).
...
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. |
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. |
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 | ||
---|---|---|
|
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) | |
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 | |
Mercurius platform, portal-site homepage | |
list of Peppol receivers registered in smp.belgium.be | |
simpl.ePRIOR relevant documentation on FSB (access, proxy-service) |
sources of diagrams shown on the page | |
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) |