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

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

Good to know: There is a Postman collection in the attachment with a ready-to-use example of browse codes 130_3 and 230_2.

Good to know: The complete documentation about browse codes can be found here: https://accounting.twinfield.com/webservices/documentation/#/ApiReference/Request/BrowseData

Often, after creating an invoice in Twinfield by a third party application, the third party application would keep track of the payment status of the invoice. When the invoice is paid in Twinfield, the related invoice in the third-party application should be set to paid also.

Since there is no automatic update mechanism from Twinfield to the outside world, the only option is to retrieve this data from Twinfield by using the Browse Data functionality.

The following steps should be taken/considered:

1. Read all invoices with the payment status available. Use browse code 130_3 when searching for sales invoices. For purchase invoices, use browse code 230_2. Only include provisional and final invoices.

2. Read all invoices with the payment status proposed. Use browse code 130_3 when searching for sales invoices. For purchase invoices, use browse code 230_2.

3. All invoices which are not returned by Twinfield as a result of the above two requests can be considered fully paid.

4. In the case of part payments, invoices remain available until the full amount is paid. So partly paid invoices will be part of the result set of the first step. When an invoice is partly paid, the remaining open amount is stated in the openvaluesigned field. This field is part of both browse code 130_3 as well browse code 230_2. In case the openvaluesigned is not equal to value (the original invoice amount), one or more part payments are made to the invoice.

5. Pay special attention to the result of step two, the invoices with status proposed. This status is used when an invoice is linked to an electronic bank statement line. In Twinfield these invoices are not considered as paid yet. When the electronic bank statement is actually posted, the status is changed into either matched or available. Besides that, the status proposed is also used when an invoice is part of Twinfield processes like "pay and collect" or "reminders".

6. It is possible that invoices which are paid before are changed into available again. Also, these invoices are part of the result set of step 1.

The prerequisite of the above steps is, that it must be possible to link an invoice created in the third party application with the corresponding invoice in Twinfield. Each invoice in Twinfield has a (by transaction type) unique transaction number. When creating an invoice, the transaction number is part of the response. Saving this transaction number together with the invoice in the third-party application ensures that there is always a unique reference to the Twinfield invoice.