n8n Community Node

n8n é uma ferramenta low-code de automação (alternativa ao Zapier, Make). O Syncro tem Community Node oficial publicado no npm — você instala em qualquer instância n8n (self-hosted ou Cloud) e ganha 7 actions + 1 trigger pra integrar com qualquer outro sistema. Esse artigo cobre instalação e uso.

Pré-requisitos

• Permissão admin no Syncro.
• Plano Starter, Growth ou Scale (n8n não vem no Trial).
• Conta n8n ativa (self-hosted ou Cloud).
• Acesso de admin no n8n pra instalar Community Nodes.

Sobre o card no Syncro

Em Configurações → Integrações, categoria Automação, tem o card n8n.

⚠️ Atenção: card é info-only — não tem OAuth nem credentials. Apenas instruções de instalação no n8n + link pra criar API Key. A integração acontece dentro do n8n.

Instalação no n8n

1. Acesse seu n8n

• Self-hosted: https://seu-n8n.dominio.com.
• n8n Cloud: https://app.n8n.cloud.

2. Configurações → Community Nodes

1. Menu Settings (canto inferior).
2. Community Nodes.
3. Botão Install Community Node.

3. Cole o nome do pacote

Pacote: n8n-nodes-syncro-crm

1. Cole no input.
2. Marque I understand the risks (n8n exige consentimento por ser node de terceiro).
3. Clique em Install.

4. Aguarde reinício

n8n leva ~30s pra instalar e reiniciar automaticamente. Quando volta, node está disponível.

5. Gerar API Key no Syncro

1. Volte pro Syncro → Configurações → API Keys.
2. Nova chave:

• Nome: "n8n Production" (ou similar).
• Permissões: marque o que precisa (leads, tasks, mensagens, etc).

3. Crie a chave.
4. Copie o token gerado (só aparece uma vez).

Veja Gerar API Key.

6. Criar credential no n8n

1. n8n → Credentials → New.
2. Buscar Syncro CRM API.
3. Configurar:

• API Key: cole o token.
• Base URL: https://app.syncro.chat/api/v1.

4. Save.

7. Usar nos workflows

Criar workflow novo → arrastar Syncro CRM node → escolher action.

Actions disponíveis (7)

1. Create Lead

Cria lead novo.

Action: Create Lead
Body:
 name: "Maria Silva"
 email: "[email protected]"
 phone: "+5511987654321"
 pipeline_id: 1
 stage_id: 5
 tags: ["webform", "alta-prioridade"]

2. Update Lead

Atualiza lead existente.

Action: Update Lead
Lead ID: 1234
Body:
 email: "[email protected]"
 stage_id: 8

3. List Leads

Lista leads com filtros + paginação.

Action: List Leads
Query:
 pipeline_id: 1
 search: "maria"
 per_page: 50
 page: 1

4. Add Tags

Adiciona uma ou mais tags.

Action: Add Tags
Lead ID: 1234
Tags: ["urgente", "vip"]

5. Remove Tag

Remove uma tag específica.

Action: Remove Tag
Lead ID: 1234
Tag: "lead-frio"

6. Upsert Lead

Cria ou atualiza match por email/telefone.

Action: Upsert Lead
Match by: email
Body:
 email: "[email protected]"
 name: "Maria Silva"
 phone: "+5511987654321"

Útil pra evitar duplicatas quando dado vem de fonte externa.

7. Delete Lead

Remove lead.

Action: Delete Lead
Lead ID: 1234

Trigger — Webhook inbound

Pra disparar workflow n8n quando algo acontece no Syncro:

1. n8n: arrastar Syncro CRM Trigger.
2. Escolher evento:

• lead.created
• lead.updated
• lead.deleted
• task.created
• task.updated
• task.completed

3. Configurar credential.
4. Ativar workflow → n8n gera URL única de webhook.
5. Sistema inscreve automaticamente no Syncro via API.
6. Cada vez que evento dispara, n8n recebe payload + processa.

Casos de uso

Cenário 1 — Sincronizar com Google Sheets

n8n workflow:

1. Trigger: lead.created.
2. Action Sheets: append row com dados do lead.

Resultado: planilha com histórico completo de leads.

Cenário 2 — Notificação Slack quando lead VIP

n8n:

1. Trigger: lead.created.
2. IF condition: lead.value > 10000 AND tags includes "vip".
3. Slack: post message no canal #vendas.

Cenário 3 — Sincronizar com Mailchimp

1. Trigger: lead.created.
2. Action Mailchimp: add subscriber to list.

Lead novo no CRM → automaticamente em sequência de e-mail.

Cenário 4 — Disparar follow-up baseado em sistema externo

Sistema X chama webhook do n8n → n8n cria task no Syncro com Action Create Lead depois cria task vinculada.

Permissões da API Key

A key herda permissões do user dono. Configure scopes específicos:

• ✅ Leads: ler, criar, atualizar, deletar.
• ✅ Tasks: ler, criar, atualizar.
• ✅ Conversations: ler.
• ✅ Mensagens WhatsApp: enviar.
• ✅ Webhooks: gerenciar inscrições.

Webhook trigger — segurança

Pra cada webhook outbound (Syncro → n8n), payload assinado com HMAC-SHA256:

• Header X-Syncro-Signature-256.
• Secret é cada subscription (gerado pelo node n8n automaticamente).
• n8n valida automaticamente.

💡 Dica: nunca exponha a URL do webhook publicamente — é um endpoint não-autenticado fora da assinatura.

Limites

• Rate limit: 60 requests/min por API Key (default).
• Webhook retry: 4 tentativas com backoff exponencial em caso de falha.
• Sem limite de subscriptions por tenant.

Versão atual e atualizações

• npm: [email protected].
• Versionamento semver.
• Atualizações se aplicam ao reinstalar o community node no n8n.

Link: npmjs.com/package/n8n-nodes-syncro-crm

Erros comuns

"Community Node not found"

• Verifique se digitou nome correto: n8n-nodes-syncro-crm.
• Sua versão do n8n suporta community nodes (n8n 0.180+).

"Invalid API Key"

• Token errado ou copiado parcialmente.
• API Key foi revogada no Syncro.
• Permissões insuficientes pra action específica.

"Connection refused / timeout"

• Base URL errada — confirme https://app.syncro.chat/api/v1.
• n8n não tem conexão de saída (firewall corporativo bloqueando?).

"Webhook não dispara"

• Workflow n8n não está ativo — clique em "Activate" no canto superior direito.
• API Key tem permissão de webhooks?
• Verifique no Syncro /configuracoes/webhooks se subscription ainda existe.

"Rate limit hit"

• 60 req/min por key. Distribua entre múltiplas keys se preciso de mais throughput.

Próximos passos

• Pra configurar API Key, veja Gerar API Key.
• Pra entender endpoints da API, veja Endpoints disponíveis.
• Pra webhooks de saída, veja Webhooks de saída.

Artigos relacionados

• Gerar API Key
• Endpoints disponíveis
• Webhooks de saída
• Assinatura HMAC