- Comece pelo resultado esperado e pelos critérios de sucesso (o que muda no processo).
- Defina gatilho e fonte de verdade (qual sistema manda).
- Mapeie dados: campos obrigatórios, formatos, normalizações e exemplos reais.
- Escreva regras e exceções (o que fazer quando faltar dado, duplicar ou der erro).
- Inclua limites: rate limit, janelas de execução, timeouts e custo por operação/execução.
- Planeje confiabilidade: idempotência, retries com backoff e fila/DLQ quando fizer sentido.
- Feche com observabilidade: logs, métricas e alertas acionáveis.
1) Declare o objetivo e o “done” (critério de sucesso)
Escreva em 2–3 linhas o que a automação vai mudar no processo. Depois, liste critérios verificáveis: exemplo: “lead criado no CRM em até X minutos após o formulário”, “sem duplicar contato”, “com registro de consentimento”. Se não dá para medir, vira discussão infinita durante a construção.
2) Defina o gatilho e a fonte de verdade
Escolha o gatilho (webhook, polling, evento) e declare qual sistema é o master de cada dado (ex.: e-mail vem do formulário, telefone vem do WhatsApp/CRM). A maior parte das automações quebra por conflito de ‘quem manda’ em campos como status, dono do lead, tags e estágio de funil.
3) Especifique entradas, saídas e contrato de dados
Liste os campos de entrada (obrigatórios/opcionais), exemplos reais e validações (DDD, CPF/CNPJ, moeda, timezone). Faça o mesmo para as saídas: o que será criado/atualizado e com quais chaves. Sempre inclua qual ID será usado para correlacionar registros entre sistemas.
4) Escreva regras de negócio como condições simples
Transforme ‘regras’ em if/else claros: “Se o lead já existir, atualizar; se não existir, criar”. Inclua também regras de roteamento (ex.: região → vendedor), prioridades e janelas de atendimento. Evite texto vago: descreva exatamente qual campo decide a regra.
5) Planeje erros, retry e deduplicação (idempotência)
Defina o que é erro recuperável (429, timeouts, 5xx) e o que é erro de dado (campo inválido). Para recuperáveis, descreva retry com backoff e limite de tentativas. Para duplicação, defina chave idempotente (ex.: order_id + event_type) e o comportamento ao receber o mesmo evento duas vezes.
6) Observabilidade: logs, alertas e reprocessamento
Defina quais eventos devem ser logados (sucesso/erro), o que vai no log (ids, payload resumido, stack/erro) e quais alertas importam (ex.: ‘fila acumulando’, ‘taxa de erro acima do normal’, ‘integração X sem resposta’). Inclua como reprocessar com segurança sem duplicar ações.
7) Testes e plano de rollout
Liste casos de teste com dados de exemplo: caminho feliz, dado faltando, duplicado, API fora, rate limit. Defina rollout: começar com um subset (um canal, um vendedor, uma loja) e como fazer rollback. Se a automação mexe com dinheiro/estoque, trate rollout como mudança de produção — sem improviso.
Modelo de spec (copie e cole)
Use este esqueleto como ponto de partida. A ideia não é burocracia: é reduzir as “surpresas” que aparecem depois que o fluxo entra em produção.
Título do workflow:
Dono (responsável pelo processo) / Responsável técnico:
Objetivo (2–3 linhas):
Critérios de sucesso (bullet points):
Gatilho (webhook/polling/evento) + frequência:
Sistemas envolvidos + fonte de verdade por campo:
Entradas (campos, exemplos, validações):
Saídas (o que cria/atualiza, chaves, ids):
Regras de negócio (if/else):
Erros e exceções (por tipo):
Retry/backoff e limites:
Idempotência/deduplicação (chave e comportamento):
Logs e alertas:
Casos de teste:
Rollout e rollback:
Checklist rápido: o que não pode faltar
Se você só tiver 30 minutos para revisar um spec antes de construir, passe por esta lista. Ela cobre os pontos que mais geram retrabalho em n8n/Make/Zapier.
- Existe um ID único para correlacionar registros entre sistemas?
- Está claro quando é “criar” vs “atualizar”?
- O que acontece quando a API responde 429 (rate limit) ou dá timeout?
- Há risco de o mesmo evento chegar duas vezes? Qual é a chave idempotente?
- Qual dado é obrigatório para seguir o fluxo? E se não vier?
- Quem será avisado quando falhar (e com qual informação para agir)?
- O reprocessamento foi pensado para não gerar duplicidade (pedido, cobrança, mensagem)?
Tabela: decisões de design que mudam tudo (e pouca gente escreve)
Abaixo estão decisões que parecem “detalhe”, mas determinam se o workflow vai escalar ou virar um festival de correções manuais.
| Decisão no spec | Opções comuns | Quando escolher | Risco se ignorar |
|---|---|---|---|
| Gatilho | Webhook vs polling | Webhook quando precisa de tempo real; polling quando a API não entrega evento confiável | Atraso, duplicidade, buracos de dados |
| Chave idempotente | order_id, message_id, lead_email+source, event_id | Sempre que houver reenvio, retry, ou eventos repetidos do provedor | Duplicar pedidos, cobranças, tarefas e mensagens |
| Retry/backoff | Tentativas limitadas + espera crescente | Quando há rate limit, instabilidade e timeouts | Loop de falhas, bloqueio por abuso, custos maiores |
| Fonte de verdade | CRM manda no status; ERP manda no estoque; e-commerce manda no pedido | Quando dois sistemas podem editar o mesmo campo | “Guerra” de atualizações e dados inconsistentes |
| Estratégia de reprocessamento | Reprocessar com lock/dedup vs reexecutar tudo | Quando a automação executa ações irreversíveis (mensagens, pagamentos, NF) | Efeito cascata: duplicar ações em massa |
Exemplo curto (realista): lead do formulário → CRM → WhatsApp
Objetivo: cadastrar lead no CRM e disparar mensagem de confirmação no WhatsApp apenas uma vez.
Gatilho: webhook do formulário (evento por envio).
Entrada mínima: nome, telefone (E.164 ou com DDD padronizado), consentimento (sim/não), origem/campanha.
Regra: se consentimento ≠ sim, criar lead no CRM sem mensagem; se sim, enviar WhatsApp e salvar message_id no CRM.
Idempotência: chave = form_submission_id. Se chegar repetido, não envia WhatsApp novamente; apenas confirma/atualiza o lead.
Erros: 429 no WhatsApp → retry com backoff; telefone inválido → marcar lead como “pendente de correção” e alertar.
Perguntas frequentes
Spec de automação precisa ser documento formal?
Qual é o tamanho ideal de um spec para n8n/Make/Zapier?
Como decidir entre webhook e polling no spec?
O que colocar no spec quando não sei os limites de rate limit da API?
Leia também
Como desenhar uma arquitetura de automação com filas, retry e idempotência (sem virar gambiarra)
Guia prático para desenhar automações resilientes: quando usar filas, como fazer retry/backoff, idempotência e DLQ. Evite duplicar pedidos, estourar rate limit e cair em loop infinito em n8n/Make/Zapier.
Ler →
Webhook ou polling em automações: como escolher (sem perder eventos e sem estourar limites)
Guia direto para decidir entre webhook e polling: latência, confiabilidade, custo por execução, rate limit e como evitar duplicidades. Inclui tabela e checklist prático.
Ler →
Como fazer idempotência em automações com webhook (e parar de duplicar pedidos, notas e leads)
Guia direto para aplicar idempotência em automações com webhook: chaves idempotentes, deduplicação, banco/planilha, retries e boas práticas para n8n/Make/Zapier.
Ler →
Como monitorar automações (n8n, Make e Zapier): alertas, logs e erros sem virar refém do “falhou e ninguém viu”
Guia prático para monitorar automações em n8n, Make e Zapier: quais alertas criar, como registrar logs, tratar erros, retries e evitar falhas silenciosas.
Ler →