🚀 n8n Corbee CRM Nodes

Nodes para integrar o n8n ao Corbee CRM. Inclui operações para listar atendimentos, alterar atendimento, atualizar cliente a partir de atendimento, marcar ganho e marcar perdido.

Pacote npm: @corlabs-holding/n8n-nodes-corbee-crm

Nota de migração: o pacote sem escopo n8n-nodes-corbee-crm foi descontinuado (deprecated). Utilize o pacote com escopo @corlabs-holding/n8n-nodes-corbee-crm.

📋 Índice

• Visão Geral
• Início Rápido
• Estrutura do Projeto
• Guia de Desenvolvimento
• Exemplos Práticos
• Scripts e Comandos
• Deploy e Publicação
• Boas Práticas
• Troubleshooting
• Recursos Úteis

🎯 Visão Geral

O que é este projeto?

Este é um template base para desenvolver nodes customizados do n8n. Ele fornece:

• ✅ Estrutura completa seguindo padrões oficiais n8n
• ✅ Sistema de autenticação flexível (API Key, Bearer, Basic Auth)
• ✅ Operações CRUD prontas para usar
• ✅ Tratamento de erros robusto
• ✅ Validação de dados
• ✅ Compatibilidade com LLMs/Agents (usableAsTool: true)
• ✅ TypeScript com tipos completos
• ✅ Configuração de linting e formatação

Quando usar este template?

Use este template quando precisar:

• Integrar uma API REST ao n8n
• Criar um node customizado para sua empresa
• Desenvolver conectores para serviços que não existem no n8n
• Aprender como desenvolver nodes para n8n

🚀 Início Rápido

1. Clone e Configure

# Clone este repositório
git clone <url-do-repo>
cd n8n_base

# Instale as dependências
pnpm install  # ou npm install

# Build inicial para verificar
pnpm run build

2. Checklist de Modificação Rápida

Para adaptar este template para sua API, você precisa modificar:

• [x] package.json: Nome, descrição, autor ajustados para Corbee
• [x] credentials/CorbeeCredentialsApi.credentials.ts: Token e URL
• [x] nodes/Corbee/Corbee.node.ts: Operações Corbee
• [x] nodes/Corbee/CorbeeHelpers.ts: Lógica de requisições
• [x] nodes/Corbee/icon.svg: Ícone do node
• [x] README.md: Documentação específica

📁 Estrutura do Projeto

n8n_base/
├── credentials/                              # Definições de credenciais
│   └── GenericApiCredentialsApi.credentials.ts  # Configuração de autenticação
│
├── nodes/                                   # Implementação dos nodes
│   └── GenericApi/
│       ├── GenericApi.node.ts              # Node principal - define UI e operações
│       ├── GenericApiHelpers.ts            # Funções auxiliares - requests, validação
│       └── icon.svg                        # Ícone do node (60x60 recomendado)
│
├── .editorconfig                            # Configuração do editor
├── .eslintrc.js                             # Regras de linting
├── .gitignore                               # Arquivos ignorados pelo git
├── .npmignore                               # Arquivos ignorados no npm publish
├── .prettierrc                              # Configuração de formatação
│
├── index.ts                                 # Entry point - exporta nodes e credentials
├── package.json                             # Configuração do projeto e dependências
├── tsconfig.json                            # Configuração TypeScript
└── README.md                                # Esta documentação

Descrição dos Arquivos Principais

credentials/CorbeeCredentialsApi.credentials.ts

Campos:

