> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounting integration

> Synchronize accounts payable and receivable data with popular accounting solutions.

## Overview

Many businesses use accounting software to prepare financial data for tax authorities. Tesouro lets you connect your users' data to their accounting software — pull financial data into your interface and push data back when they need to do post-accounting work outside your app.

### Supported accounting systems

Each [organization](/finops/guides/organizations/index) can connect to one of the following accounting systems:

* QuickBooks Online
* Xero

We'll add more accounting systems in future releases. If you have requests, contact our [Support team](/finops/support).

### Requirements and considerations

* Tesouro partners supporting accounting integration must create developer accounts in each accounting platform they support.
* Each organization must have an account with their accounting system (Xero, QuickBooks) before creating an accounting connection via the Tesouro API.

## Set up the integration

See [Set up accounting integration](/finops/guides/accounting/integration/setup).

## How the integration works

First, establish a connection to the organization's accounting software and have an organization user authorize it. Once connected, Tesouro automatically syncs the organization's financial data with their accounting software. After the initial sync, Tesouro syncs both systems every hour.

<Info>
  Tesouro doesn't push older invoices or bills during the initial sync. Only invoices and bills
  eligible for pushing **after** the sync are pushed to the accounting software.
</Info>

## What data is synchronized

Tesouro supports two actions for synchronized data:

<AccordionGroup>
  <Accordion title="Pull for matching">
    Pulls external data into Tesouro for matching with existing records. No new records are created — the pulled data is only matched against what already exists.
  </Accordion>

  <Accordion title="Pull for creation">
    Pulls external data and creates new entries in Tesouro for any unmatched records. If the pulled data doesn't match an existing record, Tesouro creates one automatically.
  </Accordion>
</AccordionGroup>

Currently, Tesouro pulls and pushes the following data from and to accounting systems. Data is synchronized every hour.

| Data                                                                                  | Pull — for access | Pull — for matching | Pull — for creation | Pushed                                                            |
| ------------------------------------------------------------------------------------- | ----------------- | ------------------- | ------------------- | ----------------------------------------------------------------- |
| [Ledger accounts](/finops/guides/accounting/integration/ledger-accounts)              | ✓                 |                     |                     | References to ledger accounts in invoice line items, and products |
| [Counterparts](/finops/guides/common/counterparts/index)                              |                   | ✓                   |                     | ✓                                                                 |
| [Products](/finops/guides/accounts-receivable/products)                               |                   | ✓                   | ✓                   | ✓                                                                 |
| Tax rates                                                                             | ✓                 | ✓                   |                     |                                                                   |
| Accounts receivable: [invoices](/finops/guides/accounts-receivable/invoices/index)    | ✓                 |                     |                     | ✓                                                                 |
| Accounts receivable: [credit notes](/finops/guides/accounts-receivable/credit-notes)  |                   |                     |                     | ✓                                                                 |
| Accounts receivable: invoice [payment records](/finops/guides/common/payment-records) |                   |                     |                     | ✓                                                                 |
| Accounts payable: [bills](/finops/guides/accounts-payable/payables/collect)           | ✓                 |                     |                     | ✓                                                                 |

Organizations can also pull records from the accounting system on demand by calling [`POST /accounting-connections/{connection_id}/sync`](/finops/reference/openapi/accounting-connections/post-accounting-connections-id-sync).

## How data is synchronized

<AccordionGroup>
  <Accordion title="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 doesn't create any new items during this process.

    To access the ledger accounts pulled from the accounting system, use [`GET /ledger-accounts`](/finops/reference/openapi/ledger-accounts/get-ledger-accounts).

    #### Counterparts

    Counterparts from the accounting system are matched with existing counterparts in Tesouro, but Tesouro doesn't create new counterparts if there's 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's no match, organizations can manually create counterparts in Tesouro to match their accounting system.

    #### Products

    All products are pulled from the accounting system on the first connection. Data is pulled and IDs are matched by name. If a product doesn't exist in Tesouro, Tesouro creates it and links it to the corresponding product in your accounting system.

    When a new product is created in the accounting system, Tesouro checks for a match.
    If it doesn't find one, Tesouro pulls the product's data and creates it internally.

    <Info title="Limitations">
      **Limitations**

      * Products with a negative price or no price aren't pulled.
      * A product isn't pulled from accounting if two or more products with the same name exist in Tesouro.

      These errors are included in results from [`GET /accounting-synced-records?object_type=product`](/finops/reference/openapi/accounting-synchronized-records/get-accounting-synced-records).
    </Info>

    #### Tax rates

    Tax rates are pulled only for mapping. Tesouro doesn't create new items during this process, so unmatched tax rates are ignored.

    To access the tax rates pulled from the accounting system, use [`GET /accounting-tax-rates`](/finops/reference/openapi/accounting-tax-rates/get-accounting-tax-rates).

    <Info>
      **Handling multiple matches**

      If a product's name matches multiple products on either system, Tesouro doesn't attempt to match any of them. The error is returned in your `sync_object`.
    </Info>

    #### 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, use [`GET /accounting/payables`](/finops/reference/openapi/accounting-data-pull/get-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, use [`GET /accounting/receivables`](/finops/reference/openapi/accounting-data-pull/get-accounting-receivables).
  </Accordion>

  <Accordion title="Pushing">
    ### Pushing

    This section describes how data is pushed to an accounting system.

    #### Ledger accounts

    Ledger accounts aren't pushed to the accounting system.

    #### Accounts payable: invoices (bills)

    Only payables in the `issued` and `canceled` statuses are pushed. Before pushing, Tesouro validates that bills have `tax_rate_ref_id`, `ledger_account_id`, and `line_items` references. Bills can’t be issued without these fields.

    #### Accounts receivable: invoices

    Tesouro doesn't push older invoices during the initial sync. After that, invoices are only pushed to the organization's accounting system when they move to the `issued` 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 manually in the accounting system.

    Pushed credit notes aren't associated with the corresponding invoices in the accounting system, so invoices there won't be automatically canceled when a credit note is pushed.

    #### Payment records

    Only payment records associated with accounts receivable invoices are pushed to the accounting system.
    Payment records for payables (bills) aren't pushed.

    Before a payment record can be pushed, the organization must specify the [ledger account](/finops/guides/accounting/integration/ledger-accounts) to attach it to.
    Use the organization setting [`accounting.ledger_account_ids.payments`](/finops/reference/openapi/identity/patch-organizations-id-settings#request.body.accounting) to specify the target ledger account. For more information, see [Assign a ledger account to payment records](/finops/guides/accounting/integration/ledger-accounts#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.

    When pushing counterparts, Tesouro first tries to find a matching counterpart by name in the accounting system.
    If there's no match, Tesouro creates the counterpart in the accounting system.

    If a counterpart in Tesouro has both `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.
  </Accordion>
</AccordionGroup>

After every synchronization, you can track its status and any errors returned by calling [`GET /accounting-synced-records/{synced_record_id}`](/finops/reference/openapi/accounting-synchronized-records/get-accounting-synced-records-id). For more information, see [Check synchronization logs](/finops/guides/accounting/integration/manage#check-synchronization-logs).