Convoca Enroll

Guía para administradores y monitores del motor de actividades e inscripciones de Convoca. Documentada sobre la versión 2.7.62.

Manual para la junta directiva (sin conocimientos técnicos)¶

Esta página es la referencia técnica del plugin. Para el día a día hay un manual en tres partes, en castellano y con capturas:

• Instalación
• Configuración
• Guía de uso

1. Introducción¶

Convoca Enroll gestiona el ciclo completo de una actividad: creación, inscripción con control de aforo y lista de espera, aportación/pago, confirmación de plaza, check-in por QR, evaluaciones, recordatorios automáticos y generación de carteles para redes.

Requiere: el plugin convoca-core (Convoca Common Utilities) activo. Sin él, el plugin se desactiva automáticamente en la activación.

2. Instalación¶

1. Asegúrate de que Convoca Core está activo.
2. Sube la carpeta convoca-enroll a /wp-content/plugins/.
3. Activa el plugin desde Plugins.
4. En la activación el plugin crea automáticamente: la página «Panel de reservas», las tablas de base de datos, las plantillas de email por defecto y los eventos de cron.

3. Menú de administración¶

El plugin registra un menú principal «Actividades» (icono portapapeles, posición 27). Sus submenús:

También añade un widget de escritorio «Inscripciones Convoca» con totales (inscripciones, confirmadas, en espera y próximas actividades).

4. Configuración (Ajustes)¶

Accede a Actividades → Configuración. Está organizada en pestañas:

Ajustes generales relevantes¶

5. Crear una actividad¶

1. Ve a Actividades → Añadir nueva actividad.
2. Rellena título, descripción y resumen corto (el resumen se usa en listados y carteles).
3. Configura los datos logísticos:

1. Asigna una imagen destacada (se usa en listados y en el cartel).
2. Publica.

Validaciones automáticas al guardar: la fecha de fin no puede ser anterior a la de inicio (se corrige sola); plazas_disponibles no puede superar plazas_totales; si dejas una vacía se iguala a la otra.

El CPT actividad es público, con archivo en /actividades/. El archive del frontend muestra solo actividades futuras, ordenadas por fecha de inicio ascendente. Cada actividad singular emite JSON-LD (EducationEvent) con fecha, lugar, precio mínimo y disponibilidad (InStock/SoldOut).

6. Shortcodes y bloques¶

Shortcodes¶

Atributos de [convoca_form_inscripcion]:

id="123"                (obligatorio) ID de la actividad
mostrar_plazas="true"   muestra plazas disponibles
mostrar_precios="true"  muestra precios

Atributos de [convoca_actividad_meta] (se formatea según el campo):

[convoca_actividad_meta field="ubicacion"]
[convoca_actividad_meta field="fecha_inicio"]   → "15 Mar 2026"
[convoca_actividad_meta field="precio"]         → "5,00 €" o "Gratis"
[convoca_actividad_meta field="plazas_disponibles"] → "4 / 20"

También admite placeholders %% dentro del contenido de una actividad: %%FECHA_INICIO%%, %%LUGAR%%, %%PRECIO%%, %%PLAZAS%%.

Bloques (Gutenberg)¶

7. Motor de inscripción¶

La lógica central vive en Motor_Inscripcion (clase Convoca\Enroll\Motor_Inscripcion).

Estados de una inscripción¶

Cómo se inscribe un usuario¶

El formulario lo pone el plugin en la ficha de la actividad (CPT_Actividad::append_registration_form()), no el tema: así funciona también en sitios cuyo tema no sea el de Convoca. Un tema que ya pinte el formulario puede tomar el relevo declarando add_theme_support( 'convoca-actividad-form' ), y cada sitio puede desactivarlo con el filtro convoca_enroll_form_en_ficha (recibe el ID de la actividad). Si la actividad ya ha empezado, la ficha no ofrece el formulario: explica que ha finalizado.

