Description

n8n-nodes-clinicorp


n8n para integrar seus fluxos com o Clinicorp — o sistema de gestão para clínicas e consultórios (odontologia e saúde).

Com um único node você consulta e cria dados no Clinicorp: orçamentos, pacientes, agendamentos, financeiro, pagamentos, vendas, procedimentos, profissionais, clínicas, leads de CRM, analytics, metas e mais. Autenticação simples por usuário + token da API (HTTP Basic), e o node é usável como Tool de Agente de IA.

n8n é uma plataforma de automação de fluxos com licença fair-code.

Instalação · Credenciais · Nós e Operações · Subscriber ID · Tool de IA · Exemplos · Desenvolvimento · Publicação · Versões · Apoie

—

🚀 Funcionalidades

• 1 node unificado — Clinicorp com seletor Recurso → Operação. 17 recursos e ~49 operações cobrindo toda a API pública do Clinicorp.
• Autenticação simples — credencial única com Usuário API e Token API (HTTP Basic). Inclui um teste embutido que valida as credenciais antes de rodar o fluxo.
• Zero repetição de Subscriber ID — o id do Assinante vive na credencial (campo obrigatório) e é enviado automaticamente em toda operação. Não existe esse campo no node. Veja Subscriber ID.
• Dropdowns dinâmicos — clínicas, profissionais, status de agendamento, categorias, especialidades e procedimentos são carregados direto da sua conta: você escolhe pelo nome, sem copiar IDs.
• Campos guiados (node versão 2) — em node novo, os procedimentos de um agendamento são uma lista da sua conta, o sexo do paciente e a cor da categoria são seletores, e horários HH:mm e IDs obrigatórios são validados antes de a requisição sair. Workflows salvos continuam na versão 1 e não mudam.
• Datas amigáveis — campos de data usam o seletor dateTime do n8n e são convertidos para o formato que o Clinicorp espera (YYYY-MM-DD ou YYYYMMDD) automaticamente.
• Usável como Tool de IA — o node tem usableAsTool: true, então um AI Agent do n8n pode chamar qualquer operação (buscar orçamentos, criar paciente, agendar, enviar lead…) preenchendo os parâmetros sozinho via $fromAI(). Todas as descrições de operações e campos foram escritas para o LLM entender. Veja Usar como Tool de Agente de IA.
• Zero dependências de runtime — usa o httpRequestWithAuthentication do próprio n8n. Passa no lint oficial n8n-node lint (0 erros), toda chamada tem timeout de 30 s e o pacote é publicado no npm com provenance.

📦 Instalação

Siga o guia de community nodes do n8n.

No n8n, vá em Settings → Community Nodes → Install e digite:

n8n-nodes-clinicorp

> Requer uma instância n8n com n8nNodesApiVersion 1.

🔑 Credenciais

O node usa uma credencial: Clinicorp API. A API do Clinicorp autentica por HTTP Basic, onde:

• API User (Username) = o seu Usuário API.
• API Token (Password) = o seu Token API.

Como encontrar essas informações no Clinicorp:

1. Faça login no sistema.
2. Clique em Gerenciar Assinatura.
3. Clique em Acesso Externo e Integrações.
4. Em Integrações, copie o Usuário API (username) e o Token API (password).

No n8n, crie uma credencial Clinicorp API, cole o usuário e o token e preencha o Subscriber ID (obrigatório). A credencial tem um teste embutido que chama GET /professional/listallprofessionals, então dá pra validar antes de rodar o fluxo.

| Item | Valor |
| — | — |
| Base da API | https://api.clinicorp.com/rest/v1 |
| Autenticação | HTTP Basic (usuário API : token API) |
| Documentação | https://sistema.clinicorp.com/api-docs/ |

🆔 Subscriber ID (id do Assinante)

Quase toda operação do Clinicorp precisa do subscriber_id (o id do Assinante/conta). Ele fica só na credencial, como campo obrigatório, e o node o envia automaticamente em toda requisição.

• Não existe campo Subscriber ID no node. Você configura uma vez na credencial e esquece.
• Para trabalhar com mais de uma conta, crie uma credencial por assinante e escolha a credencial no node.
• Se a credencial estiver sem o Subscriber ID, as operações que o exigem retornam um erro claro pedindo para preenchê-lo.

> Isso também deixa o node mais seguro como Tool de IA: o agente não consegue inventar (nem vazar) o id do Assinante, porque ele nunca é um parâmetro de entrada.

🧩 Nós e Operações

O pacote traz um node de ação (Clinicorp) com seletor Recurso → Operação.

