Como decidir quais dados incluir num evento de integração

Conceber um evento de integração parece uma decisão técnica, mas determina a autonomia das equipas, a resiliência operacional e a qualidade da informação que cada processo recebe. Quando um CRM, um ERP, um ecommerce e uma plataforma de atendimento trocam eventos, surge uma pergunta recorrente: deve a mensagem incluir todos os dados necessários ou apenas uma referência para os consultar no sistema de origem?

Não existe uma resposta universal. Um evento demasiado sucinto obriga a realizar consultas encadeadas e transforma o sistema de origem numa dependência constante. Um evento excessivamente rico duplica informação, pode propagar dados pessoais desnecessários e corre o risco de conter uma versão já desatualizada. A alternativa eficaz é decidir campo a campo, de acordo com a utilização real do consumidor e as condições de operação.

As três alternativas para transportar contexto

Um evento pode fornecer contexto de três formas. Cada modelo resolve problemas diferentes e também introduz custos que devem ser assumidos de forma explícita.

Evento com dados completos

A mensagem inclui a informação de que o consumidor necessita para executar a sua ação. Por exemplo, um evento de encomenda confirmada pode transportar linhas da encomenda, morada de entrega, canal de venda e uma fotografia dos montantes confirmados.

• É aconselhável utilizá-lo quando o consumidor tem de agir de imediato, quando o valor enviado deve ser preservado como evidência histórica ou quando o sistema de origem não terá disponibilidade garantida.
• Reduz chamadas posteriores, latência e acoplamento durante a execução.
• Exige definir o que a informação representa: normalmente uma fotografia no momento do evento, e não o estado atual em tempo real do registo.
• Aumenta o tamanho da mensagem, a complexidade do contrato e a superfície de exposição dos dados.

Evento com identificador e consulta posterior

A mensagem contém um identificador, o tipo de evento e metadados mínimos; o consumidor consulta depois uma API ou uma réplica autorizada. É apropriado se necessitar do dado em vigor, e não de uma fotografia histórica.

• É aconselhável utilizá-lo para atributos voláteis, catálogos extensos ou informação de que o consumidor apenas necessita em casos excecionais.
• Evita distribuir cópias de dados que mudam com frequência.
• Introduz dependência da disponibilidade, das permissões, dos limites de consumo e da latência do sistema de origem.
• Pode produzir consultas em cascata: um serviço consulta a encomenda, depois o cliente, a seguir o produto e, por fim, o inventário. Essa cadeia tende a ser frágil e difícil de diagnosticar.

Modelo híbrido

Na maioria das integrações maduras, o melhor resultado é híbrido: o evento transporta um núcleo autossuficiente para executar o fluxo e referências para o enriquecer quando necessário. Uma encomenda pode incluir o seu identificador, data, estado confirmado, montantes, artigos e destino logístico, mas fornecer apenas o identificador do cliente para consultar preferências atuais de contacto, se uma comunicação o exigir.

A regra não é “enviar pouco” nem “enviar tudo”: envie o necessário para concluir de forma fiável a decisão desencadeada e forneça referências para os dados que devam estar atualizados, sejam dispendiosos ou não estejam autorizados para todos os destinatários.

Critérios para decidir cada campo

A unidade correta de decisão não é o evento inteiro, mas cada atributo. Um mesmo evento pode conter dados imutáveis, voláteis, sensíveis e derivados, que exigem tratamentos opostos.