1. El formulario público (wp_ajax_convoca_inscribir) valida nombre, email (con verificación de dominio MX/A), DNI/NIE y consentimiento RGPD.
2. Motor_Inscripcion::inscribir() aplica rate limit (5 intentos por IP y hora), comprueba que la actividad existe y no ha finalizado, y valida duplicados de email/DNI en la misma actividad.
3. Se genera un código de reserva único de 8 caracteres (sin I, O, 0, 1).
4. Todo se ejecuta en transacción SQL con SELECT … FOR UPDATE sobre la fila de la actividad. Esto serializa las inscripciones concurrentes y cierra la condición de carrera de doble clic (TOCTOU): los duplicados se re-verifican dentro de la transacción.
5. Si hay plazas, se decrementa atómicamente plazas_disponibles; si no, el estado pasa a lista_espera.
6. El estado resultante es:
7. pendiente_pago si la actividad requiere pago con importe > 0;
8. pendiente si no requiere pago;
9. lista_espera si no hay plazas.
10. Se dispara el hook convoca_enroll_inscripcion_nueva (que encola el email de recepción o de lista de espera).

Flujo de pago → confirmación¶

Cuando la actividad requiere pago:

1. El formulario crea un pago en la pasarela (Convoca\Gateway\Payment_Handler::create_payment() con origin=enroll, origin_id=inscripción) y escribe _convoca_pago_id antes de pagar.
2. Al completarse el pago, la pasarela dispara el hook convoca_gateway_payment_completed.
3. Payment_Listener (clase Convoca\Enroll\Payment_Listener) lo recibe, deduplica contra el pago realmente aplicado (_convoca_pago_aplicado_id, no contra _convoca_pago_id — fix E2E-9) y llama a Motor_Inscripcion::confirmar().
4. La creación del pago está protegida con un lock atómico de BD para evitar doble creación por doble clic.
5. Si la confirmación falla (p. ej. aforo agotado mientras se pagaba), la inscripción se marca _convoca_needs_manual_review para revisión manual.

Regla clave de concurrencia: pendiente y pendiente_pago ya consumieron su plaza al inscribirse, así que confirmar() solo decrementa el aforo cuando la inscripción venía de lista_espera (fix de doble plaza).

Cancelación y liberación de plaza¶

Motor_Inscripcion::cancelar() ejecuta en transacción:

1. Si el estado consume plaza (confirmada, pendiente o pendiente_pago), libera la plaza: primero intenta promover al primero de la lista de espera y, si no hay nadie, incrementa plazas_disponibles (fix E2E-10: antes solo liberaba confirmada).
2. Marca estado = cancelada e invalida el token de check-in por seguridad.
3. Dispara convoca_enroll_inscripcion_cancelada (email de cancelación).

La cancelación puede hacerla el propio usuario desde el panel de reservas (con email + código) o un administrador/monitor desde el CRM.

Ventana de cancelación (D9): si la actividad está a menos de cancel_window_hours (opción convoca_enroll_settings, 24 h por defecto, configurable) de su inicio, la cancelación del usuario se rechaza con un mensaje de aviso, salvo que la haga un administrador, alguien con convoca_manage_enroll o se use $force=true (p. ej. liberación automática por pago fallido). Cada cancelación tardía se registra en el contador _convoca_late_cancellations_<año>; al alcanzar 3 cancelaciones tardías en un año se notifica al administrador por email para revisión manual de la actividad.

Pago fallido libera plaza (D10): si la pasarela comunica un pago rechazado (convoca_gateway_payment_failed) para una inscripción que sigue en pendiente_pago, el Payment_Listener la cancela automáticamente con motivo «pago fallido» (con $force=true, sin pasar por la ventana de cancelación) y libera la plaza para la lista de espera. Si la inscripción ya estaba confirmada o el pago ya se aplicó, el evento se ignora.

Regla de una reserva por persona¶

Con limite_una_reserva activo, un adulto no puede tener más de una reserva activa (estados confirmada, pagada, pendiente, pendiente_pago o lista_espera). Los menores a cargo quedan excluidos de esta regla.

8. Lista de espera¶

