Use the Inbound Poller API

If you retrieve transactions from Orderful via polling, the transactions sit in a “bucket” until they are retrieved and retrieval is confirmed. Upon confirmation, the transactions are cleared from the bucket.

Set up an Inbound Poller

1. Go to your Communication Channels settings .
2. Under "Inbound", click on Create Channel > Poller.
3. Enter a descriptive Name.
4. Click Create.

Test your Inbound Poller

To test that your new Poller is working correctly, you can create an inbound transaction, send it to your poller and query the polling bucket via API.

1. Go to your Communication Channels settings.
2. Under "Inbound", select the Inbound Poller that you would like to test. This will open a side panel.
3. Copy the "Retrieval URL".
4. You can now enter the URL into your HTTP client of choice. For example, if you use cURL:

curl --location --request GET 'https://api.orderful.com/v3/polling-buckets/{$bucketId}' \
--header 'orderful-api-key: {$yourAPIKey}'

On success you will receive back a JSON payload:

[
    {
        "id": "{transactionId1}",
        "sender": {
            "isaId": "senderIsaId"
        },
        "receiver": {
            "isaId": "receiverIsaId"
        },
        "type": {
            "name": "855_PURCHASE_ORDER_ACKNOWLEDGMENT"
        },
        "stream": "TEST",
        "message": {
            [...]
        },
        "createdAt": "2021-10-04T17:52:25.688Z",
        "lastUpdatedAt": "2021-10-04T17:52:25.883Z",
        "delivery": {
      	"href": "https://api.orderful.com/v3/deliveries/{deliveryId}",
      	"approve": {
        	"href": "https://api.orderful.com/v3/deliveries/{deliveryId}/approve"
        },
        "fail": {
          "href": "https://api.orderful.com/v3/deliveries/{deliveryId}/fail"
        }
      }
    }
]

For more information on this endpoint, see our API reference: Get Transactions from Poller Bucket.

Next you can either approve or fail your Transaction delivery. The links to approve or fail a Delivery are included in the JSON above for each Transaction in your Polling Bucket.

To approve a Delivery:

curl --request POST \
     --url https://api.orderful.com/v3/delivery/{deliveryId}/approve \
     --header 'Accept: application/json' \
     --header 'orderful-api-key: {yourAPIKey}' \
     --data '
{
     "note": "{optional}"
}

To fail a Delivery:

curl --request POST \
     --url https://api.orderful.com/v3/delivery/{deliveryId}/fail \
     --header 'Accept: application/json' \
     --header 'orderful-api-key: {yourAPIKey}' \
     --data '
{
     "note": "{optional}"
}

For more information on these endpoint, see our API reference: Approve a Delivery and Fail a Delivery.

📘

Delivery status and Acknowledgment status

You manage the delivery status of a transaction by either approving or failing its delivery.

• The delivery status resets if you resend your transaction to your polling bucket. It updates once you confirm the latest delivery.
• If you send your transaction to multiple communication channels, the delivery status reflects the confirmation from each communication channel.

You control the acknowledgment status by accepting or rejecting the transaction.
You can update the acknowledgment status only once.

The delivery and acknowledgment statuses operate independently. For the same transaction, you might have:

• A Failed delivery status and an Accepted acknowledgment status.
• A Delivered delivery status and an Rejected acknowledgment status.

Poller best practices

When using the Polling Bucket endpoint you can specify the number of transactions returned using the limit query parameter, to a maximum of 100 transactions or 200 MB payload size, whichever the response exceeds first.

When polling transactions, you should:

• Apply a recurring polling schedule.
• If you have a high transaction volume, adapt your polling schedule to poll transactions more frequently (every 5 to 10 minutes for example).
• If you have a high transaction volume and your transactions have a small size, you can also increase the transaction limit from the default 30 to 100 transactions by adding a limit query parameter: https://api.orderful.com/v3/polling-buckets/:pollingBucketId?limit=100