> ## 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.

# Manage accounting integrations

> Learn how to manage your accounting integrations.

## Check for an active accounting connection

Before configuring a new accounting connection for an organization, make sure this organization has no other existing accounting connections that are active at the moment. For this purpose, call `GET /accounting-connections` with the `X-Organization-Id` header containing the organization ID:

```sh lines theme={null}
curl 'https://api.sandbox.tesouro.com/v1/accounting-connections' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: YOUR_ACCESS_TOKEN'
```

If there are no other active connections set up for this organization, you will receive a `200 OK` response with an empty `data` array:

```json lines theme={null}
{
  "data": []
}
```

## Trigger accounting synchronization

By default, Tesouro automatically synchronizes the organization's data in our database with the data in the organization's accounting system every hour. However, organizations can also trigger an instant synchronization when needed. To do this, call `POST /accounting-connections/{connection_id}/sync`:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/accounting-connections/{connection_id}/sync' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The `202 Accepted` response is returned if the request is successful.

## Disconnect an accounting system

To disconnect an already established accounting connection, call [`POST /accounting-connections/{id}/disconnect`](/finops/reference/openapi/accounting-connections/post-accounting-connections-id-disconnect):

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/accounting-connections/{id}/disconnect' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The successful `200 OK` response contains `"status": "disconnected"`:

```json lines theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f76afa6",
  "status": "disconnected",
  "platform": "xero",
  "created_at": "2023-04-02T13:11:53.250Z",
  "updated_at": "2023-04-02T13:11:53.250Z",
  "last_pull": "2023-04-02T13:11:53.250Z",
  "errors": null
}
```

## Check synchronization logs

You can obtain an overview of all the synchronization events between Tesouro and the accounting system in a list. When the synchronization is successful, the status and IDs of records from both systems will be returned. If not, an error status with details will be returned instead.

To get a list with all the sync records, call [`GET /accounting-synced-records`](/finops/reference/openapi/accounting-synchronized-records/get-accounting-synced-records). Filtering the results by the `object_type` is **mandatory**. For example, `GET /accounting-synced-records?object_type=bill` will get all the sync records for bills (payables).

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/accounting-synced-records?object_type=bill' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

You can refine the request to get information about a specific object by adding the `object_id` query parameter to the request, for example:

```lines theme={null}
GET /accounting-synced-records?object_type=bill&object_id=342d33a5-e89f-4a90-8c68-7da318ad4d88
```

<Info>
  For the full list of available sort and filter parameters, see the [`GET
      /accounting-synced-records`](/finops/reference/openapi/accounting-synchronized-records/get-accounting-synced-records)
  endpoint.
</Info>

This successful response returns a synchronization object that includes the `sync_status` and `errors` fields, representing the synchronization status and information about any errors, respectively.

```json expandable lines theme={null}
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_at": "2024-03-05T15:14:14.728Z",
      "updated_at": "2024-03-05T15:14:14.728Z",
      "errors": {},
      "last_pulled_at": "2024-03-05T15:14:14.728Z",
      "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "object_type": "product",
      "object_updated_at": "2024-03-05T15:14:14.728Z",
      "platform": "xero",
      "platform_object_id": "18cb53c4-3807-4a5a-8da9-303053a40002",
      "platform_updated_at": "2024-03-05T15:14:14.728Z",
      "provider": "railz",
      "provider_object_id": "58e1d32f-a092-438a-bffb-3bf6af9ba8ec",
      "provider_updated_at": "2024-03-05T15:14:14.728Z",
      "sync_status": "pending"
    }
  ],
  "next_pagination_token": "eyJvcmRlciI6ImFzYyIsImxpbWl0IjoyLCJwYWdpbmF0aW9uX2ZpbHRlcnMiOnsiZW50aXR5X2lkIjoiOWQyYjRjOGYtMjA4Ny00NzM4LWJhOTEtNzM1OTY4M2M0OWE0In0sInBhZ2luYXRpb25fdG9rZW5fdHlwZSI6Im5leHQiLCJjdXJzb3JfZmllbGQiOm51bGwsImN1cnNvcl9maWVsZF92YWx1ZSI6bnVsbCwiY3VycmVudF9vaWQiOjR9",
  "prev_pagination_token": null
}
```

You can get the details about a specific record by sending a `GET` request to the [`/accounting-synced-records/{synced_record_id}`](/finops/reference/openapi/accounting-synchronized-records/get-accounting-synced-records-id) endpoint.

## List documents in the accounting system

You can list all invoices and payables (bills) that exist in the organization's connected accounting system without the need to pull those documents into Tesouro, so you can implement custom document comparison and synchronization logic:

