Endpoint responsável por listar transferências realizadas na conta Asaas, com suporte a filtros por data de criação, data de efetivação e tipo da transferência.

Este método retorna uma lista paginada de transferências, permitindo acompanhar o histórico de transferências realizadas, consultar transferências agendadas e identificar transferências recorrentes criadas anteriormente.

Quando utilizar este endpoint

Utilize este endpoint quando sua integração precisar:

• consultar o histórico de transferências da conta;
• monitorar transferências realizadas ou agendadas;
• buscar transferências por período de criação;
• buscar transferências por período de efetivação;
• filtrar transferências por tipo;
• montar relatórios, conciliações ou dashboards financeiros;
• listar Pix recorrentes criados a partir da rota de transferência para outra conta ou chave Pix.

Parâmetros principais da requisição

Você pode combinar os filtros disponíveis para refinar a listagem de transferências.

• dateCreated[ge]: filtra transferências criadas a partir da data informada.
• dateCreated[le]: filtra transferências criadas até a data informada.
• transferDate[ge]: filtra transferências com data de efetivação a partir da data informada.
• transferDate[le]: filtra transferências com data de efetivação até a data informada.
• type: filtra pelo tipo da transferência.

As datas devem ser enviadas no formato YYYY-MM-DD.

Comportamento da listagem

O retorno segue o padrão de listas da API do Asaas, contendo informações como object, hasMore, totalCount, limit, offset e data.

Os resultados são retornados de forma paginada. Para percorrer todos os registros, utilize os campos de paginação retornados na resposta e avance a consulta enquanto hasMore for true.

Em integrações com alto volume de transferências, recomenda-se utilizar filtros por período, como dateCreated[ge], dateCreated[le], transferDate[ge] e transferDate[le], evitando consultas muito amplas.

Requisições do tipo GET devem ser enviadas sem corpo na requisição. Caso o body seja enviado preenchido, a API poderá retornar erro 403.

Exemplos de filtros

Filtrar por data de criação

GET https://api-sandbox.asaas.com/v3/transfers?dateCreated[ge]=2019-05-01&dateCreated[le]=2019-05-31

Filtrar por data de efetivação da transferência

GET https://api-sandbox.asaas.com/v3/transfers?transferDate[ge]=2019-05-01&transferDate[le]=2019-05-31

Filtrar por tipo da transferência

GET https://api-sandbox.asaas.com/v3/transfers?type=TED

Exemplo com paginação

GET https://api-sandbox.asaas.com/v3/transfers?dateCreated[ge]=2019-05-01&dateCreated[le]=2019-05-31&limit=10&offset=0

Exemplo de requisição

curl --request GET \
  --url 'https://api-sandbox.asaas.com/v3/transfers?dateCreated%5Bge%5D=2019-05-01&dateCreated%5Ble%5D=2019-05-31' \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Exemplo de resposta

{
  "object": "list",
  "hasMore": false,
  "totalCount": 2,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "object": "transfer",
      "id": "777eb7c8-b1a2-4356-8fd8-a1b0644b5282",
      "type": "BANK_ACCOUNT",
      "dateCreated": "2019-05-02",
      "value": 1000,
      "netValue": 0,
      "status": "PENDING",
      "transferFee": 0,
      "effectiveDate": "2019-05-02",
      "scheduleDate": "2019-05-02",
      "endToEndIdentifier": null,
      "authorized": true,
      "failReason": null,
      "externalReference": null,
      "transactionReceiptUrl": null,
      "operationType": "TED",
      "description": null,
      "recurring": null,
      "bankAccount": {
        "bank": {
          "ispb": null,
          "code": "001",
          "name": "Banco do Brasil"
        },
        "accountName": "Conta Banco do Brasil",
        "ownerName": "John Doe",
        "cpfCnpj": "***.143.689-**",
        "agency": "1263",
        "agencyDigit": "3",
        "account": "9999991",
        "accountDigit": "1",
        "pixAddressKey": null
      }
    }
  ]
}

Tratamento de erros

Caso a API retorne erro 400, revise os filtros enviados na requisição, especialmente o formato das datas e os parâmetros utilizados.

Caso a API retorne erro 401, valide se a chave de API foi informada corretamente no header access_token.

Caso a API retorne erro 403, verifique se a requisição GET foi enviada sem body. Chamadas de listagem devem conter apenas headers e query params.

Boas práticas de integração

Utilize filtros de data para reduzir o volume de dados retornados e melhorar a performance da consulta.

Ao implementar paginação, consulte os próximos registros enquanto hasMore for true, ajustando o offset conforme a quantidade de registros já retornados.

Evite executar consultas amplas e repetitivas sem necessidade. Para rotinas de conciliação, prefira buscar transferências por períodos específicos.

Em caso de timeout ou instabilidade de rede, antes de repetir a consulta, valide se a requisição anterior retornou dados ou se a falha ocorreu antes do processamento da API.