Work Orders

This is the right section for you if you are acting as a production, assembly or service provider and looking to receive work orders from your customers. Throughout this guide you will learn how to pull new work orders from the Procuros API, as well as how to paginate over them, mark them as processed, or report errors with the work orders. It is important to mark the work orders 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 “processing failed”. PHP examples are included but you will likely also want to look at the relevant API calls in the API reference.

Trade partners may send updated versions of a document. Always check the isLatestVersion field before importing — if it is false, a newer version exists and this one should be skipped. See Document Versioning for full details.

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 Work Orders

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?filter[type]=WORK_ORDER', [
  'headers' => [
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <your-api-token>',
  ],
]);

$body = json_decode((string) $response->getBody());

$items = $body->items;

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);
}

If 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 Work Orders as Processed

To mark a work order 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' => [
    'success' => true
  ]
]);

... // Remember to check the request was successful

Mark Multiple Work Orders 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 = [
  [
    'procurosTransactionId' => 'abc-123',
    'success' => true
  ],
  [
    'procurosTransactionId' => 'def-456',
    'success' => 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 the request was successful

Report an Error Processing Work Orders

In the event a work order 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 work orders as “failed to process”. In this case you must set the success flag to false. Additionally you should (but are not required to) add a reason for the work order not being processed, which will be used for solving the issue.

Single Work Order

$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' => [
    'success' => false,
    'reason' => 'Unknown input item in work order'
  ]
]);

Bulk Error Reporting

$items = [
  [
    'procurosTransactionId' => 'abc-123',
    'success' => false,
    'reason' => 'Unknown input item in work order'
  ],
  [
    'procurosTransactionId' => 'def-456',
    'success' => 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
  ]
]);

Getting Started

Endpoints

Documents

Guides

Other

Authentication

Error Handling

Pull New Work Orders

Mark Work Orders as Processed

Mark Multiple Work Orders as Processed

Report an Error Processing Work Orders

Single Work Order

Bulk Error Reporting

​Authentication

​Error Handling

​Pull New Work Orders

​Pagination

​Mark Work Orders as Processed

​Mark Multiple Work Orders as Processed

​Report an Error Processing Work Orders

​Single Work Order

​Bulk Error Reporting

Authentication

Error Handling

Pull New Work Orders

Pagination

Mark Work Orders as Processed

Mark Multiple Work Orders as Processed

Report an Error Processing Work Orders

Single Work Order

Bulk Error Reporting