• apiUrl: URL base (padrão https://api.crm.corbee.com.br)
• integrationToken: token enviado em corbee-token-integration

nodes/Corbee/Corbee.node.ts

Operações:

• listAttendances (GET /pipeline/attendances com filtros id, document, phone, status)
  • Filtros são enviados no corpo do GET conforme docs oficiais do Corbee.
  • id: enviado como id no body; corresponde ao atributo id dos itens retornados.
  • document: enviado como document no body; filtra pelo CPF do cliente (normalizado automaticamente).
  • phone: filtrado no cliente contra o atributo customer_phones (o backend pode não filtrar corretamente este campo em todas as instalações).
  • status: enviado como status no body.
  • Filtros são complementares (AND).
  • Sem filtros: paginação interna (page/per_page).
• getAttendance (GET /attendances/{id}) — Busca os detalhes completos de um atendimento específico. Retorna data com informações detalhadas do atendimento, cliente e relacionamentos.
• createAttendance (POST /integrations/attendances) — Cria um novo atendimento (endpoint específico para integrações externas).
  • Campos obrigatórios: customer_id (ID do cliente)
  • Campos opcionais: value (valor do atendimento), campaign_name (nome da campanha)
  • Retorna: { "data": { "message": "Atendimento gerado com sucesso!", "attendance_id": 321 } }
• createCustomer (POST /customer) — Adiciona um novo cliente.
  • Campos obrigatórios: name (nome do cliente)
  • Campos opcionais: document (CPF/CNPJ), birth_date (DD/MM/AAAA), foundation_date (DD/MM/AAAA), phone
  • Retorna: { "message": "Cliente cadastrado com sucesso!", "customer_id": 132 }
• createCustomerWithAttendance (POST /customer/attendance) — Adiciona um novo cliente e registra um atendimento associado.
  • Campos obrigatórios: name (nome do cliente)
  • Campos opcionais: cpf, birth_date, email, phone, stage_id, campaign_name, benefit, organ_id, origin_id
  • Retorna: { "data": { "customer_id": 26, "attendance_id": 49, "message": "Cliente e atendimento cadastrados com sucesso!" } }
• updateCustomer (PUT /customer/{id}/from-attendance) — Atualiza dados completos de um cliente.
  • Aceita JSON com todos os campos do cliente (name, document, email, address, bank_account, cards, etc.)
  • Normalização automática de CPF/CNPJ
  • Retorna: { "message": "Dados alterados com sucesso!" }
• listFunnels (GET /funnels) — Lista os funis. Retorna data com objetos { id, name, organization_id, created_at, updated_at, visualization }.
• listStages (GET /funnels/stages) — Lista as etapas por funil. Retorna data com objetos { id, name, funnel_id, funnel_name }.
• listTags (GET /tags) — Lista as tags existentes. Retorna data com objetos { id, name, color }.
• updateAttendance (PUT /attendances/{id})
• updateCustomerFromAttendance (PUT /customer/{id}/from-attendance)
  • Campo de identificação: ID Do Atendimento (obrigatório).
  • Campos aceitos: name, document (CPF, enviado sem máscara), email.
  • Os campos de texto (name, document, email) aceitam entrada por modelos de IA (janela de edição expandida).
  • O corpo enviado contém apenas esses campos preenchidos.
• markAttendanceGain (PUT /attendances/{id}/gain)
• markAttendanceLoss (PUT /attendances/{id}/loss com reason_loss_id)

Observações de filtros em listAttendances:

• Os filtros são complementares (AND). Apenas os filtros preenchidos são enviados na query string.
• Se nenhum filtro for informado, nenhum parâmetro é enviado e a API retorna todos os registros.
• Este node não possui "Opções Adicionais" (headers, queryParams, timeout). Use apenas os campos de Filtros.

nodes/Corbee/CorbeeHelpers.ts

Faz a requisição HTTP com header corbee-token-integration e normaliza erros.

index.ts

Exporta Generic API (template) e Corbee CRM.

🛠 Guia de Desenvolvimento

Passo 1: Configurar Credenciais

Modifique credentials/GenericApiCredentialsApi.credentials.ts:

export class SuaApiCredentialsApi implements ICredentialType {
	name = 'suaApiCredentialsApi';  // Nome interno (sempre termina com Api)
	displayName = 'Sua API';        // Nome exibido na UI
	documentationUrl = 'https://docs.suaapi.com/auth';
	
	properties: INodeProperties[] = [
		{
			displayName: 'API URL',
			name: 'apiUrl',
			type: 'string',
			default: 'https://api.suaempresa.com',
			required: true,
		},
		// Adicione seus campos de autenticação aqui
	];
}

Passo 2: Usar o Node Corbee

Modifique nodes/GenericApi/GenericApi.node.ts:

export class SuaApi implements INodeType {
	description: INodeTypeDescription = {
		displayName: 'Sua API',
		name: 'suaApi',  // Nome interno (camelCase)
		icon: 'file:icon.svg',
		group: ['transform'],
		version: 1,
		subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
		description: 'Integração com Sua API',
		documentationUrl: 'https://docs.suaapi.com',
		defaults: {
			name: 'Sua API',
		},
		inputs: ['main'],
		outputs: ['main'],
		credentials: [
			{
				name: 'suaApiCredentialsApi',
				required: true,
			},
		],
		properties: [
			// Defina seus campos aqui
		],
	};
	
	async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
		// Lógica de execução
	}
}

