🔐 Jornada: Gerenciamento de Credenciais da API de QRCodes

Este guia apresenta o fluxo completo para gerenciar credenciais da API de QRCodes, permitindo que contas realizem operações PIX através de QR Codes e cobranças.

📋 Visão Geral

Nesta jornada, você aprenderá a:

✅ Criar credenciais da API de QRCodes automaticamente
✅ Sincronizar dados atualizados da conta
✅ Deletar credenciais quando necessário

🎯 Cenário de Uso

Imagine que você precisa:

Habilitar uma conta para usar a API de QRCodes (QR Codes e Cobranças)
Manter as credenciais sincronizadas quando os dados da conta mudarem
Remover credenciais quando a conta for encerrada ou desativada

💡 Conceito Importante: Geração Automática

Diferente de outros endpoints, os endpoints de PIX Manager Credentials não requerem body na requisição. Todos os dados necessários são:

🔍 Buscados automaticamente
🔐 Gerados automaticamente (clientId e clientSecret)
✅ Sempre consistentes e atualizados

Isso garante que:

✨ Menos código no frontend
🎯 Dados sempre corretos
🚀 Melhor experiência do desenvolvedor

🔄 Fluxo Completo

┌──────────────────────────┐
│ 1. Criar Credencial      │
│    POST /accounts/:id/   │
│    pix-manager-credentials│
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│ Credencial Criada        │
│ Conta habilitada para    │
│ usar API de QRCodes      │
└────────────┬─────────────┘
             │
             │ Tempo passa...
             │ Dados da pessoa mudam
             │ (novo email, telefone, etc)
             │
             ▼
┌──────────────────────────┐
│ 2. Atualizar Pessoa      │
│    PUT /people/:id       │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│ 3. Sincronizar Credencial│
│    PUT /accounts/:id/    │
│    pix-manager-credentials│
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│ Credencial Atualizada    │
│ API de QRCodes com dados │
│ mais recentes            │
└────────────┬─────────────┘
             │
             │ Conta será encerrada
             │
             ▼
┌──────────────────────────┐
│ 4. Deletar Credencial    │
│    DELETE /accounts/:id/ │
│    pix-manager-credentials│
│    /:clientId            │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│ Credencial Removida      │
│ Conta não pode mais usar │
│ API de QRCodes           │
└──────────────────────────┘

📝 Passo 1: Criar Credencial

Endpoint

POST /accounts/:id/pix-manager-credentials

Requisição

Importante: Não é necessário enviar body! Apenas o accountId na URL.

curl -X POST "https://api.bancodigital.com/accounts/123/pix-manager-credentials" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json"

Resposta (201 Created)

{
  "clientId": "00011234567890012345678900",
  "clientSecret": "abc123def456ghi789jkl012mno345pq",
  "pixKey": "00020126360014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426655440000",
  "pixKeyCreated": true
}

Campos da Resposta:

clientId (string): Client ID criado para o PIX Manager
clientSecret (string, opcional): Client secret - só é retornado na criação
pixKey (string): Chave PIX (EVP) associada à conta
pixKeyCreated (boolean): Indica se a chave PIX foi criada nesta requisição

Guarde o clientSecret!

O clientSecret só é retornado na criação. Guarde-o em local seguro, pois será necessário para autenticar na API de QRCodes.

Sobre a chave PIX

A resposta inclui a pixKey (chave PIX no formato EVP) associada à conta. O campo pixKeyCreated indica se a chave foi criada durante esta requisição (true) ou se já existia anteriormente (false).

Possíveis Erros

400 - Bad Request

{
  "type": "https://httpstatuses.com/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Endereço principal não encontrado para a conta"
}

Causa: A conta não possui:

Endereço principal cadastrado, ou
Email principal cadastrado, ou
Telefone principal cadastrado

Solução: Cadastre os dados faltantes antes de criar a credencial.

404 - Not Found

{
  "type": "https://httpstatuses.com/404",
  "title": "Not Found",
  "status": 404,
  "detail": "Conta não encontrada"
}

Causa: O accountId não existe ou a conta está fechada.

📝 Passo 2: Sincronizar Credencial (Update)

Quando usar?

Use este endpoint quando os dados da pessoa forem atualizados e você precisar sincronizar com a API de QRCodes:

✉️ Email foi alterado
📱 Telefone foi alterado
🏠 Endereço foi atualizado

Fluxo Recomendado

1. Atualizar dados da pessoa
   PUT /people/:id
   {
     "email": "[email protected]",
     "phone": "11988887777"
   }

2. Sincronizar credencial da API de QRCodes
   PUT /accounts/:id/pix-manager-credentials
   (sem body - dados são buscados automaticamente)

Endpoint

PUT /accounts/:id/pix-manager-credentials

Requisição

Importante: Não é necessário enviar body! Os dados atualizados são buscados automaticamente.

curl -X PUT "https://api.bancodigital.com/accounts/123/pix-manager-credentials" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json"

Resposta (200 OK)

{
  "message": "Credencial da API de QRCodes atualizada com sucesso"
}

Exemplo Completo

# 1. Atualizar email da pessoa
curl -X PUT "https://api.bancodigital.com/people/456" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

# 2. Sincronizar credencial (sem body!)
curl -X PUT "https://api.bancodigital.com/accounts/123/pix-manager-credentials" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json"

# Resposta:
# {
#   "message": "Credencial da API de QRCodes atualizada com sucesso"
# }

📝 Passo 3: Deletar Credencial

Quando usar?