• Cuando el aforo está completo, la inscripción queda en lista_espera sin consumir plaza.
• Al cancelarse una plaza confirmada/pendiente/pendiente_pago, promote_waitlist() promueve atómica y automáticamente al primero de la lista al estado pendiente.
• Prioridad de socios (D8): la promoción ordena primero por socio con cuota al día (campo es_socio/condición de socio activo vía convoca-members) y después por fecha de inscripción más antigua. Un socio en espera se promueve antes que un no socio inscrito antes.
• La promoción dispara convoca_enroll_inscripcion_promovida (email «¡Tienes una plaza disponible!»).
• El bloque convoca-enroll/lista-espera muestra el número de personas en espera.

9. Gestión de inscripciones (admin y CRM)¶

Listado principal (Actividades → Inscripciones)¶

Muestra todas las inscripciones con búsqueda, acciones masivas (Confirmar plazas), exportación CSV y (con licencia PRO) exportación PDF. Cada fila abre el detalle de la inscripción, donde puedes:

• Cambiar el estado (los cambios a confirmada/cancelada pasan por el motor para gestionar plazas correctamente).
• Marcar pagado manualmente.
• Editar notas internas.
• Reenviar el email de confirmación.

CRM de monitores (Actividades → Mis actividades)¶

Panel simplificado para el rol monitor_actividad y responsables asignados. Por actividad muestra contadores (confirmados, asistieron, faltaron, pendientes) y permite:

• Validar inscripciones pendientes o promover desde lista de espera.
• Marcar asistencia (✅/❌) por participante.
• Modo check-in rápido y exportar CSV de todas o de asistentes.

Un monitor solo ve las actividades que tiene asignadas (meta _convoca_responsables o inscripción confirmada como voluntario_aprobado).

10. Check-in con QR¶

Cada inscripción confirmada tiene un token de check-in único e impredecible (48 caracteres hexadecimales).

Como monitor/administrador¶

1. Abre /checkin/ (escáner web optimizado para móvil, usa html5-qrcode servido localmente) o usa el submenú Check-in.
2. Escanea el QR del asistente. El token se valida contra _convoca_checkin_token.
3. El registro de asistencia es idempotente y está protegido con SELECT … FOR UPDATE (evita registros duplicados bajo concurrencia).
4. También puedes marcar asistencia manualmente (✅/❌) desde el listado de inscripciones o el CRM.

Requisito de acceso: manage_inscripciones o rol voluntario_aprobado, y ser responsable de la actividad.

Las dos rutas del check-in¶

Las registra Checkin_Handler por rewrite rule. El nombre que ponen las reglas tiene que ser exactamente el de la query var que lee el handler (convoca_enroll_checkin y convoca_enroll_checkin_page); si no coincide, la ruta responde con la web normal y el escáner queda inalcanzable —que es lo que pasaba hasta la 2.7.17—. Las reglas viven en la base de datos: al actualizar el plugin hay que vaciar la caché de reglas (guardar Ajustes → Enlaces permanentes, o wp rewrite flush), o el cambio no surte efecto.

Comportamiento comprobado en vivo: el check-in directo responde «Check-in Exitoso», la asistencia queda registrada una sola vez —repetir el escaneo no la duplica— y atribuida a quien la hizo; un token que no existe o está manipulado responde «Token de check-in no válido» y sin sesión de personal la ruta devuelve 403.

Como asistente¶

El email de confirmación incluye el QR y un enlace ICS para añadir la actividad al calendario.

El QR lleva a /checkin/<token>/?h=… y funciona para quien lo recibe: el socio lo abre en su móvil y su asistencia queda registrada, sin cuenta ni permisos de administración. La firma h autoriza esa inscripción y ninguna otra (un socio no puede marcar la asistencia de otro) y se calcula con la sal persistente del sitio, así que un QR enviado ayer sigue valiendo hoy.

La imagen la pinta el propio Convoca (QR_Generator, con chillerlan/php-qrcode) y se guarda en wp-content/uploads/convoca-qr/: el token del socio no sale del sitio. Antes se le pedía la imagen a un servicio externo con la URL de check-in dentro, y por ahí se iba la credencial.