Passo 3: Operações já incluídas

Exemplo de como adicionar uma nova operação:

// Em GenericApi.node.ts, dentro de properties:
{
	displayName: 'Operação',
	name: 'operation',
	type: 'options',
	options: [
		{
			name: 'Buscar Cliente',  // Nome na UI
			value: 'getCustomer',    // Valor interno
			description: 'Busca um cliente por ID',
			action: 'Buscar um cliente',  // Descrição da ação
		},
		// Adicione mais operações aqui
	],
	default: 'getCustomer',
}

Passo 4: Validações

Em GenericApiHelpers.ts, adicione validações customizadas:

// Validação de CPF
validateCPF(cpf: string): boolean {
	// Implementação da validação
	return true;
}

// Validar antes de fazer a requisição
validateInput(data: IDataObject, operation: string): void {
	if (operation === 'createCustomer') {
		if (!this.validateCPF(data.cpf as string)) {
			throw new NodeOperationError(
				this.context.getNode(),
				'CPF inválido'
			);
		}
	}
}

Passo 5: Tratamento de Erros

Sempre use os erros apropriados do n8n:

import { NodeApiError, NodeOperationError } from 'n8n-workflow';

// Para erros de API
throw new NodeApiError(this.getNode(), error, {
	message: 'Falha na API',
	description: 'Verifique suas credenciais',
});

// Para erros de operação
throw new NodeOperationError(
	this.getNode(),
	'Operação inválida',
	{ description: 'Esta operação não é suportada' }
);

💡 Exemplos Práticos

Exemplo 1: Integração com API de CRM

// Modificar operações para CRM
options: [
	{ name: 'Criar Lead', value: 'createLead' },
	{ name: 'Buscar Lead', value: 'getLead' },
	{ name: 'Atualizar Lead', value: 'updateLead' },
	{ name: 'Converter Lead', value: 'convertLead' },
]

// Implementar no execute()
case 'createLead':
	const leadData = {
		name: this.getNodeParameter('name', i) as string,
		email: this.getNodeParameter('email', i) as string,
		phone: this.getNodeParameter('phone', i) as string,
	};
	responseData = await helper.makeRequest(
		'POST',
		'/leads',
		leadData,
		additionalOptions
	);
	break;

Exemplo 2: Adicionar Paginação

case 'getAll':
    const returnAll = this.getNodeParameter('returnAll', i) as boolean;
    // Exemplo genérico; a paginação automática do Corbee não está habilitada por padrão.
    if (returnAll) {
        // Buscar todas as páginas (exemplo)
        // ...
    } else {
        const limit = this.getNodeParameter('limit', i) as number;
        responseData = await helper.makeRequest('GET', `/items?limit=${limit}`);
    }
    break;

