Componentes principales
1. Buy Box (Shopify Theme Extension)
El buy box es un widget que se inyecta en la página de producto del storefront de Shopify. Muestra los planes de suscripción disponibles para ese producto, permite al cliente elegir frecuencia y cantidad, y genera el link firmado que lleva al checkout custom. No procesa pagos ni almacena datos: su única función es presentar opciones y redirigir.2. Checkout Custom
Página embebida en el theme de Shopify que reemplaza al checkout nativo para las suscripciones. Es donde ocurre la tokenización de la tarjeta: el SDK JS de Mercado Pago corre enteramente en el navegador del cliente, convierte los datos de tarjeta en un token opaco y ese token — nunca los datos reales — viaja al servidor de Reval. Ver Checkout Técnico para el flujo detallado.3. Servidor de Reval
El orquestador central. Es el único componente con acceso a las APIs de Shopify y Mercado Pago a la vez. Sus responsabilidades incluyen:- Crear y gestionar mandatos (preapprovals) en MP
- Programar y ejecutar los cobros de cada ciclo
- Recibir y verificar webhooks de MP
- Crear pedidos reales en Shopify tras cada cobro exitoso
- Ejecutar el job diario de reintentos para cobros fallidos
- Servir el portal del cliente con datos actualizados
4. Portal del Cliente (Shopify Theme Extension)
Sección «Mi Suscripción» dentro del área de cuenta del cliente en el storefront. Permite al suscriptor ver su plan activo, historial de ciclos, próxima fecha de cobro, y realizar acciones como pausar, cancelar o agregar add-ons. Todos los datos se obtienen del servidor de Reval mediante calls autenticadas con links firmados.5. Admin Embebido (Shopify App Bridge)
Panel de gestión incrustado en el admin de Shopify. Los merchants acceden a él sin salir del contexto de su tienda. Desde aquí se gestionan planes, se visualizan suscripciones activas, se operan cancelaciones o pausas masivas, y se consulta el dashboard de MRR y analítica.Diagrama de interacción
Principios de diseño
Tres principios guían cada decisión de arquitectura en Reval.1. Shopify es la fuente de verdad para productos
Productos, variantes, precios, inventario, clientes, impuestos y pedidos viven exclusivamente en Shopify. La base de datos de Reval almacena referencias (IDs de Shopify) y estado operativo de las suscripciones, pero nunca duplica catálogo ni datos de cliente. En cada ciclo de cobro, el servidor consulta la API de Shopify en vivo para obtener precios, opciones de envío e impuestos actualizados antes de ejecutar el pago.2. Mercado Pago solo mueve dinero
El rol de MP se limita a custodiar el mandato de débito automático y ejecutar los cobros cuando el servidor de Reval se lo indica. MP no sabe nada sobre los productos que se están cobrando, las frecuencias de envío ni la lógica de negocio del merchant. Si mañana se migrara a otro procesador de pagos, la lógica de suscripciones, pedidos y portal permanecería intacta.3. Cada cobro genera un pedido real en Shopify
Cuando MP confirma un pago, el servidor de Reval crea un pedido estándar de Shopify con todas las líneas de producto, costos de envío e impuestos. Esto garantiza que el flujo de fulfillment, gestión de inventario y analítica nativa de Shopify funcione sin modificaciones. El merchant ve sus suscripciones como pedidos normales en su panel, puede usar las apps de fulfillment que ya tiene instaladas, y el historial contable es consistente.¿Por qué un checkout custom y no el checkout de Shopify?El checkout hosteado de Shopify (Shopify Checkout) no expone una API para crear autorizaciones de débito automático con procesadores externos. Solo permite completar transacciones de pago únicas o suscripciones gestionadas a través de las APIs nativas de Shopify Subscriptions, que no tienen integración directa con Mercado Pago. El checkout custom de Reval existe precisamente para poder cargar el SDK JS de MP, tokenizar la tarjeta en el navegador y crear el mandato (preapproval) en la API de MP — algo que el checkout nativo no puede hacer.