This article is part of this article serie:
API Best Practices - IntroductionIn this article we'll explain how you can download transactions 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 browse codes and queries that are mentioned in this article.
The process of keeping a shadow database in your own software has three steps:
- Download the intial load only once
- Download the incremental load daily or weekly
- Validate if your shadow database is correct
During the initial load you will request all the transactions from Twinfield that you need. 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 browse code 030_3. Please refer to the Postman collection in the attachment of this article for a ready to use example of this browse code. Please refer to this article for the complete documentation about browse codes: https://accounting.twinfield.com/webservices/documentation/#/ApiReference/Request/BrowseData
Important: Decide which columns of the browse you want to use. Remove all columns that are not relevant to you. The purpose of this is to reduce the amount of data that is being downloaded via the API.
You will download all the transactions that you need during the initial load, but please limit your downloads to one book year at a time. If you need the years 2020, 2021 and 2022, then download 2020 first, then 2021 and then 2022.
If you notice that you receive a timeout while downloading one book year at a time, then the company has too many transactions. In this case you'll have to split up your downloads even more. In this case you can split up 2020 in periods. First download 2020/00, then 2020/01, and so forth.
You can use the column fin.trs.head.yearperiod to set the criteria for this. If you want the entire book year 2020 then ask for the periods 2020/00 until 2020/55. If you only want one period at a time then ask for 2020/00 until 2020/00.
If you want to limit the transactions you download to only profit-and-loss ledgers or to only bank statements then you can apply additional criteria to limit the amount of transactions that you download. The table below will show the most interesting criteria.
| Field_____________________ | Explanation |
|---|
| fin.trs.head.yearperiod | If you want the entire book year 2020 then ask for the periods 2020/00 until 2020/55. If you only want one period at a time then ask for 2020/00 until 2020/00.
For example:
<operator>between</operator>
<from>2020/01</from>
<to>2022/01</to> |
| fin.trs.head.code | If you only want bank statements or sales invoices then you can limit your request to a specific transaction type.
For example:
<operator>equal</operator>
<from>SLS</from>
<to></to> |
| fin.trs.line.dim1 | If you only want transaction lines for specific ledgers then you can limit your request to specific ledgers.
For example:
<operator>between</operator>
<from>0100</from>
<to>0200</to> |
The incremental load
After you have downloaded the initial load you can set up a daily or weekly request that only downloads transaction that were added or changed since your last download. You can use the same request as you used for the initial load, but this time you will add this extra criteria:
This will limit the transactions that you download to only those transactions that were added or changed within the time range that you specifiy. The date/time format is "yyyymmddhhmmss". 20220428000000 means 28 April 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 update your shadow database by adding the new transactions and updating the modified existing transactions.
The last step of the incremental load is to request a list of transactions that were deleted since your last download. You can use the query GetDeletedTransactions for this. You'll find a ready to use example in the Postman collection in the attachment. Update your shadow database by deleting those transactions in your shadow database.
For this query you also have to specify the time range. The date/time format is "yyyy-mm-ddThh:mm:ss.miliseconds" 2022-04-28T00:00:00.000 means 28 April 2022 at 00:00:00.000 hours.
Validate your shadow database
After your shadow database is up to date, it's important to validate that your data matches the data in Twinfield. You can do this by downloading the balance per ledger from Twinfield. You can use browse code 040_1 for this.
After you've downloaded the total value per ledger by using browse code 040_1, you can compare it to the total value per ledger in your shadow database.
Limit your downloads to one year at a time. If you only want to retrieve the balances for 2020 then use the criteria below.
Good to know: You can also use the other criteria of this browse code to limit the number of ledgers for which you want to view the balance.
After you have downloaded the balance per ledger from Twinfield you can calculate the balance per ledger in your own shadow database. If everything is correct then your shadow database should show the same balances as shown in browse code 040_1.
