Nó do n8n

Plano Business

O nó de CRM para n8n que cuida de contatos, negócios e conversas

Instale o n8n-nodes-pinlyx pelo painel Community Nodes, cole uma chave de API e pronto: um formulário enviado vira contato, um negócio ganho vira fatura e uma conversa sem resposta vira mensagem no canal que a sua equipe acompanha. São oito operações em três recursos, sem dependências em tempo de execução e com licença MIT.

Plano grátis para sempre · Sem cartão de crédito · Cancele quando quiser

Última atualização:

3
Recursos
Contato, negócio e conversa
8
Operações
Cinco de contatos, duas de negócios e uma de conversas
0
Dependências em execução
Toda chamada usa o helper HTTP do próprio n8n
MIT
Licença
Código no GitHub, publicado no npm

Definição

Um nó da comunidade do n8n é um pacote publicado no npm que uma instância do n8n instala em tempo de execução, acrescentando um novo bloco ao canvas. Não é um fork do n8n, nem um receptor de webhooks que você precisa hospedar e manter no ar por conta própria.

n8n-nodes-pinlyx é o nó do Pinlyx. Ele se autentica com uma chave de API que você gera no painel e entrega ao fluxo oito operações sobre contatos, negócios e conversas, com a paginação por cursor já resolvida.

Publicado no npm como n8n-nodes-pinlyx, com o código no GitHub sob licença MIT. Testado no n8n 1.60 ou mais recente, com Node.js 20.15 ou superior. npm · GitHub

O nó conversa com a mesma API REST pública que um script usaria. Tudo o que ele faz pode ser reproduzido com curl, e o que ele não faz está a um nó HTTP Request de distância.

O que o nó coloca no seu fluxo

Três recursos, escolhidos porque são os que uma automação realmente usa. Todas as regras abaixo são aplicadas pela API, não pelo nó.

Contatos, cinco operações

Criar, consultar, listar, atualizar e arquivar. A listagem filtra por busca, plataforma, e-mail, ID externo e Updated Since, que é o filtro usado numa sincronização incremental.

Negócios, duas operações

Crie um negócio com título, valor, moeda, etapa, probabilidade, data prevista de fechamento e observações. Liste com filtros por etapa, contato e busca no título.

Conversas, só leitura

As conversas com movimento recente em todos os canais conectados, das mais novas para as mais antigas. Cada linha traz o ID do contato, o canal, um indicador de não lida e uma prévia curta da última mensagem.

O ID externo impede duplicatas

Grave o seu próprio identificador no contato e uma nova execução é recusada com HTTP 409, indicando o registro que já existe, em vez de criar em silêncio uma segunda cópia da mesma pessoa.

Paginação por cursor embutida

Ative Return All e o nó percorre todas as páginas para você. Deixe desativado e defina um limite. Cada página traz no máximo 100 linhas de contatos e negócios e 50 de conversas, então uma lista grande sempre exige várias requisições.

Chave com escopos, conferida no servidor

A credencial guarda uma única chave de API. Cada operação declara o escopo de que precisa, então uma chave sem contacts:write falha ao criar com um 403, em vez de parecer funcionar sem alterar nada.

Como instalar o nó

O nó está publicado no npm como n8n-nodes-pinlyx e é instalado como qualquer nó da comunidade: de dentro do n8n, sem copiar arquivos para um servidor.

  1. Abra Settings e depois Community Nodes. Para isso você precisa da conta de proprietário da instância. Uma conta de membro não consegue instalar pacotes.
  2. Clique em Install e digite n8n-nodes-pinlyx. Aceite o aviso sobre nós da comunidade e instale. O n8n baixa o pacote e o nó aparece na busca do canvas em poucos segundos.
  3. Adicione o nó do Pinlyx a um fluxo. Ele pede uma credencial antes de deixar você escolher um recurso, então esse é o próximo passo.

Ou, numa instância auto-hospedada, pela linha de comando:

npm install n8n-nodes-pinlyx
# then restart n8n

