API Best Practices - Keeping a shadow database with customers/suppliers

This article is part of this article serie: API Best Practices - Introduction

In this article we'll explain how you can download all customers and/or suppliers from Twinfield and keep a shadow database in your own software. We ask you to follow this best practice because it supports our Fair Use Policy. You can read about our Fair Use Policy here: https://accounting.twinfield.com/webservices/documentation/#/GettingStarted/FUP

Good to know: There is a Postman-collection in the attachment of this article with ready to use examples of the xml requests that are mentioned in this article.

The process of keeping a shadow database in your own software has three steps:

1. Download the intial load only once
2. Download the incremental load daily or weekly
3. Periodically validate if your shadow database is correct

During the initial load you will request all the customers and/or suppliers from Twinfield. This is your starting point. After you have done this, you will continue by requesting only the changes since the initial load. This is called the incremental load. You can do the incremental load daily or weekly depending on your needs.
 

The initial load

For the initial load you can use the Finder. Please refer to the request Find customer/supplier codes in the Postman collection in the attachment of this article for a ready to use example. Please refer to this article for the complete documentation about using the Finder: https://accounting.twinfield.com/webservices/documentation/#/ApiReference/Miscellaneous/Finder

Important: Please follow the best practice by limiting the amount of codes that you download to 25 at a time. You can use the firstRow and maxRows parameters for this:



Important: You must download the customer and supplier codes seperately. Use dimtype DEB for customers and dimtype CRD for suppliers.



After you have downloaded all the customer and/or supplier codes you can make a seperate request to download all the details. You can use the request Read customers/suppliers in the Postman collection in the attachment.

Important: Please follow the best practice by requesting the details for 25 codes at a time. You can do this by adding multiple <read> blocks into <general>.

Good to know: Use dimtype DEB for customers and CRD for suppliers.



Known error: You must linearize the xml between <general>...</general> while sending the request to the API. This is to prevent a known error.

The incremental load

After you have downloaded the initial load you can set up a daily or weekly request that only downloads customer and/or supplier codes that were added or changed since your last download. You can use the same Finder request as you used for the initial load, but this time you will add this extra criteria:



This will limit the customer and/or supplier codes that you download to only those that were added or changed within the time range that you specify. The date/time format is "yyyymmddhhmmss". 20220725000000 means 25 July 2022 at 00:00:00 hours.

Good to know: The API only uses universal time (UTC). You can check the current time in UTC here: https://time.is/utc

The next step is to download the details for each customer and/or supplier. You can use the same request as you used for the initial load.
 

Periodically validate your shadow database

Keep in mind that the above steps will not tell you if a customer and/or supplier has been deleted in Twinfield. The only way to verify if there are deleted customers and/or suppliers is to periodically request all customer and/or supplier codes and compare them with your shadow database.

If a customer and/or supplier exists in your shadow database but not in the result of the request, then the customer and/or supplier must have been deleted in Twinfield. You can now also delete it in your shadow database.

Important: Please follow the best practice by validating once a week.

Good to know: You can repeat the steps of the initial load to find all customer and/or supplier codes.