Overview
Many SMEs use various accounting solutions to store and prepare their financial data for submission to tax authorities. With Tesouro, you can connect your users’ data to their preferred accounting software and pull necessary financial data for import into your interface, as well as push data in case they need to do any post-accounting work outside of your application.Supported accounting systems
Each organization can connect to one of the following accounting systems:- QuickBooks Online
- Xero
Requirements and considerations
- All Tesouro partners that intend to support accounting integration must create developer accounts in the accounting platforms they intend to support.
- Each organization that wants to connect to an external accounting system (like Xero or QuickBooks) must have an account with that system before attempting to create an accounting connection with the Tesouro API.
Set up the integration
See Set up accounting integration.How the integration works
The first step required to enable accounting integration for an organization is to establish a connection to an organization’s accounting software and ask an organization user to authorize the connection. Once the connection has been established, the organization’s financial data will be synchronized automatically between Tesouro’s and the organization’s accounting software. After the initial synchronization, Tesouro will automatically trigger synchronizations between both systems every hour.Tesouro does not push older invoices or bills to the organization’s accounting software during the
initial synchronization. Therefore, only invoices and bills eligible for pushing after the
accounting synchronization will be pushed to the accounting software.
What data is synchronized
In our accounting integration, we support two key actions for handling synchronized data:Pull for matching
Pull for matching
This feature pulls external data into our system for comparison or matching with existing records. No new records are created within the Tesouro platform; the purpose is solely to match the pulled data with corresponding data that already exists in our system.
Pull for creation
Pull for creation
This feature not only pulls external data but also creates new entries in the Tesouro system for any unmatched records. If the pulled data does not have a corresponding match, a new record is automatically created in our platform.
| Data | Pull — for access | Pull — for matching | Pull — for creation | Pushed |
|---|---|---|---|---|
| Ledger accounts | ✓ | References to ledger accounts in invoice line items, and products | ||
| Counterparts | ✓ | ✓ | ||
| Products | ✓ | ✓ | ✓ | |
| Tax rates | ✓ | ✓ | ||
| Accounts receivable: invoices | ✓ | ✓ | ||
| Accounts receivable: credit notes | ✓ | |||
| Accounts receivable: invoice payment records | ✓ | |||
| Accounts payable: bills | ✓ | ✓ |
POST /accounting-connections/{connection_id}/sync.
How data is synchronized
Pulling
Pulling
Pulling
This section describes how data is pulled from an accounting system.Ledger accounts
Ledger accounts are pulled only for mapping to products. Tesouro does not create any new items during this process.To access the ledger accounts pulled from the accounting system, useGET /ledger-accounts.Counterparts
Counterparts from the accounting system are matched with the existing counterparts in Tesouro, but no new counterparts are created in Tesouro if there is no match.Counterparts are matched based on their names and each part of the billing address (country, city, street name, and so on). All counterpart types - both organizations and individuals - are pulled as organizations.If there is no match, organizations can manually create counterparts in Tesouro to match the counterpart details in their accounting system.Products
All products are pulled from the accounting system on the first connection. Data is pulled, and IDs are matched based on their names alone. If a product does not exist in Tesouro, Tesouro will create a new product in our database and link it to the corresponding product from your accounting system.Every time a new product is created in the accounting system, Tesouro checks if there is a match for this product in Tesouro. If the product is not found, Tesouro pulls the product’s data and automatically creates the product internally.Limitations
- Products with a negative price or no price are not pulled.
- A products is not pulled from accounting if two or more products with the same name exist in Tesouro.
GET /accounting-synced-records?object_type=product.Tax rates
Tax rates are pulled only for mapping purposes. Tesouro does not create any new items during this process; therefore, no action is taken if no match is found.To access the tax rates pulled from the accounting system, useGET /accounting-tax-rates.Handling multiple matchesIf a product’s name matches with multiple products on either system, Tesouro does not attempt to match any of the results. The resulting error will be returned in your
sync_object.Accounts payable: invoices (bills)
Payables are pulled only for access purposes, they are neither matched nor created.To get the list of payables (bills) from the accounting system, useGET /accounting/payables.Accounts receivable: invoices
Invoices are pulled only for access purposes, they are neither matched nor created.To get the list of invoices from the accounting system, useGET /accounting/receivables.Pushing
Pushing
Pushing
This section describes how data is pushed to an accounting system.Ledger accounts
Ledger accounts are not pushed into the accounting system.Accounts payable: invoices (bills)
Only payables in the ‘issued’ and ‘canceled’ statuses are pushed. Before pushing, bills are validated to confirm the presence of references fortax_rate_ref_id, ledger_account_id, and line_items. Issuance of bills without this validation is prohibited.Accounts receivable: invoices
Tesouro does not push any of the organization’s older invoices during the initial synchronization. After synchronization, invoices in Tesouro are only pushed to the organization’s accounting system when they are moved to theissued status.The receivable line items include the accounting_tax_rate_id field, which allows overriding the default tax rate when pushing invoices to the accounting system. Valid tax rate IDs can be retrieved using the GET /accounting-tax-rates endpoint.Accounts receivable: credit notes
Credit notes are pushed without a document number. Users can backfill credit note numbers in the accounting system manually.The pushed credit notes do not get associated with the corresponding invoices in the accounting system. As a result, invoices in the accounting system will not be automatically canceled when a corresponding credit note is pushed.Payment records
Only payment records associated with accounts receivable invoices are pushed into the accounting system. Payment records for payables (bills) are not pushed.Before payment record can be pushed, the organization must specify the ledger account to attach them to. Use the organization settingaccounting.ledger_account_ids.payments to specify the target ledger account. For more information, see Assign a ledger account to payment records.Counterparts
Tesouro pushes counterparts into the accounting system when:- A new counterpart is created in Tesouro.
- An invoice issued to that counterpart is pushed into the accounting system.
is_customer and is_vendor set to true, it’s pushed twice: we create a customer in the accounting system and also create a vendor with the same details but with the _VENDOR suffix in the name.Once counterparts are matched, there is no regular check for data changes in either system.GET /accounting-synced-records/{synced_record_id}. For more information, see Check synchronization logs.