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

# Data export

> Learn how to bulk export your Accounts Payable and Accounts Receivable data from Tesouro, so you can use this data in an external accounting system.

## Overview

Tesouro allows [organizations](/finops/guides/organizations/index) to export all their [accounts payable](/finops/guides/accounts-payable/index), so they can integrate this data into their accounting systems.

The exported payables data are structured in CSV format and must be selected by specific statuses, and start and end dates.

## Compatible accounting systems

Currently, Tesouro supports accounting data export to [Xero](https://www.xero.com/). More export formats will be added in the future.

### Xero

The Xero export contains just the essential data for Xero to execute the import. Tesouro does not validate the exported data. To check Xero’s requirements and validations, check the [Xero documentation](https://developer.xero.com/).

## Considerations

* Counterpart-related data is exported only for payables that have been [submitted for approval](/finops/guides/accounts-payable/payables/collect) as the information about the [counterparts](/finops/guides/common/counterparts/index) is inserted into the payables only at this status.

* The prices in the exported data are **tax-exclusive**, that is, do not include taxes.

## Export the accounting data

To export the accounting data of a specific organization, call [`POST /data-exports`](/finops/reference/openapi/data-export/post-data-exports) and specify the desired format (`csv_xero`), the object type name (in this example - `payable`) and [statuses](/finops/guides/accounts-payable/payables/collect), and the date range:

```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/data-exports' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "format": "csv_xero",
       "objects": [
         {
           "name": "payable",
           "statuses": [
             "new"
           ]
         }
       ]
       "date_from": "2022-08-10",
       "date_to": "2022-08-18"
     }'
```

The successful response contains the data export ID:

```json lines theme={null}
{
  "id": "edb064b2-af7f-4730-9b73-38c699c383d9"
}
```

To get the link to download the exported files, call [`GET /data-exports/{data_export_id}`](/finops/reference/openapi/data-export/get-data-exports-id), passing the previously obtained data export ID in the URL:

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

The successful response contains information about the data export and the `source_url` field, which contains the URL to download the exported file:

```json lines theme={null}
{
  "source_url": "https://tesouro-file-saver-zip-eu-central-1-sandbox.s3.com/1a65fd3b-...22c4/02825c72-...f04c.zip",
  "entity_id": "c23dd09c-077a-4afa-914f-f53fc2748ec4",
  "start_datetime": "2022-08-17T13:48:57.455932+00:00",
  "end_datetime": "2022-08-17T13:48:57.584375+00:00",
  "count": 5,
  "id": "edb064b2-af7f-4730-9b73-38c699c383d9",
  "language": "pt-br,pt;q=0.9,en-us;q=0.8,en;q=0.7",
  "status": "done",
  "created_by_entity_user_id": null,
  "format": "csv_xero"
}
```

The file is exported in the ZIP format which includes one or more CSV files, depending on the amount of entries. Each file can contain up to 100 payables with multiple [line items](/finops/guides/accounts-payable/payables/line-items) per payable.

<Info>
  Bigger exports may take longer to be processed. Meanwhile, their status are presented as `pending` until the export is completed and the file is available for download.
</Info>

<AccordionGroup>
  <Accordion title="Field mapping">
    This is how the fields between Tesouro and Xero are associated:

    | Tesouro field                     | Xero field       |
    | --------------------------------- | ---------------- |
    | `counterpart.name`                | `*ContactName`   |
    | `counterpart.email`               | `EmailAddress`   |
    | `counterpart.address.line1`       | `POAddressLine1` |
    | `counterpart.address.line2`       | `POAddressLine2` |
    | `counterpart.address.city`        | `POCity`         |
    | `counterpart.address.state`       | `PORegion`       |
    | `counterpart.address.postal_code` | `POPostalCode`   |
    | `counterpart.country`             | `POCountry`      |
    | `document_id`                     | `*InvoiceNumber` |
    | `issued_at`                       | `*InvoiceDate`   |
    | `due_date`                        | `*DueDate`       |
    | `line_items.description`          | `Description`    |
    | `line_items.quantity`             | `*Quantity`      |
    | `line_items.unit_price`           | `*UnitAmount`    |
    | `line_items.account_code`         | `*AccountCode`   |
    | `line_items.tax_type`             | `*TaxType`       |

    All the fields are obtained from the `payables` object, except `tax_type` and `account_code`, which are obtained from the `/extra-data` [settings](#set-default-values).
  </Accordion>

  <Accordion title="Set default values">
    You can configure default values for specific fields in the exported data to streamline the CSV processing and reduce manual work.

    Currently, it is possible to set default values for the account code (`default_account_code`) and tax rate code (`default_tax_rate_code`) fields, which are mapped to `*AccountCode` and `*TaxType` respectively on Xero.

    Additionally, the `counterpart_id` obtained from exported payables is used to search for entries corresponding to this `counterpart_id` in the Tesouro system. If a corresponding register is found, i.e. this counterpart already exists in the Tesouro system, the exported data is enriched with the counterpart information.

    To create a default value for a specific field, send a `POST` request to the [`/data-exports/extra-data`](/finops/reference/openapi/data-export-extra-data/post-data-exports-extra-data) endpoint specifying the :

    ```sh lines theme={null}
    curl -X POST 'https://api.sandbox.tesouro.com/v1/data-exports/extra-data' \
         -H 'X-Finops-Version: 2025-06-23' \
         -H 'X-Organization-Id: ORGANIZATION_ID' \
         -H 'Authorization: Bearer ACCESS_TOKEN'
         -H 'Content-Type: application/json' \
         -d '{
           "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
           "object_type": "counterpart",
           "field_name": "default_account_code",
           "field_value": "100100"
         }'
    ```

    The successful response contains information about the default value:

    ```json lines theme={null}
    {
      "id": "4a9053d5-4023-400e-ab00-47adf7737022",
      "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "object_type": "counterpart",
      "field_name": "default_account_code",
      "field_value": "100100",
      "created_at": "2023-10-05T07:29:17.332Z",
      "updated_at": "2023-10-05T07:29:17.332Z",
      "created_by": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
    ```

    ### List all default values

    To get information about all default values, call [`GET /data-exports/extra-data`](/finops/reference/openapi/data-export-extra-data/get-data-exports-extra-data).

    ### Retrieve a default value

    To get information about a specific default value, call [`GET /data-exports/extra-data/{extra_data_id}`](/finops/reference/openapi/data-export-extra-data/get-data-exports-extra-data-id) endpoint.

    ### Update a default value

    To edit an existing default value, call [`PATCH /data-exports/extra-data/{extra_data_id}`](/finops/reference/openapi/data-export-extra-data/patch-data-exports-extra-data-id) endpoint.

    ### Delete a default value

    To delete an existing default value, call [`DELETE /data-exports/extra-data/{extra_data_id}`](/finops/reference/openapi/data-export-extra-data/delete-data-exports-extra-data-id) endpoint.
  </Accordion>
</AccordionGroup>

## Check all data exports

To check all the requested data exports, call [`GET /data-exports`](/finops/reference/openapi/data-export/get-data-exports) endpoint:

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

The successful response contains a list of all data exports requested:

```json expandable lines theme={null}
{
  "data": [
    {
      "status": "done",
      "source_url": "https://tesouro-file-saver-zip-eu-central-1-sandbox.s3.amazonaws.com/1a65fd...22c4/02825c...ff04c.zip",
      "start_datetime": "2022-08-17T13:48:57.455932+00:00",
      "format": "csv_xero",
      "end_datetime": "2022-08-17T13:48:57.584375+00:00",
      "created_by_entity_user_id": null,
      "language": "pt-br,pt;q=0.9,en-us;q=0.8,en;q=0.7",
      "entity_id": "c23dd09c-077a-4afa-914f-f53fc2748ec4",
      "id": "edb064b2-af7f-4730-9b73-38c699c383d9",
      "count": 5
    }
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}
```