API Best Practices - Downloading open invoices from Twinfield (credit management inside Twinfield)

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

Important: This best practice only works for transactions that have been posted in a transaction type that is of the category sales or purchase. Please refer to the articles below on how to post transactions in these transaction type categories:

• Importing sales transactions including customers
• Importing purchase transactions including suppliers

In this article, we'll explain how you can only download customer/supplier transactions that have been posted in the transaction type categories sales and purchase. You can do this by keeping 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: You might download more transactions than you have posted yourself. You should ignore all transactions that you haven't posted yourself.

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.

Good to know: Please refer to this article for the basics about matching in Twinfield: How does matching work in Twinfield?

The process of keeping a shadow database with customer/supplier transactions in your own software has two steps:

1. Download the intial load only once
2. Download the incremental load daily or weekly

During the initial load you will request all the customer/supplier 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

Use browse code 130_3 to download sales transactions and 230_2 to download purchase transactions. The steps described in this article are the same for sales and purchase transactions.

Important: Request the transactions for one transaction type at a time. Only request the transaction type codes that you've previously used for posting transactions. You can use the column fin.trs.head.code to set the criteria for this.



In case you receive a time-out during your download then you can limit your request size even further by only asking one financial year at a time. You can use the column fin.trs.head.yearperiod to set the criteria for this. Always request periods 00 to 56 for customer/supplier transactions.



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.

Important: Use the criteria in the table below to prevent downloading unnecessary transactions.
 

Field_____________________	Explanation
fin.trs.head.code	Important: Download only the customer/supplier transactions that you previously posted in Twinfield. Set the criteria to download only the transaction types that you've used before. Important: You can only download one transaction type at a time. Example criteria for this field: <operator>equal</operator> <from>VRK</from> <to></to>
fin.trs.head.status	You only need provisional and final transactions. Therefore you always need to use this criteria: <operator>equal</operator> <from>normal</from> <to></to>
fin.trs.line.matchstatus	Important: Don't set any criteria for this column. This way you will receive all match statuses.

  
Please refer to this article for the complete documentation about browse codes: https://accounting.twinfield.com/webservices/documentation/#/ApiReference/Request/BrowseData
 

The incremental load

After you have downloaded the initial load you can set up a daily or weekly request that only downloads transactions 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 specify. 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.