Notificações N8N

Introdução

Este documento descreve todos os eventos de notificação disponíveis no sistema backend do Gaio. Esses eventos são acionados automaticamente quando ações específicas ocorrem na plataforma e são enviados para o N8N para processamento e automação de marketing, CS e analytics.

Estrutura do Evento

Todos os eventos de notificação compartilham uma estrutura base comum e incluem um payload específico do evento.

Propriedades Base do Evento

Todo evento de notificação inclui estes campos padrão:

{
  "name": "event_type_name",
  "request_id": "uuid-v4-format",
  "idempotence_key": "unique-string-key",
  "created_at": "2024-01-28T10:30:00.000Z",
  "payload": {
    // Dados específicos do evento
  }
}

Campo	Tipo	Descrição
name	string	Tipo de evento (veja tipos de eventos abaixo)
request_id	string	Identificador UUID v4 para a solicitação
idempotence_key	string	Chave única para prevenir processamento duplicado
created_at	string	Timestamp ISO 8601 quando o evento foi criado
payload	object	Dados específicos do evento (varia por tipo)

---

Eventos Disponíveis

Nome do Evento	Condição de Acionamento
user_data_filled	Usuário preenche telefone pela primeira vez
account_connected	Conta conecta com sucesso a serviço externo
account_disconnected	Conta desconecta do serviço externo
subscription_plan_changed	Plano/tier de assinatura muda
subscription_usage_threshold	Uso atinge 50%, 75%, 90% ou 100% de limite
subscription_unpaid_limit	Uso em 100% E pagamento vencido

Dados do Usuário Preenchidos

Nome do Evento: user_data_filled

Quando é Acionado:

• Quando um usuário preenche seu número de telefone de contato pela primeira vez
• O usuário deve passar de ter um telefone vazio para ter um número de telefone

Payload:

Campo	Tipo	Obrigatório	Descrição
userId	string	Sim	Identificador único do usuário (UUID)
accountId	string	Sim	Identificador único da conta (UUID)
name	string	Não	Nome completo do usuário
contactEmail	string	Não	Email de contato do usuário
contactPhone	string	Sim	Número de telefone (recém definido)

Exemplo:

{
  "name": "user_data_filled",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotence_key": "user_550e8400_data_filled_1706438400",
  "created_at": "2024-01-28T10:30:00.000Z",
  "payload": {
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "accountId": "550e8400-e29b-41d4-a716-446655440002",
    "name": "João Silva",
    "contactEmail": "joao@exemplo.com",
    "contactPhone": "+5511999999999"
  }
}

---

Conta Conectada

Nome do Evento: account_connected

Quando é Acionado:

• Quando uma conta se conecta com sucesso a um serviço externo (Instagram, WhatsApp, etc.)
• Status da conta muda para “Conectada”

Payload:

Campo	Tipo	Obrigatório	Descrição
userId	string	Sim	Identificador único do usuário (UUID)
accountId	string	Sim	Identificador único da conta (UUID)
externalId	string	Sim	ID da conta no serviço externo
connectionType	string	Sim	Tipo de conexão (ex: “instagram”, “whatsapp”)
name	string	Não	Nome completo do usuário
alias	string	Não	Alias/nome de exibição da conta
contactPhone	string	Não	Número de telefone de contato do usuário
contactEmail	string	Não	Email de contato do usuário

Exemplo:

{
  "name": "account_connected",
  "request_id": "550e8400-e29b-41d4-a716-446655440003",
  "idempotence_key": "account_550e8400_connected_1706438500",
  "created_at": "2024-01-28T10:31:40.000Z",
  "payload": {
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "accountId": "550e8400-e29b-41d4-a716-446655440002",
    "externalId": "17841458234567890",
    "connectionType": "instagram",
    "name": "João Silva",
    "alias": "@joaosilva_oficial",
    "contactPhone": "+5511999999999",
    "contactEmail": "joao@exemplo.com"
  }
}

---

Conta Desconectada

Nome do Evento: account_disconnected

Quando é Acionado:

• Quando uma conta é desconectada de um serviço externo
• Status da conta muda para “Desconectada”
• Pode ocorrer por desconexão manual, expiração de token ou erros de API

Payload:

Campo	Tipo	Obrigatório	Descrição
userId	string	Sim	Identificador único do usuário (UUID)
accountId	string	Sim	Identificador único da conta (UUID)
externalId	string	Sim	ID da conta no serviço externo
connectionType	string	Sim	Tipo de conexão (ex: “instagram”, “whatsapp”)
name	string	Não	Nome completo do usuário
alias	string	Não	Alias/nome de exibição da conta
contactEmail	string	Não	Email de contato do usuário
contactPhone	string	Não	Número de telefone de contato do usuário