Um detalhe que vale conhecer antes de planejar qualquer coisa: o n8n Cloud oferece apenas os nós da comunidade que o próprio n8n revisou e verificou, e este pacote ainda não passou por essa revisão. Instâncias auto-hospedadas instalam qualquer pacote publicado. No Cloud, as mesmas operações ficam disponíveis pelo nó HTTP Request apontado para a API REST. Preferimos dizer isso com todas as letras a deixar escondido.

O pacote não declara dependências em tempo de execução. Toda requisição passa pelo helper HTTP do próprio n8n, que é o que permite à credencial injetar o cabeçalho Authorization e o que mantém a instalação leve.

Como criar a credencial

O nó se autentica com uma chave de API do Pinlyx: uma chave, um cabeçalho, sem ida e volta de OAuth.

  1. No painel do Pinlyx, abra Configurações e depois Desenvolvedores. Crie uma chave e dê a ela o nome do fluxo que vai usá-la. Assim você sabe o que para de funcionar no dia em que revogá-la.
  2. Conceda só os escopos de que o fluxo precisa. Quem grava contatos precisa de contacts:read e contacts:write. Um relatório de negócios precisa de deals:read. As conversas são lidas com contacts:read.
  3. Copie o token uma única vez. Chaves de produção começam com csk_live_ e chaves de teste com csk_test_. O token completo aparece na criação e nunca mais; depois disso o painel mostra só o prefixo.
  4. Adicione uma credencial Pinlyx API no n8n e cole a chave. Deixe Base URL como https://api.pinlyx.com, a menos que esteja apontando para um ambiente de staging, e rode o teste da credencial.

O teste da credencial faz a chamada autenticada mais barata que existe:

curl https://api.pinlyx.com/v1/me \
  -H "Authorization: Bearer csk_live_YOUR_KEY"

As chaves de API fazem parte do plano Business. Nos planos Free e Pro não há chave para gerar, então a credencial não tem o que guardar. É o único pré-requisito que vale conferir antes de instalar qualquer coisa.

O limite padrão é de 60 requisições por minuto por chave. Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, e quem passa do limite recebe HTTP 429 com um Retry-After em segundos. Como o limite é por chave e não por espaço de trabalho, um fluxo preso num loop freia a si mesmo em vez de sufocar as suas outras integrações.

Oito operações em três recursos

Esta é a lista completa, não uma seleção dos melhores momentos.

Cada operação corresponde a exatamente um endpoint da API pública v1, então nada aqui se comporta diferente de uma requisição que você escreveria à mão.

  • Contact, Create. Exige pelo menos um destes campos: nome, username, telefone, e-mail ou ID externo. Em Additional Fields entram e-mail, telefone, username, plataforma, observações e o seu próprio ID externo.
  • Contact, Get. Um contato pelo seu ID numérico.
  • Contact, Get Many. Filtros de busca por trecho de texto, plataforma, e-mail, ID externo e Updated Since.
  • Contact, Update. Atualização parcial: um campo que você não adiciona à coleção fica como está, em vez de ser apagado.
  • Contact, Delete. Arquiva em vez de apagar. O histórico de mensagens e os negócios vinculados continuam lá, exatamente como acontece quando você faz a mesma ação no painel.
  • Deal, Create. O título é obrigatório. Valor, moeda, etapa, probabilidade, data prevista de fechamento, observações e ID do contato são opcionais.
  • Deal, Get Many. Filtros por etapa, contato e busca no título. Aqui a etapa aceita won e lost, porque ler um negócio fechado não tem problema, mesmo que gravar um não seja permitido.
  • Conversation, Get Many. As conversas com atividade recente em todos os canais conectados, das mais novas para as mais antigas, cada uma com uma prévia da última mensagem.

O campo de plataforma de um contato aceita Telegram, WhatsApp, Instagram, LinkedIn, X e Email. Ele registra o canal pelo qual a pessoa chegou, que é como o CRM agrupa as conversas dela depois.

O que não está nessa lista não está no nó. Envio de mensagens, tags, pontuação de leads, tarefas, faturas e campanhas existem na API REST. Só não fazem parte destas oito operações.

Fluxo um: um formulário enviado vira contato

