TABLE OF CONTENTS
- What an API Is and How You Can Use It
- Setting Up API in Precoro
- How to Get the Data from the Precoro API
- How to Filter the List of the Documents in API
- How to Filter Results in API
What an API Is and How You Can Use It
An API is a tool that lets your developers access your data in an automated way and thus integrate the tools with each other.
How it can help you
With an API, you can solve the following problems:
- Procurement and accounting are not working together. There is a lot of duplicated work and manual entries, e.g., Invoices and Payments.
- You should manually manage the catalog in two places.
- Procurement and inventory are not working together. There are two manual entries: Purchase Orders in Precoro and Receipts in the accounting system.
What you can do with Precoro API
- Get all the approved Purchase Orders and then create them in the Accounting system with API.
- Get all the approved Invoices and then save them in the Accounting system with API.
- Get all the Receipts and save them in the Inventory system with API.
- Get all the Suppliers, Contracts, Products, Categories, Units, Locations, Users, and Legal Entities and use them with any tool you have in API.
Setting Up API in Precoro
1. Get your API token
To access Precoro’s API integration, first, you need to generate an API token.
Information to consider before creating a new token
- The API token is set for the user.
- Access to the API data is restricted by user roles and access to Locations, Departments, and Projects. Therefore, it is prudent to set up the API token for a user with a maximum number of roles and accesses.
- If you have multiple companies within your account, you have to set up a separate API token for each company.
API Requests Limits
The limits for API requests:
- 300 requests per minute.
- 1500 requests per hour.
- 3000 requests per day.
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 you can find 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.
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.
How to generate the API token
1. Open the API access tokens page.
2. Press the Create New API Token button below.
If you have multiple companies, switch between companies and repeat this action.
In Account Settings, you can find the list of the available companies within your account.
How to disable the API token
To disable the previously created token, press the red Cancel button on the right.
You will see the system notification, and the token status will show Disabled.
2. Define what is needed to configure your integration
The basic level of the integration is:
- Suppliers.
- Chart of Accounts — API reference Product Custom Fields.
- Documents — Purchase Orders or Invoices and Payments.
More robust integration level:
- Departments — API reference Document Custom Fields.
- Classes — API reference Document Custom Fields.
- Projects — API reference Document Custom Fields.
- Products — API reference Products.
Fields Chart of Accounts, Departments, Classes, and Projects can be set on the document and item levels.
Please note that you should set up fields in the Precoro account in accordance with your accounting system.
To set up the Document-level field, use Document Custom Fields, and for the Item-level field, use the Product Custom Field.
Document Custom Fields are described in the Purchase Orders/Invoices on two levels:
- Values — dataDocumentCustomfields.
- References to the appropriate field in Precoro — documentCustomfield.
“dataDocumentCustomfields” contains the data about all of the Document Custom Fields values (e.g., assigned values of the Departments, Projects, etc.).
“documentCustomfield” contains the Document Custom Filed ID, where you can get the corresponding name and available options.
Here you can find helpful API documentation.
How to Get Attachments from Precoro via API
Attachments are additional information linked to a transaction. Precoro supports several file formats for the attachments:
- PDF files
- XLSX files
- DOCX files
- pictures of various formats.
The GET method supports downloading the content of a single attachment or downloading attachments in bulk. All you need to know are these Attachments IDs.
Follow this sequence of requests to download the attachment you need:
1. GET request for the list of the documents with their # (IDNs).
To get a filtered list of documents, apply the filters you need in the Precoro interface to use later in your API request.
Code example: Get Invoices list.
2. Extract all the # (IDNs) from the response.
3. GET request for every document by its # (IDN).
Code example: Get Invoice by IDN.
4. Extract the IDs of all attachments.
5. GET request for the attachment by its ID.
Code example: Download document attachment by ID.
How to Approve via Precoro’s API
- Generate an API token (e.g., X-AUTH-TOKEN) for every approver in your company.
- GET all of the documents that require approval from every user by adding the parameter waitingForapprove with the value yes.
- POST an approve or reject action to the appropriate document.
- Repeat this flow with every approver to reach approved status.
How to Get the Data from the Precoro API
There are two ways to get the data regarding the documents:
- The list of the documents (API documentation)
- The documents with all the details (API documentation).
It looks like a real Precoro account: the list of the documents and the separate document.
To get all the data about corresponding documents created between the dates, you need the following:
- Request the list of the Orders.
Your request will look like this:
- Once you get some IDNs of the Orders, and you need to put those IDNs to the request Get Purchase Order by IDN.
Your request will look like this:
https://api.precoro.com/purchaseorders/{1,2,3,15,20,33}
How to Filter the List of the Documents in the API
- You can filter the real Precoro interface and see how it will look in the URL.
- Add the same to the API request.
Here is the list of the documents filtered by status Approved:
https://app.precoro.com/purchase/order?status[]=2
Your API request will look like this:
https://api.precoro.com/purchaseorders?status[]=2
How to Filter Results in API
Use interface filters in your API request to GET a filtered list of documents via API:
- Apply filters in the Precoro interface.
- Copy part of the URL.
Example: creator[]=24650&createDate[left_date]=01.04.2021&createDate[right_date]=28.04.2021 - Paste this part into your request.