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 | ||||||
---|---|---|---|---|---|---|
|
...
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
...
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:
|
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 |
|
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: )
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 |
|
(b) receving an OrderResponse
...
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 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/ |
| ||
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 - in development - target date: |
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. |
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) |