Exemplo 3: Implementar OAuth2

// Em credentials
{
	displayName: 'Grant Type',
	name: 'grantType',
	type: 'options',
	options: [
		{ name: 'Client Credentials', value: 'clientCredentials' },
		{ name: 'Authorization Code', value: 'authorizationCode' },
	],
	default: 'clientCredentials',
},

// Em helpers, implementar refresh token
async getOAuth2Token(): Promise<string> {
	if (this.tokenExpired()) {
		const response = await this.context.helpers.httpRequest({
			method: 'POST',
			url: `${this.credentials.tokenUrl}`,
			body: {
				grant_type: 'client_credentials',
				client_id: this.credentials.clientId,
				client_secret: this.credentials.clientSecret,
			},
		});
		this.saveToken(response.access_token, response.expires_in);
	}
	return this.currentToken;
}

Exemplo 4: Corbee — Buscar Detalhes Completos de um Atendimento

Use o node Corbee CRM com a operação Buscar Detalhes do Atendimento:

• ID Do Atendimento: Informe o ID do atendimento que deseja consultar (ex: 65)

Resposta da API: Retorna um objeto com dados completos incluindo:

{
  "id": 65,
  "stage_id": 17,
  "funnel_id": 4,
  "value": null,
  "status": null,
  "created_at": "2025-06-02 18:05:41",
  "user_id": 4,
  "user_name": "thattyla",
  "customer_id": 142,
  "name": "Marcelo - Teste",
  "document": "81395965153",
  "email": null,
  "customer_type": "natural_person",
  // ... outros campos do cliente e atendimento
}

Exemplo 5: Corbee — Atualizar Cliente a partir de Atendimento (com campos explícitos)

Use o node Corbee CRM com a operação updateCustomerFromAttendance e preencha os campos:

• customerId: ID do cliente (do atendimento)
• customerName: Nome do cliente (preferencial; captura por IA)
• (legado) name: Nome do cliente (fallback se customerName não for informado)
• document (CPF): CPF do cliente (aceita com ou sem máscara; enviado sem máscara)
• phone: Telefone
• email: Email
• Opcionalmente, customerData (JSON) para enviar dados adicionais (endereço, etc.)

Observações:

• Os campos explícitos (customerName/name, document, phone, email) são mesclados com customerData. Em caso de chave duplicada, o valor do campo explícito prevalece.
• customerName é o campo recomendado para Nome (otimizado para agentes de IA). Se vazio, o node usa o campo legado name.
• document (CPF) é normalizado (somente dígitos) antes de ser enviado.

Exemplo de customerData e corpo final enviado:

// customerData (opcional)
{
  "address": {
    "uf": "SP",
    "city": "São Paulo",
    "neighborhood": "Centro",
    "street": "Rua X",
    "number": "123",
    "zipcode": "01000-000"
  }
}

// Campos explícitos preenchidos na UI
// customerName = "João da Silva"  (ou use 'name' se preferir o legado)
// document = "000.000.000-00"
// phone = "+55 11 99999-9999"
// email = "[email protected]"

// Corpo final enviado ao endpoint PUT /customer/{customerId}/from-attendance
{
  "name": "João da Silva",
  "document": "00000000000",
  "phone": "+55 11 99999-9999",
  "email": "[email protected]",
  "address": {
    "uf": "SP",
    "city": "São Paulo",
    "neighborhood": "Centro",
    "street": "Rua X",
    "number": "123",
    "zipcode": "01000-000"
  }
}

Exemplo 6: Corbee — Criar Novo Atendimento

Use o node Corbee CRM com a operação Criar Atendimento:

• ID Do Cliente: ID do cliente existente no sistema (obrigatório, ex: 142)
• Valor: Valor do atendimento (opcional, ex: 1000)
• Nome Da Campanha: Nome da campanha associada (opcional, ex: "Campanha Black Friday")

Resposta da API: Retorna confirmação da criação:

