📑 Tabla de Contenidos
📋 Visión General del Sistema
🎯 Objetivo Principal
Automatizar completamente la gestión de suscripciones mensuales del club de fútbol, desde la creación de enlaces de pago hasta el seguimiento de pagos y comunicación con los padres, eliminando tareas manuales y proporcionando trazabilidad total.
✨ Funcionalidades Clave
- Generación automática de enlaces de suscripción por DNI
- Sincronización bidireccional con MercadoPago
- Gestión de pagos mensuales recurrentes
- Notificaciones automáticas por WhatsApp
- Consultas de estado para padres vía WhatsApp
- Renovaciones automáticas por problemas de pago
- Reportes semanales con métricas clave
- Recordatorios amigables mensuales
🛠️ Stack Tecnológico
🗄️ Airtable
Base de datos con tablas interconectadas para socios, pagos y configuración
⚙️ n8n
Plataforma de automatización con 7 workflows integrados
💳 MercadoPago
Sistema de pagos con planes de suscripción mensual
📱 Evolution API
Integración WhatsApp para notificaciones y consultas
external_reference de MercadoPago, permitiendo una arquitectura escalable basada en planes compartidos en lugar de suscripciones individuales.
🏗️ Arquitectura del Sistema
Diagrama de Arquitectura por Capas
🔄 Flujo de Datos Principal
crea socio
registra datos
genera enlace
procesa suscripción
↓
envía enlace
completa pago
sincroniza estado
actualizado
⚠️ Decisión Arquitectónica Importante
Arquitectura basada en PLANES vs SUSCRIPCIONES individuales:
El sistema utiliza 3 planes base de MercadoPago (Infantil, Juvenil, Cadetes) que son compartidos por todos los socios de cada categoría. La identificación individual se hace mediante el parámetro external_reference=DNI en la URL de suscripción.
Ventajas:
- ✅ Actualización centralizada de precios (un cambio afecta a todos)
- ✅ Arquitectura más simple y escalable
- ✅ Menos llamadas API a MercadoPago
- ✅ Gestión eficiente de inflación
⚙️ Workflows del Sistema
Propósito: Crear y mantener los 3 planes base de suscripción en MercadoPago
🔧 Configuración:
- Trigger: Manual o Webhook desde botón Airtable
- Frecuencia: Solo cuando se actualizan precios
- Estado: ❌ Inactivo (ejecutar manualmente cuando sea necesario)
📋 Planes Gestionados:
| Plan | Categoría | Monto Base | Frecuencia |
|---|---|---|---|
| Plan Infantil | 8-10 años | $150 | Mensual |
| Plan Juvenil | 11-13 años | $180 | Mensual |
| Plan Cadetes | 14-17 años | $200 | Mensual |
🔄 Proceso:
Propósito: Generar enlaces de suscripción personalizados por DNI y enviarlos por WhatsApp
🔧 Configuración:
- Trigger: Webhook desde botón "Crear_Suscripcion" en Airtable
- URL Webhook:
https://manager.automatizatuempresa.com.ar/webhook/webhook-crear-suscripcion-club - Estado: ❌ Debe activarse para uso en producción
🔄 Flujo Completo:
↓
↓
↓
💡 Método URL Simple (Sin API)
Este workflow NO usa la API /preapproval de MercadoPago. En su lugar, genera una URL directa:
Ventajas:
- ✅ Evita error 404 del
card_token_id - ✅ Proceso instantáneo
- ✅ MercadoPago maneja todo el checkout
- ✅ Identificación por DNI garantizada
📱 Mensaje WhatsApp Enviado:
Propósito: Atender consultas automáticas de padres sobre estado de pago vía WhatsApp
🔧 Configuración:
- Trigger: Webhook desde Evolution API cuando llega mensaje WhatsApp
- Comando activación: Mensaje conteniendo DNI del socio
- Estado: ❌ Debe activarse y configurar Evolution webhook
🔄 Proceso de Consulta:
↓
↓ SI
↓
💬 Templates de Respuesta:
✅ Al Día
"¡Tu cuenta está al día! Último pago: [fecha]. Próximo cobro: [fecha]"
⚠️ Con Deuda
"Tenés [X] pagos pendientes. Total adeudado: $[monto]. Por favor regulariza tu situación..."
❌ No Encontrado
"No encontramos ese DNI en nuestro sistema. Por favor verificá el número o contactá a administración."
Propósito: Sincronizar automáticamente estados de suscripción y pagos desde MercadoPago a Airtable
🔧 Configuración:
- Trigger: Webhook desde MercadoPago
- URL Webhook:
https://manager.automatizatuempresa.com.ar/webhook/club-futbol-webhook-mp - Eventos procesados: subscription.*, payment.*
- Estado: ❌ Debe activarse y configurar webhook en MercadoPago
🔄 Flujo de Sincronización:
↓
↓
↓
external_reference para buscar socios por DNI en lugar de usar subscription_id. Esto permite una arquitectura más robusta y escalable.
📊 Estados Sincronizados:
| Estado MercadoPago | Estado Airtable | Acción |
|---|---|---|
| authorized / approved | Activa | Actualizar fecha último pago |
| cancelled | Cancelada | Marcar para renovación |
| paused | Pausada | Notificar administrador |
| rejected | Problema_Pago | Activar Workflow 4 |
Propósito: Gestionar renovaciones automáticas para socios con problemas de pago o cambios de categoría
🔧 Configuración:
- Trigger: Schedule diario a las 09:00 AM
- Cron:
0 9 * * * - Estado: ❌ Inactivo (activar cuando sistema esté en producción)
🎯 Casos Procesados:
💳 Problema de Pago
Genera nuevo enlace cuando falla el pago automático
- Tarjeta vencida
- Fondos insuficientes
- Cambio de tarjeta
🔄 Reactivación
Procesa solicitudes de reactivación de suscripciones canceladas
- Usuario solicitó reactivar
- Genera enlace nuevo
- Envía por WhatsApp
📋 Cambio de Categoría
Gestiona cambios cuando un socio pasa de categoría (ej: Infantil → Juvenil)
- Detecta categoría pendiente
- Genera enlace con nuevo plan
- Cancela suscripción anterior
🛡️ Protecciones Anti-Spam:
- Límite temporal: Máximo 1 notificación cada 24 horas
- Límite de intentos: Máximo 3 intentos automáticos
- Después de 3 intentos: Requiere intervención manual
Propósito: Generar reportes automáticos semanales con métricas clave del sistema
🔧 Configuración:
- Trigger: Schedule semanal - Lunes 08:00 AM
- Cron:
0 8 * * 1 - Estado: ❌ Inactivo
📈 Métricas Incluidas:
👥 Estadísticas Socios
- Total de socios
- Activas / Canceladas / Con problemas
- Distribución por categoría
- Tendencia semanal
💰 Métricas Financieras
- Ingresos mensuales proyectados
- Tasa de conversión
- Índice de problemas de pago
- Comparativa mes anterior
📧 Formato Reporte:
Se genera un reporte HTML con:
- Resumen ejecutivo con métricas clave
- Tablas detalladas por categoría
- Gráficos de tendencias
- Recomendaciones automáticas basadas en datos
- Lista de acciones pendientes
Propósito: Enviar recordatorios amigables mensuales a socios activos para mantener buena relación
🔧 Configuración:
- Trigger: Schedule mensual - Día 15 a las 10:00 AM
- Cron:
0 10 15 * * - Estado: ❌ Inactivo
💬 Tipos de Mensajes:
🎉 Agradecimiento Anual
Condición: Más de 12 meses como socio
"¡Más de 1 año juntos! Gracias por confiar en nosotros..."
❤️ Agradecimiento Semestral
Condición: 6-12 meses como socio
"Gracias por seguir confiando en nosotros..."
👋 Bienvenida
Condición: Menos de 2 meses como socio
"¡Bienvenido/a! Gracias por elegirnos..."
📢 Recordatorio General
Condición: Resto de socios activos
"Recordatorio amistoso sobre tu suscripción..."
🗄️ Estructura de Base de Datos (Airtable)
📊 Tablas del Sistema
Propósito: Registro principal de todos los socios del club
Campos Principales:
| Campo | Tipo | Descripción |
|---|---|---|
| DNI | Text (Único) | Documento Nacional de Identidad del socio - CLAVE PRINCIPAL |
| Nombre_Completo | Text | Nombre y apellido completo del socio |
| Fecha_Nacimiento | Date | Fecha de nacimiento del socio (formato europeo: DD/MM/YYYY) |
| Edad_Actual | Formula (Auto) | Edad calculada automáticamente desde fecha de nacimiento |
| Categoría | Link (Planes) | Plan vinculado basado en categoría: Infantil / Juvenil / Cadetes |
| Monto | Lookup (Auto) | Monto mensual obtenido desde tabla Planes según categoría |
| Email_madre_Padre | Email del padre/tutor responsable principal | |
| Phone | Número WhatsApp para notificaciones (formato: +5491134567890) | |
| Estado_Socio | Single Select | Activo / Inactivo / Suspendido |
| Estado_Suscripcion | Single Select | Pendiente / Activa / Cancelada |
| ID_Suscripcion_MP | Text | ID de suscripción en MercadoPago (cuando se completa el pago) |
| Enlace_Suscripcion_MP | URL | Link de pago personalizado generado por Workflow 1 |
| Fecha_Inscripcion | Date | Fecha de inscripción en el club |
| Fecha_Creacion_Suscripcion | DateTime | Fecha y hora de creación de la suscripción MP |
| Ultimo_Pago_Registrado | Date | Fecha del último pago procesado exitosamente |
| Meses_Adeudados | Number | Cantidad de meses con deuda |
| Total_Deuda | Currency | Total adeudado en pesos argentinos |
| Accion_Suscripcion | Single Select | Crear_Suscripcion / Cancelar_Suscripcion / Sin_Accion |
| Fecha_Ultimo_Problema_Pago | DateTime | Última vez que se detectó rechazo de pago |
| Intentos_Renovacion | Number | Contador de intentos automáticos de renovación (máx 3) |
| Padres | Link (Padres/Madres) | Relación con tabla de padres/tutores |
| Pagos_Mensuales | Link (Pagos) | Historial de todos los pagos del socio |
| Notas | Long Text | Observaciones adicionales sobre el socio |
🔗 Botón de Acción:
Crear_Suscripcion: Botón que ejecuta Workflow 1 para generar enlace de pago
URL: https://manager.automatizatuempresa.com.ar/webhook/webhook-crear-suscripcion-club
Método: POST con record_id
Propósito: Información completa de padres, madres y tutores responsables
Campos Principales:
- Nombre_Completo: Nombre y apellido completo
- DNI_Padre: Documento del padre/tutor
- Email: Correo electrónico de contacto
- WhatsApp: Número principal de WhatsApp
- Telefono_Alternativo: Número de respaldo
- Direccion: Domicilio del padre/tutor
- Relacion_Socio: Tipo de relación (Padre/Madre/Tutor)
- Contacto_Emergencia: Datos de contacto de emergencia
- Hijos_en_Club: Link a tabla Socios (puede tener múltiples hijos)
- Fecha_Registro: Fecha de alta en sistema
- Notas_Padre: Observaciones adicionales
Propósito: Historial completo de todos los pagos mensuales procesados
Campos Principales:
| Campo | Tipo | Descripción |
|---|---|---|
| ID_Pago | Text (Auto) | Identificador único del pago |
| Socio | Link | Relación con tabla Socios |
| Año_Mes | Text | Mes correspondiente al pago (formato: 2025-11) |
| Fecha_Pago_Real | Date | Fecha exacta en que se procesó el pago |
| Monto_Pagado | Currency | Monto abonado en pesos argentinos |
| ID_Transaccion_MP | Text | ID de transacción/payment de MercadoPago |
| Estado_Pago | Single Select | Aprobado / Rechazado / Pendiente / Reembolsado |
| Metodo_Registro | Text | Automático (webhook) / Manual / Efectivo |
| Fecha_Registro | DateTime | Cuándo se registró el pago en Airtable |
| Notas_Pago | Long Text | Observaciones sobre el pago (ej: motivo rechazo) |
Propósito: Configuración centralizada del sistema
Configuraciones Clave:
| Configuracion | Tipo | Valor |
|---|---|---|
| Plan_ID_Infantiles | Credencial | ID del plan en MercadoPago |
| Plan_ID_Juveniles | Credencial | ID del plan en MercadoPago |
| Plan_ID_Adolescentes | Credencial | ID del plan en MercadoPago |
| Evolution_API_Key | Credencial | Key para WhatsApp |
| Webhook_URL_MP | URL | URL del webhook MercadoPago |
Propósito: Trazabilidad completa de todas las operaciones
Campos de Log:
- ID_Log: Identificador único
- Timestamp: Fecha/hora exacta
- Evento: Tipo de evento (Suscripcion_Creada, Pago_Procesado, etc)
- DNI_Socio: DNI involucrado
- Origen: Workflow que generó el log
- Detalles: Información detallada del evento
- Estado_Resultado: Exitoso / Error / Omitido
- Socios ←→ Padres/Madres (Many to Many vía campo "Hijos_en_Club")
- Socios ←→ Pagos_Mensuales (One to Many)
- Socios ←→ Planes (Many to One vía campo "Categoría")
- Logs_Sistema → Socios (Many to One, vía DNI)
📖 Guía de Uso del Sistema
🚀 Proceso Completo: Alta de Nuevo Socio
Paso 1: Crear Registro en Airtable
Métodos de creación:
📝 Opción 1: Administrador Crea Manualmente
El personal administrativo del club crea el registro directamente en Airtable.
- Acceso directo a la interfaz de Airtable
- Control total sobre los datos ingresados
- Validación inmediata de información
🌐 Opción 2: Formulario Web (Forms)
Los padres/tutores completan un formulario web público que crea automáticamente el registro en Airtable.
- Formularios personalizados con validaciones
- Auto-completado en Airtable vía integración
- Reduce carga administrativa
- Disponible 24/7 para inscripciones
Campos obligatorios a completar (ambos métodos):
- ✅ DNI (único, sin puntos)
- ✅ Nombre_Completo
- ✅ Fecha_Nacimiento
- ✅ Categoría (se asigna automáticamente según edad)
- ✅ Email_madre_Padre
- ✅ WhatsApp (formato: +5491134567890)
Paso 2: Generar Enlace de Suscripción
Acción: Hacer clic en botón "Crear_Suscripcion" del registro
⏱️ Tiempo de procesamiento: 5-10 segundos
✅ Resultado esperado:
- Campo "Enlace_Suscripcion_MP" se completa automáticamente
- Campo "Estado_Suscripcion" cambia a "Enlace_Generado"
- Se envía WhatsApp automático al padre con el enlace
- Se registra log en tabla Logs_Sistema
Paso 3: Padre Completa Suscripción
Acción del padre:
- Recibe WhatsApp con enlace personalizado
- Hace clic en el enlace
- Ingresa a checkout de MercadoPago
- Completa datos de pago (tarjeta o efectivo)
- Confirma suscripción mensual
⏱️ Tiempo: 2-5 minutos
Paso 4: Sincronización Automática
Proceso automático (Workflow 3):
- MercadoPago envía webhook de confirmación
- Sistema busca socio por DNI (external_reference)
- Actualiza "Estado_Suscripcion" a "Activa"
- Registra primer pago en tabla Pagos_Mensuales
- Actualiza fecha de último pago
⏱️ Tiempo: Instantáneo (2-3 segundos)
💬 Proceso: Consulta de Estado por WhatsApp
Desde el lado del padre:
- Padre envía mensaje WhatsApp al número del club
- Escribe el DNI del socio (solo números)
- Sistema procesa automáticamente (Workflow 2)
- Recibe respuesta instantánea con estado de cuenta
🔄 Proceso: Gestión de Problema de Pago
↓
↓ (Al día siguiente)
↓
⚙️ Configuración del Sistema
🔐 Credenciales Necesarias
1. Airtable
Qué se necesita:
- Personal Access Token
- Base ID:
appIM8X2lshRuKnQb
Dónde configurar: Credentials en n8n
Nombre de credencial: airtableApi
2. MercadoPago
Qué se necesita:
- Access Token (de producción)
- Public Key
Dónde obtenerlo: Panel de Desarrolladores MercadoPago → Credenciales
Nombre de credencial: mercadoPagoApi
TEST-
3. Evolution API (WhatsApp)
Qué se necesita:
- API Key
- Instance Name:
club-futbol - URL Base:
https://evolution.tudominio.com
Configuración en workflows: Header "apikey" en nodos HTTP Request
🔗 Configuración de Webhooks
Webhook: MercadoPago → n8n
URL a configurar en MercadoPago:
Eventos a suscribir:
- ✅ subscription.created
- ✅ subscription.updated
- ✅ subscription.cancelled
- ✅ payment.created
- ✅ payment.updated
Cómo configurar:
- Ir a Panel MercadoPago → Webhooks
- Crear nuevo webhook
- Pegar URL
- Seleccionar eventos
- Activar webhook
Webhook: Evolution API → n8n
URL del Workflow 2 (Consultas):
Evento a suscribir:
- ✅ message.received
Configurar en Evolution: Webhook settings para instancia "club-futbol"
Botón Airtable → n8n
Campo: Crear_Suscripcion
Tipo: Button → Open URL
Configurar en Airtable: Tabla Socios → Agregar campo tipo Button
✅ Lista de Verificación Pre-Activación
Antes de activar los workflows en producción:
- ☐ Credenciales de Airtable configuradas y probadas
- ☐ Credenciales de MercadoPago (PRODUCCIÓN) configuradas
- ☐ Evolution API Key configurada
- ☐ Webhook MercadoPago creado y activo
- ☐ Webhook Evolution API configurado
- ☐ Botón Airtable creado con URL correcta
- ☐ Planes MercadoPago creados (Workflow 0 ejecutado)
- ☐ IDs de planes guardados en tabla Configuracion_Sistema
- ☐ Prueba end-to-end con socio de prueba
- ☐ Verificar logs en tabla Logs_Sistema
🔧 Solución de Problemas
❌ Problemas Comunes y Soluciones
Problema: No se genera el enlace de suscripción
Síntomas:
- Botón "Crear_Suscripcion" no hace nada
- Campo "Enlace_Suscripcion_MP" queda vacío
Causas posibles:
- Workflow 1 está inactivo → Solución: Activar workflow
- Datos incompletos en el socio → Solución: Verificar DNI, Email_Padre, WhatsApp_Padres
- Plan_ID no configurado para la categoría → Solución: Ejecutar Workflow 0
- WhatsApp en formato incorrecto → Solución: Usar formato 5491134567890
Cómo verificar:
- Revisar tabla Logs_Sistema para el DNI
- Verificar ejecuciones del Workflow 1 en n8n
- Confirmar que Plan_ID existe en tabla Configuracion_Sistema
Problema: WhatsApp no se envía
Síntomas:
- Enlace se genera correctamente
- Pero padre no recibe WhatsApp
Causas posibles:
- Evolution API desconectada → Solución: Reconectar WhatsApp en Evolution
- API Key incorrecta → Solución: Verificar credencial en workflows
- Instance name incorrecto → Solución: Debe ser "club-futbol"
- Número bloqueado → Solución: Verificar con otro número
Cómo verificar:
- Probar envío manual desde Evolution
- Revisar logs de Evolution API
- Verificar que WhatsApp esté conectado
Problema: Estados no se sincronizan desde MercadoPago
Síntomas:
- Padre completa pago en MercadoPago
- Pero estado en Airtable no cambia
Causas posibles:
- Workflow 3 inactivo → Solución: Activar workflow
- Webhook MP no configurado → Solución: Configurar en panel MercadoPago
- URL webhook incorrecta → Solución: Verificar URL exacta
- DNI no coincide → Solución: Verificar external_reference
Cómo verificar:
- Revisar webhooks recibidos en n8n
- Verificar logs en MercadoPago
- Confirmar que Workflow 3 se ejecuta
- Buscar en tabla Logs_Sistema el evento
Problema: Consultas por WhatsApp no funcionan
Síntomas:
- Padre envía DNI por WhatsApp
- No recibe respuesta automática
Causas posibles:
- Workflow 2 inactivo → Solución: Activar workflow
- Webhook Evolution no configurado → Solución: Configurar en Evolution
- DNI no encontrado → Solución: Verificar que existe en tabla Socios
- Formato DNI incorrecto → Solución: Solo números, sin puntos ni espacios
📊 Herramientas de Diagnóstico
1. Tabla Logs_Sistema
Uso: Revisar trazabilidad de todas las operaciones
Filtros útiles:
- Por DNI_Socio: ver historial de un socio específico
- Por Evento: ver todos los eventos de un tipo
- Por Estado_Resultado: filtrar solo errores
- Por Origen: ver actividad de un workflow específico
2. Panel de Ejecuciones en n8n
Uso: Ver ejecuciones detalladas de workflows
Información disponible:
- Datos de entrada y salida de cada nodo
- Errores con stack trace completo
- Tiempo de ejecución
- Flujo de datos entre nodos
3. Panel de Webhooks en MercadoPago
Uso: Verificar que webhooks se están enviando
Qué revisar:
- Estado del webhook (activo/inactivo)
- Últimas entregas exitosas/fallidas
- Payload enviado
- Respuesta recibida de n8n
🆘 Contacto de Soporte
Para problemas técnicos:
- Email: [email protected]
- WhatsApp: +54 9 11 3456-7890
- Horario: Lunes a Viernes 9:00 - 18:00