Overview

The Procuros API is the recommended way of integrating with the Procuros Network in order to exchange business transactions with your Trade Partners.

Our API follows RESTful patterns, accepts and returns JSON-encoded data and uses standard HTTP verbs and response codes.

​

Incoming Transactions

​

Retrieving and Processing Transactions

To retrieve unprocessed incoming transactions from Procuros, we recommend using a cron job/interval for simplicity.

Looping through the list of retrieved transactions, you will try to process/import them. See our Quick Start Guide for an example how this can be done.

​

Reporting Processing Status

Once you have looped through the unprocessed transactions and attempted to process them you will report back whether processing was successful or not.

If a transaction could not be processed, you will send across an error reason and level. This will trigger the exception handling flow:

• An e-mail notification will be sent to the responsible party for resolution
• The error will show up in the Procuros Portal together with the error reason for self-service resolution by the responsible party.

​

Outgoing Transactions

​

Retrieving and Preparing Documents

To retrieve new unprocessed documents from the ERP system that should be sent via Procuros we recommend using a cron job/interval that runs every 10-30 minutes for simplicity reasons, but you are free to make this event-based as well.

To know which documents should be sent via Procuros, a list of “enabled” customers and suppliers needs to be maintained. This is explained in detail on Enabled Trade Partners. Generally, all outgoing documents for an “enabled” Trade Partner (shipping notices, invoices, etc. for customers and orders for suppliers) should be sent via Procuros. We will handle routing and inactive trade relationships. More on that later.

For every document that fulfils the above criteria, you will build the “transaction payload” according to the API specification) corresponding to the document type (order, shipping notice, etc.).

​

Sending Transactions

If you are able to successfully build and send a transaction payload to Procuros, we will respond in one of three ways:

1. For documents Procuros intends to forward to the receiving trade partner, the Procuros API responds with an 201: Created status code and you should mark the document as TRANSMITTED.
2. If we determine the transaction should not be forwarded to the trade partner (eg. because the trade relationship is not yet active or documents of that type are not currently accepted by the receiving trade partner), the Procuros API will respond with an 202: Accepted status code and you will mark the document as NO_ACTION to indicate to users that the document was accepted by Procuros but will not be forwarded. More on this in Tracking Document Status.
3. If the transaction payload sent by you contains errors, the Procuros API will respond with a 422: Validation Error. More on this below.
4. If a different error occurs, such as PayloadAlreadyReceived then this will be reported back via the status code 400: Bad Request.

​

Handling Errors

If you were not able to successfully build the transaction payload to be sent via Procuros you will send an error payload instead to trigger the Exception Handling flow and allow the responsible parties to fix the underlying issue (i.e. change or add information in the unprocessed document). Error reasons could be e.g. missing GLNs or GTIN/EAN codes.

When you send an error payload to the Procuros API, we will respond with an Error Url that points to the error within the Procuros Portal. You can attach the Link to the document for which you were unable to build the transaction payload giving your user an easy way to resolve the error fast.

You will also receive an Error Url in case the transaction payload you sent is invalid and the Procuros API responds with 422: Validation Error.

In any case, you will re-try sending the document until it succeeds.