Chaves Pix

Consultar uma chave Pix de uma conta

Consulte chaves Pix cadastradas na sua conta ou busque informações sobre qualquer chave Pix no sistema.

Visão Geral

Através deste módulo você pode:

Listar todas as chaves Pix da conta
Consultar detalhes de uma chave específica
Buscar informações sobre qualquer chave Pix no sistema

Autenticação

Todas as rotas de consulta de chaves requerem:

Token JWT no header Authorization (autenticação auth:api)
Assinatura HMAC no header X-Signature (middleware hmac-signature)

Endpoints Disponíveis

Listar Chaves da Conta

GET /api/v2/baas/key-managements

Lista todas as chaves Pix cadastradas na conta autenticada.

Headers

Campo	Tipo	Obrigatório	Descrição
`Authorization`	string	Sim	Token JWT (`Bearer {token}`)
`X-Signature`	string	Sim	Assinatura HMAC da requisição
`Accept`	string	Sim	`application/json`

Resposta de Sucesso (200)

{
  "data": [
    {
      "id": 123,
      "key": "[email protected]",
      "key_type": 2,
      "status": 1,
      "created_at": "2025-01-10 10:00:00",
      "updated_at": "2025-01-15 14:30:00"
    },
    {
      "id": 124,
      "key": "550e8400-e29b-41d4-a716-446655440000",
      "key_type": 4,
      "status": 3,
      "created_at": "2025-01-12 11:00:00",
      "updated_at": "2025-01-12 11:00:00"
    }
  ]
}

Campos da Resposta

Campo	Tipo	Descrição
`data`	array	Lista de chaves Pix
`data[].id`	integer	ID da chave
`data[].key`	string	Valor da chave Pix
`data[].key_type`	integer	Tipo da chave (0-4)
`data[].status`	integer	Código do status: `0` = Em Análise, `1` = Ativo, `2` = Inativo, `3` = Verificado
`data[].created_at`	string	Data de criação
`data[].updated_at`	string	Data de atualização

Excluir Chave Específica

DELETE /api/v2/baas/key-managements/{id}

Excluir os detalhes de uma chave Pix específica da conta.

Parâmetros de Rota

Campo	Tipo	Obrigatório	Descrição
`id`	integer	Sim	ID da chave Pix

Headers

Campo	Tipo	Obrigatório	Descrição
`Authorization`	string	Sim	Token JWT (`Bearer {token}`)
`X-Signature`	string	Sim	Assinatura HMAC da requisição
`Accept`	string	Sim	`application/json`

Resposta de Sucesso (204)

{
  //No content
}

Consultar Informações de Qualquer Chave Pix

POST /api/v2/baas/key-managements/consult

Consulta informações sobre qualquer chave Pix no sistema, incluindo dados do portador. Esse endpoint possui um limite de acessos de 20 requisições por minuto por cliente

Headers

Campo	Tipo	Obrigatório	Descrição
`Authorization`	string	Sim	Token JWT (`Bearer {token}`)
`X-Signature`	string	Sim	Assinatura HMAC da requisição
`Content-Type`	string	Sim	`application/json`
`Accept`	string	Sim	`application/json`

Campos Obrigatórios

`key` (string, obrigatório)

Chave Pix a ser consultada.

Validações:
- Obrigatório
- Deve ser uma chave Pix válida
Exemplo:
```
"key": "[email protected]"
```

Exemplo de Requisição

{
  "key": "[email protected]"
}

Resposta de Sucesso (200)

{
  "key": "[email protected]",
  "key_type": 2,
  "ispb": "12345678",
  "agency": "0001",
  "account": "12345-6",
  "account_type": 1,
  "person_type": 1,
  "document": "123***8901",
  "name": "João da Silva Santos",
  "favorite": false,
  "bank_name": "Banco Exemplo"
}

Campos da Resposta

Campo	Tipo	Descrição
`key`	string	Valor da chave Pix consultada
`key_type`	integer	Tipo da chave (0-4)
`ispb`	string	Código ISPB do banco
`agency`	string	Agência bancária
`account`	string	Número da conta
`account_type`	integer	Tipo de conta (1=corrente, 2=poupança)
`person_type`	integer	Tipo de pessoa (1=física, 2=jurídica)
`document`	string	Documento mascarado do beneficiário
`name`	string	Nome do beneficiário
`favorite`	boolean	Indica se é favorito
`bank_name`	string	Nome do banco

Respostas de Erro

400 - Chave Não Encontrada

{
  "message": "Key not found"
}

422 - Erro de Validação

{
  "message": {
    "key": [
      "O campo key é obrigatório."
    ]
  }
}

422 - Nenhuma Chave Cadastrada

{
  "message": "You don't have any key to be consult"
}

401 - Não Autenticado

{
  "message": "Unauthorized"
}

403 - Acesso Negado

{
  "message": "Forbidden"
}

429 - Rate Limit Excedido

{
  "message": "Too Many Requests"
}

Regras de Negócio

Consulta de Chaves Próprias

Use GET /key-managements para listar suas próprias chaves
Use GET /key-managements/{id} para consultar uma chave específica sua

Consulta de Qualquer Chave

Use POST /key-managements/consult para consultar qualquer chave Pix
Retorna informações do beneficiário da chave
O documento é mascarado para privacidade
Útil para validar chaves antes de realizar pagamentos

Privacidade

Documentos são mascarados na resposta (ex: 123***8901)
Apenas informações necessárias são retornadas
Dados sensíveis são protegidos

Próximos Passos

Após consultar chaves Pix, você pode:

Criar uma nova Chave se necessário
Excluir uma Chave se não for mais utilizada
Realizar Pagamentos usando as chaves consultadas

Gerenciamento de Chaves Pix

Cadastro, verificação, consulta DICT e exclusão de chaves Pix da conta.

Criar uma chave Pix

Crie e cadastre chaves Pix para receber pagamentos instantâneos. Você pode criar diferentes tipos de chaves: CPF, CNPJ, email, telefone ou chave aleatória (EVP).

Consultar uma chave Pix de uma conta

key (string, obrigatório)

`key` (string, obrigatório)