Gerenciamento de Chaves Pix
Objetivo
Gerenciar chaves Pix da conta no DICT: listar, cadastrar, confirmar e-mail/telefone, consultar chave de terceiros (cash-out) e excluir.
Pré-requisito: Login da conta. Scopes baas.key-managements.read e baas.key-managements.write.
Tipos (key_type)
| Valor | Tipo | Regra |
|---|---|---|
0 | CPF | key = CPF do titular (11 dígitos) |
1 | CNPJ | key = CNPJ (14 dígitos) |
2 | OTP por e-mail; fluxo de confirmação | |
3 | Telefone | OTP por SMS; gateway pode prefixar +55 |
4 | EVP | Chave aleatória; omitir key |
CPF, CNPJ e EVP costumam ativar direto. E-mail e telefone retornam need_confirmation: true até concluir verificação.
Fluxo e-mail / telefone
- Criar (
POST /key-managements) comkey_type2 ou 3. - Código de verificação (
POST …/verification-code) comkey+coderecebido. - Confirmar cadastro (
POST …/{id}/store-after-verification) comidda chave; corpo vazio. Ativa a chave no DICT. - Se OTP expirar: Reenviar código (
POST …/resend-code) comkey, depois repita passos 2 e 3.
Para excluir qualquer chave ativa: Excluir (DELETE …/{id}).
Consultar (POST …/consult) é fluxo à parte: dados de chave de terceiro antes do pagamento Pix. Exige ao menos uma chave ativa na própria conta. Rate limit típico: 20 req/min.
Contrato HTTP: Listar chaves.
Endpoints
Listar
| Método | GET |
| Path | /api/v2/baas/key-managements |
Contrato: Listar chaves.
Autenticação
Bearer da conta, HMAC. Corpo [] na assinatura.
Regras de negócio
- Retorna chaves da conta com
id,key,key_type,status.
Criar
| Método | POST |
| Path | /api/v2/baas/key-managements |
Contrato: Criar chave.
Corpo mínimo
| Campo | Regra |
|---|---|
key_type | 0 a 4 |
key | Obrigatório exceto EVP (4) |
Regras de negócio
- Chave já ativa no DICT →
400. - E-mail/telefone: resposta com
need_confirmation: trueeidpara os passos seguintes.
Verification code
| Método | POST |
| Path | /api/v2/baas/key-managements/verification-code |
Contrato: Validar código.
Corpo
key (valor cadastrado) e code (OTP recebido).
Regras de negócio
- Código inválido ou expirado →
422. - Sucesso retorna
ide statusverified; ainda é necessário Confirmar cadastro.
Confirmar cadastro
| Método | POST |
| Path | /api/v2/baas/key-managements/{id}/store-after-verification |
Contrato: Confirmar após verificação.
Autenticação
Bearer da conta, HMAC. Corpo vazio {} ou sem body conforme ambiente.
Regras de negócio
{id}= identificador interno da chave (criação ou passo de verification-code).- Só após verification-code bem-sucedido; caso contrário
400. - Publica a chave como
activeno DICT para recebimento e cash-in.
Reenviar código
| Método | POST |
| Path | /api/v2/baas/key-managements/resend-code |
Contrato: Reenviar código.
Corpo
key da chave pendente.
Consultar
| Método | POST |
| Path | /api/v2/baas/key-managements/consult |
Contrato: Consultar no DICT.
Corpo
{ "key": "…" } da chave do favorecido.
Regras de negócio
- Use o retorno (
name,ispb,agency,account, etc.) no pagamento por chave sem alterar dados críticos.
Excluir
| Método | DELETE |
| Path | /api/v2/baas/key-managements/{id} |
Contrato: Excluir chave.
Regras de negócio
- Remove a chave do DICT para a conta. Chave em uso em cobranças pendentes pode ter restrições conforme produto.