Receiving Dispatch Instruction Responses
This is the right section for you if you are acting as a supplier and looking to receive dispatch instruction responses from a fulfillment provider.
In this guide you will learn how to receive new dispatch instruction responses from the Procuros API, as well as how to paginate over them, mark them as processed, or report any errors with the dispatch instruction responses.
It is important to mark the dispatch instruction responses as processed (either successfully or not) so that the Procuros network can communicate this to your trade partners. This will also prevent them from re-appearing in future GET
requests for transactions data, as well as trigger the error management process in case you mark any documents as errors.
PHP examples are included but you will likely also want to look at the relevant API calls in the API reference.
Table of Contents
- Table of Contents
- Authentication
- Error Handling
- Pull New Dispatch Instruction Responses
- Mark an Dispatch Instruction Response as Processed
- Report an Error Processing Dispatch Instruction Response
Authentication
You will need an API token to authenticate.
We use a bearer token which has to be included in each request you send to the API.
Please read the Authentication section of our API reference for a detailed description.
Error Handling
The API will return a 2xx
status code for successful requests. Anything else indicates an error.
Please read the Errors section of our API reference for a detailed description plus examples of how to handle them.
Pull New Dispatch Instruction Responses
The API call List incoming Transactions is used to fetch all incoming transactions.
// install dependency
// $ composer require guzzlehttp/guzzle
<?php
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.procuros.io/v2/transactions', [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer <your-api-token>',
],
]);
$body = json_decode((string) $response->getBody());
$items = $body->items;
Loading Different Document Types
Scenario 1: You only want to load a specific document type, e.g. DISPATCH_INSTRUCTION_RESPONSE
.
In this case, the easiest way to acheive the filtering is to add the filter
parameter to the request.
$response = $client->request('GET', 'https://api.procuros.io/v2/transactions?filter[type]=DISPATCH_INSTRUCTION_RESPONSE', [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer <your-api-token>',
],
]);
Scenario 2: You want to load multiple document types, e.g. DISPATCH_INSTRUCTION_RESPONSE
and INVOICE
.
In this case, you may want to load all document types and then filter them in your code, preventing multiple round-trip requests the API. You can filter the results by type
of each returned item to get the documents you need.
$transactions = array_filter($items, function($item) {
return $item->type === 'INVOICE' || $item->type === 'DISPATCH_INSTRUCTION_RESPONSE';
});
Pagination
The response body has a hasMore
flag. If it's true
not all items are in the response.
You will then want to fetch the other items as well. Therefore, you can use the nextPageUrl
flag from the response body and perform the same request with the new URL again.
if ($body->hasMore) {
$response = $client->request('GET', $body->nextPageUrl, [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer <your-api-token>',
],
]);
... // don't forget to check for errors
$body = json_decode((string) $response->getBody());
$items = array_merge($items, $body->items);
}
Perform requests until
hasMore
is falseIf you are running your code only once a day or so, we recommend to perform the request with the new URL until
hasMore
is false. When doing so you can be sure to fetch all currently available items.
Please read the Pagination section of our API reference for a detailed description.
Mark an Dispatch Instruction Response as Processed
To mark an dispatch instruction response as processed, use the API call Mark transaction processed.
On the happy path of a transaction being processed successfully, you can make an API call such as:
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$transaction_id = 'abc-123'; // Get the transaction ID from the original `GET /v2/transactions` call
$response = $client->request('POST', "https://api.procuros.io/v2/transactions/{$transaction_id}", [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer <your-api-token>',
],
'json' => [
'hasBeenProcessed' => true
]
]);
... // Remember to check the request was successful
Mark Multiple Dispatch Instruction Responses as Processed
In addition to the above, you can specify a list of items that should be marked as processed in a single API call, via the Bulk mark transactions processed endpoint.
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
// You can find the IDs from the original `GET /v2/transactions` call
$items = [
[
'id' => 'abc-123',
'hasBeenProcessed' => true
],
[
'id' => 'def-456',
'hasBeenProcessed' => true
]
];
$response = $client->request('POST', "https://api.procuros.io/v2/transactions/bulk/mark-processed", [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer <your-api-token>',
],
'json' => [
'items' => $items
]
]);
... // Remember to check if the request was successful
Report an Error Processing Dispatch Instruction Response
In the event an dispatch instruction response was not able to be processed, you can use the same 2 API calls listed above (Mark transaction processed and Bulk mark transactions processed) to mark these dispatch instruction responses as "failed to process".
In this case you must set the hasBeenProcessed
flag to false
. Additionally you should (but are not required to) add a reason
for the dispatch instruction response not being processed, which will be used for solving the issue.
Single Dispatch Instruction Response
$transaction_id = 'abc-123';
$response = $client->request('POST', "https://api.procuros.io/v2/transactions/{$transaction_id}", [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer <your-api-token>',
],
'json' => [
'hasBeenProcessed' => false,
'reason' => 'Invalid address supplied'
]
]);
Bulk Error Reporting
$items = [
[
'id' => 'abc-123',
'hasBeenProcessed' => false,
'reason' => 'Invalid address supplied'
],
[
'id' => 'def-456',
'hasBeenProcessed' => true
],
];
$response = $client->request('POST', "https://api.procuros.io/v2/transactions/bulk/mark-processed", [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer <your-api-token>',
],
'json' => [
'items' => $items
]
]);
Updated over 1 year ago