API de Contas - Consulta de Chave PIX
Download OpenAPI specification:Download
Implementamos um controle inteligente de consultas PIX para garantir a melhor experiência aos nossos clientes. Através de um sistema de "fichas", gerenciamos a quantidade de consultas que podem ser feitas por documento (CPF/CNPJ), mantendo um padrão mais rigoroso que o exigido pelo BACEN.
Sistema de Fichas
- Cada documento possui um limite de consultas por período
- O número de consultas permitidas varia conforme o tipo de pessoa
- O sistema recarrega automaticamente as consultas permitidas periodicamente
Consumo de Consultas
| Operação | Impacto no Limite | Observação |
|---|---|---|
| Consulta de Chave PIX | -1 ficha | Consumo padrão |
| Pagamento PIX | +1 ficha | Quando usado o endToEndId da consulta |
| Consulta com Falha | Variável | Valor configurável por ambiente |
Recuperação Automática
- O sistema recarrega automaticamente as consultas permitidas
- O limite máximo é sempre respeitado para garantir a estabilidade
- Diferentes limites para Pessoa Física e Jurídica
- Consulte a chave PIX (consome 1 ficha)
- Use o endToEndId retornado para fazer o pagamento
- A ficha é devolvida ao seu limite após o pagamento bem-sucedido
- Quando o limite é atingido, o documento é temporariamente bloqueado
- O tempo de bloqueio é configurado para garantir a melhor experiência
- O sistema retornará erro 429 quando o limite for excedido
- Sempre consulte a chave antes de fazer um pagamento
- Use o endToEndId retornado na consulta para o pagamento
- Monitore seu consumo de consultas
- Planeje suas operações considerando os limites
Para mais informações sobre o controle de requisições do BACEN, consulte a documentação oficial.
Consulta informações de uma chave PIX
Endpoint para consultar informações de uma chave PIX cadastrada no DICT.
Importante: Este endpoint está sujeito a um sistema de controle de fichas que:
- Consome 1 ficha por consulta bem-sucedida
- Consome fichas em caso de falha (valor configurável por ambiente)
- Devolve 1 ficha após pagamento bem-sucedido com endToEndId
- Retorna erro 429 quando o limite é atingido
Para mais detalhes sobre o sistema de fichas, consulte a seção "Sistema de Controle de Consultas PIX" acima.
Authorizations:
path Parameters
| key required | string Example: 12345678900 Chave PIX a ser consultada |
Responses
Response Schema: application/json
| name | string Nome do titular da chave |
| tradeName | string Nome fantasia do titular |
| keyType | string Tipo da chave PIX |
| key | string Valor da chave PIX (mascarado se for CPF) |
| document | string Documento do titular (mascarado) |
| ispb | string Código ISPB do banco |
| ispb_reduced_name | string Nome reduzido do banco |
| endToEndId | string Identificador único da transação que deve ser utilizado para baixar o saldo da ficha quando executado o endpoint de pagamento PIX. Este identificador é obtido através da consulta de chave e deve ser enviado como parâmetro opcional no endpoint postDictPix para garantir a baixa correta do saldo. |
Response samples
- 200
- 400
- 403
- 429
{- "name": "João da Silva",
- "tradeName": "João Comércio",
- "keyType": "CPF",
- "key": "123.456.789-00",
- "document": "123.456.789-00",
- "ispb": "00000000",
- "ispb_reduced_name": "BANCO DO BRASIL",
- "endToEndId": "E123456789012345678901234567890123"
}