{
  "data": {
    "message": "Atendimento gerado com sucesso!",
    "attendance_id": 321
  }
}

Caso de uso: Ideal para integrar formulários de captação externos, sistemas de vendas ou automações que precisam criar novos atendimentos automaticamente no Corbee CRM.

Exemplo 7: Corbee — Adicionar Novo Cliente

Use o node Corbee CRM com a operação Adicionar Cliente:

• Nome: Nome completo do cliente (obrigatório, ex: "Thor")
• CPF/CNPJ: Documento do cliente (opcional, ex: "000.000.000-00" - será normalizado automaticamente)
• Data de Nascimento: Data no formato DD/MM/AAAA (opcional, ex: "08/10/1994")
• Data de Fundação: Para empresas (opcional, ex: "08/10/1994")
• Telefone: Telefone do cliente (opcional, ex: "11987984340")

Resposta da API:

{
  "message": "Cliente cadastrado com sucesso!",
  "customer_id": 132
}

Exemplo 8: Corbee — Adicionar Cliente e Atendimento Simultaneamente

Use o node Corbee CRM com a operação Adicionar Cliente e Atendimento:

• Nome: Nome completo (obrigatório, ex: "Maria Clara Souza")
• CPF: CPF do cliente (opcional, ex: "000.000.000-00")
• Data de Nascimento: Data no formato DD/MM/AAAA (opcional, ex: "12/12/1985")
• Email: Email do cliente (opcional, ex: "[email protected]")
• Telefone: Telefone (opcional, ex: "11987985656")
• ID da Etapa: Etapa do funil (opcional, ex: "1")
• Nome da Campanha: Campanha associada (opcional, ex: "Campanha Black Friday")
• Benefício: Código do benefício (opcional, ex: "6546979955589")
• ID do Órgão: ID do órgão (opcional, ex: 1)
• ID da Origem: ID da origem (opcional, ex: 2)

Resposta da API:

{
  "data": {
    "customer_id": 26,
    "attendance_id": 49,
    "message": "Cliente e atendimento cadastrados com sucesso!"
  }
}

Exemplo 9: Corbee — Atualizar Dados Completos do Cliente

Use o node Corbee CRM com a operação Atualizar Dados do Cliente:

• ID do Cliente: ID do cliente a ser atualizado (obrigatório)
• Dados do Cliente (JSON): Dados completos em formato JSON

Exemplo de JSON para dados completos:

{
  "name": "Thor Atualizado",
  "birth_date": "08/10/1994",
  "sex": "M",
  "document": "86625139050",
  "email": "[email protected]",
  "address": {
    "uf": "SP",
    "city": "São Paulo",
    "neighborhood": "Centro",
    "street": "Rua Nova",
    "number": "123",
    "complement": "Apto 45",
    "zipcode": "01000-000"
  },
  "bank_account": {
    "bank_id": 1,
    "type": "c",
    "agency": "5489789",
    "account": "54513564"
  },
  "cards": [
    {
      "card_name": "Thor",
      "card_number": "1234123412341234",
      "validity": "12/2033",
      "is_default": true,
      "card_type_id": 1,
      "bank_id": 1
    }
  ]
}

Resposta da API:

{
  "message": "Dados alterados com sucesso!"
}

Caso de uso: Ideal para sincronização completa de dados de clientes entre sistemas, atualizações em massa ou integração com sistemas de pagamento.

📝 Scripts e Comandos

# Desenvolvimento
pnpm run dev        # Watch mode - recompila ao salvar
pnpm run build      # Build para produção

# Qualidade de código
pnpm run lint       # Verifica erros de linting
pnpm run lint:fix   # Corrige erros automaticamente
pnpm run format     # Formata código com Prettier

# Publicação
pnpm run prepublishOnly  # Roda antes de publicar (build + lint)

🚢 Deploy e Publicação

Publicar no NPM

