> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pied.com.br/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com n8n

> O n8n é uma plataforma de automação open-source que oferece controle total sobre seus fluxos de trabalho, ideal para equipes técnicas que precisam de flexibilidade máxima. 

## Vantagens do n8n

* **Open Source:** Código aberto e gratuito
* **Self-hosted:** Controle total dos dados
* **Flexibilidade:** JavaScript personalizado
* **Visual:** Interface de fluxo intuitiva
* **Extensível:** Centenas de integrações

## Instalação e Configuração

### Opção 1: Docker (Recomendado)

```bash theme={null}
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n
```

### Opção 2: npm

```bash theme={null}
npm install n8n -g
n8n start
```

### Opção 3: n8n Cloud

Acesse [n8n.cloud](https://n8n.cloud) para versão hospedada.

## Configurando Webhook no n8n

### 1. Criando o Workflow

1. **Acesse n8n** em `http://localhost:5678`
2. **Crie um novo workflow**
3. **Adicione um nó "Webhook"**
4. **Configure o webhook:**
   * **HTTP Method:** POST
   * **Path:** `/pied-webhook`
   * **Response Mode:** Respond Immediately

### 2. Configurando no PIED

1. Acesse **Configurações > API e Webhooks** no PIED
2. Configure o webhook:
   * **Nome:** n8n - Automação PIED
   * **Endpoint:** `http://seu-servidor:5678/webhook/pied-webhook`
   * **Gatilho:** Selecione o evento desejado

### 3. Modelo JSON Otimizado

```json theme={null}
{
  "event": "{{eventType}}",
  "timestamp": "{{timestamp}}",
  "pedido": {
    "id": "{{id}}",
    "codigo": "{{code}}",
    "nome": "{{name}}",
    "valor_original": {{originalValue}},
    "valor_final": {{finalValue}},
    "status": "{{dealStatus}}",
    "potencia_total": {{totalPower}},
    "data_criacao": "{{budgetCreated}}",
    "empresa": {
      "nome": "{{company.name}}",
      "email": "{{company.email}}",
      "telefone": "{{company.phone}}",
      "cidade": "{{company.city}}",
      "estado": "{{company.state}}",
      "cnpj": "{{company.cnpj}}"
    },
    "responsavel": {
      "nome": "{{responsible.name}}",
      "email": "{{responsible.email}}"
    },
    "equipamentos": [
      {
        "tipo": "{{equipment.type}}",
        "modelo": "{{equipment.model}}",
        "quantidade": {{equipment.quantity}},
        "preco": {{equipment.price}}
      }
    ]
  }
}
```

## Exemplos de Workflows

### 1. Notificação Multi-Canal

```mermaid theme={null}
graph LR
    A[Webhook PIED] --> B[Processar Dados]
    B --> C[Slack]
    B --> D[Teams]
    B --> E[Email]
    B --> F[Google Sheets]
```

**Configuração:**

1. **Webhook** - Recebe dados do PIED
2. **Function** - Processa e formata dados
3. **Slack** - Envia notificação
4. **Microsoft Teams** - Notifica equipe
5. **Gmail** - Email para responsável
6. **Google Sheets** - Registra na planilha

### 2. CRM Sync com Validação

```mermaid theme={null}
graph LR
    A[Webhook] --> B[Validar Dados]
    B --> C{Valor > 5k?}
    C -->|Sim| D[HubSpot CRM]
    C -->|Não| E[Planilha Leads]
    D --> F[Slack VIP]
    E --> G[Email Follow-up]
```

### 3. Workflow de Aprovação

```mermaid theme={null}
graph LR
    A[Webhook] --> B{Status = Pendente?}
    B -->|Sim| C[Slack Aprovação]
    B -->|Não| D[Processar Direto]
    C --> E[Aguardar Resposta]
    E --> F[Atualizar PIED]
```

## Código JavaScript Personalizado

### Processamento de Dados

```javascript theme={null}
// Nó Function - Processar dados do webhook
const pedido = $input.first().json.pedido;

// Calcular desconto
const desconto = pedido.valor_original - pedido.valor_final;
const percentual_desconto = (desconto / pedido.valor_original) * 100;

// Formatar valores
const valor_formatado = new Intl.NumberFormat('pt-BR', {
  style: 'currency',
  currency: 'BRL'
}).format(pedido.valor_final);

// Determinar prioridade
let prioridade = 'Normal';
if (pedido.valor_final > 50000) prioridade = 'Alta';
if (pedido.valor_final > 100000) prioridade = 'Crítica';

return {
  json: {
    ...pedido,
    desconto: desconto,
    percentual_desconto: Math.round(percentual_desconto),
    valor_formatado: valor_formatado,
    prioridade: prioridade,
    urgente: pedido.valor_final > 50000
  }
};
```

### Validação de Dados

```javascript theme={null}
// Nó Function - Validar dados obrigatórios
const dados = $input.first().json;

const erros = [];

// Validações obrigatórias
if (!dados.pedido.codigo) erros.push('Código do pedido obrigatório');
if (!dados.pedido.empresa.email) erros.push('Email da empresa obrigatório');
if (dados.pedido.valor_final <= 0) erros.push('Valor deve ser maior que zero');

// Validação de email
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (dados.pedido.empresa.email && !emailRegex.test(dados.pedido.empresa.email)) {
  erros.push('Email inválido');
}

if (erros.length > 0) {
  throw new Error(`Dados inválidos: ${erros.join(', ')}`);
}

return { json: dados };
```

### Formatação para Slack

```javascript theme={null}
// Nó Function - Formatar mensagem Slack
const pedido = $input.first().json;

const blocos = [
  {
    type: "header",
    text: {
      type: "plain_text",
      text: `🎉 Novo Pedido: ${pedido.codigo}`
    }
  },
  {
    type: "section",
    fields: [
      {
        type: "mrkdwn",
        text: `*Cliente:*\n${pedido.empresa.nome}`
      },
      {
        type: "mrkdwn",
        text: `*Valor:*\n${pedido.valor_formatado}`
      },
      {
        type: "mrkdwn",
        text: `*Status:*\n${pedido.status}`
      },
      {
        type: "mrkdwn",
        text: `*Responsável:*\n${pedido.responsavel.nome}`
      }
    ]
  }
];

if (pedido.urgente) {
  blocos.push({
    type: "section",
    text: {
      type: "mrkdwn",
      text: "🚨 *PEDIDO DE ALTO VALOR* - Requer atenção especial"
    }
  });
}

return {
  json: {
    channel: pedido.urgente ? "#vendas-vip" : "#vendas",
    blocks: blocos
  }
};
```

## Integrações Avançadas

### Base de Dados Local

```javascript theme={null}
// Salvar em PostgreSQL
const query = `
  INSERT INTO pedidos (
    codigo, nome, valor, status, empresa, responsavel, data_criacao
  ) VALUES (
    $1, $2, $3, $4, $5, $6, $7
  )
`;

const values = [
  pedido.codigo,
  pedido.nome,
  pedido.valor_final,
  pedido.status,
  pedido.empresa.nome,
  pedido.responsavel.nome,
  new Date(pedido.data_criacao)
];

return { json: { query, values } };
```

### API Personalizada

```javascript theme={null}
// Chamar API interna da empresa
const response = await this.helpers.request({
  method: 'POST',
  url: 'https://api.minhaempresa.com/pedidos',
  headers: {
    'Authorization': 'Bearer ' + $env.API_TOKEN,
    'Content-Type': 'application/json'
  },
  body: {
    pedido_pied: pedido.codigo,
    cliente: pedido.empresa.nome,
    valor: pedido.valor_final,
    responsavel: pedido.responsavel.email
  }
});

return { json: response };
```

## Monitoramento e Logs

### Configuração de Logs

```javascript theme={null}
// Nó Function - Log detalhado
console.log('Processando pedido:', pedido.codigo);
console.log('Valor:', pedido.valor_final);
console.log('Status:', pedido.status);

// Salvar log em arquivo
const logEntry = {
  timestamp: new Date().toISOString(),
  pedido: pedido.codigo,
  valor: pedido.valor_final,
  processado: true
};

return { json: logEntry };
```

### Tratamento de Erros

```javascript theme={null}
try {
  // Processar dados
  const resultado = processarPedido(pedido);
  return { json: resultado };
} catch (error) {
  // Log do erro
  console.error('Erro ao processar pedido:', error.message);
  
  // Notificar equipe técnica
  await notificarErro(error, pedido);
  
  // Retornar erro estruturado
  throw new Error(`Falha no processamento: ${error.message}`);
}
```

## Deployment e Produção

### Docker Compose

```yaml theme={null}
version: '3.8'
services:
  n8n:
    image: n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=senha_segura
    volumes:
      - n8n_data:/home/node/.n8n
    restart: unless-stopped

volumes:
  n8n_data:
```

### Variáveis de Ambiente

```bash theme={null}
# .env
N8N_HOST=0.0.0.0
N8N_PORT=5678
N8N_PROTOCOL=https
N8N_BASIC_AUTH_ACTIVE=true
WEBHOOK_URL=https://n8n.minhaempresa.com
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=localhost
DB_POSTGRESDB_PORT=5432
```

## Backup e Recuperação

### Exportar Workflows

```bash theme={null}
# Via CLI
n8n export:workflow --all --output=./backups/

# Via API
curl -X GET "http://localhost:5678/rest/workflows" \
  -H "Authorization: Basic $(echo -n 'user:pass' | base64)"
```

### Importar Workflows

```bash theme={null}
n8n import:workflow --input=./backups/workflow.json
```

## Próximos Passos

* Configure [webhooks personalizados](/integrations/custom-webhooks) para casos específicos
* Explore [outras plataformas](/integrations/introduction) como Zapier e Pluga
* Veja exemplos com [Make](/integrations/make) para comparação visual