Como excluir um usuário do DDA? – Celcoin

Resumo

Este artigo descreve como remover de forma definitiva o cadastro de um usuário no serviço DDA (Débito Direto Autorizado) por meio da API. A exclusão interrompe o recebimento de notificações de novos boletos para o CPF ou CNPJ informado e exige confirmação via Webhook. O artigo é destinado a desenvolvedores e equipes técnicas que integram o DDA à sua aplicação e precisam encerrar o cadastro de um usuário.

Regras explícitas

O que o serviço DDA permite na operação de exclusão:

Excluir um usuário (CPF ou CNPJ) que esteja atualmente cadastrado e ativo no DDA.
Receber confirmação oficial da exclusão por meio do Webhook com evento deletion.

O que o serviço DDA NÃO permite na operação de exclusão:

Reverter uma exclusão já confirmada. A exclusão de um usuário do DDA é definitiva.
Reativar o cadastro do mesmo CPF ou CNPJ sem refazer o processo de adesão do zero.
Interromper o envio de notificações de novos boletos antes da confirmação do evento deletion via Webhook. Enquanto o Webhook não for recebido, o cadastro permanece ativo e o usuário continua recebendo notificações.

Pontos críticos de atenção:

Caso a chamada de exclusão à API falhe (erro de processamento no retorno imediato), o cadastro do usuário permanecerá ativo no DDA. Nesse cenário, a exclusão não ocorreu e a chamada precisa ser refeita.
Apenas o recebimento do Webhook com evento deletion confirma oficialmente que o usuário foi excluído do DDA. O retorno imediato da requisição HTTP não é, por si só, garantia de exclusão concluída.

Passo a passo

Passo 1: Enviar a requisição de exclusão para a API do DDA

A aplicação integradora deve chamar o endpoint "Excluir usuário" da API do DDA, informando no corpo ou nos parâmetros da requisição o CPF (para Pessoa Física) ou o CNPJ (para Pessoa Jurídica) do usuário a ser removido. Os detalhes técnicos do endpoint (método HTTP, formato do payload e autenticação) estão descritos na documentação técnica da API do DDA.

Passo 2: Verificar o retorno imediato da requisição de exclusão

Após enviar a requisição de exclusão ao endpoint "Excluir usuário", a aplicação integradora deve inspecionar o retorno HTTP imediato para garantir que não houve erro de processamento. Se a chamada falhar (por exemplo, retorno com código de erro), o cadastro do usuário permanecerá ativo no DDA e a exclusão precisará ser tentada novamente. Um retorno bem-sucedido nesta etapa indica apenas que a exclusão foi aceita para processamento — ainda não é a confirmação oficial.

Passo 3: Aguardar a confirmação oficial via Webhook (evento `deletion`)

A confirmação oficial de que o usuário foi excluído do DDA ocorre por meio de um Webhook enviado pelo serviço DDA para a URL configurada na aplicação integradora, com o evento deletion. A aplicação integradora deve estar preparada para receber e tratar esse evento. Enquanto o Webhook do evento deletion não for recebido, a exclusão não está oficialmente concluída.

Passo 4: Tratar a interrupção das notificações de novos boletos

Somente após o recebimento do Webhook com evento deletion, o serviço DDA interrompe o envio de notificações de novos boletos para o CPF ou CNPJ excluído. A aplicação integradora deve atualizar o status do usuário em sua própria base de dados apenas após essa confirmação, para que a experiência do usuário fique coerente com a desativação efetiva do serviço.

Passo 5: Validar o status final da operação

Recomenda-se que a aplicação integradora valide o status final da operação de exclusão antes de comunicar ao usuário que o serviço foi desativado. A validação consiste em confirmar o recebimento do Webhook com evento deletion para o CPF ou CNPJ correspondente. Isso evita que o usuário seja informado da desativação antes que ela tenha sido efetivada pelo DDA.

Para mais informações acesse a nossa documentação.