Checkout para Moodle

Documentación técnica · versión 1.3.1 (2026100231) · local_tiendacursos + block_tiendacursos

1. Compatibilidad y requisitos

• Moodle 4.5 LTS (2024100700) a 5.1 ($plugin->supported = [405, 501]), PHP 8.1 o superior, PostgreSQL, MySQL o MariaDB.
• Cron cada 1–5 minutos. Salida HTTPS hacia www.flow.cl, sandbox.flow.cl, api.mercadopago.com y licencias.norteduc.cl (activación única).
• Sin dependencias externas ni CDN: JavaScript mínimo en línea, estilos en styles.css con variables del tema.
• El bloque depende de local_tiendacursos ≥ 2026100221 (bloque 1.2.0).

2. Arquitectura y por qué no se usa paygw + enrol_fee

Moodle trae un subsistema de pagos (core_payment, pasarelas paygw_*) y la matrícula por pago (enrol_fee). Ese diseño exige que el comprador ya sea usuario y esté autenticado: la «cuenta de pago» se asocia a un userid y la matrícula se hace sobre ese usuario. La tienda necesita lo contrario:

• compra sin cuenta: el pedido existe antes que el usuario, y la cuenta se crea al confirmarse el pago;
• un pedido con N estudiantes distintos del comprador (compra grupal);
• renovación de la misma matrícula vencida, cupones y descuentos por tramo;
• pasarelas chilenas (Flow) con confirmación servidor a servidor y conciliación propia.

