Exclusão de Conta

O módulo de exclusão de conta permite encerrar contas digitais de forma segura, com validações obrigatórias para garantir que não há saldo ou transações pendentes. Este módulo está disponível após a conclusão do onboarding e criação da conta.

Visão Geral

Através deste módulo você pode:

• Encerrar contas digitais de forma segura
• Validar condições antes da exclusão
• Garantir que não há saldo ou transações pendentes
• Manter integridade dos dados históricos

Autenticação

Todas as rotas de exclusão de conta requerem:

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

Endpoints Disponíveis

Excluir Conta

POST /api/v2/baas/accounts/close

Encerra uma conta digital de forma permanente. A exclusão só é permitida quando a conta não possui saldo e não há transações pendentes.

Headers

Validações Obrigatórias

Antes de permitir a exclusão, o sistema valida automaticamente:

1. Saldo Zero: A conta não pode ter saldo disponível ou bloqueado
2. Sem Transações Pendentes: Não pode haver transações em processamento
3. Conta Ativa: A conta deve estar ativa (não pode estar já encerrada)
4. Permissão do Seller: O seller deve ter permissão para encerrar a conta
5. Autenticação Válida: O token JWT deve ser válido e não expirado

Exemplo de Requisição

POST /api/v2/baas/accounts/close

Resposta de Sucesso (200)

{
  "message": "Account closed successfully",
  "account_id": 456
}

Campos da Resposta

Respostas de Erro

400 - Conta com Saldo

{
  "message": "Account cannot be closed because it has balance. Please withdraw all funds before closing the account.",
  "error_code": "ACCOUNT_HAS_BALANCE",
  "balance": 10000,
  "blocked_balance": "50.00"
}

400 - Transações Pendentes

{
  "message": "Account cannot be closed because it has pending transactions. Please wait for all transactions to complete.",
  "error_code": "ACCOUNT_HAS_PENDING_TRANSACTIONS",
  "pending_count": 3
}

400 - Conta Já Encerrada

{
  "message": "Account is already closed.",
  "error_code": "ACCOUNT_ALREADY_CLOSED",
  "closed_at": "2025-01-10 10:00:00"
}

400 - Conta Não Encontrada

{
  "message": "Account not found.",
  "error_code": "ACCOUNT_NOT_FOUND"
}

400 - Conta Primária

{
  "message": "Primary account cannot be closed. Please set another account as primary first.",
  "error_code": "ACCOUNT_IS_PRIMARY"
}

401 - Não Autenticado

{
  "message": "Unauthorized"
}

403 - Acesso Negado

{
  "message": "Forbidden. You do not have permission to close this account.",
  "error_code": "FORBIDDEN_CLOSE_ACCOUNT"
}

422 - Erro de Validação

{
  "message": {
    "deregistration_reason": [
      "O campo deregistration_reason é obrigatório.",
      "O campo deregistration_reason deve ser um dos valores: ec_cancelled_inactive, ec_cancelled_by_user, ec_cancelled_by_seller."
    ]
  }
}

429 - Rate Limit Excedido

{
  "message": "Too Many Requests"
}

500 - Erro Interno do Servidor

{
  "message": "Server Error",
  "error_code": "INTERNAL_SERVER_ERROR"
}

Regras de Segurança e Validações

Validações Obrigatórias

1. Saldo Zero

• Regra: A conta não pode ter saldo disponível ou bloqueado
• Validação: O sistema verifica ambos os saldos antes de permitir a exclusão
• Ação: Se houver saldo, a exclusão é bloqueada e retorna erro ACCOUNT_HAS_BALANCE

2. Sem Transações Pendentes

• Regra: Não pode haver transações em processamento ou pendentes
• Validação: O sistema verifica todas as transações com status pending ou processing
• Ação: Se houver transações pendentes, a exclusão é bloqueada e retorna erro ACCOUNT_HAS_PENDING_TRANSACTIONS

3. Conta Ativa

• Regra: A conta deve estar ativa (não pode estar já encerrada)
• Validação: O sistema verifica o status da conta
• Ação: Se a conta já estiver encerrada, retorna erro ACCOUNT_ALREADY_CLOSED

4. Permissão do Seller

• Regra: O seller deve ter permissão para encerrar a conta
• Validação: O sistema verifica se o token corresponde à conta do integrador
• Ação: Se não houver permissão, retorna erro FORBIDDEN_CLOSE_ACCOUNT

5. Conta Primária

• Regra: Se o cliente tiver múltiplas contas, a conta primária não pode ser encerrada diretamente
• Validação: O sistema verifica se a conta é primária e se existem outras contas
• Ação: Se for primária e houver outras contas, uma delas é automaticamente definida como primária antes do encerramento

Comportamento em Caso de Conta com Saldo

Quando uma conta possui saldo:

1. Erro Retornado: ACCOUNT_HAS_BALANCE (400)
2. Informações Fornecidas:
   • Saldo total atual
   • Saldo disponível
   • Saldo bloqueado
3. Ação Necessária: O cliente deve sacar ou transferir todo o saldo antes de tentar novamente

Comportamento em Caso de Transações Pendentes

Quando uma conta possui transações pendentes:

1. Erro Retornado: ACCOUNT_HAS_PENDING_TRANSACTIONS (400)
2. Informações Fornecidas:
   • Número de transações pendentes
3. Ação Necessária: O cliente deve aguardar a conclusão de todas as transações antes de tentar novamente

Motivos de Encerramento

Os motivos de encerramento são registrados para fins de auditoria e compliance:

• ec_cancelled_inactive: Conta cancelada por inatividade
• ec_cancelled_by_user: Conta cancelada pelo próprio usuário
• ec_cancelled_by_seller: Conta cancelada pelo seller/parceiro

Fluxo Recomendado

Antes de Encerrar a Conta

1. Verificar Saldo: Consulte o saldo atual usando GET /api/v2/baas/balances
2. Sacar Saldo: Se houver saldo, realize uma transferência ou saque
3. Verificar Transações: Consulte o extrato para verificar transações pendentes
4. Aguardar Conclusão: Aguarde todas as transações pendentes serem concluídas
5. Verificar Novamente: Confirme que não há mais saldo ou transações pendentes

Processo de Encerramento

1. Enviar Requisição: Envie a requisição POST com o motivo de encerramento
2. Aguardar Validação: O sistema valida todas as condições
3. Verificar Resposta: Se houver erro, corrija a situação e tente novamente
4. Confirmar Encerramento: Se bem-sucedido, a conta será encerrada permanentemente

Exemplo Completo

Cenário: Encerrar Conta sem Saldo

1. Verificar Saldo:

GET /api/v2/baas/balances

Resposta:

{
  "id": 123,
  "balance": 000,
  "blocked_balance": 000,
  "account_id": 456,
  "last_change": "2025-01-15 10:00:00"
}

2. Verificar Transações Pendentes:

GET /api/v2/baas/statements?status=pending

Resposta:

{
  "data": [],
  "pagination": {
    "current_page": 0,
    "per_page": 100,
    "total": 0,
    "has_more": false
  }
}

3. Encerrar Conta:

POST /api/v2/baas/accounts/close

Corpo:

{
  "deregistration_reason": "ec_cancelled_by_user"
}

Resposta:

{
  "message": "Account closed successfully",
  "account_id": 456,
  "closed_at": "2025-01-15 14:30:00",
  "deregistration_reason": "ec_cancelled_by_user"
}

Próximos Passos

Após encerrar uma conta, você pode:

1. Listar Contas para verificar outras contas do cliente
2. Criação de Contas para criar novas contas se necessário