Consultar Chave Pix

Esta documentação detalha o recurso de consulta de titularidade de uma chave Pix a partir dos dados da própria chave. Com ele, você consegue identificar o destinatário antes de realizar uma transferência via Pix.

A API aplica dois mecanismos independentes de controle de uso: o Rate Limit, que limita a frequência de requisições por minuto, e o Token Bucket, que controla o volume acumulado de consultas ao longo do tempo. Ambos precisam ter saldo disponível para que uma consulta seja realizada com sucesso.

RateLimit

• A consulta é limitada à 5 requests por minuto (por conta Asaas).
• Caso o valor seja ultrapassado, as consultas serão temporariamente bloqueadas.

TokenBucket

O TokenBucket é um mecanismo de créditos disponibilizados para consultas e transações utilizando chaves Pix. Ele atua como uma camada de proteção para garantir uma utilização saudável do mecanismo de consultas, mantendo a performance e a disponibilidade do serviço. Quando as fichas se esgotam, novas consultas são bloqueadas até que o balde seja reabastecido.

TokenBucket para Pessoa Física

Limites de Fichas
Tamanho máximo do balde para consultas de telefone celular, e-mail, CPF, CNPJ ou chave aleatória: 60 fichas.

Gestão de Fichas
Decréscimo de Fichas:

• 1 ficha é descontada por consulta válida de qualquer chave.
• 10 fichas são descontadas por consulta inválida de qualquer chave, por balde.

Acréscimo de Fichas:

• 1 ficha é acrescentada por consulta de qualquer chave após o recebimento da ordem de pagamento pelo SPI, por balde.

Incremento Temporal:

• 2 fichas são acrescidas a cada minuto em cada balde.

TokenBucket para Pessoa Jurídica

Limites de Fichas

Tamanho máximo do balde para consultas de telefone celular, e-mail, CPF, CNPJ ou chave aleatória: 300 fichas.

Gestão de Fichas
Decréscimo de Fichas:

• 1 ficha é descontada por consulta válida de qualquer chave.
• 15 fichas são descontadas por consulta inválida de qualquer chave, por balde.

Acréscimo de Fichas:

• 1 ficha é acrescentada por consulta de qualquer chave após o recebimento da ordem de pagamento pelo SPI, por balde.

Incremento Temporal:

• 2 fichas são acrescidas a cada minuto em cada balde.

Consultando o saldo de fichas

Antes de realizar consultas em volume, você pode verificar quantas fichas estão disponíveis no seu balde em tempo real.

GET /pix/tokenBucket/addressKey
Confira a referência completa deste endpoint

Isso é especialmente útil para evitar penalidades por consultas bloqueadas, se o balde estiver com poucas fichas, aguarde o incremento temporal (+2 fichas/min) antes de prosseguir.

Realizando a consulta chave pix

Enums aceitos para o type

CPF - Buscar dados de titular por chave CPF
CNPJ - Buscar dados de titular por chave CNPJ
EMAIL - Buscar dados de titular por chave de e-mail
PHONE - Buscar dados de titular por chave de telefone
EVP - Buscar dados de titular por chave EVP (aleatória)

Exemplo do endpoint

GET /pix/addressKeys/external?type=&key=
Confira a referência completa deste endpoint

🚧

Atenção

Atualmente em ambiente sanbdox é possível consultar apenas a chave pix 47996515839.

O campo cpfCnpj, sempre retornará de forma mascarada, por exemplo: "***.202.745-**"