Description

n8n-nodes-arco-crm

n8n community node para o Arco CRM via Public API.

Permite criar workflows automatizados consumindo a API do Arco CRM — leads, deals, pessoas, organizações, atividades, notas, tags, pipelines, memberships, origens e tipos de atividade — com seleção por dropdown (sem precisar colar UUIDs).

Instalação

Na sua instância n8n:

1. Vá em Settings → Community Nodes.
2. Clique em Install e digite n8n-nodes-arco-crm.
3. Aceite os riscos (n8n exige confirmação explícita para community nodes) e instale.

Configuração

1. Crie uma chave de API no Arco CRM (Configurações → API Keys), com os escopos necessários:
– leads:read, leads:write
– deals:read, deals:write
– people:read, people:write
– organizations:read, organizations:write
– activities:read, activities:write
– notes:read, notes:write
– tags:read
– origins:read
– memberships:read
– activity_types:read
– loss_reasons:read

> Lead Pipelines reusa leads:read. Deal Pipelines reusa deals:read. Não existe scope pipelines:read dedicado.
2. No n8n, crie uma credencial Arco CRM API:
– Base URL: https://crm.grupoarco.cc/api (ou a URL da sua instância)
– API Key: a chave ark_… gerada
3. Use o botão Test para validar.

> Se algum dropdown ficar vazio (Origin, Membership, Loss Reason) é porque o scope correspondente está ausente na sua API key — o node trata SCOPE_DENIED silenciosamente para não quebrar o formulário inteiro.

Recursos suportados

| Recurso | Operações |
|—|—|
| Lead | Create · Get · List · Update · Change Stage · Disqualify · Convert · Convert Preview · Claim · Stage History · List/Add/Remove Tags |
| Deal | Create · Get · List · Update · Change Stage · Mark Won · Mark Lost · Reopen · Claim · Stage History · List/Add/Remove Tags |
| Person | Create · Get · List · Update · Claim |
| Organization | Create · Get · List · Update · Claim |
| Activity | Create · Get · List · Update · Complete |
| Activity Type | List (read-only) |
| Note | Create · Get · List · Update |
| Tag | List (read-only) |
| Pipeline | List (Lead ou Deal, com Include Stages opcional) |
| Membership | List · Get (read-only) |
| Origin | List · Get (read-only) |
| Lookup | Find (busca exata por telefone, e-mail, CPF ou CNPJ em leads, pessoas e organizações) |

