Um erro de integração nem sempre é resolvido com uma nova tentativa. Se faltar um dado, houver uma divergência comercial ou o sistema de destino exigir uma decisão, repetir a mesma solicitação pode gerar mais erros ou até duplicar efeitos. A gestão de exceções em integrações PHP consiste em detectar esses casos, preservar as informações necessárias e oferecer um caminho controlado para investigá-los e resolvê-los.
O objetivo não é, por padrão, criar outro backoffice. É tornar as exceções visíveis, compreensíveis e atribuíveis, e garantir que qualquer ação manual deixe um registro verificável. Uma boa solução separa a lógica de cada integração do processo comum de revisão, sem ocultar as diferenças que afetam a segurança ou o resultado do negócio.
Quando parar de tentar novamente automaticamente
As novas tentativas são úteis diante de falhas possivelmente transitórias: uma desconexão, um limite temporário de solicitações ou uma resposta temporariamente indisponível. Convém limitá-las com uma política explícita, por exemplo, um número máximo de tentativas e um intervalo crescente entre elas. Se o problema persistir, o fluxo deve parar de insistir e passar para uma condição que possa ser investigada.
Já uma rejeição por dados inválidos, uma referência inexistente ou uma regra de negócio não atendida normalmente exige outra resposta. Tentar novamente sem alterar as condições não vai corrigir o problema. Uma operação cujo resultado seja incerto também pode precisar de intervenção: por exemplo, se a conexão for perdida depois do envio de uma solicitação e não for possível saber se o sistema externo a processou. Nesse caso, antes de repetir, é preciso verificar o estado ou aplicar um mecanismo que evite duplicações.
Defina, para cada integração, quais erros são transitórios, quais são definitivos e quais exigem verificação. Mantenha essa classificação junto ao contrato da integração, em vez de dispersá-la em condições diferentes nos controladores. Assim, evita-se que uma alteração técnica mude acidentalmente a resposta operacional.
Preservar contexto útil para a investigação
Ninguém deveria precisar reconstruir uma transação consultando separadamente logs da aplicação, bancos de dados e sistemas externos. Cada exceção deve reunir o necessário para entender o que aconteceu e decidir o que fazer, respeitando os limites de proteção de dados.
- Identidade: identificador da exceção, do fluxo e da entidade de negócio relacionada.
- Origem e destino: integração envolvida, operação e sistema externo, sem armazenar segredos ou credenciais.
- Estado técnico: data, número de tentativas, resultado, código de resposta e descrição normalizada do erro.
- Contexto de negócio: campos relevantes e referências necessárias para resolver o caso, com dados sensíveis minimizados ou ocultados.
- Correlação: identificadores que permitam localizar registros relacionados em diferentes serviços.
Armazene um snapshot do contexto que explique a falha, além das referências aos dados atuais, quando necessário. Se os registros forem alterados posteriormente, a investigação deve permitir distinguir o que foi enviado originalmente do que existe agora. Estabeleça limites de acesso e retenção compatíveis com a sensibilidade das informações.
Modelar estados e transições explícitas
Os estados descrevem a situação operacional; não são apenas rótulos visuais. Um conjunto inicial pode incluir pendente de revisão, em investigação, resolvida e descartada. Acrescente estados intermediários somente se eles mudarem o que o sistema pode fazer ou o que se espera da pessoa responsável.
Defina quais transições são permitidas. Por exemplo, uma exceção pendente pode ser atribuída e passar para investigação; uma exceção resolvida deve preservar o resultado da correção e, se aplicável, o identificador da nova execução. Descartar não deve equivaler a excluir: exige um motivo, e seu efeito sobre o fluxo deve estar claro. Evite permitir alterações arbitrárias de estado em qualquer tela ou processo.
Separe o estado da revisão do resultado técnico quando isso trouxer clareza. Uma exceção pode estar resolvida em termos operacionais, enquanto a repetição ainda aguarda confirmação. Representar essas dimensões separadamente evita estados ambíguos e facilita identificar se ainda há trabalho pendente.
Atribuir responsáveis, prazos e escalonamento
Uma fila sem responsável acumula casos. Atribua responsáveis com base em regras compreensíveis, como o tipo de operação, a equipe que mantém o processo ou a área de negócio capaz de corrigir os dados. Permita a reatribuição com justificativa e preserve tanto a atribuição anterior quanto a nova.
Os prazos devem expressar uma expectativa operacional, não uma promessa automática de resolução. Determine por quanto tempo um caso pode permanecer sem revisão e o que acontece quando esse prazo é excedido: aviso ao responsável, escalonamento para uma equipe ou inclusão em uma fila prioritária. Evite codificar a identidade de pessoas específicas em cada integração; mantenha regras configuráveis e uma alternativa para quando o responsável não estiver disponível.
A interface deve mostrar rapidamente quais casos precisam de atenção, quem está cuidando deles e há quanto tempo estão aguardando. Se o volume ou os horários de atendimento forem relevantes, defina regras diferentes por prioridade e tipo de exceção, em vez de aplicar um único prazo a tudo.
Registrar ações e repetir com segurança
Cada intervenção deve gerar um evento de auditoria: quem agiu, quando, qual ação realizou, por qual motivo e qual era o estado antes e depois. Registre separadamente as alterações manuais, as execuções automáticas e as respostas do sistema externo. Não sobrescreva o histórico para mostrar apenas o estado atual.
Antes de oferecer uma ação para repetir a operação, determine se ela é idempotente. Quando o sistema de destino permitir, use uma chave de idempotência estável para que repetir a mesma operação não crie um segundo efeito. Se essa garantia não existir, consulte primeiro o estado remoto ou estabeleça uma etapa de conciliação; quando não for possível verificar o resultado, mostre essa incerteza e exija uma decisão autorizada.
Valide novamente os dados e as regras de negócio antes da execução. A ação manual não deve ignorar as validações que protegem o fluxo. Salve a relação entre a exceção original e a nova tentativa e informe de forma inequívoca se a operação foi aceita, rejeitada ou está pendente de confirmação. Uma opção para corrigir dados deve indicar quais campos serão alterados e se a correção afeta o registro de origem ou apenas a solicitação enviada.
Medir o funcionamento da fila
O número total de exceções não é suficiente para diagnosticar o processo. Acompanhe o tempo até a primeira revisão e até a resolução, a idade dos casos abertos, os casos reabertos, as tentativas por exceção e a proporção que acaba descartada. Segmente por integração, tipo de erro e equipe, sem transformar as métricas em incentivos para fechar casos sem resolvê-los.
Um aumento de exceções recorrentes pode indicar uma alteração no contrato da API, validação insuficiente ou dados de origem defeituosos. Um aumento do tempo de espera, mesmo sem mudança no volume, pode indicar falta de capacidade ou regras de atribuição ineficazes. Combine as métricas com alertas para filas envelhecidas e analise amostras de casos para confirmar a causa.
Escolher entre um console e um backoffice
Uma interface de resolução com escopo limitado pode ser suficiente se as pessoas precisarem revisar o contexto, atribuir casos, adicionar notas, alterar estados e solicitar uma nova tentativa controlada. Ela deve facilitar as tarefas frequentes, oferecer permissões adequadas e mostrar o histórico sem expor informações desnecessárias.
É necessário considerar um backoffice mais amplo quando o trabalho inclui processos relacionados, edição de entidades de negócio, aprovações, pesquisa transversal ou gestão complexa de permissões. Não confunda uma fila operacional com um sistema de administração completo: amplie o escopo somente quando houver necessidades reais que a interface limitada não possa atender com segurança.
Checklist antes de implementar a gestão
- Classificar os erros transitórios, definitivos e de resultado incerto.
- Definir estados, transições, motivos de encerramento e regras de reabertura.
- Armazenar contexto suficiente, minimizando e protegendo os dados sensíveis.
- Atribuir responsáveis, prazos e caminhos de escalonamento, com uma alternativa.
- Auditar as alterações e relacionar cada intervenção às tentativas posteriores.
- Validar antes de repetir e proteger contra efeitos duplicados.
- Medir a idade dos casos, os tempos de atendimento e os padrões recorrentes, não apenas o volume.
- Escolher uma interface proporcional às tarefas e revisar permissões e retenção.
Uma gestão confiável de exceções não elimina todas as falhas. Ela explicita o que deve acontecer quando a automação não é suficiente, evita novas tentativas às cegas e permite que cada pessoa aja com contexto, responsabilidade e rastreabilidade.