É o motivo mais comum para usar este nó. Um lead preenche um formulário e o registro já está no CRM antes de alguém abrir uma aba.

  1. Dispare o fluxo pelo formulário. Um Form Trigger do n8n, um nó Webhook atrás do seu próprio formulário ou um nó do Typeform ou do Google Forms. Serve qualquer coisa que entregue um objeto JSON ao próximo nó.
  2. Mapeie os campos em Contact, Create. O nome vem do campo de nome e, em Additional Fields, entram e-mail, telefone e observações. Defina Platform como Email quando o lead chegar sem um contato de mensageria.
  3. Use o ID do envio como External ID. É esse campo que torna seguro executar o fluxo de novo. Uma segunda criação com o mesmo ID externo é recusada com HTTP 409, e o corpo do erro indica o contato que já existe. Assim, uma reexecução gera um aviso de duplicata, e não uma pessoa duplicada.
  4. Ative Continue On Fail quando reexecuções forem rotina. Com a opção ativada, o 409 chega como um item com mensagem de erro e o restante do lote segue em frente. Com ela desativada, a execução para, o que você quer na primeira vez e não às três da manhã.

Se você precisa de um upsert de verdade em vez de um 409, a API REST tem um endpoint em lote que busca correspondência por ID externo, e-mail, telefone ou username e aceita até 200 linhas por requisição. O nó não expõe esse endpoint. Aponte um nó HTTP Request para POST /v1/contacts/batch e você tem o mesmo resultado com uma chamada em vez de duzentas.

Fluxo dois: um negócio ganho vira fatura

Vale ler antes de montar, porque o desenho óbvio é o errado.

Não dá para marcar um negócio como ganho pela API. Ganhar um negócio lança uma entrada de receita no livro-caixa do CRM, então essa mudança fica reservada de propósito ao painel, onde uma pessoa está olhando. O nó reflete isso: Deal, Create recusa as etapas won e lost, e não existe operação de atualização. Você lê negócios ganhos; não grava.

  1. Consulte os negócios ganhos de tempos em tempos. Um Schedule Trigger a cada quinze minutos ligado a Pinlyx, Deal, Get Many, com o filtro Stage em Won.
  2. Fique só com os que você ainda não viu. Os negócios vêm do maior ID para o menor. Guarde o maior ID já processado nos dados estáticos do fluxo e descarte tudo o que for igual ou menor, ou grave o ID do negócio na referência da fatura e deixe a ferramenta de contabilidade recusar a repetição.
  3. Crie a fatura. Passe título, valor e moeda para o nó de cobrança que você já usa. O negócio traz o ID do contato, então um Contact, Get antes disso entrega o e-mail para onde enviar.

Se quinze minutos é lento demais, não encurte a consulta. Assine o evento: o Pinlyx dispara um webhook de saída em deal.won, assinado com HMAC-SHA256 no cabeçalho X-Webhook-Signature e com o nome do evento em X-Webhook-Event. Aponte-o para um nó Webhook do n8n e a fatura sai segundos depois de alguém fechar o negócio, sem gastar nada do limite com consultas. O mesmo vale para contact.created, contact.updated e message.received.

Fluxo três: ler conversas e encaminhá-las

Conversation, Get Many devolve as conversas que tiveram movimento recente em todos os canais conectados: Telegram, WhatsApp, Instagram, X, e-mail e chat ao vivo do site numa só lista. Cada linha traz o ID do contato, o canal, se está não lida e até 160 caracteres da última mensagem.

  1. Puxe a lista recente de tempos em tempos. Um limite de 50 dá conta da maioria das caixas de entrada. Filtre só as não lidas com um nó IF antes de gastar qualquer coisa com elas.
  2. Classifique a prévia. Envie o texto da prévia para o nó de modelo que você usa e peça um único rótulo: dúvida sobre preço, problema de suporte, spam ou nada a fazer.
  3. Aja de acordo com o rótulo. Publique as dúvidas sobre preço no canal que o time de vendas acompanha, abra um chamado para os problemas de suporte e grave a classificação com Contact, Update, para que ela fique no registro e não só no chat.

Antes de montar isso, vale conhecer dois limites. A prévia é só uma prévia: o nó não percorre a conversa inteira, então o classificador sempre vê apenas a última mensagem. E o nó não consegue marcar um contato com tag nem enviar uma resposta. As duas coisas existem na API REST e no servidor MCP; nenhuma faz parte destas oito operações.

