N8N Node - Pulse Agenda

Node customizado completo para integração com a plataforma Pulse Agenda no N8N.

🚀 Instalação

1. Copie este diretório para ~/.n8n/custom/nodes/
2. Reinicie o N8N

⚙️ Configuração

Credenciais

Crie uma credencial do tipo "Pulse Agenda API" com:

• API Key: Sua chave de API gerada na plataforma
• URL da API: http://localhost/scheduling-api/index.php

📋 Operações Disponíveis

1. 📅 Criar Agendamento

Cria um novo agendamento na plataforma.

Parâmetros:

• Nome do Cliente (obrigatório)
• Email do Cliente
• Telefone do Cliente
• Data/Hora de Início (obrigatório) - Formato: YYYY-MM-DD HH:MM:SS
• Data/Hora de Término (obrigatório) - Formato: YYYY-MM-DD HH:MM:SS
• Notas

Exemplo:

{
  "client_name": "João Silva",
  "client_email": "[email protected]",
  "client_phone": "11999999999",
  "start_time": "2024-02-10 14:00:00",
  "end_time": "2024-02-10 15:00:00",
  "notes": "Primeira consulta"
}

2. 📋 Listar Agendamentos

Lista agendamentos com filtros opcionais.

Parâmetros:

• Data Inicial (opcional) - Formato: YYYY-MM-DD
• Data Final (opcional) - Formato: YYYY-MM-DD
• Status (opcional): confirmed, cancelled, completed

3. 🕐 Ver Horários Disponíveis

Verifica horários disponíveis em uma data específica.

Parâmetros:

• Data para Verificar (obrigatório) - Formato: YYYY-MM-DD
• Horário de Início (padrão: 08:00)
• Horário de Fim (padrão: 18:00)
• Duração do Slot em minutos (padrão: 60)

Retorna:

{
  "date": "2024-02-10",
  "available_slots": [
    {
      "start_time": "08:00",
      "end_time": "09:00",
      "start_datetime": "2024-02-10 08:00:00",
      "end_datetime": "2024-02-10 09:00:00"
    }
  ],
  "total_slots": 5,
  "occupied_slots": 3
}

4. 🔄 Reagendar

Reagenda um agendamento existente para nova data/hora.

Parâmetros:

• ID do Agendamento (obrigatório)
• Nova Data/Hora de Início (obrigatório)
• Nova Data/Hora de Término (obrigatório)

5. ⏰ Adiantar Agendamento

Adianta um agendamento por X minutos.

Parâmetros:

• ID do Agendamento (obrigatório)
• Minutos para Adiantar (padrão: 30)

Exemplo: Se o agendamento era às 14:00, com 30 minutos de adianto fica às 13:30.

6. ❌ Cancelar Agendamento

Cancela um agendamento (muda status para "cancelled").

Parâmetros:

• ID do Agendamento (obrigatório)

7. 🗑️ Excluir Agendamento

Exclui permanentemente um agendamento do sistema.

Parâmetros:

• ID do Agendamento (obrigatório)

8. 🔍 Buscar por Cliente

Busca agendamentos por nome ou telefone do cliente.

Parâmetros:

• Termo de Busca (obrigatório) - Nome ou telefone

Retorna:

{
  "search_term": "João",
  "appointments": [...],
  "total_found": 3
}

🤖 Exemplos de Workflows

Exemplo 1: Agendamento via WhatsApp

Webhook (WhatsApp) 
  ↓
Parse JSON (extrair: nome, data, hora)
  ↓
Scheduling SaaS (Ver Horários Disponíveis)
  ↓
IF (horário disponível)
  ↓
Scheduling SaaS (Criar Agendamento)
  ↓
Send WhatsApp (confirmar agendamento)
ELSE
  ↓
Send WhatsApp (sugerir horários disponíveis)

Exemplo 2: Reagendamento Automático

Webhook (cliente solicita reagendamento)
  ↓
Scheduling SaaS (Buscar por Cliente)
  ↓
Scheduling SaaS (Ver Horários Disponíveis)
  ↓
Scheduling SaaS (Reagendar)
  ↓
Send Email/WhatsApp (confirmação)

Exemplo 3: Lembretes Automáticos

Cron (diariamente às 8h)
  ↓
Scheduling SaaS (Listar Agendamentos - hoje)
  ↓
For Each (agendamento)
  ↓
Send WhatsApp (lembrete 1h antes)

Exemplo 4: Cancelamento por Inatividade

Cron (semanalmente)
  ↓
Scheduling SaaS (Listar Agendamentos - próximos 7 dias)
  ↓
Filter (agendamentos sem confirmação)
  ↓
For Each
  ↓
Scheduling SaaS (Cancelar Agendamento)
  ↓
Send Email (notificação de cancelamento)

Exemplo 5: Otimização de Agenda

Cron (diariamente)
  ↓
Scheduling SaaS (Listar Agendamentos - hoje)
  ↓
Filter (agendamentos com gaps grandes)
  ↓
For Each
  ↓
Scheduling SaaS (Adiantar Agendamento)
  ↓
Send WhatsApp (notificar cliente sobre mudança)

📱 Integração WhatsApp

Comandos de Texto Sugeridos:

Agendar:

• "agendar João Silva 10/02 14:00"
• "marcar consulta Maria 15/02 09:30"

Reagendar:

• "reagendar 123 para 12/02 15:00"
• "mudar agendamento 456 para amanhã 10:00"

Cancelar:

• "cancelar agendamento 789"
• "desmarcar consulta João"

Ver disponibilidade:

• "horários livres 10/02"
• "que horas tem vaga amanhã"

Processamento de Mensagens:

// Exemplo de parsing de mensagem
const message = "agendar João Silva 10/02 14:00";
const parts = message.split(' ');
const action = parts[0]; // "agendar"
const name = parts[1] + ' ' + parts[2]; // "João Silva"
const date = parts[3]; // "10/02"
const time = parts[4]; // "14:00"

🔧 Configurações Avançadas

Horários de Funcionamento

Configure os horários padrão no node "Ver Horários Disponíveis":

• Segunda a Sexta: 08:00 - 18:00
• Sábado: 08:00 - 12:00
• Domingo: Fechado

Duração de Slots

• Consulta rápida: 30 minutos
• Consulta normal: 60 minutos
• Procedimento: 120 minutos

Regras de Negócio

• Mínimo 1 hora de antecedência para agendamento
• Máximo 30 dias de antecedência
• Não permitir agendamentos em feriados

🐛 Troubleshooting

Erro: Invalid API key

• Verifique se a API Key está correta nas credenciais

Erro: Appointment not found

• Verifique se o ID do agendamento existe e não foi excluído

Erro: Time slot not available

• Use "Ver Horários Disponíveis" antes de criar agendamento

Erro: Invalid date format

• Use sempre o formato YYYY-MM-DD HH:MM:SS para datas

📊 Monitoramento

Métricas Importantes:

• Taxa de agendamentos criados vs cancelados
• Horários mais procurados
• Clientes mais ativos
• Tempo médio entre agendamento e atendimento

Logs Recomendados:

• Todas as operações de agendamento
• Tentativas de agendamento em horários ocupados
• Cancelamentos e reagendamentos

🔐 Segurança

• Use HTTPS em produção
• Mantenha a API Key segura
• Implemente rate limiting
• Valide todos os inputs
• Log de auditoria para operações críticas

📞 Suporte

Para dúvidas ou problemas:

1. Verifique os logs do N8N
2. Teste a API diretamente
3. Consulte a documentação da API em /api/docs
4. Abra uma issue no repositório