Using API in Precoro

TABLE OF CONTENTS

• What is an API and How Can You Use It?
• Setting Up API in Precoro

  • Step 1: Generate the API Key

    • API Requests Limits
      

  • Step 2: Define the Requirements for the Integration

• How to Approve via Precoro’s API

• How to Get the Data from the Precoro API
• How to Handle Responses and Errors

• API Integration Best Practices

What is an API and How Can You Use It?

An API (Application Programming Interface) allows developers to connect different tools and automate data sharing between them. 

With an API, you can simplify your workflows and address common challenges, such as:

• Lack of communication between procurement and accounting that leads to duplicated work and manual data entry for invoices and payments.
• The need to manually manage catalogs in multiple locations.
• Disconnected procurement and inventory systems that require extra manual work.

Instead of these cumbersome processes, the Precoro API enables you to automate essential functions across procurement, accounting, and inventory systems. Here is how you can improve processes:

• Automatically push approved POs and invoices from Precoro to your accounting system.
• Transfer receipts to your inventory management system.
• Pull data such as Suppliers, Contracts, Products, Categories, Units, Locations, Users, and Legal Entities and integrate it with any tool that works with the API.

Setting Up the API in Precoro

 

Step 1: Get Your API Key

To access Precoro API integration, you first need to generate an API key. Here are some important points to consider:

• The key will be available to view and copy only once — at the moment of generation. After that, you must save the key and store it in a safe place, as you will not be able to view it again in Precoro. 
• The API key is user-specific.
• Access to API data is restricted based on user roles and permissions related to Locations, Departments, and Projects. It’s best to create the API key for a user with the broadest access.
• If you have multiple companies under your account, you must create a separate API key for each one.

To generate the API token:

1. Open the API Access Keys page.
2. Click the Generate API Key button.

To deactivate a previously created API key, press the red cancel button next to the key. You will receive a system notification confirming that the key has been turned off.

API Requests Limits 

The limits for API requests: 

• 60 requests per minute (1 request per 1 second);
• 1500 requests per hour;
• 3000 requests per day. 

Special limits are enabled for duplicate requests—identical requests happening in succession:

• 1 request per minute; 
• 30 requests per hour.

These are the features that could help you to follow the limits:

• Webhooks allow you to receive a request when a user adds or updates something in Precoro. More information on working with Webhooks can be found here.
• Filter Modified since allows you to receive the most relevant and updated information and not iterate all the values. Find helpful documentation on this topic here.
• Filter Approval Date shows the final approval date (when the latest approver made a last document confirmation). Using this filter, you can quickly obtain information on current documents that have been Approved and ready for further action.

What will happen if some of the limits are reached:

• You will receive a 429 error, description, and date and time when you can retry.
• All the subsequent requests will fail until the next minute/hour/day.
• Even failed requests counted as a request. So please, look at all the errors received in the responses.

Step 2: Define the Requirements for the Integration

The integration can be set up at two levels.

The basic integration level includes:

• Suppliers.
• Chart of Accounts — API reference Product Custom Fields.
• Documents — Purchase Orders or Invoices and Payments.

More robust integration level:

• Departments — API reference Custom Fields for Documents.
• Classes — API reference Custom Fields for Documents.
• Projects — API reference Custom Fields for Documents.
• Products — API reference Products.

To set up Document-level fields, use Custom Fields for Documents. For Item-level fields, use Product Custom Fields.

Custom Fields for Documents can be broken down into two key levels in Purchase Orders and Invoices:

• Values — dataDocumentCustomfields.
• References to the appropriate field in Precoro — documentCustomfield.

“dataDocumentCustomfields” contains the data about all of the Custom Fields for Documents values (e.g., assigned values of the Departments, Projects, etc.).

“documentCustomfield” contains the Custom Fields for Documents ID, where you can get the corresponding name and available options.

How to Approve via Precoro API

To approve documents via Precoro’s API, follow these steps:

1. Generate an API key (e.g., X-AUTH-KEY) for every approver in your company.
2. Retrieve all documents waiting for approval by adding the "waitingForapprove" parameter with the value yes to the GET request. 
3. Submit an approval or rejection action for each document using the POST request.
4. Repeat this process for each approver until the document reaches approved status.

How to Retrieve Purchase Data with Precoro API

You can retrieve document data from the Precoro API in two ways:

• List of documents (API documentation).
• Full document details (API documentation).

To get data for documents created between specific dates, follow these steps:

1. Request the list of orders. Use this URL format, adjusting the date range: https://api.precoro.com/purchaseorders?createDate[left_date]=01.10.2020&createDate[right_date]=15.10.2020
2. Retrieve detailed data for specific orders. Once you have the IDNs from the list, use them to get detailed information for each purchase order. The request should look like this:https://api.precoro.com/purchaseorders/{1,2,3,15,20,33}

How to Handle Responses and Errors

When working with APIs, it's crucial to effectively manage errors and monitor usage to ensure seamless integration. Here are some key practices to follow:

• Check request format: If you receive an error response, such as a 403 or 401 status code, first ensure that your request is correctly formatted. Verify the endpoint, headers, and parameters to avoid any authorization issues.
• Verify permissions: Confirm that the user associated with your API key has the necessary permissions for the requested calls. A lack of access rights can lead to authorization errors.
• Avoid repeated requests: When errors occur, refrain from repeating the same request until you identify and resolve the underlying issue.
• Monitor rate limits: Keep a close eye on rate limits to stay within defined thresholds. Exceeding these limits can temporarily disrupt your integration.

API Integration Best Practices

To optimize your API integration, consider these specific best practices:

• Use the modifiedSince filter:

Retrieve the most up-to-date data by using the "modifiedSince" filter. This reduces redundant requests. For example, to get all POs created or updated since October 10, 2023, use:

https://api.precoro.com/purchaseorders?modifiedSince=2023-10-10T00:00:00

• Implement webhooks for real-time data updates:

Implement webhooks to receive real-time updates on documents, suppliers, budgets, or stock transfers. Webhooks ensure that you always have the latest data without the need for constant data polling. Read more information on how to work with Webhooks here.

• Filter data by specific parameters:

Use filters like "status" to retrieve only the data you need. Avoid unnecessary API requests and review parameters to ensure only essential ones are included.

• Record data from API responses locally:

Save the data you receive from API requests to avoid repeatedly querying unchanged information.