Tutorial: Receiving an "Order Response" from the seller

Once the purchase order is successfully delivered to the receiver access point you can expect to get a hook with topic OrderResponseReceived. The OrderResponseReceived event message will contain the status of the document on the seller's behalf.

Prerequisite

• An order is successfully delivered, an OrderSent topic is provided.
• The buyer supports the "Order Response".

Step 1: Register hook

Register a hook for the topic OrderResponseReceived.

Webhook example:

{
   "id": "1",
   "name": "webhook",
   "action": "https://webhook.site/a81a0be5-8aad-4110-a40c-aa41a2c6e9ac#secureKey",
   "topics": [
     "OrderResponseReceived"
   ],
   "isActive": true
}

Step 2: Register capability in Peppol

You have to register the Order Response as a capability in the SMP if you want to receive status messages via Peppol.

We advise to update your default Peppol configuration using PUT /api/v1/peppol/config by putting the state of the orderResponse or orderResponseAdvanced capability to "on". For example:

{  
  "capabilities": {
    "orderResponse": {
      "state": "on",
      "description": "PEPPOL Order response transaction 3.3"
    }
  }
}

It is also possible to do this per partyId using the PUT /api/v1/peppol/config/party/{partyId} endpoint. Read more about the the Peppol SMP.

Step 3: Wait till the event arrives

Once the order response message is received a hook with topic OrderResponseReceived will be sent.

{
	"topic": "OrderResponseReceived",
	"partyId": "NL:KVK:RECEIVER",
	"hookId": "111",
	"documentId": "b34d7213-dd81-4a23-8867-99b12b4ca39e",
	"refToDocumentId": "2a737b9e-a724-4153-8a86-4fb8f334db8b",
	"message": "'OrderResponse' received. Status: 'Accept'.",
	"details": {
		"note": "Order accepted and will be delivered on due date.",
		"statusCode": "AP",
		"status": "Accept",
		"id": "12115118",
		"protocol": "As4",
		"returnedMessageId": "b34d7213-dd81-4a23-8867-99b12b4ca39e@econnect.eu",
		"sender": "NL:KVK:SENDER",
		"accessPoint": "C=NL, O=eConnect International B.V., OU=PEPPOL TEST AP, CN=PNL000052",
		"documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2::OrderResponse##urn:fdc:peppol.eu:poacc:trns:order_response:3::2.1",
		"profileId": "urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3",
		"receiver": "NL:KVK:RECEIVER",
		"messageId": "5156bf0f-9bf7-4687-9ae7-a678c7931a9b@econnect.eu",
		"refToMessageId": "2a737b9e-a724-4153-8a86-4fb8f334db8b@econnect.eu"
	},
	"createdOn": "2022-01-28T14:26:52.3980938+00:00",
	"sentOn": "2022-01-28T14:26:52.6101319+00:00"
}

Some useful fields of the received order response are:

Field	Description
documentId	Id that uniquely identifies the received Order Response
refToDocumentId	Id that identifies sent Order
message	Summarize message
details	Order response object

The hook contains most information to process the response. However, you could also download the received Order Response using GET /api/v1-beta/{partyId}/generic/{documentId}/download. When a Conditionally Accepted response is received it's important to always download the full response message, because the response codes on line level are not included in the hook.