• Imediatismo: se o consumidor tiver de agir antes de poder consultar uma API, o dado deve seguir no evento. A logística não deve esperar por uma consulta adicional para conhecer a morada validada que tem de utilizar no envio.
• Atualidade: se a decisão exigir o último valor disponível, é preferível uma referência. As preferências de comunicação ou o estado atual de uma conta podem mudar depois da encomenda.
• Valor histórico: se for importante reconstruir o que se sabia quando ocorreu um facto, inclua uma fotografia com data. O preço aceite e os impostos aplicados não devem ser reinterpretados com base no catálogo atual.
• Volume e frequência: imagens, descrições extensas, documentos ou estruturas volumosas raramente pertencem à mensagem principal. Envie uma referência estável, uma versão e, quando aplicável, um resumo.
• Disponibilidade: se uma indisponibilidade do sistema de origem bloquear um processo crítico, o evento deve fornecer o mínimo necessário para uma degradação segura.
• Permissões: nem todos os consumidores que conhecem um identificador devem receber dados pessoais, financeiros ou internos. O evento não deve contornar o modelo de autorização dos sistemas.
• Rastreabilidade: todo o valor decisivo deve indicar de que versão ou momento provém. Um campo sem contexto temporal pode conduzir a decisões erradas.

Classifique também os dados. Os imutáveis, como um identificador de encomenda ou uma data de criação, são candidatos claros a seguir no evento. Os voláteis, como a disponibilidade de inventário, exigem normalmente uma consulta ou um evento específico de atualização. Os sensíveis devem ser minimizados, limitados por audiência e protegidos de acordo com as políticas aplicáveis. Os derivados, como uma segmentação ou uma pontuação, precisam de indicar a sua regra, versão ou validade para não parecerem factos permanentes.

Matriz prática e padrões de conceção

Antes de adicionar um campo ao contrato, a equipa de negócio, produto e tecnologia pode avaliá-lo com estas perguntas. Se várias respostas forem afirmativas na primeira parte, provavelmente deve ser incluído; se predominarem as da segunda, é aconselhável referenciá-lo.

1. O consumidor não consegue concluir a sua ação sem este valor?
2. É necessário preservar a versão exata válida quando o evento foi produzido?
3. Uma consulta posterior pode falhar ou chegar demasiado tarde?
4. É pequeno e estável dentro do ciclo de vida do processo?
5. Muda frequentemente ou só é necessário em casos específicos?
6. Contém dados sensíveis de que o consumidor não necessita explicitamente?
7. Existe uma fonte autorizada e disponível para o consultar mais tarde?
8. O consumidor pode tolerar uma resposta diferida, uma cache ou uma revisão manual?

Desta avaliação resultam três padrões úteis:

• Fotografia rastreável: transporte o dado e adicione occurred_at, um identificador de evento, a versão do esquema e, quando aplicável, a versão do recurso. É ideal para montantes, condições aceites e destino operacional.
• Referência enriquecível: envie um identificador estável, o tipo de recurso e, se existir, uma versão. O consumidor consulta apenas quando necessita e regista a resposta que utilizou.
• Dados mínimos com cache controlada: inclua uma seleção mínima e permita o enriquecimento a partir de uma cópia de leitura com validade definida. É útil para catálogos ou perfis não sensíveis em que um pequeno atraso é aceitável.

Um contrato simples pode exprimir claramente a diferença entre facto e informação de consulta:

{
  "event_id": "evt_123",
  "event_type": "order.confirmed",
  "occurred_at": "2025-03-08T10:30:00Z",
  "order": {
    "id": "ord_456",
    "total_confirmed": 125.00,
    "delivery_address_snapshot": { "country": "ES" }
  },
  "customer_ref": { "id": "cus_789" }
}

A morada incluída é uma fotografia operacional; o identificador do cliente permite consultar atributos atuais com autorização. Não se deve interpretar que todos os campos do cliente eram válidos ou estavam aprovados no momento da encomenda.

Disponibilidade, falhas e degradação operacional

Optar pela consulta posterior obriga a conceber o que acontecerá quando essa consulta falhar. Não basta implementar uma nova tentativa automática: uma indisponibilidade persistente pode gerar duplicados, saturar a API de origem e bloquear filas inteiras.

Defina o comportamento de degradação antes de publicar o evento. Para cada consumidor, estabeleça se pode processar com dados mínimos, tentar novamente mais tarde, encaminhar para uma fila de exceções ou exigir intervenção manual. O atendimento ao cliente pode abrir um caso com informação parcial; a logística talvez tenha de reter o envio se faltar uma morada verificável.

