Workflows que quebram porque um sistema de terceiros mudou um campo

Um dos erros mais comuns em produção não tem nada de exótico: "Cannot read property of undefined". Uma expressão que buscava um campo específico do retorno de uma API — algo como o e-mail de um cliente dentro de um objeto aninhado — funcionou perfeitamente por meses, até o dia em que o provedor daquela API mudou, sem aviso, a estrutura da resposta. O campo que antes vinha preenchido passou a vir vazio, ou o objeto que continha esse campo deixou de existir em determinados casos.

O workflow, que nunca tinha sido projetado para lidar com essa possibilidade, quebra. E quebra exatamente no tipo de situação mais difícil de prever em teste: um caso de borda que só aparece com dados reais, meses depois de o workflow ter sido validado com uma amostra que não incluía aquele cenário.

Por que isso acontece

Expressões escritas assumindo que um campo sempre vai existir, sempre vai vir preenchido e sempre vai ter o mesmo tipo de dado funcionam bem enquanto essas três suposições se sustentam. O problema é que nenhuma dessas suposições é garantida quando o dado vem de um sistema externo: uma integração pode retornar um campo nulo em vez de omiti-lo, um array pode vir vazio em vez de ausente, um provedor pode alterar o formato de uma resposta em uma atualização de API sem que isso seja tratado como uma mudança que quebra compatibilidade.

Testar apenas com dados ideais — o caso feliz, em que tudo vem preenchido como esperado — esconde exatamente esse tipo de fragilidade, porque o workflow nunca é exposto, durante o teste, ao tipo de dado incompleto ou inesperado que eventualmente vai aparecer em produção.

A solução: acesso defensivo e validação na entrada

Acesso defensivo a dados significa nunca presumir que um campo existe sem verificar antes — usando valores padrão para campos ausentes, checagens explícitas antes de acessar propriedades aninhadas, e tratamento específico para o caso em que um valor esperado vem nulo ou vazio, em vez de deixar que a ausência do dado derrube o workflow inteiro.

Validação de payload na entrada do workflow é o complemento dessa prática: antes de processar os dados recebidos de um webhook ou de uma chamada de API, um passo de validação confirma que a estrutura básica esperada está presente. Quando não está, o workflow pode registrar o problema, notificar alguém e interromper de forma controlada — em vez de seguir adiante e falhar de forma imprevisível vários nós depois, num ponto que dificulta identificar a causa raiz.

Essa combinação desloca o momento da falha: em vez de quebrar de forma inesperada no meio do processamento, o workflow identifica o dado problemático logo na entrada, com uma mensagem de erro clara sobre o que estava faltando — o que reduz drasticamente o tempo de diagnóstico quando algo precisa ser corrigido.

Problema aplicado: cadastro de cliente com endereço opcional

EXEMPLO APLICADO

Um workflow de onboarding de clientes lia o campo de endereço a partir de um formulário externo, assumindo que ele sempre viria como um objeto com rua, número e cidade preenchidos. Quando o formulário foi atualizado para tornar o endereço opcional, os cadastros sem esse campo passaram a derrubar o workflow com um erro de propriedade indefinida, silenciando o restante do processamento — inclusive campos que não dependiam do endereço. A correção envolveu adicionar uma verificação explícita antes de acessar os campos do endereço, com um valor padrão para quando ele não existisse, permitindo que o restante do cadastro seguisse normalmente mesmo sem esse dado.

Onde aplicar esse cuidado primeiro

Vale priorizar essa revisão nos pontos de entrada de dados vindos de sistemas fora do controle direto da equipe — webhooks de terceiros, APIs de parceiros, formulários públicos — porque são exatamente os pontos em que uma mudança de formato pode acontecer sem aviso prévio e sem que a equipe de automação seja informada com antecedência.

Sinais de que sua operação tem esse problema

• Algum workflow já falhou recentemente com um erro do tipo "propriedade indefinida" ou similar?
• Os workflows que recebem dados de sistemas de terceiros validam a estrutura recebida antes de processá-la?
• Os testes de um workflow incluem casos com dados incompletos, nulos ou em formato inesperado — ou só o caso ideal?
• Existe algum ponto de entrada de dados externos sem nenhuma checagem antes de acessar campos aninhados?

Para concluir

Dados de sistemas externos vão mudar de formato mais cedo ou mais tarde — isso não é uma exceção a ser evitada, é uma característica de qualquer integração de longo prazo. Workflows construídos com acesso defensivo e validação na entrada absorvem essa mudança sem quebrar; os que não são, apenas adiam o problema para o dia em que ele vai doer mais.