Use este endpoint quando:

🚫 A conta será encerrada
⛔ O cliente não usará mais a API de QRCodes
🔒 Por questões de segurança, as credenciais precisam ser revogadas

Endpoint

DELETE /accounts/:id/pix-manager-credentials/:clientId

Requisição

curl -X DELETE "https://api.bancodigital.com/accounts/123/pix-manager-credentials/00011234567890012345678900" \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta (200 OK)

{
  "message": "Credencial da API de QRCodes deletada com sucesso"
}

Possíveis Erros

404 - Not Found

{
  "type": "https://httpstatuses.com/404",
  "title": "Not Found",
  "status": 404,
  "detail": "Conta não encontrada"
}

503 - Service Unavailable

{
  "type": "https://httpstatuses.com/503",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Falha ao deletar credencial na API de QRCodes"
}

Causa: O serviço está indisponível ou a credencial não existe.

🔐 Segurança

Autenticação

Todos os endpoints requerem Bearer Token JWT:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Permissões

O usuário autenticado só pode:

✅ Criar credenciais da API de QRCodes para suas próprias contas
✅ Atualizar credenciais da API de QRCodes de suas próprias contas
✅ Deletar credenciais da API de QRCodes de suas próprias contas

Request ID

Todas as requisições incluem um x-request-id para rastreamento distribuído:

x-request-id: 550e8400-e29b-41d4-a716-446655440000

📊 Comparação: Sistema Legado vs Novo

Aspecto	Sistema Legado	Sistema Novo
Body da Requisição	Todos os dados no body	Sem body (geração automática)
Responsabilidade	Frontend coleta dados	Backend busca dados
Consistência	Pode ter dados desatualizados	Sempre dados atualizados
Complexidade Frontend	Alta	Baixa
Erros de Validação	Frequentes	Raros
Manutenção	Difícil	Fácil

✅ Checklist de Implementação

Antes de criar uma credencial, certifique-se que a conta possui:

Endereço principal cadastrado e ativo
Email principal cadastrado e ativo
Telefone principal cadastrado e ativo
Dados da pessoa completos (nome, documento, tipo)
Conta ativa (não fechada)

🚨 Troubleshooting

Erro: "Endereço principal não encontrado"

Problema: A conta não possui endereço principal.

Solução:

# 1. Cadastrar endereço
POST /people/:id/addresses
{
  "address": "Avenida Paulista",
  "number": "1000",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "zipCode": "01310100",
  "main": true
}

# 2. Tentar criar credencial novamente
POST /accounts/:id/pix-manager-credentials

Erro: "Email ou telefone principal não encontrado"

Problema: A conta não possui email ou telefone principal.

Solução:

# 1. Cadastrar contatos
POST /people/:id/contacts
{
  "type": "EMAIL",
  "contact": "[email protected]",
  "main": true
}

POST /people/:id/contacts
{
  "type": "PHONE",
  "contact": "11999999999",
  "main": true
}

# 2. Tentar criar credencial novamente
POST /accounts/:id/pix-manager-credentials

Erro 503: "Falha ao criar credencial na API de QRCodes"

Problema: O serviço está indisponível ou retornou erro.

Solução:

Tente novamente em alguns minutos
Se o problema persistir, contate o suporte

📚 Recursos Adicionais

💬 Suporte

Precisa de ajuda? Entre em contato:

📧 Email: [email protected]
📖 Documentação: https://docs.bancodigital.com
🐛 Reportar Bug: https://github.com/seu-repo/issues

📋 Visão Geral​

🎯 Cenário de Uso​

💡 Conceito Importante: Geração Automática​

🔄 Fluxo Completo​

📝 Passo 1: Criar Credencial​

Endpoint​

Requisição​

Resposta (201 Created)​

Possíveis Erros​

📝 Passo 2: Sincronizar Credencial (Update)​

Quando usar?​

Fluxo Recomendado​

Endpoint​

Requisição​

Resposta (200 OK)​

Exemplo Completo​

📝 Passo 3: Deletar Credencial​

Quando usar?​

Endpoint​

Requisição​

Resposta (200 OK)​

Possíveis Erros​

🔐 Segurança​

Autenticação​

Permissões​

Request ID​

📊 Comparação: Sistema Legado vs Novo​

✅ Checklist de Implementação​

🚨 Troubleshooting​

Erro: "Endereço principal não encontrado"​

Erro: "Email ou telefone principal não encontrado"​

Erro 503: "Falha ao criar credencial na API de QRCodes"​

📚 Recursos Adicionais​

💬 Suporte​

📋 Visão Geral

🎯 Cenário de Uso

💡 Conceito Importante: Geração Automática

🔄 Fluxo Completo

📝 Passo 1: Criar Credencial

Endpoint

Requisição

Resposta (201 Created)

Possíveis Erros

📝 Passo 2: Sincronizar Credencial (Update)

Quando usar?

Fluxo Recomendado

Endpoint

Requisição

Resposta (200 OK)

Exemplo Completo

📝 Passo 3: Deletar Credencial

Quando usar?

Endpoint

Requisição

Resposta (200 OK)

Possíveis Erros

🔐 Segurança

Autenticação

Permissões

Request ID

📊 Comparação: Sistema Legado vs Novo

✅ Checklist de Implementação

🚨 Troubleshooting

Erro: "Endereço principal não encontrado"

Erro: "Email ou telefone principal não encontrado"

Erro 503: "Falha ao criar credencial na API de QRCodes"

📚 Recursos Adicionais

💬 Suporte