* [`GET /accounting/receivables`](/finops/reference/openapi/accounting-data-pull/get-accounting-receivables) - to list all invoices
* [`GET /accounting/receivables/{invoice_id}`](/finops/reference/openapi/accounting-data-pull/get-accounting-receivables-id) - to retrieve a specific invoice
* [`GET /accounting/payables`](/finops/reference/openapi/accounting-data-pull/get-accounting-payables) - to list all payables (bills)
* [`GET /accounting/payables/{payable_id}`](/finops/reference/openapi/accounting-data-pull/get-accounting-payables-id)- to retrieve a specific payable (bill)

## Accounting tax rates

### Retrieve accounting tax rates

When pushing an invoice to an accounting system, FinOps Hub tries to map the applicable tax rates used in the invoice to the tax rates available in the organization's accounting system. Organizations can retrieve the available tax rates from the accounting system to ensure that they match the `tax_rate_value` field in the invoice line items. To do this, call `GET /accounting-tax-rates`:

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/accounting-tax-rates' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The response returns the list of tax rates available in the organization's accounting system. Any tax rates that are used in the invoice line items and are missing from the organization's accounting system must be created manually by the organization in their accounting system.

### Internal accounting tax rates

In addition to tax rates retrieved from your connected accounting system, Tesouro allows you to create and manage custom tax rates internally. Custom tax rates created in Tesouro have the `is_external` field set as `false`.

#### Create an internal tax rate

If your organization needs a tax rate that does not exist in the connected accounting system, you can create a custom tax rate calling `POST /accounting-tax-rates`:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/accounting-tax-rates' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Reduced tax",
    "code": "RED_TAX",
    "description": "Reduced tax rate for specific goods"
  }'
```

The successful `201` response returns the newly created tax rate:

```json lines theme={null}
{
  "id": "4gb96g75-6828-5673-c4gd-3d074g87bgb7",
  "name": "Reduced tax",
  "code": "RED_TAX",
  "description": "Reduced tax rate for specific goods",
  "effective_tax_rate": 0,
  "created_at": "2024-03-05T16:20:57.066Z",
  "updated_at": "2024-03-05T16:20:57.066Z",
  "is_external": false
}
```

<Info>
  Custom tax rates created in Tesouro (`is_external = false`) can be used in invoices but may need
  to be manually created in your accounting system if they do not already exist there.
</Info>

#### Retrieve internal tax rates

To get all available internal tax rates for an organization, call `GET /accounting-tax-rates?is_external=false`. To get details about a specific tax rate, call `GET /accounting-tax-rates/{tax_rate_id}`.

#### Edit an internal tax rate

You can update the details of an existing tax rate using `PATCH /accounting-tax-rates/{tax_rate_id}`:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/accounting-tax-rates/{tax_rate_id}' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Updated description for the tax rate"
  }'
```

<Warning>
  Updating tax rates may affect existing invoices and documents that reference these rates. Consider
  the impact on historical data before making changes.
</Warning>

#### Delete an internal tax rate

To delete a tax rate, call `DELETE /accounting-tax-rates/{tax_rate_id}`.

<Warning>
  Before deleting a tax rate, ensure it is not being used by any existing invoices or documents.
  Deleting a tax rate that is in use may cause synchronization issues with your accounting system.
</Warning>

## Retry pushing data

You can manually retry a failed sync to the accounting system in cases where errors occur during the attempt by calling [`POST /accounting-synced-records/{synced_record_id}/push`](/finops/reference/openapi/accounting-synchronized-records/post-accounting-synced-records-id-push). The `synced_record_id` of the failed sync can be obtained in the [synchronization log](#check-synchronization-logs):

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/accounting-synced-records/{synced_record_id}/push' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The successful response returns the information of the retried sync:

```json expandable lines theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2024-03-05T16:20:57.066Z",
  "updated_at": "2024-03-05T16:20:57.066Z",
  "errors": {},
  "last_pulled_at": "2024-03-05T16:20:57.066Z",
  "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object_type": "product",
  "object_updated_at": "2024-03-05T16:20:57.066Z",
  "platform": "xero",
  "platform_object_id": "18cb53c4-3807-4a5a-8da9-303053a40002",
  "platform_updated_at": "2024-03-05T16:20:57.066Z",
  "provider": "railz",
  "provider_object_id": "58e1d32f-a092-438a-bffb-3bf6af9ba8ec",
  "provider_updated_at": "2024-03-05T16:20:57.066Z",
  "sync_status": "pending"
}
```