Uma integração pode responder corretamente e, ainda assim, deixar dados diferentes em dois sistemas. Uma requisição pode expirar depois que o sistema externo salvou a alteração; um evento pode chegar atrasado; ou uma atualização local pode modificar um campo que o outro sistema também controla. Por isso, além de sincronizar eventos, convém poder comparar estados e resolver discrepâncias de forma deliberada.
A reconciliação de dados entre sistemas em PHP é um processo periódico ou sob demanda que identifica diferenças entre registros relacionados, determina o que elas significam e propõe ou executa uma ação. Não consiste em copiar indiscriminadamente um sistema sobre o outro. Para evitar perder informações válidas, é preciso definir a autoridade de cada dado, preservar evidências da comparação e proteger a aplicação contra correções repetidas ou em massa.
Defina qual sistema tem autoridade antes de comparar
A fonte da verdade nem sempre é única para toda uma entidade. O CRM pode ser responsável pelo nome comercial e pelos dados de contato, enquanto o sistema de faturamento controla o status do pagamento e o identificador fiscal validado. Se um sistema inteiro for designado como autoridade sem que os campos sejam avaliados, a reconciliação poderá substituir informações corretas por uma cópia antiga ou incompleta.
Documente a propriedade dos campos que são trocados. Para cada um, registre qual sistema pode originar alterações, qual deve prevalecer em caso de conflito, se o valor pode ser nulo e quais transformações são aceitáveis. Também convém distinguir campos editáveis de campos derivados: um total calculado, por exemplo, talvez precise ser regenerado a partir de seus componentes, em vez de ser copiado.
- Autoridade por campo: defina quem decide seu valor e o que fazer se os dois sistemas apresentarem alterações.
- Regras de combinação: especifique se é possível preencher um dado ausente sem substituir um dado existente.
- Exceções: indique quais conflitos precisam de aprovação, validação adicional ou intervenção da equipe responsável.
Quando não houver uma regra segura, a ação correta é marcar o conflito para revisão, não escolher arbitrariamente o registro com a data mais recente. Os relógios podem estar dessincronizados, e um carimbo de data e hora, por si só, não prova que uma alteração é legítima.
Torne a comparação reproduzível
Uma comparação útil precisa identificar o mesmo registro nos dois lados. Use um identificador estável compartilhado ou uma tabela de correspondências mantida explicitamente. Não dependa apenas de nomes, e-mails ou outros campos que possam mudar, se repetir ou ser normalizados de maneiras diferentes. Se não for possível encontrar uma relação inequívoca, classifique o caso como pendente de vinculação, em vez de mesclar registros por aproximação.
Compare valores normalizados de acordo com regras documentadas: por exemplo, espaços, letras maiúsculas ou formatos de data. Preserve também o valor original, pois normalizar para comparar não autoriza alterar os dados persistidos. Tenha cuidado com fusos horários, precisão decimal, valores vazios e diferenças entre um campo ausente e um campo presente com valor nulo. Tratar esses estados como equivalentes pode ocultar alterações relevantes.
Em conjuntos grandes, defina uma janela de trabalho e um marcador de progresso, como uma data de modificação ou um cursor de paginação. Salve o ponto de avanço somente quando o lote tiver sido processado de forma consistente. Se o provedor não oferecer marcadores confiáveis, uma varredura completa menos frequente ou uma combinação de amostragem e reconciliação direcionada pode ser mais segura do que fingir uma incrementalidade que a API não garante. A estratégia depende dos limites, da estabilidade e das garantias reais de cada sistema.
Em PHP, separe a obtenção dos dados da comparação e da persistência dos resultados. Por exemplo, uma função de comparação pode receber duas representações normalizadas e retornar uma lista de diferenças tipadas, sem executar chamadas remotas nem atualizar registros. Essa separação permite testar regras com casos controlados e revisar propostas antes de habilitar gravações.
Classifique as discrepâncias e decida como responder
Nem todas as diferenças indicam um erro, e cada classe exige uma política diferente. Uma classificação explícita melhora o diagnóstico e evita que uma única regra destrutiva seja aplicada a situações distintas.
- Ausente: o registro existe em um sistema, mas não no outro. Verifique se é uma criação recente, uma exclusão legítima, um filtro ou uma falha de paginação.
- Duplicado: vários registros parecem corresponder a uma entidade. Não escolha um automaticamente sem uma regra de identidade verificável.
- Alteração incompatível: os dois lados alteraram um campo controlado por ambos. Aplique uma política de propriedade ou encaminhe o conflito para revisão.
- Dado inválido: o valor não atende ao formato ou às restrições esperadas. Coloque-o em quarentena e evite propagá-lo.
- Defasagem temporal: a diferença pode ser causada por atraso na entrega ou no processamento. Tente novamente ou aguarde uma janela definida antes de declarar um conflito persistente.
Separe três etapas: detecção da diferença, decisão sobre a ação e aplicação da alteração. Uma proposta pode consistir em atualizar um campo, criar uma associação, solicitar revisão ou não fazer nada. Manter essas etapas separadas permite começar em modo somente leitura e entender o que teria mudado antes de ativar correções automáticas.
Aplique alterações sem criar novos danos
Automatize somente os casos cobertos por regras claras e verificáveis. Para os demais, ofereça uma fila de revisão com o identificador da entidade, os valores observados, a regra que seria acionada e a ação proposta. A interface ou o processo operacional deve permitir aceitar, rejeitar ou escalar a proposta e, quando apropriado, registrar quem tomou a decisão.
Projete as operações para que sejam idempotentes: reprocessar a mesma discrepância não deve criar duplicados nem alternar valores indefinidamente. Antes de gravar, verifique se o registro ainda está no estado esperado. Se tiver mudado desde a leitura, interrompa a atualização e compare novamente. Quando a API externa permitir, use versões, condições de gravação ou chaves de idempotência; não presuma que esses recursos existem sem verificá-los.
Limite o escopo com lotes pequenos, limites de alterações por execução e opções de pausa. Uma correção que ultrapasse o volume previsto deve ser interrompida ou exigir autorização, não continuar silenciosamente. Para alterações de alto impacto, registre uma possível operação compensatória, mas não a apresente como garantia de reversão: podem ter ocorrido alterações posteriores ou efeitos externos que não possam ser desfeitos.
Registre cada execução para investigar e repetir
Armazene um identificador da execução, seus horários de início e término, o intervalo ou cursor processado, os sistemas consultados, o resultado por categoria e os erros. Para cada discrepância, preserve a chave de correlação, os valores relevantes ou uma representação protegida, a regra avaliada, a ação proposta e o resultado da aplicação. Assim, é possível explicar por que uma decisão foi tomada e distinguir uma falha de integração de um conflito real.
Proteja os registros: eles podem conter dados pessoais, credenciais indiretas ou informações comerciais. Evite despejar cargas completas quando campos específicos forem suficientes, limite o acesso e defina a retenção. Inclua referências aos registros de origem e o horário da observação para facilitar investigações sem transformar o log em um segundo banco de dados sem controle.
Tente novamente somente em caso de falhas transitórias, com limites e espera progressiva. Registre as tentativas e separe os erros permanentes — como dados inválidos ou permissões insuficientes — para evitar ciclos que repitam o mesmo problema. Deve ser possível retomar uma execução usando um critério conhecido, sem depender de que o processo PHP permaneça ativo indefinidamente.
Lista de verificação antes de automatizar
- A autoridade de cada campo e o tratamento de valores nulos e exclusões estão definidos?
- Os identificadores vinculam registros sem ambiguidade, e os duplicados são tratados?
- Paginação, atrasos, limites da API, novas tentativas e alterações concorrentes foram testados?
- As diferenças são classificadas, e as exceções são encaminhadas para revisão ou quarentena?
- A comparação pode ser executada em modo somente leitura e mostrar as ações que propõe?
- As gravações são idempotentes, condicionadas ao estado esperado e limitadas por volume?
- As decisões e os resultados são registrados com proteção de dados e acesso apropriados?
- Há testes com dados representativos, incluindo conflitos, valores vazios, duplicados e falhas parciais?
Comece observando e classificando, não corrigindo. Depois de validar as regras com dados reais e revisar as propostas, ative a automação somente para discrepâncias de baixo risco. Mantenha uma opção de pausa e revise periodicamente falsos positivos, casos não resolvidos e alterações nos sistemas externos. Assim, a reconciliação se torna um controle operacional repetível, em vez de uma sincronização que oculta conflitos até que alguém perceba suas consequências.
