n8n-nodes-syncro-crm

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

Oferece:

• Action Node Syncro CRM — CRUD de leads, tasks, pipelines + operações de WhatsApp, nurture sequences e campos personalizados.
• 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

| Operação | Descrição | |---|---| | Criar | Cria novo lead (valida limites de plano) | | Criar ou Atualizar | Upsert por email/phone — retorna created: true/false | | Listar | Filtros: pipeline, stage, assigned_to, source, tags, query (nome/email/phone), updated_since, criados de/até + paginação | | Buscar | Retorna 1 lead com relations | | Atualizar Etapa | Move o lead no funil (valida tarefas obrigatórias) | | Marcar como Ganho | Cria Sale, valida pending tasks | | Marcar como Perdido | Cria LostSale com reason_id opcional | | Adicionar Tags | CSV de tags → attachTagsByName | | Remover Tag | Por nome | | Inscrever em Sequência | Enroll idempotente (reusa NurtureSequenceService::enroll) | | Desinscrever de Sequência | Marca exited | | Enviar WhatsApp | Texto ou imagem, reusa Foundation SOLID (ChatIdResolver + WindowChecker + Factory + Persister) | | Enviar Template HSM | Cloud API, variáveis posicionais, header media opcional | | Deletar | Remove permanente |

Tarefa

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

Pipeline

Listar Tudo — retorna funis com stages + lost_reasons em árvore.

Campo Personalizado

Listar Definições — útil pra montar custom_fields no create/upsert de lead.

Sequência de Nutrição

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

WhatsApp

Listar Instâncias — mostra WAHA + Cloud API com flags de capability (supports_templates, has_window_restriction). Listar Templates HSM — com filtro por status/instance/language.

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.won
• lead.lost
• lead.deleted
• task.created
• task.updated
• task.completed
• conversation.message_received

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": "[email protected]",
    "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.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: [email protected]
• n8n docs: n8n.io/integrations