Torne fiáveis os eventos de conversão e reembolso

Antes de começar

Receber um evento não demonstra que a comissão está correta. Mensagens podem repetir-se, um reembolso chegar antes de terminar o processamento e um serviço responder apesar de falhar o registo comercial. Programa e integração precisam de provas verificáveis. Confirme as propriedades do transporte na documentação do fornecedor; o Stripe é um exemplo técnico documentado, sem generalizar as suas propriedades a outros sistemas.

Distinga três identificadores

Separe identificador da mensagem, da operação comercial e do parceiro. Reconhecem entregas repetidas, relacionam encomenda, fatura, cancelamento e exportação e sustentam a atribuição. Acrescente tipo de evento, versão e data comercial à grelha de teste. Não deduza uma referência de encomenda a partir do valor e da morada do cliente.

Verifique antes de processar

Use o mecanismo de autenticidade documentado pelo fornecedor, incluindo assinatura quando disponível. Defina o registo de assinaturas inválidas sem divulgar dados pessoais. Não altere segredos durante uma verificação editorial. Uma resposta HTTP favorável não prova autenticidade nem processamento comercial bem-sucedido. Distinga receção, armazenamento e execução para diagnosticar o primeiro ponto de falha.

Evite efeitos duplicados nas repetições

Quando o evento regressa, recupere o resultado existente em vez de criar outra comissão. Guarde prova de processamento ligada à operação comercial. Chaves de idempotência de API e deduplicação de eventos recebidos resolvem problemas distintos. Teste os dois caminhos separadamente; uma proteção não cobre automaticamente o outro. Inclua receções simultâneas na verificação.

Aceite eventos fora de ordem

Descreva um reembolso recebido antes de existir a encomenda localmente. Prepare espera controlada ou consulta ao sistema de origem, conforme as capacidades disponíveis. Uma atualização antiga não deve substituir um estado recente sem regra explícita. Preserve hora de ocorrência e de receção para explicar atrasos, sequência e correções posteriores.

Teste falha e recuperação

Num ambiente autorizado, simule indisponibilidade, resposta atrasada e receção repetida. Verifique limites e tempos de repetição do fornecedor. Uma repetição manual pode coexistir com uma automática. Defina quem pode repetir operações, provas necessárias e controlos posteriores. O objetivo é um único efeito comercial, não apenas uma mensagem marcada como recebida.

Reconcilie com os dados comerciais

Compare regularmente encomendas e faturas de origem com operações elegíveis na plataforma. Distinga atraso normal, recusa documentada e perda real. Confira número de operações e montantes por moeda: um total pode esconder duplicados compensados por ausências. Guarde referências de ponta a ponta para compras, reembolsos parciais e cancelamentos.

Prepare provas úteis em incidentes

Reúna referência comercial, tipo, datas, versão e estados esperado e observado sem expor segredos. Identifique o primeiro passo divergente e atribua responsável e prazo. Após corrigir, repita o caso e os casos próximos: reparar reembolsos não deve duplicar compras. Registe causa, resultado e controlo que permitirá detetar a repetição do problema.

Respostas práticas

Perguntas para decidir