Por eso la tienda es un complemento local con su propia tabla de pedidos y adaptadores de pasarela (classes/gateway/*) con una interfaz común (start, verify, order_from_notification, test_connection). La matrícula usa la API estándar de enrol_manual (enrol_user, update_user_enrol), así que el resto de Moodle (informes, finalización, certificados) ve matrículas normales.

3. Flujo de un pedido

checkout.php ──► orders::create()            pedido "pending" + filas de estudiantes (transacción)
             └─► orders::start_payment()     $0 → mark_paid · transferencia → instrucciones · en línea → URL pasarela
pasarela ──server──► notify.php              NO_MOODLE_COOKIES, sin exigir user-agent; GET+POST+JSON
             └─► gateway::order_from_notification() → gateway::verify()   (consulta a la API, nunca confía en el aviso)
             └─► orders::apply_verification() estado + monto ≥ pedido + referencia propia
             └─► orders::mark_paid()          lock por pedido; idempotente
                    ├─ primera vez: estado paid, uso de cupón, evento order_paid, comprobante, aviso a ventas
                    └─ fulfil(): por estudiante → ensure_user() → enrol() / renovación → evento student_enrolled → bienvenida
result.php (regreso del navegador)            si sigue pendiente, vuelve a consultar la API; nunca matricula por sí mismo
task\reconcile_orders (cada 15 min)          consulta pedidos en línea pendientes (>5 min); expira: en línea 3 días, transferencia 30

4. Seguridad

5. Modelo de datos (XMLDB)

Las consultas del panel están paginadas (50 por página) y precargan cursos y conteos en una sola consulta (sin N+1). La exportación se transmite con \core\dataformat y un recordset.

6. Pasarelas

Flow (API v2)

• Base: integración https://sandbox.flow.cl/api, producción https://www.flow.cl/api.
• Firma: parámetros ordenados por nombre, concatenados nombre+valor, HMAC-SHA256 con la Secret Key, en s.
• POST /payment/create (commerceOrder = referencia, urlConfirmation, urlReturn, paymentMethod 9) → redirección a url?token=….
• Verificación: GET /payment/getStatus (token) o /payment/getStatusByCommerceId. Estados 1 pendiente, 2 pagado, 3 rechazado, 4 anulado.
• Prueba de conexión: getStatusByCommerceId de una orden inexistente (solo lectura).

Mercado Pago (Checkout Pro)

• POST /checkout/preferences con external_reference, back_urls, auto_return y notification_url.
• Integración usa sandbox_init_point; producción init_point.
• Webhook (type=payment&data.id) o IPN (topic=payment&id) → GET /v1/payments/{id}; sin id se busca en /v1/payments/search?external_reference=.
• Prueba de conexión: GET /users/me.

Transferencia

No es en línea: el pedido queda pendiente hasta que un administrador confirma el pago en el panel.

Cada pasarela guarda su modo en <gw>_mode (sandbox|production) y sus credenciales en <gw>_<campo>_sandbox y <gw>_<campo>_prod. El cliente HTTP (gateway\http) es reemplazable en pruebas.

7. Cuentas, matrícula y renovación

• Usuario = RUT normalizado en minúsculas sin puntos (12345678-5), auth manual, idnumber = RUT con formato, institución = empresa, auth_forcepasswordchange.
• Estado de acceso (local\access): activo, vencido (timeend ≤ ahora), suspendido (matrícula o instancia deshabilitada con fecha vigente) o sin matrícula; considera cualquier método de matriculación.
• Renovación: update_user_enrol(instancia existente, ACTIVE, ahora, ahora + días), habilita la instancia si estaba deshabilitada y reasigna el rol estudiante si faltaba. No crea matrículas duplicadas.
• Packs (orders::enrol_until()): la fecha de término del estudiante se fija una vez (student.timeend) y se aplica a cada curso del snapshot packcourses: vencido → se renueva la misma matrícula; vigente → se conserva y solo se extiende si terminaba antes (nunca se acorta; sin término queda sin término); sin matrícula → matrícula manual; suspendido → error del estudiante (reintentable desde Ventas). Reintentar da las mismas fechas. Validación previa: suspendido en algún curso o vigente en todos = no puede comprar.
• Precio del pack: oferta si offerprice > 0 y (sin término o ahora ≤ offeruntil), si no la suma. Tramos: los generales (courseid 0). Cupones: solo los «para todos los cursos» (coupon_notpack).
• Se vende con licencia de pago, activo, ≥ 2 cursos visibles y precio > 0 (packs::sellable(), verificado también en orders::create()).

8. Correo

• local\transport: email_to_user (respeta smtphosts, noreply, divertallemailsto) o SMTP propio con moodle_phpmailer (Date, Message-ID con el dominio del remitente, HTML + texto, Reply-To).
• local\mailer: plantillas con marca del sitio (logo, nombre y brandcolor del tema; respaldo Boost). Si el envío falla, cola con reintento escalonado (15 min × intentos, máx. 6 h, 12 intentos).
• local\templates (1.2): 9 tipos (welcome_new, welcome_existing, renewal, receipt, transfer, admin_sale, admin_pending, expiry_soon, expired) con destinatario, si es opcional y si requiere licencia. Sin fila en _tpl se usa la cadena del idioma del destinatario (get_string_manager()->get_string(..., $lang)), escrita con variables {nombre} al pasarle un objeto de marcadores. Variables permitidas por tipo y obligatorias validadas al guardar (texto limpio con clean_text); los valores se escapan con s(); un href que termina en una variable (también %7Bvar%7D que deja el editor) recibe el valor exacto. Los opcionales desactivados no se envían ni se reintentan.
• local\expiry + tarea send_expiry_notices (diaria 9:00, solo con licencia): candidatos = estudiantes matriculados por la tienda con término entre hace 3 días y hoy + máx(días); el término real se lee de user_enrolments (en packs, el menor de sus cursos). Envía el umbral más pequeño alcanzado y registra todos los mayores; «vencido» solo dentro de 3 días; registro único por persona, curso/pack, tipo y término (idempotente). Sin cola: si falla, se intenta al día siguiente.

9. Integración con Moodle

10. Licencia, planes y actualizaciones

Código común de los complementos Norteduc (norteduc_license, norteduc_panel_perms, norteduc_updates, copias idénticas verificadas con shared/sync.py --check). Código de activación Ed25519 de un solo dominio (producto tc), activado una vez en línea con comprobante firmado.

Las funciones bloqueadas se muestran con lock_html() («Comprar licencia» → https://www.norteduc.cl/tienda/#complementos, fija en el código). «Contactar a soporte» (support_button(), mailto contacto@norteduc.cl con asunto y datos técnicos) va en el pie del panel y en Licencia, en todas las versiones. La tarea check_updates lee https://licencias.norteduc.cl/version/tc.json y el panel muestra el aviso de nueva versión (descarga POST con el código si la licencia está vigente; enlace download público en la gratuita; «renueva» si la anual venció).

11. Catálogo para sitios externos (1.3)

Clase \local_tiendacursos\local\sites (política de acceso, claves, feed, caché, límite) y la sección del panel sites.php (permiso de sección sites, nuevo = «Sin acceso»; la 1.3 no migra niveles). Función de pago sites en license::PAID_FUNCTIONS.

Formato del feed (versión 1)

{
  "version": 1,
  "site": {"name": "...", "url": "https://aula.example.com/", "showcase": ".../local/tiendacursos/index.php",
           "currency": "CLP", "locale": "es-CL"},
  "labels": {"buy": "Comprar", "pack": "Pack", "hours": "{n} horas", "days": "Acceso por {n} días", ...},
  "items": [
    {"type": "pack", "id": 1, "name": "...", "category": "", "summary": "texto plano (≤300)", "hours": null,
     "access_days": 90, "price": {"currency": "CLP", "normal": 189700, "offer": 149900, "offer_until": "2026-12-31T23:59:00-03:00",
     "current": 149900, "formatted": "$149.900", "formatted_normal": "$189.700"}, "savings": 39800, "featured": true,
     "courses": [{"id": 5, "name": "..."}], "image": ".../image.php?pack=1&v=...", "url": ".../checkout.php?pack=1"},
    {"type": "course", "id": 3, "category_id": 2, ...}
  ]
}

Primero los packs (como en la vitrina) y luego los cursos; los packs traen category_ids (categorías de sus cursos) para filtrar igual que la vitrina. El feed y el iframe usan siempre el idioma del sitio (force_current_language($CFG->lang)), así la caché compartida nunca queda en el idioma de un visitante. Caché MUC feed (60 s, clave por idioma) que se purga al guardar ofertas, packs o los ajustes; el ETag depende solo del contenido y Last-Modified es la hora en que cambió ese ETag (ajuste ext_lm_feed_<idioma>), así también cambia al borrar un curso, renombrar una categoría o cambiar una portada. Caché MUC ratelimit: una entrada por IP (ventana:contador, ventana de un minuto, sobrescrita; no crece); el conteo no es atómico (tolerancia aceptable para un límite anti-abuso). Detrás de un proxy o CDN hay que configurar getremoteaddrconf/reverseproxy para que getremoteaddr() entregue la IP real. El 429 se envía después de las cabeceras CORS para que la página autorizada pueda leerlo.

Reglas de acceso (sites::decide())

1. Publicación apagada o sin licencia → 404 disabled; frame-ancestors 'self'.
2. Origin: null → 403.
3. Con k: debe ser la clave de un sitio activo; si llega Origin, debe ser ese sitio (con o sin «www.», mismo esquema y puerto).
4. Sin k y ext_requirekey → 403. Sin k ni exigencia: con Origin, debe ser un sitio activo; sin Origin (servidor, curl) se responde.

12. Pruebas y calidad

• 1.3: PHPUnit 106 pruebas en Moodle 4.5 LTS y 5.0 (13 nuevas en sites_test: normalización de direcciones, «www.», decisión CORS, claves y exigencia, versión gratuita, frame-ancestors, contenido del feed sin cupones, tramos, cursos ocultos ni compradores, ETag, 304, límite por IP, validación al guardar, permisos de sección y códigos generados). Prueba real con un sitio en otro origen (feed, código para pegar, iframe) y compra hasta confirmar el pago; un origen no autorizado queda bloqueado por CORS y frame-ancestors. Actualización 1.2 → 1.3 en 4.5 y 5.0.
• 1.2: PHPUnit 90 pruebas + 2 del bloque en Moodle 4.5 LTS y 5.0: packs (precios, reglas de venta, tarjetas, compra grupal con tramo y cupón, misma fecha en todos los cursos, un correo, extensión y renovación, filtros, borrar/inactivar), plantillas (texto original = cadenas, validación de variables, texto propio usado y sin contraseñas guardadas, activar y desactivar, prueba, migración de permisos) y avisos (secuencia 7/1/vencido, sin repetir, hueco, renovación, pack, gratis, privacidad). Actualización 1.1 → 1.2 probada en 4.5 (gratis) y 5.0 (licencia, usuarios del panel) sin pérdida de datos.
• 1.1: PHPUnit 71 pruebas en Moodle 4.5 LTS y 5.0 (las de 1.0 más: permisos por sección, solo el administrador gestiona usuarios, roles de Moodle sin acceso, versión gratuita sin usuarios del panel, 1 medio de pago, 1 estudiante, cupones y tramos ignorados pero conservados, vencimiento anual con gracia, ayudantes de actualización, aviso de nueva versión y las pruebas de las clases comunes de licencia) + 1 del bloque.
• Actualización probada desde 1.0.2 (con pedidos, cupones, tramos, credenciales y un gestor) en Moodle 4.5 y 5.0.
• moodle-cs (moodle-extra): 0 errores.
• Herramientas de desarrollo (datos demo) en dev/, fuera del ZIP.