npm package: @leonidasjf/n8n-nodes-recrutei
Description: Nó customizado para n8n com integração completa ao Recrutei ATS - Webhooks, operações CRUD e cobertura da API
Author: Leônidas Freitas
Latest version: 1.0.4

# n8n-nodes-recrutei

[![NPM Version](https://img.shields.io/npm/v/n8n-nodes-recrutei)](https://www.npmjs.com/package/n8n-nodes-recrutei)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Node customizado para [n8n](https://n8n.io) que integra com a API do [Recrutei ATS](https://www.recrutei.com.br), permitindo automação completa de processos de recrutamento e seleção.

## 📋 Pré-requisitos

- n8n instalado (versão 0.210.0 ou superior)
- Conta ativa no Recrutei
- Credenciais de API do Recrutei (API Key + API Secret)

## 🚀 Instalação

### Via n8n Community Nodes (Recomendado)

1. Acesse sua instância do n8n
2. Vá em **Settings** > **Community Nodes**
3. Clique em **Install**
4. Digite: `n8n-nodes-recrutei`
5. Clique em **Install**

### Via npm (Manual)

```bash
npm install n8n-nodes-recrutei
```

## 🔐 Configuração de Credenciais

### Obtendo as credenciais no Recrutei

1. Faça login no [painel do Recrutei](https://app.recrutei.com.br)
2. Acesse **Configurações** > **Integrações** > **API**
3. Copie sua **API Key** e **API Secret**

### Configurando no n8n

1. No n8n, adicione o node **Recrutei** ao workflow
2. Clique em **Create New Credentials**
3. Preencha os campos:
   - **API Key**: Sua API Key do Recrutei
   - **API Secret**: Seu API Secret do Recrutei
   - **Email**: Email de login da conta Recrutei
   - **Password**: Senha de login da conta Recrutei
   - **Base URL**: `https://api.recrutei.com.br` (padrão)
4. Clique em **Save**

## 📦 Resources Disponíveis

### Vacancy (Vagas)

Gerenciamento completo de vagas de emprego.

**Operations:**
- **Create**: Criar nova vaga
- **Get**: Buscar vaga por ID
- **Get Many**: Listar vagas com filtros
- **Update**: Atualizar vaga existente
- **Delete**: Deletar vaga

**Exemplo - Criar Vaga:**
```javascript
{
  "resource": "vacancy",
  "operation": "create",
  "title": "Desenvolvedor Full Stack",
  "description": "Desenvolvedor com experiência em Node.js e React",
  "location": "São Paulo - SP",
  "salary_min": 8000,
  "salary_max": 12000,
  "client_id": 123,
  "department_id": 456
}
```

### Candidate (Candidatos)

Busca e importação de candidatos.

**Operations:**
- **Search**: Buscar candidatos por filtros (nome, email, telefone, CPF)
- **Import Batch**: Importar até 50 candidatos por vez para uma vaga

**Exemplo - Importar Candidatos:**
```javascript
{
  "resource": "candidate",
  "operation": "importBatch",
  "vacancyId": 789,
  "candidates": [
    {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "11999887766",
      "cpf": "12345678901",
      "linkedin": "https://linkedin.com/in/joaosilva"
    }
  ]
}
```

### Application (Candidaturas)

Gerenciamento de candidaturas e movimentação no pipeline.

**Operations:**
- **Get**: Buscar candidatura por ID
- **Get Many**: Listar candidaturas
- **Get By Vacancy Stage**: Buscar candidatos em etapa específica
- **Move Stage**: Mover candidato para outra etapa

**Exemplo - Mover Candidato:**
```javascript
{
  "resource": "application",
  "operation": "moveStage",
  "applicationId": 12345,
  "stageId": 67890,
  "reason": "Aprovado na entrevista técnica"
}
```

### Tag (Tags)

Gerenciamento de tags para categorizar candidatos.

**Operations:**
- **Create**: Criar tag para candidato
- **Get Many**: Listar tags
- **Delete**: Deletar tag

### Observation (Observações)

Gerenciamento de observações/notas sobre candidatos.

**Operations:**
- **Create**: Criar observação
- **Get**: Buscar observação por ID
- **Get Many**: Listar observações
- **Update**: Atualizar observação
- **Delete**: Deletar observação

### Reference (Dados de Referência)

Busca de dados auxiliares do sistema.

**Operations:**
- **Get Clients**: Listar clientes/empresas
- **Get Departments**: Listar departamentos
- **Get Regimes**: Listar regimes de contratação
- **Get Pipes**: Listar pipelines
- **Get Managers**: Listar gestores

## 🔔 Recrutei Trigger (Webhooks)

Recebe eventos em tempo real do Recrutei.

**Eventos Disponíveis:**
- `candidate.applied` - Candidato aplicou para vaga
- `vacancy.created` - Nova vaga criada
- `hiring.completed` - Contratação finalizada
- `vacancy.frozen` - Vaga congelada
- `sla.alert` - Alerta de SLA
- `*` - Qualquer evento

**Configuração:**

1. Adicione o node **Recrutei Trigger** ao workflow
2. Selecione o tipo de evento
3. Copie a **Webhook URL** gerada
4. No painel do Recrutei, vá em **Configurações** > **Webhooks**
5. Adicione a URL copiada
6. Salve e ative o workflow

## 🎯 Exemplos de Workflows

### Workflow 1: Importar Candidatos do Google Sheets

```
Google Sheets Trigger → Recrutei (Import Batch)
```

### Workflow 2: Notificar no Slack quando candidato aplica

```
Recrutei Trigger (candidate.applied) → Slack (Send Message)
```

### Workflow 3: Mover candidatos aprovados automaticamente

```
Recrutei Trigger (candidate.applied) →
Condition (verificar requisitos) →
Recrutei (Move Stage)
```

## ⚙️ Features Técnicas

- ✅ **Autenticação Bearer Token** com cache automático
- ✅ **Retry Logic**: Tenta automaticamente em caso de 401, 429 ou 5xx
- ✅ **Paginação Automática**: Opção `returnAll` busca todos os registros
- ✅ **Rate Limiting**: 200ms entre páginas para não sobrecarregar a API
- ✅ **Dropdowns Dinâmicos**: Carrega vagas, clientes, departamentos automaticamente
- ✅ **Batch Operations**: Importa até 50 candidatos por vez
- ✅ **TypeScript**: Código 100% tipado com interfaces da API

## 🐛 Troubleshooting

### Erro 401 Unauthorized

Verifique se:
- API Key e API Secret estão corretos
- Email e senha estão corretos
- Credenciais não expiraram

### Erro 429 Too Many Requests

O node já faz retry automático com backoff exponencial. Se persistir:
- Reduza o número de operações simultâneas
- Aumente o intervalo entre execuções

### Webhook não dispara

Verifique se:
- A URL do webhook está cadastrada no painel Recrutei
- O workflow está ativado
- O tipo de evento está correto

## 📝 Documentação da API

Para mais detalhes sobre a API do Recrutei, consulte:
- [Documentação Oficial](https://developers.recrutei.com.br/docs/getting-started)

## 🤝 Contribuindo

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

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

## 📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo [LICENSE.md](LICENSE.md) para mais detalhes.

## 👤 Autor

**Leônidas Freitas**
- Email: leonidas@contalents.com.br
- GitHub: [@leonidasjf](https://github.com/leonidasjf)

## 🙏 Agradecimentos

- Equipe n8n pelo framework incrível
- Recrutei pela API robusta
- Comunidade open source

---

**Nota**: Este é um projeto community-driven e não é oficialmente mantido pelo Recrutei.