Qué responde cada caso, para poder diagnosticar de un vistazo:

Al cancelar una inscripción, el token de check-in se invalida inmediatamente.

11. Evaluaciones¶

Las evaluaciones son un CPT interno (convoca_evaluacion, no público). El formulario se muestra con [convoca_evaluacion actividad_id="X"] o el bloque convoca-enroll/evaluacion.

Reglas de acceso al formulario:

• Solo después de que la actividad haya finalizado (_convoca_fecha_fin en el pasado).
• Requiere sesión iniciada.
• Pueden evaluar: administradores, convoca_manage_evaluations, monitores responsables o voluntario_aprobado con asistencia registrada (si).
• Un usuario solo puede enviar una evaluación por actividad.

El formulario recoge 4 valoraciones de 1–5 estrellas (gestión, instalaciones, participantes, comunicación) y campos de texto abierto. Al enviarse dispara el hook convoca_evaluacion_completada.

Recordatorios de evaluación¶

Eval_Reminder_Cron (cron diario convoca_enroll_eval_reminder) envía automáticamente un recordatorio a los monitores y voluntarios que asistieron, N días después de la finalización (configurable en Ajustes → Recordatorios de evaluación). Por defecto 3 días, con variables {nombre_actividad}, {fecha_actividad}, {evaluador_nombre}, {link_evaluacion}.

El email feedback_post (7 días después, vía cron diario) es independiente y pide opinión por correo directo.

12. Emails automáticos¶

Email_Automation gestiona 11 plantillas editables en Ajustes → Emails, todas con el layout HTML de Convoca y enviadas de forma asíncrona a través de Email_Queue (cola procesada por cron cada minuto).

Variables disponibles: {nombre}, {email}, {actividad}, {fecha}, {hora}, {ubicacion}, {estado}, {importe}, {plazas_restantes}, {codigo_reserva}, {panel_reservas}, {qr_code}, {url_checkin}, {album_url}, {calendario_link}.

Cada envío tiene deduplicación atómica (no se reenvía el mismo correo en una ventana de 5 minutos) y notifica una copia al email del administrador. Los recordatorios solo se envían si la actividad tiene el flag de recordatorio activado (reminder_7dias, reminder_1dia, reminder_1hora, reminder_post_evento).

Recordatorio configurable X horas antes (D27): además de los fijos, Activity_Reminder_Cron (cron horario, hook convoca_enroll_activity_reminder) envía un recordatorio a las X horas configurables (_convoca_reminder_hours, opción de la actividad, 24 h por defecto) antes del inicio, con fecha/hora/lugar y enlace al panel. El envío es por inscripción con dedupe (meta _convoca_reminder_activity_sent): cada inscripción confirmada recibe el recordatorio una sola vez por actividad.

13. Integraciones de Google¶

Google Calendar¶

• Sincroniza actividades como eventos (creación, actualización y borrado) vía OAuth 2.0.
• _convoca_google_event_id / _convoca_google_event_link guardan la referencia.
• Cada confirmación adjunta un archivo ICS (librería eluceo/ical).
• Configurable en Ajustes → Google Calendar (sincronización automática, ID de calendario, credenciales).

Google Photos¶

• Crea álbumes por actividad y los comparte con los participantes confirmados.
• Meta relacionada: _convoca_google_album_id, _convoca_google_album_url, _convoca_google_album_shared.
• Acciones AJAX desde la metabox de la actividad: crear álbum y compartir.

Google Sheets¶

• Sincronización opcional (sheets_enabled) con API key (se recomienda definirla vía constante CONV_ENROLL_GOOGLE_SHEETS_API_KEY).

14. Webhooks¶

Funcionalidad PRO (licencia webhooks). Webhook_Dispatcher encola eventos de cambio de estado en la tabla convoca_enroll_webhook_queue (o delega en Convoca\Core\Webhook_Manager si está disponible).

