Skip to content
  • There are no suggestions because the search field is empty.

Typical API Usage Scenarios

Here are some common usage scenarios for Precoro API and recommended steps for setting up each scenario effectively.

TABLE OF CONTENTS

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 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 from Items


1. Find Custom Fields for Items ID

In the response, you should find a dataItemCustomFields field. This field contains a collection of custom fields for the items.

For example, let’s take a request with Invoices: https://api.precoro.com/invoices/45


Inside the dataItemCustomFields, you can find all the Custom Fields for Items and their values. Find the itemCustomField within the custom field object. It has an ID value you need to retrieve.


2. Get Custom Fields for Items information by ID

Send a GET request itemcustomfields/{id} to receive data on CFI. To do this, we take the ID value from one of the fields, add it to the request, and get all the information on that CFI.


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. 

More about Webhooks usage can be found here.

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

How to Get Custom Fields from Documents


1. Find Custom Fields for Documents ID

In the response, locate the dataDocumentCustomFields. This field contains a collection of custom fields for the document.

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

In the response, you should find a dataDocumentCustomFields. This field contains a collection of custom fields for the documents.

Inside the dataDocumentCustomFields object, you can find all the custom fields that the documents have, as well as their values. Within the custom field object, find the DocumentCustomField value. It contains an ID field of the CFD you need to retrieve.


2. Get Custom Fields for Documents information by ID

Send a GET request documentcustomfields/{id} to receive data on CFD. To do this, we take the ID value from one of the fields, add it to the request, and get all the information on that CFD.


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. 

More about Webhooks usage can be found here.

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.