n8n-nodes-syncro-crm

Pacote oficial de nodes n8n para integrar com o Syncro CRM.

Oferece:

• Action Node Syncro CRM — 52 operações em 9 recursos: leads, tarefas, pipelines, automações, chatbots, WhatsApp, campos personalizados, sequências de nutrição e dados da conta. Cobre todos os endpoints da API v1.
• Trigger Node Syncro CRM Trigger — dispara workflows em tempo real quando eventos acontecem no CRM (lead criado, mudou de etapa, tarefa concluída, etc). Zero polling.

Instalação

Self-hosted n8n

Settings → Community Nodes → instalar n8n-nodes-syncro-crm.

npm (dev local)

cd ~/.n8n/custom
npm i n8n-nodes-syncro-crm

Credenciais

1. No Syncro CRM: /configuracoes/api-keys → criar API Key com os scopes necessários:

   • leads:read, leads:write — pra manipular leads
   • pipelines:read — sempre necessário (pro loadOptions do node)
   • tasks:read, tasks:write — pra manipular tarefas
   • custom_fields:read — pra popular custom fields no create/upsert
   • sequences:read — pra listar nurture sequences
   • whatsapp:read, whatsapp:write — pra enviar mensagens e templates
   • webhooks:read, webhooks:write — obrigatório pro Trigger Node
   • Ou * pra dar todos

2. No n8n: Credentials → New → Syncro CRM API:

   • Base URL: https://app.syncro.chat (ou sua instância)
   • API Key: cola o token (crm_xxxxxxx...)

Recursos & Operações (Action Node)

Lead

Tarefa

CRUD completo + Marcar como Feita/Pendente (toggle). Filtros por status, type, priority, lead_id, assigned_to, due_from/to.

Pipeline

Automação

Automação criada pela API nasce sempre inativa. Ativar é passo separado, porque uma automação ativa manda WhatsApp pra cliente de verdade.

Antes de enviar de verdade, marque Só Validar (Dry-Run): a API devolve os erros apontando o caminho exato (actions[2].config.tags) sem escrever nada.

Chatbot

Mesmas operações da automação (sem modelos). Duas regras da API valem lembrar: o canal é imutável depois de criado, e Atualizar substitui o grafo inteiro — busque antes e mande completo.

Campo Personalizado

Sequência de Nutrição

Listar — enroll/unenroll rodam em Lead, não aqui.

WhatsApp

Conta

Trigger Node (tempo real)

Registra uma webhook subscription no Syncro CRM automaticamente. Quando o evento acontece, o CRM faz POST na URL do n8n. Sem polling, sem delay, sem queimar rate limit.

Eventos suportados

• lead.created
• lead.updated
• lead.stage_changed
• lead.assignment_changed
• lead.won
• lead.lost
• lead.tags_changed
• lead.merged
• lead.deleted
• sale.created
• note.added
• nps.answered
• task.created
• task.updated
• task.completed
• conversation.message_received — declarado pela API mas ainda não emitido; inscrever não dá erro e também não dispara nada

Segurança

O CRM assina cada payload com HMAC-SHA256 usando um secret gerado na criação da subscription. O trigger node valida o header X-Syncro-Signature com timing-safe comparison antes de disparar o workflow. Pode desativar a validação (não recomendado).

Lifecycle

• Ao ativar o workflow: POST /api/v1/webhooks cria a subscription no CRM
• Ao desativar: DELETE /api/v1/webhooks/{id} remove automaticamente
• Re-attach: se a URL do webhook já existe no CRM (activation+deactivation repetido), reaproveita

Formato do payload

{
  "event": "lead.stage_changed",
  "tenant_id": 260,
  "emitted_at": "2026-04-23T16:30:00-03:00",
  "data": {
    "id": 12602,
    "name": "Maria Silva",
    "email": "maria@example.com",
    "previous_stage_id": 4,
    "new_stage_id": 7,
    "new_stage_name": "Proposta enviada",
    // ... demais campos do lead
  }
}

Exemplos de workflow

1. Sincronizar lead novo pro Google Sheets

Syncro CRM Trigger (lead.created)
  → Set (map fields)
  → Google Sheets: Append Row

2. Enviar WhatsApp quando lead vira "Proposta enviada"

Syncro CRM Trigger (lead.stage_changed)
  → IF {{ $json.data.new_stage_name === 'Proposta enviada' }}
  → Syncro CRM (Lead > Enviar Template HSM)

3. Importar contatos de um CDP externo (upsert em batch)

HTTP Request (GET contatos CDP)
  → Split In Batches
  → Syncro CRM (Lead > Criar ou Atualizar, match_by: email)

4. Criar tarefa de follow-up quando lead não responde

Syncro CRM Trigger (conversation.message_received)
  → Wait 24h
  → IF (lead ainda não respondeu)
  → Syncro CRM (Tarefa > Criar)

Changelog

2.1.0 (2026-08-10)

Alinha o node com tudo que a API v1 ganhou desde a 2.0. Puramente aditivo — nenhum parâmetro foi renomeado, então workflow salvo continua funcionando sem tocar em nada.

• Recursos novos: Automação (9 operações), Chatbot (7) e Conta (dados da conta + listar usuários).
• Pipeline saiu de 1 operação para 8: CRUD completo, modelos e regras.
• Lead ganhou ?include= — traz responsável, produtos, notas, tarefas, vendas, score, histórico e conversa junto, em vez de uma chamada por relação. Sem nada marcado a resposta é idêntica à de antes.
• Lead aceita responsável, utm_id e os click ids fbclid / fbc / gclid.
• Campo Personalizado ganhou Criar (idempotente por rótulo).
• WhatsApp ganhou Listar Grupos.
• Trigger ganhou 6 eventos: mudança de responsável, tags alteradas, lead mesclado, venda registrada, nota adicionada e NPS respondido.
• Cobertura: o node passa a chamar os 39 endpoints da API v1 (era 24).
• npm run lint limpo (eram 27 erros herdados). Três regras do ruleset da comunidade ficaram desligadas com o motivo escrito no .eslintrc.js — o autofix delas quebrava a marca "WhatsApp" nas ações e camelCasava a URL da credencial.

2.0.0 (2026-04-23)

• BREAKING: remove resource Campaign (módulo Campanhas foi removido do Syncro em abr/2026)
• Adiciona resources: Task, Custom Field, Nurture Sequence, WhatsApp
• Adiciona ~15 novas operations em Lead: list (com filtros + updated_since), upsert, addTags, removeTag, enrollSequence, unenrollSequence, sendWhatsapp, sendWhatsappTemplate
• Novo node de trigger Syncro CRM Trigger — webhook em tempo real com HMAC
• Refactor completo: monolito de 678 linhas virou main node enxuto + descriptions por resource + GenericFunctions.ts
• tsconfig strict, zero any, types completos
• Helper syncroApiRequest com retry exponencial em 408/429/5xx
• Cache de loadOptions (pipelines) in-memory — 1 chamada em vez de 5 ao abrir o form
• README, ESLint, Prettier, GitHub-friendly

1.0.1

• CRUD básico de Lead, Campaign (deprecated), Pipeline

License

MIT

Links

• Syncro CRM: app.syncro.chat
• Support: contato@syncro.chat
• n8n docs: n8n.io/integrations