• Eventos: state_change (nueva, cancelada, confirmada, promovida) y attendance_change.
• La cola se procesa por cron (cada minuto) con reintentos (máx. 3) y lock de concurrencia.
• El secreto configurado se envía en la cabecera X-Convoca-Signature (HMAC-SHA256 del payload).

Configuración en Ajustes → General → Webhooks (URL y secreto).

15. Carteles (Poster Engine)¶

El Poster Engine v6 genera carteles de actividad con Imagick directamente (sin pipeline HTML/CSS/PDF). Requiere la extensión PHP Imagick.

Formatos¶

Plantillas¶

8 plantillas de sistema (paleta + composición) almacenadas en la tabla convoca_media_templates como JSON (layers, design_tokens, formats): nature-classic, modern-ngo, educational-workshop, volunteer-campaign, kids-family, full-photo-hero, story-focused, minimal-corporate.

• Tipografías Montserrat y Playfair Display servidas desde assets/fonts/.
• La imagen se toma de: imagen destacada → _convoca_poster_image_id → primera imagen del contenido/galería. Si no hay, se dibuja un placeholder.
• Incluye QR (librería chillerlan/php-qrcode) que apunta al blog post, landing o URL de inscripción de la actividad.
• Los carteles se cachean en wp-content/uploads/convoca-posters/.

Cómo se generan: por API (no hay pantalla)¶

El cartel se genera por API REST, que es la interfaz real del módulo:

No hay pantalla (ni metabox ni página de administración) para lanzarlo a mano desde el escritorio, y no la ha habido nunca: los ficheros que la pretendían —assets/js/media-admin.js, assets/js/convoca-editor.js y assets/css/media-admin.css— eran de junio, no los encolaba ningún PHP, y sus acciones (convoca_render_poster, convoca_create_blog_post) y su página (convoca-media-editor) no existían en ninguna parte; la API, el Poster Engine y el gestor de entradas son posteriores. Se retiraron como código muerto en las versiones 2.7.19 y 2.7.20, con copia previa y explicación. Si se quiere una pantalla para hacerlo a mano, es un envoltorio fino sobre esas cuatro rutas.

Suite Social¶

Módulo social/ para publicar en redes vía OAuth 2.0:

• Meta (Facebook/Instagram) y Google Business Profile, más un proveedor de WhatsApp.
• Tokens cifrados con AES-256-CBC (clave CONVOCA_SOCIAL_KEY o wp_salt('auth')).
• Publicación asíncrona con Action Scheduler (hook convoca_social_publish).
• Tablas: convoca_social_accounts, convoca_social_queue, convoca_media_logs.

16. API REST¶

Dos namespaces.

convoca-enroll/v1 (inscripciones y actividades)¶

convoca/v1 (medios y redes)¶

Formato de error estándar de WP REST (rest_forbidden, etc.). El token de check-in nunca se expone en las respuestas de inscripciones.

17. Roles y capacidades¶

El plugin crea el rol monitor_actividad (Monitor de Actividad) y garantiza estas capacidades al actualizar:

Un monitor solo puede editar/leer actividades donde esté asignado como responsable (map_meta_cap); no puede borrarlas.

18. Hooks públicos principales¶

add_action( 'convoca_enroll_inscripcion_nueva', function ( $inscripcion_id, $actividad_id, $estado ) {
    // Lógica al crearse una inscripción (nueva o en lista de espera).
}, 10, 3 );

add_action( 'convoca_inscripcion_confirmada', function ( $inscripcion_id, $actividad_id ) {
    // Lógica al confirmarse una plaza.
}, 10, 2 );

19. Cron y tablas de base de datos¶

Eventos de cron¶

Tablas personalizadas¶

20. WP-CLI¶

wp bde webhooks   # gestión de webhooks
wp bde migrate    # migración de datos

Copia de los correos a los monitores¶

Los correos de inscripciones y actividades se copian a los responsables (monitores) de la actividad mediante Convoca\Core\Email_Copy; si la actividad no tiene responsables, la copia va al correo de administración. Los responsables se toman del campo Responsables de la actividad (usuarios de WordPress).

21. Problemas comunes¶