Synchronizing Entities With Precoro

This guide outlines practical methods for syncing data with the Precoro API, covering important sync guidelines, initial setup, and continuous synchronization options using either the Modified Since filter or Precoro Webhooks for real-time updates.

TABLE OF CONTENTS

• Important Precoro Synchronization Guidelines

• Initial Precoro Sync Setup

• Continuous Synchronization Setup

  • Option 1: Continuous Synchronization with Modified Since Filter

  • Option 2: Continuous Synchronization with Precoro Webhooks

To Master External Integrations with Precoro, please consult this article for more information.

Important Precoro Synchronization Guidelines

It is essential to carefully plan and implement your integration to ensure smooth synchronization with the Precoro API and avoid exceeding API limits. Here are some practical recommendations:

• Understand API limits: Precoro’s API allows 300 requests per minute, 1500 requests per hour, and 3000 requests per day. Ensure your application complies with these limits to prevent being restricted or blocked.

• Implement caching: Use caching for frequently accessed or unchanging data (such as suppliers/CFIs/CFDs) to decrease the number of API calls and avoid hitting limits. This can substantially reduce the API load and boost your application’s performance.
• Use incremental updates: Instead of retrieving the entire dataset use the modifiedSince filter for incremental updates with each API call. This method retrieves only the changed data since the last sync, minimizing data transfer and reducing the risk of hitting API limits.
• Implement exponential backoff: Implement an exponential backoff strategy if you encounter rate limiting or other temporary errors. This involves retrying failed requests with an increasing delay between each attempt. This strategy reduces the API load and allows recovery time. The RateLimit-Retry-After parameter can help understand when the API will be unlocked again, allowing you to delay the call until then.
• Use webhooks: Precoro’s webhook capabilities can help you build effective synchronization and avoid API limit issues. Webhooks allow you to receive real-time notifications of changes in Precoro, eliminating the need for frequent polling. Subscribe to relevant webhooks and handle them to retrieve and update data incrementally. This event-driven approach minimizes unnecessary API calls and reduces the risk of hitting API limits.

Initial Precoro Sync Setup

• If you are setting up a new account without any existing entities in Precoro, you can add new entities (such as suppliers) directly to Precoro, along with the externalId field. This field should contain a unique identifier from the external system for future synchronization and updates.
• If you already have some entities (like suppliers) in both Precoro and the external system, you need to sync the data between the two systems and set the externalId in Precoro for matching entities.
  • Identify corresponding entities in both systems by selecting the matching fields (such as name, email, unique code, or business registration number).
  • Find the matching entities in both systems based on the selected fields.
  • For each matching entity, set the externalId in Precoro using the PATCH method with the corresponding unique identifier from the external system.

Continuous Synchronization Setup

Option 1: Continuous Synchronization with Modified Since Filter

After synchronizing all initial entities, set up an integration for continuous data synchronization between your external system and Precoro.

1. Use the Precoro ModifiedSince filter to retrieve only entities created or updated since the last sync session (https://api.precoro.com/suppliers?modifiedSince=2024-06-06T00:00:00).
   • If the requested entity does not have the externalId set, it indicates a new value that needs to be added to your external system.
   • If the requested entity has the externalId set, it indicates an existing entity that needs to be updated in your external system.
2. When a new entity is added, or an existing entity is updated in your external system, reflect those changes in Precoro:
   • If the entity does not exist in Precoro, add a new entity to Precoro using the appropriate POST method.
   • If the entity exists in Precoro (indicated by a populated externalId), update the existing entity using the PATCH method (e.g., PATCH Suppliers).

Option 2: Continuous Synchronization with Precoro Webhooks

• After synchronizing all initial entities, set up an integration for continuous synchronization of data between your external system and Precoro.
• Use Precoro’s webhooks to receive notifications about changes in Precoro, such as newly added or updated suppliers.
• Upon receiving a webhook notification about a change in Precoro:
  • If the changed entities do not have an externalId set, it shows it is a new value that needs to be added to the external system.
  • If the changed entity has an externalId set, it shows it is an existing entity that needs to be updated in the external system.
• Same, when a new entity is added or an existing entity is updated in the external system, reflect those changes in Precoro:
  • If the entity does not exist in Precoro, add a new entity to Precoro using the appropriate POST method.
  • If the entity exists in Precoro (based on the externalId), update the existing entity using the PATCH method (e.g., PATCH Suppliers).