...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
version | 1.1 |
---|---|
published |
|
comment | This page is still the subject of additional validation cycles. Readers are welcome to send questions and/or provide comments by email to mercurius@bosa.fgov.be |
Contents
Table of Contents | ||||||
---|---|---|---|---|---|---|
|
Purpose and target Audience
...
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.
...
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 offers a framework that enables this universal "new way of posting".
...
SRC https://peppol.eu/about-openpeppol/
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.
...
Scope covered by this document
...
The Simpl.ePRIOR webs service defines the following four operations : submitDocument, submitInboxRequest, retrieveDocument, and markDocument. Each 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 (BISv3 INVOICE, BISv2 ORDER, BISv2 MLR, ...) and (b) be combined appropriately.
Example: to handle an inbound invoice, the following 3-phases sequence applies:
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 BISv3 Invoice (see later form more explanations over document formats, BISv2 and BIS v3)
the consumer performs a retrieveRequest to pick up the invoice
the consumer performs a mark request to notify Mercurius that it successfully retrieved the invoice, and that the invoice can be removed from the business entity's inbox
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 posts a response to the original document sender, notifying him of the results of the processing by the business entity. It uses the following document format: PEPPOL BIS v2 MessageLevelResponse (MLR).
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 only supports the transport of UBL documents. Although the subject has been informally discussed, no requirements any other syntax have been raised to date, such as UN/CEFACT, EDIFACT, ...
(**) 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 [
Cmt
: hasn't yet been checked]
).Inbound document validation is performed asynchronously - due to a lack of consensus to exploit the PEPPOL transport protocol (AS2/AS4), to send non-conformance feedback (it is questionable whether this belongs to the transport layer). Fatal validation errors on inbound documents are handled as breaches against the PEPPOL agreements. Therefore the documents are intercepted and propped with no further follow up. This aspect does not affect the interface with the Public sector. Howver, it adds context to the end-to-end business exchanges with business correspondents, which our service consumer must be aware of to properly drive their end-to-end projects.
How to test the service?
To familiarise yourself with the web service, you can use SOAPUI.
...
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.
View file | ||
---|---|---|
|
...
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
...
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, 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
|
To process an offered invoice, you must perform the following steps in this order :
Submit Inbox
Retrieve Document
Mark document
Submit Document
Submit Inbox
Description
This operation accesses the inbox on Mercurius for a particular receiverID. Note that you need to have a contractual obligation before you can access a receiver's inbox ( to be configured with your integrator ).
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> |
Response
...
submitInboxRequestResponse
Code Block | ||||
---|---|---|---|---|
| ||||
<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 | 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> |
Response
...
...
retrieveDocumentResponse
Code Block | ||||
---|---|---|---|---|
| ||||
<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 | 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> |
Response
...
MarkDocumentResponse
Code Block | ||||
---|---|---|---|---|
| ||||
<soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:v1="http://fsb.belgium.be/einvoicing/simpleprior/v1_00"> <soapenv:Header> <wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wsu:Timestamp wsu:Id="Timestamp-HvumButHp993jGDym7t89Q22" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsu:Created>2018-10-03T10:07:55Z</wsu:Created> <wsu:Expires>2018-10-03T10:12:55Z</wsu:Expires> </wsu:Timestamp> <!—More elements on security and signature:--> </wsse:Security> </soapenv:Header> <soapenv:Body> <v1:markDocumentResponse> <!—When successful ackIndicator is true--> <v1:ackIndicator>true</v1:ackIndicator> <!—When an exception occurred ackIndicator is false--> <v1:ackIndicator>false</v1:ackIndicator> --> </v1:markDocumentResponse> </soapenv:Body> </soapenv:Envelope> |
Submit Document
Description
This operation allows to send a document type to a supplier. The format of the document must be supported by Mercurius/simpl.ePRIOR, which involves an intake of the format (see supported document flows). Additionally, the receiver must support that document format, meaning he must have published the receiving capability in a PEPPOL SMP. NB: to increase interoperability, Mercurius will soon add a default conversion to human readable of the documents whose receivers do not yet support the document format used by the sender. This echoes the already existing conversion for inbound documents, that was implemented to accelerate regularisation of Belgian public sector towards directive 2014/55.
Parameters
Input | Output | Exception |
---|---|---|
valid 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> |
Response
...
...
submitDocumentResponse
Code Block | ||||
---|---|---|---|---|
| ||||
<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> |
...
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 that this might make the UBL document invalid regarding the specific schematron validation. This must accepted, however, the document must be valid if the base64 are re-inserted in the UBL.
Code Block |
---|
------=_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.
...
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
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, ... ).
...
The initial, inbound flow of this pattern currently handles four possible formats:
PEPPOL BISv2 INVOICE (CENBII-conformant) : optional since . In practice all current users do support this format and need to maintain it, to preserve business continuity
PEPPOL BISv2 CREDIT NOTE (CENBII-conformant ): optional since . In practice all current users do support this format and need to maintain it, to preserve business continuity
PEPPOL BIS v3 INVOICE (EN 16931-conformant) : mandatory since due to Directive 2014/55. In practice current users are still finalizing the intake of this format
PEPPOL BIS v3 CREDIT NOTE (EN 16931-conformant): mandatory since 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
...
Each time a new processing cycle starts, the collection of incoming documents takes three steps:
sequence | comment |
---|---|
1. submitInboxRequest |
|
2. 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 Mark request 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
...
It is performed in one single step:
sequence | comments | |||
---|---|---|---|---|
submitDocumentRequest | the following table provides the explanation of the response codes used by the Belgian public sector to communicate the result of the processing of the invoice/CN/attached document. This results from the original implementation ePRIOR | |||
Code | Valeur | Remarque | Légende de la remarque | |
81:1 | Credit Note approved | 1: In case of response code 81:2 or 380:2, the response also contains additional textual description of the rejection, provided by the customer | ||
81:2 | Credit Note rejected | 1 | ||
81:3 | Credit Note ID already exists | 2 | ||
81:4 | Hard business rule violated | 2 | ||
380:1 | Invoice approved | 2: codes 81:3, 81:4, 380:3 and 380:4 relate to business preprocessing, performed by Mercurius. see next paragraph for more info | ||
380:2 | Invoice disputed | 1 | ||
380:3 | Invoice ID already exists | 2 | ||
380:4 | Hard business rule violated | 2 |
Upcoming changes (update: )
generalization of PEPPOL BISv3 INVOICE and CREDIT NOTE: support of PEPPOL BISv3 invoice and credit note is active on Mercurius; however the activation of this format in Production must still happen. This step takes various test and coordnation activities. It is expected to be over in the coming weeks.
phase out of PEPPOL BIS v2 MLR , phase-in of PEPPOL BIS v3 IMR:
The MLR is not the most suitable format to exchange business information between business entities. This document format was chosen for historical reasons.
Now there is a new document format available, BIS IMR. Mercurius will be configured soon to support the BIS IMR v3.
this configuration has not yet been scheduled. additionally, the proper introduction of IMR requires coordination with suppliers actually using MLR. This is a significant piece of work that must be duly analyzed and planned together with the configuration
Outbound invoicing
This pattern currently consists only one outbound flow : submission of an invoice /CN.
The inbound flow, collection of the response, is not configured yet. It is foreseen, but not scheduled yet. see "upcoming changes"
For Mercurius staff, see also page
201 - Simpl.ePRIOR: Outbound Invoicing - Implementation
(secured page)
sending an Invoice/CN
supported formats:
PEPPOL BISv2 INVOICE (CENBII-conformant )
PEPPOL BISv2 CREDIT NOTE (CENBII-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 |
---|---|
submitDocumentRequest |
|
Upcoming changes (update: )
add PEPPOL BISv3 INVOICE and CREDIT NOTE document formats:
This capability will enable G2G exchanges of EN-conformant invoices. It requires configuration on the simpl.ePRIOR flow.
It is a high-priority requirement. It is planned, target date .
For Mercurius staff only: see page 219 - Outbound (G2B) Invoicing - BIS3 support (secured page).
add a response reception flow: this involves configuring inbound PEPPOL BIS IMR support, and may also require more configuration and more preparation.
adding a PDF plan B to the main flow:
the current situation generates a lot of burden to the public sector entity that sends the documents: the entity must know in advance for each receiver if he is capable of receiving the PEPPOL BIS format, and find other ways to handle the sendings to other receivers
to improve this, Mercurius will soon generalize a logic that converts the document and sends it via pdf/email if the receiver does not have suitable receiing capabilities. this way the public sector entities are freed from the cumbersome process described above, and can plan massive use of the outbound flows.
Outbound ordering
This pattern currently consists only one outbound flow : sending an order.
...
This exchange is performed in one single step:
sequence | comments |
---|---|
submitDocumentRequest |
|
Upcoming changes (update: )
adding the response reception flow: order response. This is currently not being planned yet.
adding a PDF plan B to the main flow:
the current situation generates a lot of burden to the public sector entity that sends the documents: the entity must know in advance for each receiver if he is capable of receiving the PEPPOL BIS format, and find other ways to handle the sendings to other receivers
to improve this, Mercurius will soon generalize a logic that converts the document and sends it via pdf/email if the receiver does not have suitable receiing capabilities. this way the public sector entities are freed from the cumbersome process described above, and can plan massive use of the outbound flows.
Outbound e-Ordering
This section will be available soon.
...
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, the following series of flows was set up and kept alive until ePRIOR interface is completely stopped. See also Transition from ePRIOR interface to simpl.ePRIOR (temporary section).
These flows are:
inbound ePRIOR Invoice
inbound ePRIOR CreditNote
inbound ePRIOR Attached Document
outbound ePRIOR Application Response
Document formats specifications
The document in the payload are based on specificatiosn 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 3 Invoice format is an implementation of the european standard for electronic invoice, that provides the semantic specification and the syntaxt 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 |
---|---|---|---|---|
BIS V2 Invoice | 380 |
| ||
BIS V2 Credit Note | 81 | |||
BIS V3 Invoice | http://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL1001-inv/ |
| ||
BIS V3 Credit Note | https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL1001-cn/ | |||
BIS V2 Message Level Response (MLR) | 301 |
| ||
BISV2 Order | //// | outbound support | ||
Order Response | 231 | Not supported, no intake programmed yet | ||
Invoice Response | 23 | intake programmed, but not yet started |
( * ) the codes shown in this table were historicaly used with ePRIOR to qualify the invoice and credit note. They are also reflected in the status codes that were used then (confer the table in section Inbound Invoicing). All invoice and credit notes receivers are supposed to be able to handle the documents with these UBL Document Type Codes. NB: due to the alignment of Mercurius to the Peppol framework, other codes can be used in teh invoices and credit notes. to see the full list, please consult these documents : Invoice type code (UNCL1001 subset) and Credit note type code (UNCL1001 subset). It is up to each document receiver to decide how to handle these patterns.
PEPPOL Format identifiers
format | Document Format Id /Document identifier/ customisationID | Process ID / Profile ID |
---|---|---|
BISV2 Invoice | busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0::2.1 busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0::2.1 | cenbii-procid-ubl::urn:www.cenbii.eu:profile:bii04:ver2.0 cenbii-procid-ubl::urn:www.cenbii.eu:profile:bii05:ver2.0 |
BISV2 CN | busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:www.cenbii.eu:transaction:biitrns014:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0::2.1 | cenbii-procid-ubl::urn:www.cenbii.eu:profile:bii05:ver2.0 |
BIS V3 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 V3 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 |
BISV2 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 |
The message type you have to support are the one defined for your organisation in the SMP. See http://smp.belgium.be.
...
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.
...
This paragraph provides users of former ePRIOR with specific information to migrate from ePRIOR to simpl.ePRIOR.
Transition
Both interfaces are available in parallel.
The legacy invoices and CNs, sent by (5) suppliers still using the interface implemented during the Pilot-phase (not yet PEPPOL), are only accessible through the ePRIOR interface.
All portal invoices (and CN), all BIS2 Invoices (and CN), and all EDIFACT-pilot invoices are accessible through both interfaces.
Only simpl.ePRIOR gives access to BIS3 and UNCEFACT/CII invoices and CNs.
Only simpl.ePRIOR enables outbound flows.
The message layer data accessible through the Mercurius Portal, enables the follow up of the pickup of the documents on both interfaces, making it very convenient to follow up.
It is recommended to encourage pilot suppliers to migrate to PEPPOL. If a few weeks is needed, it is recommended to use following pattern at each invoice collection cycle:
pick up invoices through simpl.ePRIOR interface (and mark all collected invoices);
pick up remaining invoices on ePRIOR interface.
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 platform |
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 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) |