Mastering External Precoro Integrations

Discover how to efficiently manage ExternalIDs: Learn to update entities with PATCH, track errors using externalIntegrationLog, filter by ExternalID, and streamline data syncs with the modifiedSince parameter for smoother Precoro integrations.

TABLE OF CONTENTS

• How to Work with ExternalIDs in Precoro

  • Entities Supporting “PATCH External ID”

  • Entities Supporting “externalIntegrationLog”

  • Filtering Entities With “has_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:

Filtering Entities With “has_external_id”

Precoro provides a convenient way to filter entities based on the presence or absence of an ExternalID using the has_external_id filter. This filter allows you to retrieve only the entities with an ExternalID assigned or those that do not have an ExternalID.

To use the has_external_id filter, include it as a query parameter in your API request. The filter accepts a boolean value of true or false.

• When set to 1, the API will return only the entities with an ExternalID.
• When set to 0, the API will return only the entities that do not have an ExternalID.

Here is an example of an API request using the has_external_id filter to retrieve suppliers with an externalID:

This request will return a list of suppliers that have an ExternalID assigned.

Similarly, you can use the has_external_id filter with other supported entities to filter based on the presence or absence of an ExternalID. For example:

This request will return a list of invoices that do not have an ExternalID assigned.

By utilizing the has_external_id filter, you can easily identify and manage entities based on their ExternalID status. This filter is particularly useful when you need to differentiate between entities that have been synchronized with external systems and those that have not.

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.