Typical API Usage Scenarios

TABLE OF CONTENTS

• How to Retrieve Approved Purchase Orders
• How to Retrieve and Update Suppliers
• How to Manage Items of a Specific Supplier
• How to Download Attachments from Documents
• How to Get Custom Fields for Documents and Items
• Get Documents With a Certain Status
• Difference Between GET List and GET IDN
• How to Mark Precoro Invoices as Paid After Recording Payment in Your Accounting System
• How to Keep Precoro Payments in Sync with Another Integration
• How to Integrate Delivery Tracking Tools via API
• How to Use Pagination in Precoro API Responses

How to Retrieve Approved Purchase Orders

Use case: Retrieve approved Purchase Orders and integrate them into your Accounting system.

Steps to set up:

1. Make a GET request to retrieve all approved Purchase Orders using the endpoint https://api.precoro.com/purchaseorders?modifiedSince=2023-10-10T00:00:00&approvalDate[left_date]=01.12.2023&approvalDate[right_date]=31.12.2023&status[]=2
2. For each Purchase Order, use the request https://api.precoro.com/purchaseorders/{idn} to access full information if needed.
3. To keep your records up-to-date, set the approvalDate or modifiedSince parameter to the date of your last data retrieval in subsequent requests.

How to Retrieve and Update Suppliers

Use case: Efficiently retrieve and update supplier records or add new suppliers.

Steps to set up:

1. Make a GET request to /suppliers?modifiedSince=2022-12-12T00:00:00&status[]=2 to fetch all approved suppliers.
2. To filter only active suppliers, add ?enable=true to the request. You can use any parameter from the response to further filter suppliers as needed.
3. For each supplier, use the request /suppliers/{id} to retrieve full information.
4. To ensure your records stay current, set the approvalDate or modifiedSince parameter to the date of your last data retrieval in future requests.
5. To update a supplier’s information, use a PUT request to /suppliers/{id}.
6. To add new suppliers, make a POST request to /suppliers.

How to Manage Items of a Specific Supplier

Use Case: Efficiently retrieve a list of items by supplier and make updates to existing items or create new ones as necessary.

Steps to set up:

1. Make a GET request with a filter to retrieve a list of items. Use the endpoint https://api.precoro.com/items?supplier[]={id} to fetch all items of this supplier from Precoro. To stay current with updates, use the modifiedSince filter when retrieving items. This ensures you only receive items that have been created or updated since your last check.
2. Review the details of the retrieved items to identify those that require updates or those that need to be created.
3. If you need to make changes to existing items, use a PUT request to modify the item’s information. Use endpoint https://api.precoro.com/items/{id} for item updates.
4. For new items, use a POST request to add them to your system. The endpoint is https://api.precoro.com/items

How to Download Attachments from Documents

Use case: Efficiently retrieve attachments from documents, allowing you to access relevant files for further use or storage.

Steps to set up:

1. Identify Documents with Attached Files:

Begin by making a GET request to identify documents with attached files. Use the endpoint https://api.precoro.com/purchaseorders?modifiedSince=2023-10-10T00:00:00&attachedFile=1 to retrieve all purchase orders created or updated after the specified date with attached files.

2. Retrieve Attachment IDs:

For each document that requires attachment retrieval, make a GET request to https://api.precoro.com/purchaseorders/{idn} to access the document details. Within the document information, locate the attachments field, which contains the IDs of the attached files.

3. Download Attachments:

With the attachment IDs in hand, initiate a GET request to https://api.precoro.com/attachments/{id} for each attachment you want to download. This will allow you to download the associated files.

How to Get Custom Fields for Documents and Items

It’s essential to fetch the list of all available Custom Fields for Documents and Items prior to requesting any documents.

Step 1: Get All Information about Custom Fields for Documents

Send a GET request /documentcustomfields to receive data on custom document fields. 

Also, send a GET request /itemcustomfields to receive data on custom item fields.

The response contains:

• Custom field ID
• Field name
• Field type (number, text, date, dropdown, etc.)
• Options (for dropdown type)
• Additional configuration (required, limit access, etc.)

Please store this data locally (cache, database, or in-memory) for further use in Step 2.

Step 2: Fetch Documents and Read Custom Field Values

For example, let’s take a request for PO: https://api.precoro.com/purchaseorders/45

In the response, you should find a dataDocumentCustomFields and dataItemCustomFields. These fields contain a collection of custom fields for documents and items, respectively.

The dataDocumentCustomFields object contains the retrieved document’s custom field IDs and values. 

1. “documentCustomField” is the ID of the custom field.
2. “value” is the ID of the option selected in this custom field (if it has the Drop-down list type) or its value (text or date).

If you need the names of the custom fields and/or the selected options, please map the IDs to the custom field list fetched in Step 1.

The dataItemCustomFields object contains Custom Fields for Items available in this document and their values. 

1. “itemCustomField” is the ID of the custom field.
2. “value” is the ID of the option selected in this custom field (if it has the Drop-down list type) or its value (text or date).

