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",
        "version": "v3"
    }
]

For more information on this endpoint, see our API reference: Get Polling Resources.

Next you can mark the transactions as being delivered or failed:

curl --request POST \
     --url https://api.orderful.com/v3/transactions/confirm-delivery \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'orderful-api-key: {$yourAPIKey}' \
     --data '
[
     {
          "transactionId": "{$transactionId1}",
          "deliveryStatus": "DELIVERED",
          "note": "{optional}"
     },
     {
          "transactionId": "{$transactionId2}",
          "deliveryStatus": "DELIVERED",
          "note": "{optional}"
     }
]
'

On success you will get an HTTP 200. For more information on this endpoint see our API reference: Confirms the delivery of a set of transactions

You should then confirm retrieval and remove the transactions:

curl --location --request POST 'https://api.orderful.com/v3/polling-buckets/{$bucketId}/confirm-retrieval' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'orderful-api-key: {$yourAPIKey}' \
--data '{
    "resourceIds": [{$transactionId1}, {$transactionId2}] 
}'

On success you will get an HTTP 200. For more information on this endpoint see our API reference: Removes a Set of Transaction From a Bucket

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
• Ensure you’re removing transactions from the polling bucket after processing them, using the endpoint that Removes a Set of Transaction From a Bucket.