Mastering External Precoro Integrations

TABLE OF CONTENTS

• How to Work with ExternalIDs in Precoro

  • Entities Supporting “PATCH External ID”

  • Entities Supporting “externalIntegrationLog”

  • How to Filter Entities by External ID

  • Syncing Entities Based On “modifiedSince”

How to Work with ExternalIDs in Precoro

ExternalID is a field used to map corresponding values from third-party systems to Precoro. This guide will walk you through key aspects of working with ExternalIDs in Precoro, including:

• Entities supporting PATCH External ID.
• Using externalIntegrationLog for error logging.
• Filtering entities based on ExternalID presence.
• Syncing entities using the modifiedSince parameter.

Entities Supporting “PATCH External ID”

Precoro supports PATCH External ID for various entities, allowing you to update the ExternalID field for existing records.

The following entities support PATCH External ID:

1. Suppliers — PATCH <https://api.precoro.com/suppliers/{id}>
2. Invoices — PATCH <https://api.precoro.com/invoices/{idn}>
3. Purchase Orders — PATCH <https://api.precoro.com/purchaseorders/{idn}>
4. Payments — PATCH <https://api.precoro.com/payments/{idn}>
5. Taxes — PATCH <https://api.precoro.com/taxes/{id}>
6. Payment Terms — PATCH <https://api.precoro.com/paymentterms/{id}>
7. Custom Fields for Item options — PATCH <https://api.precoro.com/itemcustomfields/{id}/options/{id}>
8. Custom Fields for Document options — PATCH <https://api.precoro.com/documentcustomfields/{id}/options/{id}>
9. Items — PATCH <https://api.precoro.com/items/{id}>
10. Locations — PATCH <https://api.precoro.com/locations/{id}>
11. Legal Entities — PATCH <https://api.precoro.com/legalentities/{id}>

To update the ExternalID for an entity, send a PATCH request to the relevant API endpoint. For example, to update a supplier’s ExternalID:

Replace {id} with the actual ID of the supplier you want to update. The externalId field in the request payload should contain the new ExternalID value.

You can follow the same process for other entities by sending PATCH requests to their corresponding API endpoints and including the necessary data in the request.

Entities Supporting “externalIntegrationLog”

In addition to the ExternalID parameter, Precoro supports the externalIntegrationLog parameter so that certain entities can record error messages during synchronization. The externalIntegrationLog is mainly used for documents such as purchase orders and invoices.

If an error occurs during synchronization with an external system, you can log the error using the externalIntegrationLog property. This error message will be displayed on the document details page in Precoro, and the filled externalIntegrationLog will be used as criteria to show the “Not synced” info card, providing visibility into any problems during the synchronization process.

To log an error message, include the externalIntegrationLog property in the API request payload along with the ExternalID. If there are no errors during the synchronization process, you can simply leave the externalIntegrationLog property empty/null.

Here is an example:

How to Filter Entities by External ID

Use Case: Syncing entities between Precoro and an external platform without fetching and iterating through the entire list.

If you store external system's ID in Precoro's external_id field when creating or updating a record, you can later retrieve exactly the records you need using the external_id[] filter.

Supported Endpoints:

The external_id[] filter is available for the following document and entity types:

Steps to Set Up:

Step 1: Store your external ID in Precoro when creating or updating a record

When creating or updating an entity in Precoro (e.g., a supplier), include the externalId field with the ID from your external system:

This links the Precoro record to the corresponding record in your accounting system.

Step 2: Retrieve records by external ID

When you need to look up a specific record (before deciding whether an update is needed), pass one or more external IDs using the external_id[] parameter:

GET <https://api.precoro.com/suppliers?external_id[]=SUP-98765>

To look up multiple records in a single request, pass several values:

GET <https://api.precoro.com/suppliers?external_id[]=SUP-98765&external_id[]=SUP-11234&external_id[]=SUP-44401>

Step 3: Compare and update only what has changed

Use the returned records to compare the current state in Precoro with the state in your external system. To avoid redundant updates, only send a PUT request if there is an actual difference.

Example: Syncing suppliers from your accounting system

Let's review a case when three suppliers were updated in the integrated system. Here's how to efficiently update the data in Precoro:

1. Look up the affected suppliers by their external IDs: 
   GET <https://api.precoro.com/suppliers?external_id[]=SUP-001&external_id[]=SUP-002&external_id[]=SUP-003>
2. Compare each returned supplier's fields against your accounting system's data.
3. For suppliers where data is different, send a PUT request with the updated values: 
   PUT <https://api.precoro.com/suppliers/{id}>
4. For suppliers where nothing has changed, skip the update entirely.

Syncing Entities Based On “modifiedSince”

The modifiedSince parameter is a powerful feature in Precoro that allows you to synchronize entities based on their modification date. By specifying a timestamp with the modifiedSince parameter, you can retrieve only those entities created or modified since that specific timestamp.

Here is an example of an API request using the modifiedSince parameter on suppliers:

To identify which entities need to be synchronized based on the modifiedSince parameter, follow these steps:

1. Store the timestamp of the last successful sync.
2. When initiating a new sync, send an API request with the modifiedSince parameter set to the stored timestamp.
3. Precoro will return the entities that have been created or modified since that timestamp.
4. Process and synchronize the returned entities with your external system.
5. Update the stored timestamp to the current time to mark the successful synchronization.

You can use the modifiedSince parameter to perform incremental syncs, retrieving only those entities that have been created or updated since the last sync. This approach optimizes the sync process by reducing the amount of data transferred and processed. Note that the modifiedSince parameter works based on the modification timestamp of the entities. If an entity has been modified multiple times since the last sync, it will still only appear once in the results. Using the modifiedSince parameter effectively lets you keep external systems in sync with Precoro by capturing and processing only the relevant changes since the last synchronization point.