If you need the names of the custom fields and/or the selected options, please map the IDs to the custom field list fetched in Step 1.

Step 3: Get Updated Data

We recommend using webhooks if you want to be aware of any changes. Select the necessary fields as shown in the instructions, save them, and configure webhooks for custom fields. 

After that, as soon as you receive a webhook, you will know which field it refers to and continue working with it.

Get Documents With a Certain Status

To receive documents with a certain status, you need to include status[]=2 and the status number in the request.

Example of request: https://api.precoro.com/purchaseorders?status[]=2&per_page=50&page=1

The request will return the first 50 purchase orders (to get other objects, change page param), with the Approved status.

Difference Between GET List and GET IDN

• Get List will return a list of documents with all the information on them, with no item information included.
• Get IDN will return information both about documents and items in the document.

How to Mark Precoro Invoices as Paid After Recording Payment in Your Accounting System

Use Case: Create Payments in Precoro for the invoices that are already paid in your accounting system. 

Steps to Set Up:

1. Make a GET request to retrieve a list of unpaid or partly paid Invoices in Precoro 
   GET https://api.precoro.com/invoices?page=1&per_page=10&status[]=2&status[]=4 
2. If those Invoices are unpaid in your system as well, create a payment for them. 
3. Send a POST request to Precoro to create a new payment for the corresponding invoices.
   POST https://api.precoro.com/payments with the required payment details.

How to Keep Precoro Payments in Sync with Another Integration

Use Case: Create payments and ensure the information about paid invoices in Precoro is consistent with that on other platforms you use.

Steps to Set Up:

1. Retrieve a list of paid invoices in Precoro:
   • Make a GET request to our API to retrieve a list of all paid invoices.
     GET https://api.precoro.com/invoices?page=1&per_page=10&status[]=5
   • Save the received IDs of paid invoices for further verification.  
2. Check the payment information in the service you integrate with Precoro:
   • Send a request to the service where your payments are stored.
   • Ensure there is a way to map invoices in the service and in Precoro. For example, you can map invoices by filling out your external ID or another similar field with the Precoro Invoice ID.
3. Check for new invoices:
   • Compare the received list and the previously saved list of IDs of paid invoices from Precoro.
   • Determine if there are any new invoices (invoice IDs that are not already in your database).
4. Create payments:
   If new invoices are found, create a new payment for each of them in your system.

Additional recommendations:

To keep your data up-to-date, use the request parameters, such as the date of the last synchronization, for future requests.

Ensure the invoice mapping between your system and Precoro is configured correctly to avoid duplication or errors when creating invoices.

How to Integrate Delivery Tracking Tools via API

Use Case: When you create a receipt on another platform, you can automatically send a request to add a corresponding receipt in Precoro. The receipt is then linked to a related purchase order and sent for approval (if an approval workflow is configured for receipts) to ensure purchases are completed correctly and promptly.

Endpoint: POST /receipts/{purchase_order_id}

When configuring a POST request, please include these required fields:

• requiredDate in the ISO-8601 format (for instance, "2025-07-24T00:00:00+00:00").
• dataDocumentCustomFields.data (if there are required custom document fields). The array should contain all required fields’ values in the necessary format:
  • Date fields—ISO-8601 format;
  • Text fields—text;
  • Drop-down lists—option ID.
• selectedItems (an associative array containing at least one element; the PO item ID is used as the key). Each element should contain the following:
  • purchaseOrderItem.id (required);
  • received (required)—quantity of items received;
  • dataItemCustomFields (optional)—an array containing custom item field values.

You can also add the following optional fields:

• warehouse—warehouse ID;
• Note—text or null;
• receiptNumber—a unique custom number mostly used for integrations.

Please note: If the Automatically Transfer Notes from PO to Receipt setting is active in your company, notes from purchase orders are automatically added to receipts if the Note field is null. If you fill out the Note field in the receipt, the new value will be saved, and the note from the order won’t be transferred.  

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

Field	Description
total	Total number of records available for the request
count	Number of records returned in the current response
per_page	Maximum number of records per page. Available options: 10, 20, 50, 100, 200
current_page	Current page number
total_pages	Total number of pages available
links	Optional navigation links (may be empty)

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
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:

"current_page": 1,

"total_pages": 5

Step 2: Loop through the remaining pages

Continue requesting pages until current_page = total_pages

Example:

GET /purchaseorders?page=2&per_page=100

GET /purchaseorders?page=3&per_page=100

…

Recommended Pagination Strategy

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

1. Check meta.pagination for accurateinformation

The meta.pagination object is the most reliable source to learn:

• page sizes,
• how many pages responses contain,
• record counts.

We highly recommend always read pagination data from the response.

2. Use pagination for large datasets

Here's the process we suggest for integrations and data syncs:

• Start from page 1.
• Process one page at a time.
• Continue until all pages are fetched.

This approach allows you to avoid timeouts, memory issues, and large payloads so your integration is quicker and more stable.

3. Combine pagination with filtering

Pagination works best when combined with filters, such as:

• Updated date
• Status
• Legal entity

Example:

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