Quando um CRM alimenta um ERP, uma loja envia encomendas para a logística ou uma aplicação interna publica eventos para outros sistemas, a integração depende de mais do que um URL, uma fila ou um ficheiro partilhado. Depende de todas as partes interpretarem os dados da mesma forma ao longo do tempo. Os contratos de dados para integrações transformam essa expectativa em regras explícitas, verificáveis e governáveis.
O seu objetivo não é documentar uma interface apenas uma vez, mas evitar que uma alteração aparentemente pequena —renomear um campo, admitir um novo estado ou modificar uma unidade monetária— provoque erros silenciosos, reprocessamentos ou decisões de negócio incorretas. São especialmente úteis quando intervêm equipas diferentes, aplicações de terceiros e deployments com cronogramas independentes.
O que é um contrato de dados e que problema resolve
Um contrato de dados define o acordo operacional entre quem produz informação e quem a consome. É aplicável a uma resposta de serviço, um evento, um ficheiro periódico, uma tabela partilhada ou uma mensagem numa fila. Descreve o que é entregue, o que significa, em que condições é válido e como evoluirá.
Por exemplo, uma mensagem de encomenda com orderId, status e amount precisa de especificar se o montante está em unidades ou cêntimos, que moeda se aplica, que estados são admissíveis, se uma encomenda cancelada pode ter montante zero e se a mesma mensagem pode chegar mais de uma vez. Sem estas regras, dois sistemas podem aceitar tecnicamente o mesmo JSON e, ainda assim, atuar de forma incompatível.
O contrato reduz três riscos frequentes:
- Falhas diretas: um consumidor não consegue desserializar, validar ou processar um dado alterado.
- Erros semânticos: o formato parece correto, mas o significado de um campo ou de uma regra de negócio muda.
- Dependências invisíveis: um produtor desconhece que um campo, valor ou comportamento é utilizado por outros consumidores.
Documentação, esquema e contrato operacional
A documentação explica como uma integração deveria funcionar. Um esquema formaliza parte dessa explicação: estrutura, nomes, tipos, campos obrigatórios e, consoante a tecnologia, restrições. Ambos são necessários, mas não bastam para operar uma integração de forma segura.
O contrato operacional reúne o esquema com decisões que podem ser revistas e testadas: proprietário, consumidores conhecidos, política de compatibilidade, versionamento, regras semânticas, qualidade mínima, tratamento de erros e procedimento de alteração. Pode ser representado com OpenAPI, AsyncAPI, JSON Schema, Avro, Protobuf, SQL ou outra especificação, mas a ferramenta não substitui essas decisões.
Um contrato útil deveria incluir, no mínimo:
- Identidade e âmbito: nome, propósito, canal, produtor, responsável e classificação de sensibilidade.
- Estrutura: campos, tipos, cardinalidade, obrigatoriedade, formatos e exemplos válidos.
- Semântica: significado, unidade, fuso horário, moeda, catálogo de valores e regras de cálculo.
- Qualidade: unicidade, intervalos, relações entre campos, frescura esperada e ordenação quando relevante.
- Operação: frequência, limites de tamanho, ordem de entrega, novas tentativas, retenção e canal de incidentes.
- Evolução: versão, alterações compatíveis, alterações que exigem coordenação e período de descontinuação.
Compatibilidade: avaliar alterações com uma perspetiva explícita
A terminologia de compatibilidade pode variar entre equipas. Para evitar decisões erradas, convém adotar a perspetiva habitual de leitura de esquemas, utilizada por numerosos registos de esquemas: a compatibilidade retroativa significa que o esquema ou consumidor novo pode ler dados produzidos com o esquema anterior; a compatibilidade progressiva significa que o esquema ou consumidor anterior pode ler dados produzidos com o esquema novo. A compatibilidade total exige ambas as direções.
Esta definição não permite deduzir o comportamento real apenas ao observar uma regra abstrata. Deve ser verificada com o formato, o serializador, o esquema de leitura e a implementação concreta do consumidor. Adicionar um campo opcional com valor predefinido, por exemplo, pode ser retroativamente compatível se a nova versão souber completar a sua ausência ao ler dados antigos. Mas um consumidor antigo só poderá ler a nova mensagem se a sua tecnologia e implementação ignorarem campos desconhecidos ou se o seu esquema de leitura resolver corretamente esse campo mediante um valor predefinido. Não se deve assumir isso sem um teste.
Antes de aprovar uma alteração, formule perguntas concretas: a nova versão consegue processar mensagens já armazenadas? A versão anterior consegue continuar a processar mensagens emitidas durante um deployment gradual? O que acontece com consumidores externos que não são atualizados ao mesmo ritmo? A resposta deve resultar de testes representativos, e não apenas da etiqueta de compatibilidade do registo.
Como regra prática, adicionar campos realmente opcionais, ampliar metadados não interpretados ou corrigir descrições tende a ser uma alteração de menor risco. Eliminar ou renomear campos, alterar tipos, restringir intervalos, modificar unidades, reinterpretar nulos ou introduzir valores de enumeração que ativem lógica diferente tende a exigir uma nova versão e coordenação. Manter temporariamente um campo obsoleto e publicar uma data de descontinuação oferece uma transição mais segura do que removê-lo de imediato.
Conceção consoante o tipo de intercâmbio
O mesmo princípio assume formas diferentes consoante o mecanismo. Em eventos, identifique o facto ocorrido, o instante de negócio, a origem, o identificador do evento e a entidade afetada. Declare se o evento é imutável, se pode chegar fora de ordem e se existem eventos de correção.
Se a entrega ocorrer pelo menos uma vez, o consumidor necessita de uma estratégia verificável para detetar ou tolerar duplicados. Pode utilizar um identificador de evento guardado num registo de desduplicação, uma chave de negócio com operações idempotentes, uma restrição no armazenamento ou um mecanismo equivalente acordado. Uma chave de idempotência é uma opção frequente, mas não um requisito universal. O importante é definir que duplicados são esperados, durante quanto tempo são detetados e que resultado o seu reprocessamento deve produzir.
Em respostas síncronas de serviços, o contrato deve distinguir dados de negócio, erros funcionais e falhas técnicas. É preferível definir códigos, estrutura de erro, campos seguros para diagnóstico e condições de nova tentativa. Em cargas periódicas, especifique o corte temporal, o fuso horário, se o ficheiro contém uma carga completa ou incremental, a chave de reconciliação e o comportamento perante registos repetidos ou ausentes.
Testes de contrato antes e depois da produção
Os testes de contrato automatizam a verificação de que produtor e consumidor respeitam o acordo. Durante o desenvolvimento, valide exemplos válidos e inválidos perante o esquema e as regras semânticas relevantes. Inclua casos-limite: nulos permitidos, valores desconhecidos, decimais, datas com fuso horário e combinações de campos dependentes.
Na integração contínua, a alteração do contrato deve ser comparada com a última versão publicada. O controlo pode bloquear modificações incompatíveis, exigir uma nova versão ou requerer aprovação do responsável. Também convém executar consumidores de referência ou testes acordados por consumidores críticos com dados de teste produzidos pela nova versão.
Antes da produção, teste a coexistência entre versões que realmente existirá durante o deployment. Após publicar, observe taxas de validação falhada, mensagens enviadas para quarentena, erros de desserialização, atraso de processamento e proporção de valores desconhecidos. Registe identificadores técnicos, versão do contrato, tipo de erro e origem; evite incluir dados pessoais, segredos ou cargas completas quando não forem imprescindíveis para diagnosticar.
Governação da alteração, exceções e rastreabilidade
Um fluxo leve e explícito evita que o contrato se torne um documento esquecido. O produtor propõe a alteração com a sua motivação, impacto previsto, exemplo de antes e depois, classificação de compatibilidade e plano de descontinuação. Os responsáveis pelos consumidores afetados reveem a semântica e os testes. Um proprietário designado aprova, publica a versão e comunica a janela de adoção.
As exceções também devem estar definidas. Se chegar um valor fora do intervalo, nem sempre é adequado rejeitar toda a carga: pode ser enviado para quarentena, marcado para revisão ou aceite com um indicador de qualidade, consoante o risco de negócio. Para valores de catálogo desconhecidos, determine se o consumidor deve ignorá-los, preservá-los, aplicar um comportamento seguro ou interromper o processo. Diferencie cuidadosamente entre campo ausente, campo null e valor vazio: podem expressar situações diferentes.
Por último, mantenha um registo versionado de contratos, decisões de compatibilidade, aprovações, datas de descontinuação e evidência de testes. Esta rastreabilidade permite responder quem alterou o quê, porque foi considerado seguro e que consumidores precisavam de se adaptar. Assim, a evolução deixa de depender de verificações manuais e passa a ser uma disciplina técnica verificável.