corbee-crm

Nodes do n8n para integração com a API do Corbee CRM

Package Information

Released: 9/17/2025

Downloads: 29 weekly / 143 monthly

Latest Version: 2.5.0

Author: Corlabs

Available Nodes

Generic API

No description available

Corbee CRM

No description available

Documentation

🚀 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.

🎯 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:

package.json: Nome, descrição, autor ajustados para Corbee
credentials/CorbeeCredentialsApi.credentials.ts: Token e URL
nodes/Corbee/Corbee.node.ts: Operações Corbee
nodes/Corbee/CorbeeHelpers.ts: Lógica de requisições
nodes/Corbee/icon.svg: Ícone do node
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 = "cliente@exemplo.com"

// Corpo final enviado ao endpoint PUT /customer/{customerId}/from-attendance
{
  "name": "João da Silva",
  "document": "00000000000",
  "phone": "+55 11 99999-9999",
  "email": "cliente@exemplo.com",
  "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: "maria@gmail.com")
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": "thor.novo@gmail.com",
  "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

Atualize a versão em package.json
Build e teste:
```
pnpm run build
pnpm run lint
```
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:

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

Problema: "Credenciais não funcionam"

Soluções:

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

Problema: "TypeScript errors no build"

Soluções:

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

Problema: "Lint errors"

Soluções:

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

📚 Recursos Úteis

Documentação Oficial

Exemplos e Templates

Comunidade

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:

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

💬 Suporte

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

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

Desenvolvido com ❤️ para a comunidade n8n

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

corbee-crm

Package Information

Available Nodes

Documentation

🚀 n8n Corbee CRM Nodes

📋 Índice

🎯 Visão Geral

O que é este projeto?

Quando usar este template?

🚀 Início Rápido

1. Clone e Configure

2. Checklist de Modificação Rápida

📁 Estrutura do Projeto

Descrição dos Arquivos Principais

credentials/CorbeeCredentialsApi.credentials.ts

nodes/Corbee/Corbee.node.ts

nodes/Corbee/CorbeeHelpers.ts

index.ts

🛠 Guia de Desenvolvimento

Passo 1: Configurar Credenciais

Passo 2: Usar o Node Corbee

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

Passo 4: Validações

Passo 5: Tratamento de Erros

💡 Exemplos Práticos

Exemplo 1: Integração com API de CRM

Exemplo 2: Adicionar Paginação

Exemplo 3: Implementar OAuth2

Exemplo 4: Corbee — Buscar Detalhes Completos de um Atendimento

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

Exemplo 6: Corbee — Criar Novo Atendimento

Exemplo 7: Corbee — Adicionar Novo Cliente

Exemplo 8: Corbee — Adicionar Cliente e Atendimento Simultaneamente

Exemplo 9: Corbee — Atualizar Dados Completos do Cliente

📝 Scripts e Comandos

🚢 Deploy e Publicação

Publicar no NPM

Instalar em Produção

Desenvolvimento Local

✅ Boas Práticas

1. Nomenclatura

2. Segurança

3. Performance

4. UX

5. Código

🐛 Troubleshooting

Problema: "Node não aparece no n8n"

Problema: "Credenciais não funcionam"

Problema: "TypeScript errors no build"

Problema: "Lint errors"

📚 Recursos Úteis

Documentação Oficial

Exemplos e Templates

Comunidade

Ferramentas Úteis

📄 Licença

🤝 Contribuindo

💬 Suporte

Discussion

`credentials/CorbeeCredentialsApi.credentials.ts`

`nodes/Corbee/Corbee.node.ts`

`nodes/Corbee/CorbeeHelpers.ts`

`index.ts`