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

  • Step 2: Define the Requirements for the Integration

• API Requests Limits

• How to Approve via Precoro’s API

• How to Get the Data from the Precoro API

• How to Use Pagination in Precoro API Responses

• How to Handle Responses and Errors

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 (API Access Keys for precoro.us).
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.

 

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.

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.

A separate set of limits applies to the Power BI connector:

• 300 requests per minute;

• 1500 requests per hour;

• 3000 requests per day. 

These are the features that could help you 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 count as requests. Please look at all the errors received in the responses.

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 Get the Data from the Precoro API

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

• GET List — returns a list of documents with all the information on them, but no item information included (Postman API documentation).
• GET IDN — returns information about both the document and the items within it (Postman API documentation).

To retrieve 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 Use Pagination in Precoro API Responses

When requesting lists of entities (such as Purchase Requisitions, Purchase Orders, Invoices, etc.), Precoro APIs return paginated responses.

Pagination helps control response size, improves performance, and allows clients to retrieve large datasets incrementally.

Pagination Structure in API Responses

Each list response includes a meta.pagination object at the end of the payload:

Pagination Fields Explained

Standard Fields (Always returned in responses)

Field	Description
count	Number of records returned in the current response.
per_page	Maximum number of records per page. Only the following options are allowed: 10, 20, 50, 100, 200.
current_page	Current page number.
has_next_page	Indicates if there is a next page of records available (Boolean).
links	Optional navigation links (may be empty).

Conditional Fields (Returned ONLY when the &page=last parameter is passed)

Field	Description
total	Total number of records available for the request.
total_pages	Total number of pages available.

How to Request Paginated Data

To navigate through pages, include pagination parameters in your request:

GET /purchaseorders?page=1&per_page=100

Parameter	Description
page	Page number to retrieve (or last to get the final page and total counts)
per_page	Number of records per page (max limit applies)

Example Pagination Flow

Step 1: Request the first page

GET /purchaseorders?page=1&per_page=100

Response snippet:

"current_page": 1,
"has_next_page": true

Step 2: Loop through the remaining pages

Continue requesting the next page as long as has_next_page is true.

Example:

GET /purchaseorders?page=2&per_page=100 (Response: has_next_page: true)

GET /purchaseorders?page=3&per_page=100 (Response: has_next_page: false — stop here)

Step 3: Request the last page (Optional)

If you need to know the exact total number of records or pages, use the last parameter.

GET /purchaseorders?page=last&per_page=100

Response snippet:

"current_page": 5,
"total_pages": 5,
"total": 450,
"has_next_page": false

Recommended Pagination Strategy

Here are a few tips that can help you use pagination to ensure a smooth integration.

1. Use has_next_page for simple loops

The has_next_page field is the most efficient way to iterate through data without needing to fetch the total count upfront. Simply stop your loop when has_next_page becomes false.

2. Check meta.pagination for detailed info

The meta.pagination object remains the reliable source for:

1. page sizes,

2. total pages and record counts (specifically when using &page=last).

We highly recommend always reading pagination data from the response.

3. Use pagination for large datasets

To avoid timeouts and memory issues:

1. Start from page 1.

2. Process one page at a time.

3. Continue until has_next_page is false.

4. Combine pagination with filtering

Pagination works best when combined with filters, such as:

1. Updated date

2. Status

3. Legal entity

Example:

GET /purchaseorders?modifiedSince=2025-08-10T00:00:00&page=1&per_page=100

Example Implementation (Python)

Here is a practical example of how to fetch all purchase orders using Python and the has_next_page logic:

import requests

API_BASE = "https://api.precoro.com"

headers = {
    "X-AUTH-TOKEN": "your_api_token",
    "email": "your_email"
}

page = 1
all_orders = []

while True:
    response = requests.get(
        f"{API_BASE}/purchaseorders",
        headers=headers,
        params={"page": page, "per_page": 100}
    )
    data = response.json()

    all_orders.extend(data["data"])

    # Stop the loop if there are no more pages
    if not data["meta"]["pagination"]["has_next_page"]:
        break

    page += 1

print(f"Fetched {len(all_orders)} purchase orders")

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.