Paginação, limites e como é um erro

Três comportamentos que decidem se um fluxo sobrevive à primeira semana de uso real.

  • A paginação é por cursor. Uma resposta de listagem traz as linhas e um cursor para a próxima página. Return All segue esse cursor até as páginas acabarem; um limite para antes. O servidor limita cada página a 100 linhas de contatos e negócios e 50 de conversas, então Return All sobre 4.000 contatos são 40 requisições, não uma.
  • O limite de requisições é por chave. São sessenta requisições por minuto por padrão. Acima disso você recebe HTTP 429 com Retry-After em segundos, e os três cabeçalhos X-RateLimit em toda resposta mostram o quanto você estava perto antes de acontecer.
  • Os erros dizem o motivo. 401 significa que a chave está errada ou foi revogada. 403 significa que a chave é válida, mas não tem o escopo que a operação declara. 404 significa que o ID não pertence a este espaço de trabalho, a mesma resposta dada a um ID que não existe, de propósito. 409 significa colisão de ID externo e indica o registro que já usa esse ID.

Uma resposta de listagem da API sobre a qual o nó funciona:

{
  "items": [ { "Id": 812, "Name": "Sarah Lin", "Platform": "email" } ],
  "nextCursor": 764,
  "hasMore": true
}

Sincronizações incrementais usam Updated Since. Guarde o horário da última execução bem-sucedida, passe esse valor na próxima e você puxa só o punhado de contatos que mudou, não todos. É a diferença entre uma sincronização noturna que termina e uma que gasta todo o limite com linhas que ninguém mexeu.

Limites sinceros

O que este nó não faz

Seis coisas que é melhor ler aqui do que descobrir no meio da montagem de um fluxo.

Ele não envia mensagens

A API REST consegue enfileirar uma mensagem no Telegram ou uma DM no X, e o servidor MCP também. Essas operações não estão neste nó. Se o fluxo precisa falar com um cliente, use um nó HTTP Request ou um dos nós de canal do próprio n8n.

Ele não marca negócios como ganhos

Ganhar um negócio lança uma entrada de receita no livro-caixa, então essa mudança só acontece no painel. O nó cria negócios e os lista. Ele não os fecha, e Create recusa logo de cara as etapas won e lost.

Não existe nó de gatilho

Este é um nó de ação. Para iniciar um fluxo a partir de algo que acontece no CRM, cadastre um webhook de saída e receba-o com o nó Webhook do n8n. Consultar com um Schedule Trigger também funciona, mas consome um limite de requisições que o webhook não gasta.

Ele não aplica tags, pontuação nem responsáveis

Tags, pontuação de leads, atribuição de responsável, tarefas e movimentações no funil existem na API REST. Nenhuma delas está entre as oito operações. Contact, Update grava os campos simples e nada além disso.

Ele não mexe com dinheiro

Nada de faturas, lançamentos no livro-caixa, pagamentos ou reembolsos. Nada neste nó movimenta dinheiro em nenhuma direção, o mesmo limite que o servidor MCP respeita.

Ele exige o plano Business

As chaves de API são um recurso do plano Business. Nos planos Free e Pro não há chave para colar na credencial, então o nó não tem com o que se autenticar, por mais correta que seja a instalação.

Nó, webhook ou servidor MCP

Três jeitos de conectar o mesmo CRM, cada um certo para um tipo de trabalho. A maioria das equipes acaba usando dois deles.

O nó do n8n

Trabalho previsível, por agendamento ou gatilho

Você sabe exatamente o que deve acontecer e quando. Chega um formulário, um contato é criado. Um negócio fecha, sai uma fatura. A lógica fica num canvas que toda a equipe consegue ler, e uma execução com falha aparece na lista de execuções junto com o payload que a causou.

Ideal quando a regra é fixa e o volume é constante.

Webhooks de saída

Reagir no instante em que algo acontece

Cadastre um endpoint no CRM e ele envia dados para você em contact.created, contact.updated, message.received, deal.won e outros eventos. Assinados com HMAC-SHA256, reenviados com backoff e reprocessáveis a partir de um registro de entregas. Combine com um nó Webhook do n8n e você troca a consulta periódica pelo envio imediato.

