Especificar uma integração com identidade, estados, recuperação e limites de automação.
DO CONCEITO À ENTREGA
Especificar uma integração com identidade, estados, recuperação e limites de automação.
O destino concluiu a operação e a automação perdeu a resposta. Depois, um humano resolveu o atendimento. Desenhe a retomada que reconhece ambos os fatos e não executa o trabalho novamente.
Ao final deste módulo
Você terá: Contrato de integração e recuperação.
Em cobrança, evite duplicidade financeira; em estoque, movimentação repetida; em atendimento, mensagem atrasada após intervenção humana. Use apenas ambientes de teste para ensaiar efeitos.
Seu objetivo: Contrato de integração em linguagem de negócio.
Integração exige identidade e confirmação. Ampliar o mapa
Uma API permite que sistemas troquem solicitações e respostas conforme um contrato. Um webhook informa eventos por uma chamada. Nenhum desses mecanismos define automaticamente o significado de negócio ou garante que toda a operação foi concluída. A empresa precisa relacionar a comunicação ao processo.
Na Horizonte, o sistema recebe uma confirmação e prepara uma tarefa. O evento deve possuir uma referência que permita reconhecer o contrato e a solicitação corretos. Usar apenas o nome do cliente pode relacionar a informação à operação errada.
Defina a fonte oficial de cada estado. Se um fornecedor confirma pagamento, outro componente não deve inventar esse fato porque uma mensagem foi enviada. A integração deve registrar o que recebeu, o que pediu e o que foi confirmado.
Verifique documentação, acesso e limites antes de prometer a conexão. A existência de uma API não significa que o plano contratado permita todas as operações necessárias. A proposta deve explicitar essas dependências e quem pode liberá-las.
APROFUNDE O RACIOCÍNIO
Como pensar essa decisão na empresa
Uma API é uma interface pela qual sistemas trocam informações ou solicitam operações segundo um contrato. Um evento informa que um fato ocorreu ou que há uma mudança a verificar. A integração precisa conhecer o significado da mensagem, a identidade do objeto e a confirmação esperada.
Defina a fonte de verdade para cada informação. Se o cadastro comercial é responsável por uma condição, uma cópia em outro sistema não deveria alterá-la silenciosamente. Podem existir dados derivados e cópias úteis, mas o projeto precisa explicar como são atualizados e como divergências são resolvidas.
Também diferencie leitura e escrita. Consultar uma situação não tem a mesma consequência de criar uma cobrança ou aprovar um pedido. Permissões, validações e evidências devem acompanhar a operação. O fornecedor não deve receber acesso amplo apenas porque isso facilita um teste inicial.
Exemplo resolvido e transferência de contexto
A Horizonte quer criar uma solicitação quando uma contratação é confirmada. A origem envia a referência do contrato e o tipo de serviço. O destino valida os dados, relaciona o cliente e devolve a referência da solicitação. O aceite comercial permanece na origem apropriada; a integração não inventa uma aprovação ausente.
Em um ERP B2B, uma confirmação de pedido pode iniciar uma etapa logística. A mensagem precisa distinguir pedido recebido, aprovado e pronto para expedição. Nomes parecidos não representam o mesmo evento.
Parte do acordo
Exemplo
Pergunta de verificação
Origem
Contratação confirmada
Quem comprova esse estado?
Identidade
Contrato e evento de origem
Como reconhecer repetição?
Dados
Cliente, serviço e condições
Quais campos são necessários?
Destino
Solicitação registrada
Qual referência confirma o efeito?
Falha
Pendência de integração
Quem acompanha e como retoma?
Roteiro para aplicar
Escolha uma troca e escreva o evento em linguagem de negócio.
Identifique a origem responsável por cada campo.
Defina os identificadores e os dados mínimos.
Descreva a confirmação e a condição de falha.
Valide limites de acesso e de uso com o fornecedor.
OFICINA INDIVIDUAL
Construa uma parte do seu dossiê
Descreva uma integração com origem, destino, evento, identificadores e confirmação esperada.
Entregável: Contrato de integração em linguagem de negócio.
Use o caso fictício da Horizonte ou dados autorizados do seu contexto. Registre uma incerteza e quem pode esclarecê-la. A resposta deve permitir que outra pessoa entenda a decisão sem depender de sua explicação oral.
Conferir referência e critérios
Origem informa contratação confirmada; integração relaciona o contrato; destino cria a solicitação e devolve sua referência; falha deixa uma pendência acompanhável.
Origem e destino são conhecidos
O evento tem significado claro
Existe confirmação além do envio
Para elevar a qualidade: acrescente o contexto, uma condição de exceção e o próximo passo de validação. O modelo orienta o raciocínio; não precisa ser copiado.
Explique com suas palavras qual decisão esta aula ajuda a tomar. Indique o que você já pode aplicar e o que ainda depende de uma pessoa, dado ou acesso.
Seu objetivo: Matriz de recuperação com responsável.
A confirmação pode se perder depois do efeito. Ampliar o mapa
Uma resposta pode se perder depois de uma ação externa ter ocorrido. Repetir automaticamente não é sempre seguro. O projeto deve reconhecer a mesma solicitação e investigar resultados incertos antes de criar outro efeito.
No caso da Horizonte, criar uma tarefa e enviar uma confirmação são etapas distintas. Se apenas a mensagem falhar, reiniciar tudo não pode duplicar a tarefa. A automação precisa guardar referências e retomar a parte pendente.
O n8n pode coordenar fluxos e tratamento de erros. Ainda assim, o registro de negócio precisa mostrar o que está pendente. Uma execução concluída pode apenas ter encaminhado uma exceção; uma execução falha pode ter produzido efeitos antes da interrupção.
Peça testes com evento repetido, dados incompletos, atraso e indisponibilidade. Defina também quem acompanha e quando a rotina deve parar. Uma fila que repete indefinidamente um problema não representa uma operação recuperável.
APROFUNDE O RACIOCÍNIO
Como pensar essa decisão na empresa
Sistemas podem receber eventos repetidos e perder confirmações. Uma rotina confiável precisa lidar com essas condições de forma explícita. Idempotência é a propriedade desejada de repetir uma solicitação reconhecida sem repetir indevidamente seu efeito. Sua implementação depende do contrato e dos sistemas envolvidos.
Não trate qualquer falha como motivo para repetir tudo. Um dado inválido pede correção; uma recusa legítima pede decisão; uma indisponibilidade temporária pode permitir tentativa controlada. Já um resultado desconhecido exige consulta ou conciliação antes de uma operação que possa produzir duplicidade.
No n8n, o desenho do fluxo deve incluir registros de execução, tratamento de erros e acompanhamento das pendências. O editor visual ajuda a compor etapas, mas não decide a política de recuperação. O empresário deve saber quem recebe o alerta, o que pode ser retomado e quais situações exigem intervenção.
Exemplo resolvido e transferência de contexto
O destino da Horizonte criou uma solicitação, mas a resposta não chegou à automação. O evento possui uma referência estável. A recuperação consulta essa referência e identifica o registro existente. A nova tentativa não cria uma segunda solicitação.
Em uma rotina de cobrança, repetir sem essa conferência pode produzir um efeito financeiro duplicado. O ensaio deve usar dados e ambiente de teste e mostrar a fronteira entre tentativa técnica e operação efetivamente confirmada.
Ocorrência
Tratamento a planejar
O que evitar
Evento repetido
Reconhecer a mesma referência
Criar outro registro
Campo inválido
Registrar motivo e solicitar correção
Repetição sem dado novo
Serviço indisponível
Tentativa limitada e acompanhamento
Espera infinita sem dono
Resultado desconhecido
Consultar e conciliar
Assumir sucesso ou fracasso
Roteiro para aplicar
Identifique quais efeitos não podem ser duplicados.
Defina referência de operação e política de tentativas.
Diferencie erro técnico, dado inválido e recusa de negócio.
Simule queda antes e depois de uma gravação.
Prepare um relatório de pendências que alguém consiga resolver.
OFICINA INDIVIDUAL
Construa uma parte do seu dossiê
Escreva o comportamento esperado em quatro falhas de sua integração.
Entregável: Matriz de recuperação com responsável.
Use o caso fictício da Horizonte ou dados autorizados do seu contexto. Registre uma incerteza e quem pode esclarecê-la. A resposta deve permitir que outra pessoa entenda a decisão sem depender de sua explicação oral.
Para elevar a qualidade: acrescente o contexto, uma condição de exceção e o próximo passo de validação. O modelo orienta o raciocínio; não precisa ser copiado.
Explique com suas palavras qual decisão esta aula ajuda a tomar. Indique o que você já pode aplicar e o que ainda depende de uma pessoa, dado ou acesso.
Seu objetivo: Política operacional de IA e base inicial de testes.
Contexto não é autorização para inventar fatos. Ampliar o mapa
Um agente pode produzir uma resposta convincente e incorreta. O projeto precisa definir fontes autorizadas, tarefas permitidas e situações de encaminhamento. A fluência do texto não comprova precisão, autorização ou aderência à política da empresa.
Na Horizonte, uma IA pode sugerir uma categoria e resumir a solicitação. A descrição original deve ser preservada. Se a interpretação estiver incerta, a equipe precisa de uma forma de revisar, em vez de receber uma classificação apresentada como fato.
Separe leitura, sugestão e execução. Consultar informações tem um efeito diferente de alterar preço, conceder acesso ou enviar uma mensagem. A autorização deve considerar o impacto da ação, com conferência humana quando apropriado ao risco.
Monte exemplos de avaliação antes de ampliar. Inclua informações ausentes, contradições e pedidos fora do escopo. Meça qualidade e retrabalho por tarefa resolvida. O número de respostas geradas pode crescer enquanto o atendimento piora, se a equipe precisa corrigir continuamente o conteúdo.
APROFUNDE O RACIOCÍNIO
Como pensar essa decisão na empresa
IA pode interpretar linguagem, classificar conteúdo e apoiar a elaboração de respostas. Ela não deve ser tratada como origem automática de preço, prazo, permissão ou compromisso. Essas informações precisam de fontes e regras apropriadas ao processo. O projeto define quando o modelo sugere e quando a aplicação pode executar.
Monte uma base de avaliação com situações representativas: entrada incompleta, informação contraditória, conteúdo sem resposta e tentativa de acesso indevido. A qualidade não aparece apenas em perguntas escolhidas para uma demonstração. Compare a saída com critérios e registre os motivos de revisão humana.
Conhecimento, memória e ferramentas têm papéis distintos. Conhecimento fornece material de referência; memória guarda contexto relevante da interação; ferramentas consultam ou operam sistemas. Nenhum desses componentes autoriza inventar uma reunião, aplicar uma condição antiga a outro cliente ou considerar um exemplo de proposta como regra universal.
Exemplo resolvido e transferência de contexto
Um agente da Horizonte recebe “preciso de ajuda com meu processo”. Ele começa esclarecendo segmento, objetivo e situação atual. Um contrato usado como exemplo serve para entender estrutura, não para afirmar que aquele cliente já aprovou valor ou reunião. Um compromisso só é confirmado quando existe evidência e autorização.
Em uma consultoria financeira, o agente pode organizar dúvidas e localizar documentos permitidos. Decisões e cálculos relevantes continuam sujeitos às fontes e validações definidas para o serviço.
Componente
Função
Controle necessário
Modelo
Interpretar e elaborar
Avaliação e limites
Conhecimento
Recuperar referência
Origem, vigência e acesso
Memória
Preservar contexto útil
Isolamento e retenção
Ferramenta
Consultar ou realizar ação
Permissão e confirmação
Humano
Decidir ou assumir exceção
Contexto e responsabilidade
Roteiro para aplicar
Defina uma tarefa específica em vez de pedir um agente que faça tudo.
Separe fatos confirmados, declarações e hipóteses.
Estabeleça fontes e operações autorizadas.
Teste casos normais, ausências e conflitos antes da liberação.
Meça resolução e retrabalho, além do número de mensagens.
OFICINA INDIVIDUAL
Construa uma parte do seu dossiê
Defina três tarefas permitidas, três proibidas sem aprovação e quatro casos de avaliação para um agente.
Entregável: Política operacional de IA e base inicial de testes.
Use o caso fictício da Horizonte ou dados autorizados do seu contexto. Registre uma incerteza e quem pode esclarecê-la. A resposta deve permitir que outra pessoa entenda a decisão sem depender de sua explicação oral.
Conferir referência e critérios
Permitido: sugerir categoria com fonte. Exige aprovação: conceder desconto ou confirmar prazo especial. Teste: cliente pede uma condição não prevista; agente deve reconhecer o limite e encaminhar.
Consulta e execução são diferenciadas
Limites são concretos
Os testes incluem incerteza e exceções
Para elevar a qualidade: acrescente o contexto, uma condição de exceção e o próximo passo de validação. O modelo orienta o raciocínio; não precisa ser copiado.
Explique com suas palavras qual decisão esta aula ajuda a tomar. Indique o que você já pode aplicar e o que ainda depende de uma pessoa, dado ou acesso.
O destino concluiu a operação e a automação perdeu a resposta. Depois, um humano resolveu o atendimento. Desenhe a retomada que reconhece ambos os fatos e não executa o trabalho novamente.
Como conduzir
Prepare uma versão inicial de contrato de integração e recuperação usando o modelo.
Execute a dinâmica do módulo com papéis separados. Se estiver sozinho, registre uma resposta por perspectiva antes de compará-las.
Introduza uma exceção: informação ausente, autoridade indisponível ou mudança de contexto.
Reveja a decisão e registre o que mudou, a evidência e o responsável pelo próximo passo.
Transferência para outros negócios
Em cobrança, evite duplicidade financeira; em estoque, movimentação repetida; em atendimento, mensagem atrasada após intervenção humana. Use apenas ambientes de teste para ensaiar efeitos.
Autoavaliação da entrega
Tentativa e conclusão estão separadas?
Existe identidade que atravessa os sistemas?
A recuperação considera o estado atual e ações humanas?
Use a escala do projeto: ausente, genérico, aplicável ou verificável. Uma lacuna crítica deve aparecer como pendência, mesmo que os demais itens estejam bem apresentados.
Discussão: O que você precisava registrar para não repetir o efeito?
Em estudo individual, represente os papéis separadamente e registre onde suas respostas entram em conflito. Em grupo, reserve aproximadamente 25 minutos e finalize com uma decisão documentada.
Entrega do projeto: Origem, destino, identidade, confirmação e recuperação.