Resposta direta
Reconstruir o contrato pelo comportamento observado, e não pela lembrança de quem participou da implantação. O caminho prático é levantar os campos que realmente trafegam, registrar o formato aceito em cada ponta, mapear quem responde por cada sistema e conter mudanças até existir esse registro. Sem isso, qualquer alteração vira tentativa. A documentação nasce da operação observada e do teste controlado, não de uma reunião de resgate de memória. O que não se consegue explicar com um exemplo real de dado ainda não está entendido o bastante para ser alterado.
- Objetivo
- Orientar implementação
- Formato indicado
- Projeto de implementação
- Atualizado em
O que esta página acrescenta: Trata a integração sem documentação como ativo em operação: parte do comportamento observado e do responsável nomeado, não da tentativa de recuperar a intenção original de quem implantou
O contrato se confirma no que trafega
A documentação útil sai da observação do que circula entre os sistemas. Registrar o campo enviado, o campo aceito e o que acontece quando falta um deles é mais confiável do que reconstruir a intenção de quem escreveu a integração.
A prioridade costuma ser a execução mais frequente e a que gera prejuízo quando falha. Um exemplo real de requisição e de resposta vale mais que qualquer descrição de fluxo. O que não aparece em nenhuma execução registrada permanece desconhecido e deve ser tratado como tal.
Responsável nomeado e mudança contida
Sem um responsável nomeado por ponta, o registro envelhece em silêncio. Cada sistema precisa de alguém que responda pelo formato aceito e aprove alterações, mesmo que esse trabalho seja dividido com outras funções.
Mudar uma integração sem registro é aposta. Uma janela combinada, com registro da versão anterior e forma de voltar atrás, reduz o custo do erro. O log de execução é a única prova de que a alteração funcionou como esperado.
O limite da reconstrução pelo comportamento
A reconstrução pelo comportamento não recupera a intenção original. Regras que nunca foram registradas como exceção continuam invisíveis até o dia em que o caso raro aparece, e nenhuma leitura de log cobre o que nunca executou.
Também não resolve dados já inconsistentes entre as pontas, nem substitui a definição da regra de negócio pela área responsável. Se a integração será substituída, o esforço de documentar tudo o que existe pode não compensar; nesse caso, o registro mínimo serve apenas para migrar com segurança.
Recurso prático
O que registrar antes de alterar uma integração sem documentação
| Elemento da integração | Como levantar sem a documentação |
|---|---|
| Campos que trafegam | Comparar a requisição gravada com o que a outra ponta aceita, campo por campo |
| Campos obrigatórios e opcionais | Testar envio sem o campo em ambiente separado e registrar a reação de cada ponta |
| Gatilho e frequência de execução | Ler o agendador ou o evento que dispara e confirmar contra o log de execução |
| Responsável por cada ponta | Nomear quem decide mudanças e quem responde pelo sistema de origem e pelo de destino |
| Comportamento em erro | Provocar uma falha conhecida e registrar a mensagem, o destino e quem é avisado |
O erro mais comum é registrar o formato que o sistema deveria aceitar em vez do que ele aceita hoje. O registro só serve depois de confirmado por teste com dado real de execução.
Conceitos usados nesta página
- Registro de execução — Registro de execução é a evidência de que uma rotina, automação ou tarefa rodou — com identificador, data, insumo, resultado e responsável.
Sobre o que está escrito aqui
Conceitos relacionados: contrato de integração · campos trafegados · log de execução · responsável pelo sistema · janela de mudança. Exemplos são ilustrativos. Não há cliente, resultado, preço, prazo ou certificação nesta página. Quando o formato indicado é Projeto de implementação, ele descreve uma possibilidade de trabalho — a conversa inicial avalia contexto e aderência.
Para continuar
- Integrações, sistemas e qualidade de dados — Página central do tema
- Números que não batem: por que a divergência… — planilhas divergentes
- Falhas silenciosas em integrações: como perce… — falhas silenciosas
Páginas relacionadas
O mesmo problema em outro objetivo
- Integração sem documentação: como reconstruir o que ela faz — Diagnosticar
- Integração sem documentação: como reconstruir o registro — Organizar um processo
- Integração sem documentação: o que comparar antes de mexer — Comparar alternativas
- Integração sem documentação: como medir o que ficou — Explicar medição
- Integração sem documentação: como avaliar antes de contratar — Orientar avaliação e contratação
Outras leituras em Integrações, sistemas e qualidade de dados
- Sistema que ninguém desliga: como comparar alternativas — Comparação de alternativas para decidir o que manter, o que substituir e o que precisa existir antes de encerrar um sistema antigo.
- Falha de integração sem aviso: como montar o alerta — O que precisa existir para que uma falha de integração avise alguém: sinal, responsável, escalonamento e o limite de cada aviso.
- Sistemas que ninguém desliga: como avaliar o custo — Mostra como levantar dependências, obrigações e responsáveis que mantêm um sistema ativo sem prazo definido, antes de decidir desligar, congelar ou manter.
- Integração sem monitoramento: o que verificar primeiro — Como levantar o estado real de uma integração sem monitoramento: onde olhar, o que registrar e quais sinais indicam risco de falha.
- Log de integração sem nível de erro: o que medir na saída — A página define sinais substitutos ao nível de erro, como contagem, atraso e conciliação, para avaliar a integração pelo que o log registra.