n8n-nodes-sherlock

Nós da comunidade n8n para o Sherlock CRM:

• Sherlock CRM: todas as 53 rotas da API pública (/api/public/v1) em 20 recursos.
• Sherlock CRM Trigger: recebe os webhooks do Sherlock e verifica a assinatura HMAC.

Instalação · Credenciais · Operações ·
Webhooks · Comportamentos ·
Desenvolvimento

Instalação

No n8n self-hosted: Settings › Community Nodes › Install e informe n8n-nodes-sherlock
(guia).

O pacote é publicado sem provenance (o repositório é privado), então não é um nó
verificado: a instância precisa aceitar pacotes não verificados
(N8N_UNVERIFIED_PACKAGES_ENABLED=true, cujo padrão está mudando nas versões recentes do n8n).
Não é instalável no n8n Cloud.

Credenciais

Sherlock CRM API

A API pública fica na mesma origem da aplicação web, sob /api/public/v1. A chave vai no
cabeçalho Authorization: Bearer.

• A chave aparece uma única vez, na criação. Se for perdida, crie outra e revogue a antiga.
• O escopo da credencial (read, read_write, finance, cloud) define o que ela pode
  fazer. Uma credencial de leitura recebe 403 em operações de escrita.
• A credencial só enxerga o que o Admin atribuiu a ela. Registros fora desse escopo
  respondem 404, e não 403.

O teste da credencial faz um GET /catalogs.

Sherlock CRM Webhook API

Guarda o segredo de assinatura devolvido uma única vez na criação da assinatura de webhook.
Ele é usado pelo trigger para validar cada entrega.

Operações

A referência de cada campo está em docs/api/ do repositório sherlock-crm.

Webhooks

O Sherlock não tem rota pública para gerenciar assinaturas: quem cria a assinatura é o
Admin. Por isso o trigger não registra nada sozinho. Para configurar:

1. Adicione o nó Sherlock CRM Trigger e copie a URL de produção do webhook.
2. No Sherlock, em Administração › Integrações › Webhooks, crie a assinatura com essa URL, os
   eventos e a credencial de integração (que define o escopo de visibilidade das entregas).
3. Copie o segredo exibido e cadastre-o numa credencial Sherlock CRM Webhook API.
4. Ative o workflow.

O que o trigger faz com cada entrega:

• verifica X-Sherlock-Signature (t=<unix>,v1=<hex>): HMAC-SHA256 sobre <t>.<corpo cru>,
  comparado em tempo constante; também rejeita timestamps fora da tolerância (padrão 300 s).
  Entrega inválida recebe 401 e não dispara o workflow;
• filtra pelos eventos escolhidos no nó. Eventos fora do filtro são confirmados e ignorados;
• ignora entregas repetidas com o mesmo X-Sherlock-Event-Id, como retentativas e reenvios
  manuais (dá para desligar em Options);
• responde na hora (onReceived), já que o Sherlock desiste da tentativa depois de 10 s.

A saída é o envelope { event, id, data } mais eventId.

Comportamentos que valem saber

• Update sem version. As entidades com concorrência otimista (Deal, Person, Organization,
  Activity) aceitam version em Update Fields. Se ficar vazio, o nó lê o registro e usa a
  versão atual. Em caso de 409 (alguém gravou no meio do caminho), relê e tenta de novo
  uma vez.
• Deal e Activity usam PUT (substituição completa). O nó lê o registro atual e envia
  junto os campos que você não informou, para que um update parcial não apague nada. As tags
  lidas como objetos são convertidas em ids.
• Campos obrigatórios que aceitam null (por exemplo dueAt, dealId e notes na criação
  de atividade) aparecem em Additional Fields e são enviados como null quando ficam vazios.
• Return All pagina por limit/offset (ou cursor, nos lançamentos financeiros)
  respeitando o teto de limit de cada rota.
• 429 é repetido até 4 vezes, respeitando Retry-After ou com backoff exponencial.
• Erros mostram a mensagem da API, o codigo estável e os detalhes por campo do 422.
• Idempotency-Key está disponível em Options nas operações de criação.
• Lotes (WhatsApp Message › Ingest e Cloud Usage › Create Batch): no modo padrão, cada item
  de entrada vira uma entrada do lote, enviada em blocos de até 500. O modo JSON Array per
  Input Item envia um array por item.
• Listas de ids (tags, customColumns) são digitadas separadas por vírgula.
• Campos JSON (emails, phones, customFields, preenchimentos…) aceitam texto JSON ou
  um objeto vindo de expressão.
• Não há como limpar um campo anulável num update a partir dos campos do nó, porque campo
  vazio é omitido. Para isso, use um nó HTTP Request com a mesma credencial.

Desenvolvimento

npm install --ignore-scripts   # --ignore-scripts evita a compilação nativa de isolated-vm no Node 25
npm run build
npm test                        # build + testes de comportamento (contexto n8n e HTTP simulados)
npm run lint
npm run dev                     # sobe um n8n local com os nós carregados

Publicação

A publicação é manual, a partir da máquina de quem publica (logado no npm com npm login):

npm version patch   # ou minor / major — atualize o CHANGELOG.md antes
npm run publish:npm # lint + build + testes + npm publish
git push --follow-tags

npm publish direto é bloqueado de propósito pelo prepublishOnly do @n8n/node-cli; o
script publish:npm libera com RELEASE_MODE=true depois de lint e testes.

Contrato gerado

As descrições do nó não são escritas à mão: nodes/Sherlock/generated/ sai de
scripts/generate.mjs, que lê o contrato publicado pelo sherlock-crm:

• docs/api/openapi.json: rotas, parâmetros, corpos, enums e tetos de limit;
• docs/api/publica/eventos.md: o catálogo fechado de eventos de webhook.

npm run generate                      # espera ../sherlock-crm
npm run generate -- /caminho/sherlock-crm

A curadoria (nome de recurso e operação, dropdowns dinâmicos, placeholders) fica no topo do
gerador. Toda rota pública precisa estar mapeada em ROUTES: rota nova sem mapeamento,
ou rota mapeada que sumiu, faz a geração falhar. Assim nenhuma rota fica de fora sem aviso.

Quando o sherlock-crm publicar mudanças na API (veja docs/api/changelog/), rode
npm run generate, revise o diff de generated/ e rode npm test e npm run lint.

Compatibilidade

Construído e verificado com @n8n/node-cli 0.50 (lint em modo strict, compatível com o n8n
Cloud). Não usa dependências de runtime.

Licença

MIT