Exemplo:

{
  "name": "account_disconnected",
  "request_id": "550e8400-e29b-41d4-a716-446655440004",
  "idempotence_key": "account_550e8400_disconnected_1706438600",
  "created_at": "2024-01-28T10:33:20.000Z",
  "payload": {
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "accountId": "550e8400-e29b-41d4-a716-446655440002",
    "externalId": "17841458234567890",
    "connectionType": "instagram",
    "name": "João Silva",
    "alias": "@joaosilva_oficial",
    "contactEmail": "joao@exemplo.com",
    "contactPhone": "+5511999999999"
  }
}

---

Plano de Assinatura Alterado

Nome do Evento: subscription_plan_changed

Quando é Acionado:

• Quando um plano de assinatura ou tier é alterado
• Pode ser acionado por upgrade, downgrade ou mudança de tier

Payload:

Campo	Tipo	Obrigatório	Descrição
userId	string	Sim	Identificador único do usuário (UUID)
accountId	string	Sim	Identificador único da conta (UUID)
name	string	Não	Nome completo do usuário
contactEmail	string	Não	Email de contato do usuário
contactPhone	string	Não	Número de telefone de contato do usuário
changeType	string	Sim	Tipo de mudança: “upgrade”, “downgrade”, “tier_change”
previousPlanId	string	Sim	Identificador único do plano anterior
previousPlanTitle	string	Sim	Nome de exibição do plano anterior
newPlanId	string	Sim	Identificador único do novo plano
newPlanTitle	string	Sim	Nome de exibição do novo plano
previousLimit	number	Não	Limite anterior (se aplicável)
newLimit	number	Não	Novo limite de uso (se aplicável)
hasPaymentMethod	boolean	Sim	Se a conta possui método de pagamento registrado no Stripe

Tipos de Mudança:

• upgrade: Usuário passou para um plano de tier superior
• downgrade: Usuário passou para um plano de tier inferior
• tier_change: Usuário mudou de tiers no mesmo nível de plano

Exemplo:

{
  "name": "subscription_plan_changed",
  "request_id": "550e8400-e29b-41d4-a716-446655440005",
  "idempotence_key": "subscription_550e8400_plan_changed_1706438700",
  "created_at": "2024-01-28T10:35:00.000Z",
  "payload": {
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "accountId": "550e8400-e29b-41d4-a716-446655440002",
    "name": "João Silva",
    "contactEmail": "joao@exemplo.com",
    "contactPhone": "+5511999999999",
    "changeType": "upgrade",
    "previousPlanId": "plan_basic_001",
    "previousPlanTitle": "Plano Básico",
    "newPlanId": "plan_pro_001",
    "newPlanTitle": "Plano Pro",
    "previousLimit": 1000,
    "newLimit": 5000,
    "hasPaymentMethod": true
  }
}

---

Limite de Uso da Assinatura

Nome do Evento: subscription_usage_threshold

Quando é Acionado:

• Quando o uso atinge 50%, 75%, 90% ou 100% do limite do último tier
• Ajuda a avisar usuários antes de atingirem seus limites de uso
• Só dispara uma vez por nível de limite por período de faturamento

Payload:

Campo	Tipo	Obrigatório	Descrição
userId	string	Sim	Identificador único do usuário (UUID)
accountId	string	Sim	Identificador único da conta (UUID)
name	string	Não	Nome completo do usuário
contactEmail	string	Não	Email de contato do usuário
contactPhone	string	Não	Número de telefone de contato do usuário
planId	string	Sim	Identificador único do plano atual
planTitle	string	Sim	Nome de exibição do plano atual
thresholdLevel	number	Sim	Limite atingido: 50, 75, 90 ou 100
currentUsage	number	Sim	Contagem de uso atual
usageLimit	number	Sim	Limite máximo de uso do tier atual
usagePercentage	number	Sim	Percentual do limite usado (decimal: 0.50 = 50%)
hasPaymentMethod	boolean	Sim	Se a conta possui método de pagamento registrado no Stripe

Níveis de Limite:

• 50: Usuário usou 50% de seu limite
• 75: Usuário usou 75% de seu limite
• 90: Usuário usou 90% de seu limite
• 100: Usuário atingiu 100% de seu limite

Exemplo:

{
  "name": "subscription_usage_threshold",
  "request_id": "550e8400-e29b-41d4-a716-446655440006",
  "idempotence_key": "subscription_550e8400_threshold_75_1706438800",
  "created_at": "2024-01-28T10:36:40.000Z",
  "payload": {
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "accountId": "550e8400-e29b-41d4-a716-446655440002",
    "name": "João Silva",
    "contactEmail": "joao@exemplo.com",
    "contactPhone": "+5511999999999",
    "planId": "plan_pro_001",
    "planTitle": "Plano Pro",
    "thresholdLevel": 75,
    "currentUsage": 3750,
    "usageLimit": 5000,
    "usagePercentage": 0.75,
    "hasPaymentMethod": true
  }
}

---

Limite de Assinatura Não Pago

Nome do Evento: subscription_unpaid_limit

Quando é Acionado:

• Quando o uso atinge 100% do limite do último tier E o pagamento está vencido
• Alerta crítico indicando que a conta pode ser suspensa
• Fatura está em status “past_due” ou “unpaid”

Payload:

Campo	Tipo	Obrigatório	Descrição
userId	string	Sim	Identificador único do usuário (UUID)
accountId	string	Sim	Identificador único da conta (UUID)
name	string	Não	Nome completo do usuário
contactEmail	string	Não	Email de contato do usuário
contactPhone	string	Não	Número de telefone de contato do usuário
planId	string	Sim	Identificador único do plano atual
planTitle	string	Sim	Nome de exibição do plano atual
currentUsage	number	Sim	Contagem de uso atual
usageLimit	number	Sim	Limite máximo de uso do tier atual
invoiceStatus	string	Sim	Status da fatura (ex: “past_due”, “unpaid”)
invoiceDueAt	string	Sim	Data de vencimento da fatura (formato ISO 8601)
gracePeriodEnd	string	Não	Data fim do período de tolerância (formato ISO 8601)
hasPaymentMethod	boolean	Sim	Se a conta possui método de pagamento registrado no Stripe

Status de Fatura:

• past_due: Pagamento está vencido
• unpaid: Fatura não foi paga

Exemplo:

{
  "name": "subscription_unpaid_limit",
  "request_id": "550e8400-e29b-41d4-a716-446655440007",
  "idempotence_key": "subscription_550e8400_unpaid_1706438900",
  "created_at": "2024-01-28T10:38:20.000Z",
  "payload": {
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "accountId": "550e8400-e29b-41d4-a716-446655440002",
    "name": "João Silva",
    "contactEmail": "joao@exemplo.com",
    "contactPhone": "+5511999999999",
    "planId": "plan_pro_001",
    "planTitle": "Plano Pro",
    "currentUsage": 5000,
    "usageLimit": 5000,
    "invoiceStatus": "past_due",
    "invoiceDueAt": "2024-01-25T00:00:00.000Z",
    "gracePeriodEnd": "2024-02-01T00:00:00.000Z",
    "hasPaymentMethod": false
  }
}

---

Integração com N8N

Configuração do Webhook

Para receber esses eventos no N8N:

1. Crie um nó Webhook em seu fluxo de trabalho N8N
2. Defina o Método HTTP como POST
3. Use a URL do webhook na configuração do backend Gaio
4. Configure autenticação se necessário (recomendado)

Roteamento de Eventos

Você pode rotear eventos com base no campo name:

// Exemplo de condição Switch/Router no N8N
if (event.name === "user_data_filled") {
  // Rotear para fluxo de onboarding de usuário
} else if (event.name === "account_connected") {
  // Rotear para fluxo de mensagem de boas-vindas
} else if (event.name === "subscription_usage_threshold") {
  // Rotear para fluxo de aviso de uso
}
// ... etc

Idempotência

Sempre use a idempotence_key para prevenir processamento duplicado:

1. Armazene a idempotence_key ao processar um evento
2. Verifique se a chave existe antes de processar
3. Pule o processamento se a chave já foi processada

Exemplo de Nó de Código N8N:

const event = $input.all()[0].json;
const idempotenceKey = event.idempotence_key;

// Verificar se já foi processado (pseudo-código)
const alreadyProcessed = await checkIfProcessed(idempotenceKey);

if (alreadyProcessed) {
  return { skip: true };
}

// Processar evento
await processEvent(event);

// Marcar como processado
await markAsProcessed(idempotenceKey);

return { processed: true };

---

Testes

Para testar a entrega de eventos, use o endpoint de teste de notificação:

POST /api/console/notification-test

Este endpoint permite que você acione eventos de teste para fins de desenvolvimento e integração.