Evite Cobranças e Créditos em Dobro

Um cliente pode pagar uma vez e receber dois créditos na loja, dois e-mails de boas-vindas ou dois pedidos. Isso pode acontecer porque um serviço de pagamento, agenda, formulário ou entrega manda um aviso automático ao seu app quando algo ocorre. O nome técnico desse aviso enviado de um serviço para outro é webhook. Ele é útil porque o app consegue reagir sem que alguém consulte o outro serviço manualmente, mas toda reação precisa aceitar repetições com segurança.

Um aviso repetido não significa automaticamente que alguém está atacando seu app. O serviço remetente pode ter esperado uma resposta, perdido a conexão ou voltado a funcionar depois de uma manutenção. Então, manda o aviso novamente porque não sabe se a primeira cópia funcionou. Seu app deve tratar a nova cópia como um lembrete para confirmar o resultado existente, não como permissão para cobrar, creditar, reservar, enviar e-mail ou alterar o cadastro outra vez.

Cada aviso recebido deve trazer uma referência exclusiva criada pelo serviço remetente. Antes de criar um pedido, adicionar crédito, mudar uma assinatura ou enviar um e-mail, o app deve reservar essa referência em seus registros. Se a reserva já existir, ele deve confirmar o recebimento normalmente sem repetir a ação. O nome técnico desse comportamento é idempotência: processar novamente a mesma instrução mantém o mesmo resultado final, em vez de produzir outro resultado.

O armazenamento organizado usado pelo app recebe o nome técnico de banco de dados. Salve nele o nome do serviço, a referência exclusiva, o horário de chegada, a situação do trabalho e o resultado final. O nome técnico da regra que proíbe uma segunda referência igual é restrição de unicidade. Use a referência fornecida pelo serviço, não o e-mail, o nome do cliente, o valor da compra ou o horário atual. Um cliente pode fazer várias compras legítimas, e pessoas diferentes podem ter nomes ou valores iguais.

Uma mensagem pode afirmar que o pagamento foi aprovado sem ter vindo da empresa de pagamento. Serviços confiáveis acrescentam uma comprovação protegida que o app pode conferir antes de alterar dinheiro ou informações de clientes. O nome técnico dessa conferência é verificação de assinatura. O serviço fornece ao app uma senha de assinatura, também chamada de segredo de assinatura, que permite distinguir um aviso verdadeiro de outro inventado ou alterado. Uma comprovação ausente ou inválida não deve causar nenhuma ação.

O processo em um computador que executa o trabalho protegido do app longe dos visitantes é chamado pelos desenvolvedores de servidor. Guarde a senha de assinatura apenas nas configurações desse servidor, nunca em arquivos enviados ao aparelho de um visitante. Quando o serviço incluir um horário de envio confiável, aceite somente um intervalo curto e documentado. O nome técnico para impedir o reenvio de um aviso verdadeiro e antigo é proteção contra replay. Confirmar o remetente e reconhecer repetições são cuidados necessários, pois um serviço legítimo também pode reenviar um aviso legítimo.

Imagine duas pessoas consultando a mesma lista no mesmo instante. As duas encontram uma linha vazia, escrevem o próprio nome e fazem o trabalho. Um app comete o mesmo erro quando primeiro pergunta se uma referência existe e só depois a salva. As duas cópias podem passar pela consulta antes que qualquer uma registre a reserva. Esse problema de tempo é especialmente importante quando há dinheiro, vagas limitadas, estoque, créditos ou mensagens para clientes.

A reserva precisa acontecer como uma única etapa que não pode ser dividida. O nome técnico dessa etapa indivisível é operação atômica. Deixe o banco de dados aceitar uma reserva e recusar a outra por meio da restrição de unicidade. Marque o trabalho aceito como iniciado antes de executar a ação para o cliente. Se ele parar no meio, mantenha uma situação de trabalho incompleto e detalhes não sensíveis para uma revisão controlada. Não repita uma cobrança ou um crédito sem saber o resultado anterior.

Mantenha um histórico curto com nome do serviço, referência do aviso, horário de chegada, resultado da conferência, situação do trabalho e resultado final. O nome técnico desses registros é logs. Não coloque neles senhas de clientes, números completos de cartões, senhas de assinatura ou conteúdos desnecessários das mensagens. Revise regularmente os trabalhos repetidos, rejeitados, incompletos ou com falha. Uma mudança fora do normal pode revelar conexão quebrada, problema na confirmação do remetente ou uma alteração recente que removeu a reserva única.

Após mudar pagamentos, cadastros, agendas, entregas ou automações, envie duas vezes o mesmo aviso de teste aprovado e confirme que aparece apenas um resultado. Depois, teste um aviso inválido e outro antigo, confirmando que nenhum deles altera informações de clientes. O nome técnico das verificações repetidas ao longo do tempo é monitoramento contínuo. O VibeCodeWall confere o app público por fora e acompanha mudanças importantes ao longo do tempo. Ele não vê as instruções internas do app nem substitui os registros e testes feitos dentro dele.