Todas as operações usam o contrato /v1/* da Public API.

Lookup (deduplicação)

O recurso Lookup (GET /v1/lookup) localiza leads, pessoas e organizações por chave exata — Phone, Email, CPF ou CNPJ — após normalização feita pela API (máscara removida, DV de CPF/CNPJ validado, telefone brasileiro casa com e sem o nono dígito). Pelo menos uma chave é obrigatória; várias chaves combinam por OR e cada resultado informa em matched_by quais casaram.

• Types escolhe quais entidades buscar (padrão: todas). Cada tipo exige o scope {tipo}:read:all na API key.
• Limit Per Type vale por tipo (padrão 10, máx. 50). O endpoint não tem cursor, então não há Return All.
• Split Into Items transforma a resposta agrupada (data.leads, data.people, data.organizations) em um item por registro encontrado, com um campo type — útil para ramificar “já existe / não existe” com um IF logo depois.

Dropdowns inteligentes

Campos que referenciam outras entidades (organizationid, personid, pipelineid, stageid, leadpipelineid, leadstageid, ownermembershipid, disqualificationreasonid, lossreasonid, origin_id etc.) oferecem 3 modos:

• From List — dropdown paginado com busca por nome.
• By ID — UUID direto, útil em loops e expressions.
• By URL — cola o link da UI do CRM; o node extrai o UUID.

Selects de Stage dependem do Pipeline correspondente — escolha o pipeline primeiro para que os stages carreguem.

Idempotência

As operações Create de Lead, Deal, Person, Organization, Activity e Note têm um campo opcional Idempotency Key. Quando preenchido, é enviado no header Idempotency-Key:

• A mesma chave + o mesmo body em até 24h retornam a resposta original — evita duplicatas em retries (timeout, re-execução do workflow).
• A mesma chave com body diferente retorna 409 IDEMPOTENCY_CONFLICT.

Use um valor estável por requisição lógica (ex.: um UUID derivado do registro de origem). Deixe vazio para desativar.

Desenvolvimento

pnpm install
pnpm dev      # sobe n8n local em :5678 com o node linkado
pnpm lint
pnpm build

Changelog

0.8.0

• Novo recurso Lookup (GET /v1/lookup): operação Find que localiza leads, pessoas e organizações por telefone, e-mail, CPF ou CNPJ (chaves combinam por OR; matched_by indica quais casaram). Campos Types, Limit Per Type e a opção Split Into Items (um item por registro, com type). O node valida “pelo menos uma chave” antes de chamar a API e só envia as chaves preenchidas.

0.6.2

• Fix (definitivo): operações POST sem corpo (Reopen, Claim de Lead/Deal) ou com campos opcionais vazios (Disqualify, Mark Won, Mark Lost) falhavam com Body cannot be empty when content-type is set to 'application/json'. Causa raiz: o header Content-Type: application/json era fixado em toda requisição. Agora o node usa json: true, então o header só é enviado quando há corpo — requisições sem corpo não disparam mais o erro. (A tentativa da 0.6.1 via body: {} não resolvia porque o n8n descarta corpos vazios antes de enviar.)

0.6.1

• Tentativa de correção do erro de corpo vazio via body: {} (substituída pela 0.6.2).

0.6.0

• Mover Lead/Deal de funil no Change Stage: o campo Lead Pipeline (Lead) e Deal Pipeline (Deal) do Change Stage agora é enviado no corpo (leadpipelineid / pipeline_id). Escolha um pipeline diferente para mover a entidade para outro funil (precisa estar open); mantenha o atual — ou deixe vazio — para apenas trocar de estágio. Retrocompatível: só é enviado quando preenchido, então workflows que só mudam de etapa continuam idênticos.
• Nova operação Reopen no Lead (POST /v1/leads/:id/reopen): reverte um lead disqualified para open, preservando a etapa atual. Espelha o Reopen já existente em Deal.

0.5.0

• Novo recurso Campaign (API v1.10, scopes campaigns:read:all / campaigns:operate:all): List, Get, Get Stages, Get Summary, List Participants (filtros Stage/Outcome), Add Participants (listas de Lead IDs / Person IDs + Force), Change Participant Stage, Qualify Participant (payload JSON, kind-aware), Disqualify Participant (Loss Reason / Comment) e Remove Participant. Dropdowns From List para Campaign e Campaign Stage (a etapa lê a campanha escolhida no formulário).
• Campo Campaign no Create de Lead e Person: resourceLocator (From List / By ID / By URL) que envia campaignid, criando o registro já vinculado como participante na primeira etapa da campanha. Requer também o scope campaigns:operate:all; a operação é atômica (rollback se o vínculo falhar). Disponível apenas no Create — a API não aceita campaignid no update.

0.4.0

• Busca textual nas listagens (List) de Lead, Deal, Person, Organization e Membership via o novo parâmetro search da API (substring, case-insensitive, combinado com os demais filtros via AND, máx. 200 caracteres). Lead/Person buscam por nome, e-mail ou telefone; Deal por título; Organization por nome; Membership por e-mail.
• Dropdowns (From List) agora buscam no servidor para Lead, Deal, Person e Organization: em vez de carregar os primeiros 50 registros e filtrar no navegador, enviam ?search= e pesquisam a base inteira. O debounce do campo é feito pelo próprio editor do n8n. Tags, Origins, Pipelines, Stages, Loss Reasons e Membership seguem com filtro local (o backend não expõe search neles, ou — no caso de Membership — só busca por e-mail enquanto a lista exibe o nome).

0.3.0

• Idempotency Key opcional nas operações Create de Lead, Deal, Person, Organization, Activity e Note (header Idempotency-Key, TTL 24h). Vazio = comportamento anterior.

0.2.0

Cobertura completa do contrato /v1/* (após o backend expor deal-pipelines, loss-reasons e o ciclo completo de Deal).

Novos recursos

• Deal: Change Stage, Mark Won, Mark Lost, Reopen, Claim, Stage History, List/Add/Remove Tags.
• Dropdowns de Deal Pipeline e Deal Stage em Deal (Create/List/Change Stage) e em Lead Convert.
• Dropdowns de Lead Pipeline e Lead Stage no filtro de Lead List.
• Dropdown de Loss Reason em Lead Disqualify e Deal Mark Lost.
• Pipeline → List aceita Type (lead ou deal) para escolher o endpoint.

Correções

• Dropdowns sem scope (Origin, Membership, Loss Reason) ficam vazios em vez de pintar vermelho. O erro SCOPE_DENIED deixa de poluir o formulário.
• Busca em Lead/Person/Organization/Deal passa a filtrar no cliente (o backend ignorava ?search=).

Breaking changes

• pipelineid / stageid no Deal Create deixam de ser string e viram resourceLocator (3 modos: From List / By ID / By URL). Workflows existentes preservam o UUID via modo “By ID”.
• leadpipelineid no filtro de Lead List idem.
• dealpipelineid / dealstageid no Lead Convert idem.
• disqualificationreasonid no Lead Disqualify idem.
• Pipeline → List agora exige escolher Type (default Lead Pipelines mantém o comportamento anterior).

0.1.2

Alinhamento à Public API v1.4.9.3.

Novos recursos

• Membership, Origin, Activity Type (read-only).
• Dropdown de Owner Membership em Lead, Deal, Person, Organization e Activity.
• Pipeline → List aceita Include Stages para retornar stages embutidos.

Breaking changes (rotas/campos que não existem no contrato público /v1/*)

• Tag: removidas operações Create, Update, Delete (Tag agora é read-only).
• Activity: removidas Delete e Uncomplete. Campo activitytypeid renomeado para typeid; description renomeado para notes; ownermembershipid agora é obrigatório no Create; filtros dueafter/due_before removidos; status removido do Update.
• Note: removida operação Delete. Campo body renomeado para content.
• Pipeline: removidas Get e List Stages (use List com Include Stages: true). Agora aponta para /v1/lead-pipelines (deal pipelines não eram expostos pela Public API).
• Deal: campo name renomeado para title (Create e Update).

Correções

• Todas as rotas internas (/activities, /notes, /tags, /pipelines, /origins, /activity-types) migradas para o prefixo público /v1/.

Licença

MIT