# Promoción por WhatsApp

Sistema automatizado de promoción vía WhatsApp utilizando n8n, Supabase y WhatsApp Cloud API.

---

# Descripción General

Este flujo administra la interacción completa con usuarios mediante WhatsApp para registrar participantes en una promoción.

Incluye:

- Validación de mensajes entrantes
- Gestión de consentimiento de privacidad y marketing
- Registro de información del usuario
- Validación y registro de códigos de productos
- Control de estados del usuario
- Prevención de fraude y spam

---

# Tecnologías Utilizadas

- n8n
- Supabase
- PostgreSQL
- WhatsApp Cloud API

---

# Arquitectura del Flujo

El sistema funciona mediante una máquina de estados (`state machine`) donde cada usuario tiene un estado actual que determina la siguiente acción del flujo.

## Estados Disponibles

- `CONSENT_PRIVACY`
- `CONSENT_MARKETING`
- `ASK_NAME`
- `ASK_ID`
- `ASK_EMAIL`
- `ASK_LOCATION`
- `ASK_CODE`
- `MENU_AFTER_CODE`
- `DONE`

---

# Flujo General

## 1. Recepción y Normalización

El flujo recibe mensajes desde WhatsApp y:

- Extrae el contenido del mensaje
- Detecta el tipo de mensaje:
  - Texto
  - Imagen
  - Interactivo
- Normaliza caracteres y acentos
- Filtra números bloqueados

---

## 2. Validación Inicial

Si el mensaje no contiene contenido válido:

- El flujo se detiene automáticamente

---

## 3. Creación o Consulta del Usuario

Se ejecuta la función RPC:

```sql
ensure_user_wa
```

Esta función:

- Crea el usuario si no existe
- Consulta el estado actual del usuario
- Devuelve `out_state`

---

# Router de Estados

Según el valor de `out_state`, el flujo dirige al usuario a la etapa correspondiente.

| Estado            | Acción                             |
| ----------------- | ---------------------------------- |
| CONSENT_PRIVACY   | Solicitar aceptación de privacidad |
| CONSENT_MARKETING | Solicitar consentimiento marketing |
| ASK_NAME          | Solicitar nombre completo          |
| ASK_ID            | Solicitar identificación           |
| ASK_EMAIL         | Solicitar correo electrónico       |
| ASK_LOCATION      | Solicitar ubicación                |
| ASK_CODE          | Solicitar código del producto      |
| MENU_AFTER_CODE   | Mostrar menú posterior             |
| DONE              | Finalizar flujo                    |

---

# Consentimientos

## Consentimiento de Privacidad

El usuario puede responder:

- `SI`
- `NO`

### Comportamiento

- `SI` → continúa el flujo
- `NO` → se detiene el avance

### RPC utilizada

```sql
set_consent_privacy_wa
```

---

## Consentimiento de Marketing

El usuario puede responder:

- `SI`
- `NO`

### Comportamiento

- `SI` → opt-in marketing
- `NO` → opt-out marketing

### RPC utilizada

```sql
set_consent_marketing_wa
```

---

# Captura de Datos

## Nombre

### Validaciones

- Mínimo 6 caracteres
- Debe contener al menos 2 palabras
- Solo letras permitidas

### RPC

```sql
set_name_wa
```

---

## Identificación

### Validaciones

- Campo obligatorio
- No vacío

### RPC

```sql
set_id_wa
```

---

## Email

### Opciones permitidas

- Correo válido
- `NO` para omitir

### Validación

Se utiliza validación mediante regex para verificar formato email.

### RPC

```sql
set_email_wa
```

---

## Ubicación

### Validación

- Debe pertenecer a una lista cerrada de departamentos

### RPC

```sql
set_location_wa
```

---

# Registro de Códigos

## Formato del Código

El sistema valida códigos con la siguiente estructura:

- 4 números
- 1 letra
- 3 números
- marcador (`C`, `S`, `M`, `T`)
- 1 número

### Ejemplo

```txt
1234A567C9
```

---

## Registro del Código

### RPC utilizada

```sql
register_lot_code
```

---

## Posibles Respuestas

| Respuesta             | Descripción                               |
| --------------------- | ----------------------------------------- |
| ❌ Código inválido    | Formato incorrecto                        |
| ⚠️ Código duplicado   | Código ya registrado                      |
| 🚫 Límite diario      | Usuario alcanzó límite                    |
| 🚫 Bloqueo por fraude | Detección antifraude                      |
| 🎉 Código exitoso     | Registro correcto y generación de cupones |

---

# Menú Posterior al Registro

Después de registrar un código, el usuario puede elegir:

1. Seguir ingresando códigos
2. Salir

## Opción 1

El estado cambia a:

```txt
ASK_CODE
```

## Opción 2

El estado cambia a:

```txt
DONE
```

---

# Reinicio del Flujo

Si el usuario envía alguno de estos mensajes:

- `hola`
- `buenas`
- `hello`

El sistema reinicia el flujo mediante:

```sql
restart_wa
```

---

# Tipos de Mensajes

El flujo soporta:

- Texto simple
- Botones interactivos
- Listas interactivas

---

# API Utilizada

- WhatsApp Cloud API

---

# Características Técnicas

- Arquitectura basada en estados
- Integración con Supabase mediante RPC
- Manejo intensivo de nodos `Code`
- Normalización de texto y caracteres
- Sistema antifraude
- Validaciones avanzadas
- Manejo de errores

---

# Estructura del Proyecto

```txt
Base de datos Supabase/
├── Base de datos Postgre Presto.txt
├── Triggers.png
└── pg-dump-postgres1-1776492006.dmp

Flujo n8n/
├── Flujo WhatsApp.docx
└── Flujo con WSP.json
```