| Recurso | Operações |
| — | — |
| Estimate (Orçamento) | Get, Get Many |
| Patient (Paciente) | Create, Get, Get Birthdays, Get Estimate Totals, Get Many Appointments |
| Appointment (Agendamento) | Cancel, Change Status, Confirm, Create, Create Online Scheduling, Get, Get Available Days, Get Available Times, Get Info, Get Many, Get Many Categories, Get Occupation, Get Statuses |
| Financial (Financeiro) | Get Average Installments, Get Cash Flow, Get Invoices, Get Payments, Get Receipts, Get Summary |
| Payment (Pagamento) | Get Health Insurance Claims, Get Many |
| Sales (Vendas) | Get Estimates And Conversion, Get Revenue By Specialty |
| Analytics | Get Results |
| Operational (Operacional) | Get Miss Goals, Get Sales Goals |
| Clinic (Clínica) | Get Available Times, Get Chairs, Get Many |
| Professional (Profissional) | Get Many |
| Procedure (Procedimento) | Get Many, Get Many Specialties |
| CRM | Add Lead, Get Active Campaigns |
| Group (Franquia) | Get Clinics Info, Get Franchise Units |
| User (Usuário) | Get Many |
| Product (Produto) | Create Order |
| Migration (Migração) | Create From Connection, Create From File, Get Upload URL |
| File (Arquivo) | Upload |

🤖 Usar como Tool de Agente de IA

O node Clinicorp é usável como tool por nós de AI Agent do n8n (Tools Agent). Isso deixa o modelo consultar e agir no Clinicorp sozinho — por exemplo: “quantos orçamentos foram criados este mês e qual a taxa de conversão?” ou “agende a Maria para amanhã às 14h com o Dr. João”.

Como ligar (2 passos)

1. No servidor n8n, habilite o uso de community nodes como tools (por segurança, vem desligado por padrão). Defina a variável de ambiente:

   N8NCOMMUNITYPACKAGESALLOWTOOL_USAGE=true
   

| Instalação | Onde definir |
| — | — |
| Docker / docker-compose | Adicione em environment: do serviço n8n (ou no .env) e recrie o container (docker compose up -d). |
| npm / npx | Exporte antes de subir: export N8NCOMMUNITYPACKAGESALLOWTOOL_USAGE=true && n8n start. |
| n8n Cloud | Já habilitado nos planos que suportam community nodes. |

> Sem essa variável o node não aparece na lista de tools do AI Agent — é a causa nº 1 de “não acho o node como tool”.

2. No workflow, adicione um node AI Agent, conecte um Chat Model e, no conector Tool, adicione o Clinicorp. Escolha o Recurso e a Operação que o agente pode usar (ex.: Estimate → Get Many). Uma tool por operação é a prática recomendada.

Deixe o modelo preencher os campos ($fromAI)

Em cada campo do node em modo tool aparece o botão “Let the model define this”, que usa a expressão:

{{ $fromAI('from', 'Data inicial do período no formato YYYY-MM-DD', 'string') }}

• Assinatura: $fromAI(key, description?, type?, defaultValue?) — key de 1–64 caracteres ([a-zA-Z0-9_-]); type = string | number | boolean | json.
• Você pode misturar: deixar o modelo preencher datas, filtros e nome do paciente (o Subscriber ID nunca é um campo — vem da credencial).
• As descrições de cada operação e campo deste node foram escritas para o LLM entender o que cada uma faz e como preencher — quanto mais específico o seu prompt/System Message do agente, melhor o resultado.

Boas práticas

