Uma integração torna-se crítica quando a sua falha altera um processo de negócio relevante: impedir a criação de encomendas, atrasar a faturação, deixar os dados dos clientes desatualizados ou bloquear uma operação interna. Nesses cenários, conhecer a arquitetura não é suficiente. A equipa precisa de um procedimento que permita tomar decisões seguras sob pressão. Esse procedimento é o runbook para integrações críticas.
Um bom runbook não é uma lista genérica de verificações técnicas nem um documento que apenas quem o escreveu entende. Deve indicar que serviço de negócio está afetado, como detetar o problema, quem pode decidir uma contenção, que ações são reversíveis e que provas confirmam a recuperação. O seu objetivo não é eliminar todos os incidentes, mas reduzir o tempo de diagnóstico, limitar o alcance e evitar que a resposta agrave a perda ou corrupção de dados.
O que torna uma integração crítica
A criticidade não depende apenas de uma ligação utilizar uma API, uma fila de mensagens ou um processo agendado. Depende das suas consequências. Para a classificar, avalie o fluxo completo com critérios verificáveis:
- Impacto no negócio: receitas, cumprimento contratual, apoio ao cliente, logística, faturação ou decisões operacionais que dependam dos dados.
- Janela de tolerância: quanto tempo o processo pode atrasar-se antes de causar danos. Uma sincronização analítica diária não é o mesmo que a validação de uma transação em tempo real.
- Integridade: se um erro pode criar duplicados, omitir registos, modificar estados incorretos ou expor informação.
- Dependências: sistemas de origem e destino, autenticação, rede, fornecedor externo, esquema de dados, filas e tarefas de processamento.
- Recuperabilidade: possibilidade de repetir a tentativa ou reprocessar sem efeitos secundários e capacidade de reverter alterações.
Defina também os limites do serviço. Por exemplo: “a integração envia criações de encomendas para o sistema de gestão; não atualiza o stock nem confirma o pagamento”. Esta delimitação evita que o incidente se alastre devido a suposições e esclarece que equipas devem intervir.
O inventário mínimo antes de escrever o runbook
Um runbook útil baseia-se num inventário breve e mantido. Não precisa de replicar toda a documentação de arquitetura, mas deve disponibilizar os dados necessários para atuar. Para cada fluxo, documente:
- Nome do fluxo e processo de negócio afetado.
- Sistema de origem, sistema de destino e componentes intermédios.
- Evento ou agendamento que inicia o processamento.
- Dados trocados, identificador único de correlação e regras de idempotência.
- Credenciais ou mecanismo de autenticação, sem incluir segredos no documento.
- Painéis, registos e consultas autorizadas para observar o estado.
- Proprietário técnico, responsável de negócio, equipa executora e canal de escalonamento.
- Ações disponíveis: pausar, repetir a tentativa, reprocessar, colocar em quarentena e reverter.
Se uma integração for publicada ou distribuída através de uma plataforma como a Apification, o inventário deve incluir o URL ou a referência operacional aprovada, o proprietário da publicação, as dependências declaradas e o procedimento para substituir ou retirar uma versão. Não é aconselhável assumir que a plataforma resolve, por si só, a observabilidade, as novas tentativas ou a recuperação: esses controlos devem ser validados no desenho concreto da integração.
Sinais e limiares que permitem atuar
Os alertas úteis baseiam-se em sintomas que exigem uma decisão, e não em qualquer variação técnica. Cada sinal deve responder a três perguntas: o que mede, que limiar ativa a intervenção e qual é a primeira ação. Combine pelo menos estas categorias:
- Falhas: erros de autenticação, respostas inválidas, rejeições do destino ou tarefas terminadas com erro.
- Atraso: idade da mensagem mais antiga, tempo desde a última entrega correta ou incumprimento de uma janela de processamento.
- Volume anómalo: queda para zero quando deveria existir atividade, aumento invulgar de eventos ou uma fila que cresce de forma sustentada.
- Duplicados: a mesma chave de negócio processada mais de uma vez fora da regra prevista.
- Perda de rastreabilidade: eventos sem identificador de correlação, registos incompletos ou impossibilidade de associar origem e destino.
Evite limiares arbitrários. Calcule uma linha de base com o comportamento normal por faixa horária e estabeleça limites ligados à tolerância do negócio. Se uma encomenda pode esperar quinze minutos, um alerta ao fim de duas horas não é operacional. Se as novas tentativas automáticas são expectáveis, alertar à primeira tentativa falhada apenas gerará ruído.
Estrutura de um runbook útil sob pressão
O procedimento deve poder ser seguido de cima para baixo durante um incidente. Utilize instruções curtas, ligações diretas para evidências e condições explícitas para avançar. Uma estrutura eficaz contém seis fases.
- Verificar: confirmar o alerta através de um painel, de uma amostra de registos e do identificador de correlação. Excluir manutenção planeada ou um falso positivo.
- Classificar: identificar se afeta a disponibilidade, a validade dos dados, a compatibilidade, a capacidade ou o processamento parcial. Estimar o alcance por período, entidade e sistemas afetados.
- Conter: interromper a propagação quando existir risco de corrupção. Pode consistir em pausar o consumidor, desativar um acionador ou enviar registos para uma fila de quarentena.
- Comunicar: informar com factos: fluxo afetado, hora estimada de início, impacto conhecido, medida de contenção e próxima atualização. Não comunique causas não confirmadas.
- Recuperar: aplicar a correção aprovada, executar novas tentativas ou reprocessamento controlado e verificar o resultado de uma amostra antes de ampliar o alcance.
- Registar: conservar a cronologia, as decisões, os comandos ou ações realizados, as evidências e o trabalho pendente.
Inclua pré-requisitos e permissões. Uma instrução como reprocessar mensagens pendentes é insuficiente se não explicar a partir de que intervalo, que filtro impede duplicados, quem autoriza a operação e como o resultado é validado.
Árvore de decisão para falhas frequentes
Uma árvore de decisão reduz a ambiguidade. Pode ser expressa de forma simples e adaptada a cada integração:
O destino está disponível?
- Não: verificar o estado e as credenciais; pausar se a fila crescer além do limite.
- Sim: a mensagem cumpre o contrato de dados?
- Não: enviar para quarentena; não repetir a tentativa sem correção.
- Sim: o contrato ou a versão esperada foi alterado?
- Sim: interromper deployments e aplicar compatibilidade ou reversão.
- Não: rever limites, tempos de espera e erros transitórios.Perante indisponibilidade, priorize a preservação dos eventos e evite saturar o destino com novas tentativas. Perante dados inválidos, isole os registos afetados e determine se o defeito está na origem, na transformação ou no contrato. Perante uma alteração incompatível, congele alterações adicionais, compare esquemas e reverta apenas se a reversão não quebrar registos já processados. Se as novas tentativas se esgotarem, não as reinicie indiscriminadamente: classifique a causa e confirme a idempotência.
O processamento parcial merece uma secção específica. É o caso em que a origem considera uma operação concluída, mas o destino não, ou vice-versa. A recuperação exige reconciliação por identificadores de negócio e não apenas por contadores. Um total de eventos processados pode coincidir mesmo que existam entidades incorretas ou duplicadas.
Quando pausar, repetir a tentativa, reprocessar ou reverter
Estas ações têm riscos distintos. O runbook deve convertê-los em critérios de decisão:
- Pausar quando continua a entrar informação incorreta, não existe rastreabilidade suficiente ou a acumulação ameaça a integridade. Defina a capacidade máxima de retenção antes de escolher esta opção.
- Repetir a tentativa perante erros transitórios comprovados, como uma indisponibilidade temporária, desde que a operação seja idempotente ou disponha de uma chave de desduplicação.
- Reprocessar depois de corrigir a causa e delimitar o intervalo ou conjunto afetado. Faça-o por lotes controlados, com validação entre lotes.
- Reverter uma alteração quando existe uma versão anterior conhecida, a reversão é compatível com os dados em curso e foi avaliado o efeito sobre consumidores e dependências.
A velocidade não justifica alterar dados sem controlo. Se não for possível garantir a idempotência, trate o reprocessamento como uma operação de risco: solicite aprovação, teste com uma amostra e prepare uma reconciliação posterior.
Responsabilidades, encerramento e aprendizagem
Separe os papéis, ainda que a mesma pessoa os possa assumir em equipas pequenas. O responsável de plantão executa o diagnóstico inicial; o proprietário técnico aprova alterações de arquitetura ou recuperação complexa; o responsável de negócio decide sobre prioridades e comunicação do impacto. Estabeleça prazos de escalonamento e um canal único para o estado do incidente.
Não encerre um incidente porque o alerta desapareceu. Exija evidências: intervalo afetado confirmado, registos de erro preservados, dados reconciliados entre origem e destino, filas ou tarefas pendentes revistas e comunicação final emitida. Crie ações posteriores com responsável e data: corrigir um contrato, adicionar um sinal, ajustar um limiar, melhorar a idempotência ou atualizar contactos.
Teste e mantenha o procedimento
Um runbook não testado é uma hipótese. Realize simulações controladas de credenciais inválidas, destino indisponível, evento duplicado, alteração de esquema e atraso sustentado. Verifique se os alertas chegam à equipa adequada, se os acessos funcionam e se os passos podem ser executados sem depender de conhecimento tácito.
Reveja o documento após cada incidente relevante e perante alterações em sistemas, contratos, responsáveis ou mecanismos de deployment. Uma revisão periódica pode verificar ligações, permissões, limiares, contactos e procedimentos de reversão. O resultado é uma integração tratada como um serviço operacional: com limites claros, decisões repetíveis e uma recuperação baseada em evidências.