PEPPOL Service Bus Reviews

With review (beta) you can send and receive technical (and hopefully soon business) messages about processing the business documents. It is very useful to let the sender know about the internal state of the received document.

When an access point has accepted an inbound message, it does not guarantee that the final recipient has successfully processed the document. That is why the Peppol community came up with the Message Level Response (MLR) and Business Level Response (BLR) in order to return this information to the original sender.

Send reviews

To notify the original sender about the processing of your received documents use the POST /api/v1-beta/{partyId}/review endpoint.

You could either “accept” or “reject” the document and provide a reason for that. For example, the document is rejected, because the given purchase order is not known. The Peppol Service Bus (PSB) will notify the sender about your review via the Peppol network.

{
   "documentId": "{the inbound documentId}",
   "type": "Technical",
   "verdict": "Reject",
   "reason": "Purchase order PO12389 not known."
}

It could happen that the receiver of the review (the sender of the original document) doesn’t support this flow. Then the PSB will trigger the hooks with the topic “ReviewSentError”. It is advised to implement a fallback flow based on this topic.

Send review fallback

If you don’t have a flow for the “ReviewSentError”, then the PSB can send an email to the original sender of the document. Then you need to register a mail hook that listens to the “ReviewSentError”, like this:

{
   "id": "tvr-fallback",
   "name": "mail",
   "action": "mailto:[ReceiverEmailAddress]",
   "topics": [
     "ReviewSentError"
   ],
   "isActive": true
}

Receiving reviews

To receive reviews you have to register a hook with the topic “ReviewReceived”. Note that the webhook will contain a details element with the verdict of the review.

{
	"topic": "ReviewReceived",
	"partyId": "NL:KVK:ECONNECTTEST",
	"hookId": "2",
	"documentId": "bbb84a79-f8b8-48dc-96ef-4d7ad9a80b64",
	"details": {
		"reviewId": "d6fb6485-8350-40f0-b697-0ad1858490b9",
		"verdict": "Reject",
		"type": "Technical",
		"reason": "Purchase order PO12389 not known."
	},
	"createdOn": "2019-06-18T14:06:35.4399175+00:00",
	"sentOn": "2019-06-18T14:06:35.6383675+00:00"
}

DocumentId referse to the document that is reviewed.

You can download the full application response XML using the reviewId as {documentId} via the GET /api/v1/{partyId}/review/{documentId}/download endpoint.

It’s also possible to delete the received review via the DELETE /api/v1/{partyId}/reivew/{documentId}

Topics

The available topics for the hooks are:

  • ReviewReceived
  • ReviewReceivedError
  • ReviewSent
  • ReviewSentError
  • ReviewSentRetry

In-depth

The MLR is a UBL Application Response document that is sent via the regular send flow. Thus, via a SMP lookup, as they do in Belgium.

The following document type id is used: urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse2::ApplicationResponse##urn:www.cenbii.eu:transaction:biitrns0071:ver2.0:ex tended:urn:www.peppol.eu:bis:peppol36a:ver2.0::2.1

When the technical validation response (TVR) is ready we might switch to the Peppol envelope (SBHD) for the response document. At this moment nobody is using the TVR, so we focus on the MLR. In the meanwhile, we are waiting for the Peppol workgroup to finish the TVR specifications.

Was this article helpful?