Resposta direta
A saída é tratar a integração como ativo com registro próprio, e não como código de autor. O ponto de partida é o fluxo em produção: origem do dado, transformação, destino e horário de execução. Em seguida vem a responsabilidade nominal por trecho, incluindo quem corrige falha fora do horário. Depois as decisões embutidas: regras de negócio, campos ignorados, exceções tratadas à mão. O registro não precisa ser completo para ser útil; precisa ser conferível por outra pessoa. Sem ele, cada mudança passa a depender de memória, e o custo aparece na troca de equipe.
- Objetivo
- Organizar um processo
- Formato indicado
- Projeto de implementação
- Atualizado em
O que esta página acrescenta: Trata o registro da integração como item de operação com responsável e critério de conferência, não como documentação técnica ideal a ser escrita do zero.
O que o comportamento atual revela
Antes de escrever qualquer registro, a pergunta útil é o que a integração faz hoje, não o que deveria fazer. Isso costuma aparecer em três lugares: a agenda de execução, os registros de erro e as correções feitas à mão por quem opera.
Divergências entre o desenho original e o comportamento atual são normais. Alterações feitas sob pressão raramente voltam ao desenho. O registro parte do que roda e só depois confronta a intenção inicial, documentada ou lembrada.
Responsável por trecho, não por sistema
Apontar um dono do sistema inteiro não resolve, porque ninguém conhece toda a cadeia. A divisão útil é por trecho: quem fornece o dado, quem transforma, quem consome e quem corrige quando algo falha fora do horário comercial.
Esse mapa também define o que fica fora da integração. Campos que ninguém usa, rotinas mantidas por hábito e exceções sem dono aparecem nesse passo, e a decisão sobre eles é de negócio, não técnica.
O que o registro não resolve
Registrar não corrige a integração. Erros de regra, dados inconsistentes na origem e dependências frágeis continuam existindo depois do registro pronto. Ele reduz o tempo de diagnóstico e a dependência de uma pessoa, nada além disso.
Também não substitui teste. Um registro correto pode descrever um fluxo que já está errado. Onde não há ambiente de teste nem dado de referência, o limite é conhecido e deve constar como tal, em vez de ser tratado como resolvido.
Recurso prático
Registro mínimo de uma integração existente
| Item a registrar | O que precisa constar |
|---|---|
| Fluxo em produção | origem do dado, transformação aplicada, destino e horário de execução |
| Responsabilidade | quem responde por cada trecho e quem corrige falha fora do horário |
| Decisão embutida | regra de negócio aplicada, campo ignorado e exceção tratada à mão |
O erro comum é registrar a intenção original e não o comportamento atual. A integração que roda hoje costuma divergir do que foi desenhado, e o desenho é justamente o que engana quem assume a manutenção.
Sobre o que está escrito aqui
Conceitos relacionados: fluxo em produção · responsável nominal por trecho · regra de negócio embutida · critério de conferência · registro 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
- APIs e integração: o que perguntar antes de c… — sistema sem integração
- Validação na entrada: onde o dado errado nasce — dado errado na origem
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: 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: por onde reconstruir o contrato — Orientar implementaçã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
- Número sem origem: como medir o que o relatório não explica — O que registrar para reconstruir o número de um relatório: origem, regra de cálculo, responsável e critério de conferência antes de discutir o resultado.
- Conciliação no fechamento: comparar onde tratar o retrabalho — Compara três pontos de tratamento do retrabalho de conciliação no fechamento, o que cada um exige e em que situações não compensa.
- Dependência de uma pessoa para extrair dado: como avaliar — O que fazer quando a extração de dados depende de uma pessoa: o que documentar, o que exigir do fornecedor e o que a contratação não resolve.
- Arquivo chega por mensagem: o que avaliar ao contratar — Explica o que definir antes de contratar o tratamento de arquivos que entram por mensagem: dono, critério de aceite, recusa com motivo e rastro de aprovação.
- Campo de observação virou status: como diagnosticar — Mostra como identificar quando o campo de observação virou o status real da operação, quais sinais denunciam isso e o que medir antes de mudar.