• Restrinja o escopo: exponha só as operações que o agente precisa (ex.: só Get Many de Estimate e Appointment), em vez de liberar tudo.
• Credencial dedicada por assinante — o Subscriber ID vive na credencial, então o agente nunca precisa (nem consegue) adivinhá-lo.
• n8n atualizado: versões antigas tinham um bug em que a tool de community node retornava resposta vazia para o agente (n8n#26202); já corrigido.

Referências

• Tools Agent — n8n Docs
• Let AI specify tool parameters ($fromAI) — n8n Docs
• Variáveis de ambiente de nodes — n8n Docs

💡 Exemplos

listar orçamentos do mês

1. Clinicorp → Recurso Estimate, Operação Get Many.
2. Defina From Date e To Date (o node envia como YYYY-MM-DD).
3. Opcional: escolha a Clinic pelo dropdown para filtrar uma clínica específica.
4. O subscriber_id vem automaticamente da credencial.

criar um paciente e um lead de CRM

1. Clinicorp → Recurso Patient, Operação Create (informe o Name e os campos adicionais).
2. Clinicorp → Recurso CRM, Operação Add Lead, usando o nome/e-mail do paciente.

Agendar com procedimentos (node versão 2)

1. Clinicorp → Recurso Appointment, Operação Get Available Times (ou Clinic → Get Available Times) para ver os horários livres.
2. Clinicorp → Recurso Appointment, Operação Create. Preencha o horário no formato HH:mm (por exemplo 14:00); o node recusa 9h ou 24:00 antes de chamar o Clinicorp.
3. Em Additional Fields, adicione Procedures e escolha os procedimentos na lista da sua conta. O node os envia ao Clinicorp separados por vírgula.

🛠️ Desenvolvimento

Instalar dependências
npm install
Compilar (n8n-node build: tsc + cópia de ícones)
npm run build
Testes (compila e roda node --test sobre o dist)
npm test
Modo watch
npm run dev
Lint oficial do n8n (n8n-node lint)
npm run lint
npm run lint:fix

Estrutura resumida:

n8n-nodes-clinicorp/
├── credentials/
│   └── ClinicorpApi.credentials.ts     # HTTP Basic (usuário API + token API)
├── nodes/
│   └── Clinicorp/
│       ├── Clinicorp.node.ts           # node de ação (Recurso → Operação)
│       ├── actions/                    # um arquivo por recurso (operações + campos)
│       ├── methods/                    # loadOptions (dropdowns dinâmicos)
│       ├── helpers/                    # datas, bodies, campos guiados e versões do node
│       └── transport/                  # cliente HTTP + resolução do Subscriber ID
├── test/                               # node --test sobre o dist
└── dist/                               # saída compilada (publicada)

✅ Compatibilidade

• Requer n8n com n8nNodesApiVersion 1.
• Base da API: https://api.clinicorp.com/rest/v1.
• Versão 1 ou 2 do node: node novo nasce na versão 2 (campos guiados). Workflows salvos ficam na versão 1, com os mesmos campos da 1.1.2, e continuam funcionando sem edição.

📚 Recursos

• Documentação de community nodes do n8n
• Documentação da API do Clinicorp

🚀 Publicação

A tag vX.Y.Z dispara o workflow publish.yml, que envia a versão com npm stage publish e provenance. A versão fica em espera: ela só vai ao ar depois que o dono a aprova, com 2FA, na aba Staged Packages do npmjs.com. Sem a aprovação, nada muda no registro.

📈 Versões

• 1.2.0 — Campos guiados e lint oficial. Node versão 2: procedimentos do agendamento em lista da conta, sexo do paciente e cor da categoria em seletores, horário HH:mm e IDs de agendamento e orçamento validados antes da chamada, com dica de onde achar cada ID. Toda chamada ao Clinicorp tem timeout de 30 s. Migração para o @n8n/node-cli 0.55.5 (lint oficial sem erros), testes e CI. Workflows salvos continuam na versão 1. Veja o CHANGELOG.md.
• 1.1.1 — Documentação: adicionado selo do GitHub Actions no README e workflow de CI para validar lint e build.
• 1.1.0 — Subscriber ID sai do node e vira obrigatório na credencial. O campo Subscriber ID foi removido de todas as operações; agora ele é preenchido uma única vez na credencial Clinicorp API (campo obrigatório) e enviado automaticamente. Menos configuração por node, e o agente de IA não consegue mais inventar o id do Assinante. Para múltiplas contas, use uma credencial por assinante.
• 1.0.2 — Menos alucinação da IA. Passada de descrições focada em uso como Tool de Agente: as operações de agenda (ver e marcar) ganharam desambiguação explícita — Appointment → Create (agenda interna) vs Create Online Scheduling (solicitação pelo link público), e Appointment → Get Available Times (por Code Link) vs Clinic → Get Available Times (por profissional) — além do encadeamento recomendado (consultar disponibilidade → criar com o horário exato). Enum de convênio passa a listar os valores válidos (ALL, OPEN, DISPUTE, REJECT, PARTIAL_PAID, PAID); telefone, CPF, cor de categoria e horários ganharam formato + exemplo; Board Name do CRM instrui a copiar o nome exato de Get Active Campaigns; e a descrição do node passa a declarar as convenções (datas YYYY-MM-DD, horas HH:mm, IDs sempre vindos da operação de listagem, Subscriber ID vindo da credencial).
• 1.0.1 — Correção: o node não aparecia na busca de ações do editor (embora instalasse e funcionasse ao colar). Causa: o pacote publicava um arquivo codex (*.node.json) que fazia o n8n categorizar o node fora da busca normal. O codex deixou de ser publicado (mesma abordagem do node RD Station). O node continua utilizável como Tool de IA (usableAsTool fica na descrição do node, não no codex).
• 1.0.0 — Primeira versão. Node único Clinicorp (Recurso → Operação) com 17 recursos e ~49 operações; credencial HTTP Basic com teste embutido; Subscriber ID reaproveitável pela credencial; dropdowns dinâmicos (clínicas, profissionais, status, categorias, especialidades, procedimentos); usableAsTool: true com descrições otimizadas para IA; publicação no npm com provenance via GitHub Actions.

🆘 Suporte

Se algo não funcionar:

1. Confirme se o Usuário API e o Token API estão corretos (Gerenciar Assinatura → Acesso Externo e Integrações → Integrações).
2. Confirme se o Subscriber ID está preenchido (na credencial ou no node).
3. Verifique se a versão do n8n é compatível.
4. Consulte os logs do n8n para detalhes do erro.
5. Abra uma issue no GitHub.

☕ Apoie o projeto

Este node é mantido de forma independente. Se ele ajuda suas automações, você pode apoiar o desenvolvimento, a manutenção e as novas integrações pelo Buy Me a Coffee.

📄 Licença

MIT