• Utilize identificadores de evento e idempotência para que uma nova tentativa não execute duas vezes a mesma ação.
• Separe os erros temporários dos permanentes, como uma referência inexistente ou permissões insuficientes.
• Evite novas tentativas sincronizadas e sem limite que amplifiquem uma incidência no sistema de origem.
• Monitorize o atraso das filas, os erros de enriquecimento, a idade do último dado consultado e a percentagem de processamento degradado.
• Mantenha uma via de revisão para decisões bloqueadas, com o motivo e o evento original disponíveis para auditoria.

Versionamento, segurança e governação do contrato

Os contratos de eventos evoluem. Adicionar um campo opcional tende a ser menos arriscado do que alterar o significado de um campo existente, transformar um campo opcional em obrigatório ou retirar informação que um consumidor assumia estar disponível. A compatibilidade não consiste apenas em a mensagem poder ser lida; também exige que mantenha o seu significado de negócio.

Defina um responsável por cada campo e documente a sua origem, classificação, semântica, formato, validade e consumidores autorizados. Inclua uma versão do esquema e trate alterações semânticas importantes como novas versões ou novos tipos de evento. Não reutilize um nome para expressar outra coisa: um campo chamado status sem um catálogo de valores e uma definição temporal é uma fonte comum de interpretações incompatíveis.

Em segurança, aplique a minimização de dados. Um evento difundido por uma infraestrutura partilhada pode alcançar mais consumidores do que os inicialmente previstos. Não inclua dados pessoais “por precaução”, segredos, credenciais ou atributos que não tenham uma finalidade concreta. Se um processo necessitar de informação sensível, considere um canal restrito ou uma consulta autorizada em vez de a propagar num evento geral.

Exemplo: encomenda para logística, atendimento e comunicações

Imagine que uma encomenda confirmada ativa três fluxos. A logística necessita de artigos, quantidades, morada de envio validada, método de entrega e data de confirmação. Estes dados devem seguir como fotografia porque permitem preparar o envio mesmo que o ecommerce deixe de estar disponível.

O atendimento ao cliente necessita do identificador da encomenda, do seu estado e da referência do cliente. Pode consultar o histórico atualizado do cliente ao atender uma ocorrência, desde que tenha permissões. As comunicações transacionais exigem o tipo de evento e uma referência autorizada ao destinatário, mas não precisam de receber a encomenda inteira nem o perfil completo do cliente.

Esta separação reduz a exposição e evita que um único evento se transforme numa réplica acidental do CRM ou do ERP. Também clarifica responsabilidades: o ecommerce emite o facto confirmado, a logística utiliza a fotografia de cumprimento e cada canal consulta apenas o contexto atual que lhe corresponde.

Checklist de decisão antes de publicar

• O evento descreve um facto ocorrido ou tenta replicar o estado completo de outro sistema?
• Cada campo tem um consumidor, uma finalidade e um responsável identificados?
• É claro quais os campos que são fotografias e quais devem ser consultados como estado atual?
• Os dados sensíveis foram minimizados e as permissões de acesso definidas?
• O processo continua a funcionar, é adiado ou escalado manualmente se o enriquecimento falhar?
• Existem identificador de evento, data de ocorrência, idempotência e versão do esquema?
• Os consumidores conseguem ignorar novos campos sem falhar?
• Existem métricas e alertas para detetar consultas falhadas, atrasos e mensagens não processadas?

A decisão correta transforma o evento num contrato de negócio fiável, e não num contentor arbitrário de dados. Envie contexto suficiente para que o facto possa gerar valor de forma autónoma; consulte o que deva estar atualizado, seja sensível ou não seja indispensável. Assim, reduz-se o acoplamento sem sacrificar a rastreabilidade nem a continuidade operacional.