Endpoint responsável por listar as chaves Pix cadastradas na conta Asaas autenticada.

A listagem pode retornar todas as chaves Pix da conta ou apenas as chaves que estão em um ou mais status específicos.

Esse endpoint é útil para integrações que precisam consultar as chaves existentes antes de criar, exibir, validar ou remover uma chave Pix.

Quando utilizar

Utilize este endpoint quando sua integração precisar:

• listar as chaves Pix cadastradas na conta;
• verificar se já existe uma chave Pix ativa;
• consultar chaves que ainda aguardam ativação;
• identificar chaves em processo de exclusão;
• validar se uma chave pode ser removida;
• exibir chaves Pix disponíveis em um painel administrativo;
• sincronizar as chaves Pix da conta com o sistema de origem;
• consultar o payload e a imagem do QR Code associados à chave, quando retornados.

Esse endpoint realiza apenas a consulta das chaves. Ele não cria, ativa, atualiza ou remove chaves Pix.

Parâmetros de consulta

Este endpoint aceita filtros opcionais por paginação e status.

Status disponíveis

Os filtros status e statusList aceitam os seguintes valores:

Exemplos de filtros

Listar todas as chaves

Para listar todas as chaves Pix da conta, omita os filtros de status.

GET https://api.asaas.com/v3/pix/addressKeys

Listar chaves por um único status

Para listar apenas as chaves com um determinado status, informe o parâmetro status.

GET https://api.asaas.com/v3/pix/addressKeys?status=ACTIVE

Listar chaves por múltiplos status

Para listar chaves com diferentes status, informe o parâmetro statusList com os status separados por vírgula.

GET https://api.asaas.com/v3/pix/addressKeys?statusList=ACTIVE,AWAITING_DELETION

Listar chaves com paginação

Para controlar a quantidade de registros retornados, utilize limit e offset.

GET https://api.asaas.com/v3/pix/addressKeys?limit=50&offset=0

Exemplo de chamada

curl --request GET \
  --url 'https://api-sandbox.asaas.com/v3/pix/addressKeys?status=ACTIVE&limit=100&offset=0' \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Exemplo de resposta

{
  "data": [
    {
      "id": "a33047b1-fb19-4b68-9373-a7ba8a8162aa",
      "key": "b6295ee1-f054-47d1-9e90-ee57b74f60d9",
      "type": "EVP",
      "status": "ACTIVE",
      "dateCreated": "2022-02-07 17:17:48",
      "canBeDeleted": true,
      "cannotBeDeletedReason": null,
      "qrCode": {
        "encodedImage": "QRCODE IMAGE IN BASE64",
        "payload": "00020126580014br.gov.bcb.pix0136a9fe43bc-164d-44d1-91c2-2f9b4d6956e95204000053039865802BR5925Joao da Silva6009Joinville62290525JOAOSILVA00000055ASA6304E62B"
      }
    }
  ]
}

Principais campos da resposta

Comportamentos importantes

Ao utilizar este endpoint, considere que:

• a listagem retorna apenas chaves Pix vinculadas à conta autenticada;
• o retorno pode ser filtrado por um único status ou por múltiplos status;
• o parâmetro limit possui valor máximo de 100;
• para contas com muitas chaves, utilize paginação com offset e limit;
• chaves em status transitórios podem mudar de estado após nova consulta;
• o campo qrCode pode conter informações úteis para exibição ou pagamento via Pix;
• este endpoint não altera o estado das chaves listadas;
• chamadas GET devem ser realizadas sem body.

Paginação

Para evitar respostas muito grandes, utilize paginação sempre que sua integração listar chaves de forma recorrente ou em contas com alto volume de registros.

Exemplo de paginação:

Primeira página:  limit=100&offset=0
Segunda página:   limit=100&offset=100
Terceira página:  limit=100&offset=200

Continue incrementando o offset até que não existam mais registros a serem processados.

Erros comuns

Alguns erros comuns ao utilizar este endpoint incluem:

Boas práticas

Ao implementar a listagem de chaves Pix, recomenda-se:

• utilizar filtros por status quando não for necessário consultar todas as chaves;
• aplicar paginação com limit e offset;
• não enviar body em requisições GET;
• validar se statusList está no formato correto, com status separados por vírgula;
• armazenar o id da chave caso sua aplicação precise consultar ou remover a chave posteriormente;
• validar canBeDeleted antes de tentar excluir uma chave Pix;
• tratar chaves em status transitórios com nova consulta antes de executar ações críticas;
• evitar consultas desnecessárias em intervalos muito curtos;
• proteger dados retornados, como chave Pix e payload do QR Code.

Impactos operacionais

A listagem de chaves Pix pode ser utilizada em fluxos administrativos e operacionais da integração.

Alguns impactos importantes:

• uma chave com status ACTIVE pode ser utilizada em operações Pix;
• uma chave em AWAITING_ACTIVATION pode ainda não estar pronta para uso;
• uma chave em AWAITING_DELETION pode não estar disponível para novas operações;
• uma chave com ERROR pode exigir análise antes de ser utilizada;
• o uso incorreto de chaves inativas ou removidas pode causar falhas em fluxos de cobrança ou pagamento Pix;
• consultas sem paginação podem dificultar o processamento em contas com muitas chaves.

Por isso, utilize os filtros e a paginação de forma adequada ao volume e ao objetivo da integração.

Conteúdos relacionados

Consulte também:

• Criar chave Pix;
• Recuperar chave Pix;
• Remover chave Pix;
• Criar QR Code estático;
• Pagar um QR Code;
• Webhooks para Pix;
• O que pode ser testado em Sandbox.