Typical API Usage Scenarios

TABLE OF CONTENTS

• Typical API Usage Scenarios

  • How to Retrieve Approved Purchase Orders

  • How to Manage Items of a specific supplier

  • How to Download Attachments from Documents

  • How to Get Items Custom Fields from Documents

  • How to Get Documents Custom Fields from Documents

  • Get Documents With a Certain Status

  • Difference Between GET List and GET IDN

Typical API Usage Scenarios

Here are some common usage scenarios for Precoro API, along with recommended steps for setting up each scenario effectively:

How to Retrieve Approved Purchase Orders

Usage 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

Usage 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

Usage 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 Items Custom Fields from Documents

1. Find Items Custom Field ID

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

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

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

2. Get Items Custom Field information by ID

Send a GET request itemcustomfields/{id} to receive data on ICF. 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 ICF.

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.

How to Get Documents Custom Fields from Documents

1. Find Documents Custom Field 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 DCF you need to retrieve.

2. Get Document Custom Field information by ID

Send a GET request documentcustomfields/{id} to receive data on DCF. 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 DCF.

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.