Ideal quando a latência importa mais que a simplicidade.

O servidor MCP

Discernimento, não encanamento

Um assistente de IA decide na hora da chamada, com a conversa real diante dele, em vez de seguir uma regra escrita semanas antes. Ferramentas, recursos e prompts num único endpoint autenticado, com cada chamada limitada pelos escopos da chave.

Ideal quando a resposta depende de entender a situação.

Perguntas frequentes sobre a integração com o n8n

As dúvidas que aparecem na primeira hora, respondidas com o comportamento real.

É um nó da comunidade do n8n publicado no npm como n8n-nodes-pinlyx. Instalado numa instância do n8n, ele adiciona ao canvas um bloco do Pinlyx com oito operações: criar, consultar, listar, atualizar e arquivar um contato; criar e listar negócios; e listar conversas recentes. Ele se autentica com uma chave de API do Pinlyx com escopos e não tem dependências em tempo de execução.
Num n8n auto-hospedado, abra Settings, depois Community Nodes, clique em Install e digite n8n-nodes-pinlyx. Você precisa da conta de proprietário da instância. Também dá para rodar npm install n8n-nodes-pinlyx no diretório de dados do n8n e reiniciar o processo, que é o caminho quando o instalador de nós da comunidade está desativado na sua instância.
O n8n Cloud oferece apenas nós da comunidade que o n8n revisou e verificou, e este pacote ainda não passou por essa revisão. No Cloud, as mesmas operações estão disponíveis pelo nó HTTP Request apontado para a API REST do Pinlyx com a mesma chave bearer. Dá um pouco mais de configuração, mas o comportamento é exatamente o mesmo.
Do Business. As chaves de API são um recurso do plano Business, então espaços de trabalho nos planos Free e Pro não conseguem gerar a chave que a credencial exige. Todo o resto do nó é grátis: o pacote tem licença MIT e não há cobrança para instalar nem para usar.
Sozinho, não. Ele é um nó de ação, não de gatilho. Para iniciar um fluxo a partir de um evento do CRM, cadastre um webhook de saída no painel e receba-o com o nó Webhook do n8n. Os webhooks disparam em contact.created, contact.updated, message.received e deal.won, entre outros, são assinados com HMAC-SHA256 no cabeçalho X-Webhook-Signature e reenviados com backoff.
Em Contact, Create, preencha External ID com um identificador estável seu para aquela pessoa, como o ID do envio do formulário ou o ID do cliente na sua loja. Uma segunda criação com o mesmo ID externo é recusada com HTTP 409, e o corpo do erro traz o ID do contato existente. Ative Continue On Fail para que uma reexecução relate a colisão em vez de interromper a execução.
Não. Não existe nenhuma operação de envio. O envio existe na API REST e no servidor MCP, protegido por escopos como telegram:send e social:write, mas fica de fora deste nó de propósito. Um fluxo que precisa falar com uma pessoa precisa de um nó HTTP Request ou de um dos nós de canal do próprio n8n.
A requisição falha com HTTP 403, em vez de parecer que deu certo. Cada operação declara o único escopo de que precisa: contacts:read para as leituras, contacts:write para criar, atualizar e excluir, deals:read e deals:write para as operações de negócios. Os escopos são aplicados no servidor, então restringir uma chave é uma restrição real, não uma sugestão.
Use o filtro Updated Since em Contact, Get Many. Guarde o horário da última execução bem-sucedida, passe esse valor na próxima, e a API devolve só os contatos alterados a partir daquele instante. Junto com Return All, é a base de uma sincronização incremental e mantém uma rotina noturna dentro do limite de requisições por minuto.
Sim, com licença MIT, no GitHub em Pinlyx/n8n-nodes-pinlyx. O nó é um único arquivo TypeScript mais a definição da credencial, então lê-lo do começo ao fim leva poucos minutos e mostra exatamente qual endpoint cada operação chama.

Hora de começar

Coloque o seu CRM dentro do fluxo

Instale o nó, gere uma chave com dois escopos e deixe o primeiro formulário enviado chegar como contato. Daí em diante, é só arrastar mais um nó para o canvas.

Plano grátis para sempre · Preparado para o GDPR · Sem cartão de crédito