API Best Practices - Importing sales transactions including customers

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

Good to know: Please find the complete description about sales transactions here: https://accounting.twinfield.com/webservices/documentation/#/ApiReference/Transactions/SalesTransactions

Good to know: Please find the complete description about customers here: https://accounting.twinfield.com/webservices/documentation/#/ApiReference/Masters/Customers

Good to know: There are five transaction type categories. These are sales, purchase, bank, cashbook and journal. This article will only explain how to import sales transactions.

In this article we'll explain how you can import sales transactions into Twinfield. 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 steps that are mentioned in this article.

Good to know: If you need to post revenue to a cost center or a project then you can follow steps 1 to 3 below for downloading, adding and updating customers. Customers are dimension type DEB, cost centers are KPL and projects are PRJ.

The process of importing sales transactions has seven steps:

1. Download all customers that currently exist in Twinfield
2. Update the dimension type mask
3. Add or update customers into Twinfield
4. Find the available transaction types
5. Find the available general ledgers
6. Find the available vat codes
7. Import new sales transactions

Download all customers that currently exist in Twinfield

To make sure that the starting point in both your software and Twinfield with relation to customer data is the same, it is advised to download all customers that currently exist in Twinfield. You can do this by downloading the initial load that is described in this article: Keeping a shadow database with customers/suppliers
 

Confirm that the end-user has configured the dimension type for customers in Twinfield

Twinfield can be configured to allow only certain codes for customers. For example, codes in the range from 1000 until 1999. To make sure that each customer has a unique code in Twinfield, the end-user must configure this range in the user interface of Twinfield.

Important: It's important that you let Twinfield decide the code for each new customer. This is to avoid the scenario where multiple connected software applications use the same customer code for different customers.

The end-user can read this Dutch knowledge article to learn how to do this in Twinfield: Beheer administraties - Dimensietypen
 

Add or update customers into Twinfield

Add or update customers into Twinfield. You can use the request named ‘Add or update customers into Twinfield’ in the Postman collection in the attachment of this article.

Good to know: For adding or updating cost centers or projects, use the request named 'Add or update cost centers or projects' in the Postman collection.

Important: Please follow the best practice by limiting the amount of customers to 25 at a time.



Important: In case a customer already exists in Twinfield, then Twinfield will first delete all existing addresses and banks of the customer when you use <addresses> or <banks> in the xml request. After they are deleted, Twinfield will only add the addresses and banks that you provided in the xml request.


 

Find the available transaction types

To make sure that you are sending the sales transactions to the correct transaction type in Twinfield you must request the available sales transaction types first. A company in Twinfield can have multiple sales transaction types.

To request the available transaction types you can use the Postman collection in the attachment of this article, specifically the request ‘Find the available transaction types’.

Important: Please follow the best practices below while finding the available sales transaction types.

1. Limit the amount of transaction types to 25 at a time. You can use the firstRow and maxRows parameters for this.



2. Only request the transaction types that are of the category sales. 


 

Find the available general ledgers

Make sure that you are sending the sales transactions to the correct general ledgers in Twinfield by requesting the available codes first. To request the available ledger codes, you can use the Postman collection in the attachment of this article, specifically the request ‘Find the available general ledgers’.

Important: Limit the amount of codes to 25 at a time. You can use the firstRow and maxRows parameters for this.



Important: Use PNL for profit and loss and BAS for balance.

Find the available vat codes

Make sure that you are sending the sales transactions to the correct vat codes in Twinfield by requesting the available vat codes first. To request the available vat codes, you can use the Postman collection in the attachment of this article, specifically the request ‘Find the available vat codes’.

Important: Limit the amount of codes to 25 at a time. You can use the firstRow and maxRows parameters for this.



Important: Only request the vat type sales.

Import new sales transactions

To import new sales transactions into Twinfield you can use the Postman collection in the attachment of this article. You can use the request named ‘Import new sales transactions’.

Important: Please follow the best practices below while importing new sales transactions.

1. Limit the amount of transactions to 25. You can insert multiple <transaction> blocks into <transactions>.



2. Limit a sales transaction to a maximum of 500 detail lines.



3. It's recommended to:

• Set the attribute 'destiny' to 'final' to prevent differences between your software and Twinfield.
• Set the attribute 'autobalancevat' to 'true' to avoid rounding errors in the vat.
• Set the attribute ‘raisewarning’ to ‘false’ to make sure that data from your software is leading.