1. Atualize a versão em package.json
2. Build e teste:

   pnpm run build
   pnpm run lint

3. Publique:

   npm publish

Instalar em Produção

# No diretório custom do n8n (recomendado)
cd ~/.n8n/custom
npm install @corlabs-holding/n8n-nodes-corbee-crm

# Reinicie o n8n
n8n start

Desenvolvimento Local

Para testar no n8n local:

# No diretório do seu node (este repositório)
npm link

# No diretório custom do n8n
cd ~/.n8n/custom
npm link @corlabs-holding/n8n-nodes-corbee-crm

# Reinicie o n8n
n8n start

✅ Boas Práticas

1. Nomenclatura

• Credentials: Sempre termine com Api (ex: SuaEmpresaCredentialsApi)
• Node name: Use camelCase (ex: suaEmpresa)
• Display name: Use title case (ex: Sua Empresa)
• Operations: Use verbos descritivos (ex: Create User, não User)

2. Segurança

• ✅ Nunca logue credenciais
• ✅ Use typeOptions: { password: true } para campos sensíveis
• ✅ Valide todos os inputs
• ✅ Sanitize dados antes de enviar para API
• ✅ Use HTTPS sempre que possível

3. Performance

• ✅ Implemente paginação para listas grandes
• ✅ Use batch operations quando disponível
• ✅ Adicione timeout apropriado
• ✅ Implemente retry com backoff exponencial
• ✅ Cache tokens OAuth quando apropriado

4. UX

• ✅ Mensagens de erro claras e acionáveis
• ✅ Placeholders úteis nos campos
• ✅ Descrições explicativas
• ✅ Valores padrão sensatos
• ✅ Use displayOptions para mostrar campos condicionalmente

5. Código

• ✅ Use TypeScript strict mode
• ✅ Sempre trate erros
• ✅ Documente funções complexas
• ✅ Mantenha funções pequenas e focadas
• ✅ Use helpers para lógica reutilizável

🐛 Troubleshooting

Problema: "Node não aparece no n8n"

Soluções:

1. Verifique se o build foi feito: pnpm run build
2. Confirme o caminho em package.json -> n8n.nodes
3. Reinicie o n8n após instalar
4. Verifique logs do n8n para erros de carregamento

Problema: "Credenciais não funcionam"

Soluções:

1. Nome da credential deve terminar com Api
2. Verifique se o nome em node.credentials corresponde
3. Teste a autenticação com Postman/Insomnia primeiro
4. Verifique os headers sendo enviados

Problema: "TypeScript errors no build"

Soluções:

1. Instale types: pnpm install -D @types/node
2. Verifique versão do TypeScript: deve ser 5.x
3. Use as any para tipos complexos do n8n se necessário

Problema: "Lint errors"

Soluções:

1. Run: pnpm run lint:fix
2. Para regras específicas do n8n, pode desabilitar em .eslintrc.js
3. Mantenha consistência com o estilo do projeto

📚 Recursos Úteis

Documentação Oficial

• n8n - Creating Nodes
• n8n - Node Development
• n8n - Built-in Nodes

Exemplos e Templates

• n8n-nodes-starter
• Community Nodes

Comunidade

• n8n Community Forum
• n8n Discord
• Stack Overflow - tag n8n

Ferramentas Úteis

• Postman - Testar APIs
• JSON Schema Validator - Validar estruturas
• TypeScript Playground - Testar código TS

📄 Licença

MIT - Sinta-se livre para usar este template em seus projetos!

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie sua feature branch (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Add: MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

💬 Suporte

Se você tiver dúvidas ou precisar de ajuda:

1. Verifique a seção Troubleshooting
2. Procure em Issues existentes
3. Abra uma nova issue com detalhes do problema
4. Pergunte na comunidade n8n

Desenvolvido com ❤️ para a comunidade n8n

Este é um template base. Personalize-o para suas necessidades específicas!