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.
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.
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:
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.).
If you are able to successfully build and send a transaction payload to Procuros, we will respond in one of three ways:
201: Created
status code and you should mark the document as TRANSMITTED
.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.422: Validation Error
. More on this below.PayloadAlreadyReceived
then this will be reported back via the status code 400: Bad Request
.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.