TABLE OF CONTENTS
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.
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.
Whenever you create a new API key, we will send you this letter below, with the tips and useful links to improve your experience working with this functionality:
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.
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 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 counted as a request. So please, look at all the errors received in the responses.
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 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, 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}
API Integration Best Practices
To optimize your API integration, consider these specific best practices:
- Use the modifiedSince filter:
Utilize the ‘modifiedSince’ filter to retrieve the most relevant and up-to-date data and reduce redundant requests.
For instance, to retrieve all Purchase Orders created or updated since October 10, 2023, use the following example:
https://api.precoro.com/purchaseorders?modifiedSince=2023-10-10T00:00:00.
- Use Webhooks for Real-Time Updates:
Implement webhooks to receive real-time updates on documents, suppliers, budgets, or stock transfers. Webhooks ensure that you always have the latest data without the need for constant data polling. Read more information on how to work with Webhooks here.
- Filter Data by Specific Parameters and delete the redundant ones:
Narrow down your data retrieval by using filters like status, which allows you to retrieve only the information you need. Avoid requesting and filtering all data locally, as you may face the API call limit.
In addition, review your requests and remove unnecessary parameters that do not affect the outcome.
- Record Data from API Responses locally:
When you make a request, record the data you receive, thus minimizing the need for repetitive requests for the same unchanged data.
- Handling Errors and Avoiding Rate Limit Issues:
- If you receive an error response, like a 403 or 401 status code, first ensure your request is written correctly. Verify the endpoint, headers, and parameters to avoid authorization issues.
- Confirm the user linked to your API token has the necessary permissions for the requested calls. Lack of necessary access rights can lead to authorization errors.
- When errors occur, avoid repeating the same request until you discover the problem.
- Monitor rate limits closely to stay within defined thresholds. Exceeding limits can temporarily disrupt your integration.
Please follow to the Typical API Usage Scenarios article to see the detailed usage case scenario descriptions that can help you with API utilization.