> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appreval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Arquitectura de Reval: Componentes e Interacciones

> Visión general de los cinco componentes de Reval, cómo interactúan y los principios de diseño que guían cada decisión técnica de la plataforma.

Reval está compuesto por cinco piezas que trabajan en conjunto para conectar la experiencia de compra en Shopify con la infraestructura de pagos recurrentes de Mercado Pago. Cada componente tiene una responsabilidad clara y delimitada: ninguno duplica lo que otro ya hace, y el servidor de Reval es el único que orquesta el flujo completo.

## 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](/desarrolladores/checkout-tecnico) 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

```text theme={null}
 STOREFRONT DE SHOPIFY
 ┌──────────────────────────────────────────────┐
 │                                              │
 │  [Página de Producto]                        │
 │       │                                      │
 │  ┌────▼─────────────────────────────────┐   │
 │  │   Buy Box (Theme Extension)          │   │
 │  │   • Muestra planes disponibles       │   │
 │  │   • Genera link firmado (HMAC)       │   │
 │  └────────────────┬─────────────────────┘   │
 │                   │ redirect                  │
 │  ┌────────────────▼─────────────────────┐   │
 │  │   Checkout Custom (Theme Page)       │   │
 │  │   • SDK JS de MP tokeniza tarjeta    │   │
 │  │   • Envía token → Servidor Reval     │   │
 │  └──────────────────────────────────────┘   │
 │                                              │
 │  [Cuenta del Cliente]                        │
 │  ┌──────────────────────────────────────┐   │
 │  │   Portal (Theme Extension)           │   │
 │  │   • Ver suscripción activa           │   │
 │  │   • Pausar / Cancelar / Add-ons      │   │
 │  └──────────────────────────────────────┘   │
 └──────────────────────────────────────────────┘
                    │  ▲
        API calls   │  │  datos / acciones
                    ▼  │
 ┌──────────────────────────────────────────────┐
 │         SERVIDOR DE REVAL                    │
 │                                              │
 │  • Gestión de mandatos y ciclos              │
 │  • Job de reintentos (diario)                │
 │  • Verificación de webhooks                  │
 │  • Creación de pedidos en Shopify            │
 └──────┬──────────────────────┬────────────────┘
        │                      │
        ▼                      ▼
 ┌─────────────┐      ┌─────────────────────┐
 │  SHOPIFY    │      │   MERCADO PAGO      │
 │  Admin API  │      │   Payments API      │
 │             │      │                     │
 │  • Pedidos  │      │  • Preapprovals     │
 │  • Clientes │      │  • Cobros           │
 │  • Precios  │      │  • Webhooks         │
 │  • Envío    │      │  • Estado mandato   │
 │  • Impuest. │      │                     │
 └─────────────┘      └─────────────────────┘
        ▲
        │
 ┌──────────────────┐
 │  ADMIN EMBEBIDO  │
 │  (App Bridge)    │
 │  • Planes        │
 │  • Dashboard MRR │
 │  • Ops. masivas  │
 └──────────────────┘
```

***

## 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.

***

<Note>
  **¿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.
</Note>

***

## Restricciones que resuelve Reval

El valor de Reval está en las restricciones que ingenia a su alrededor. Cada componente y decisión de arquitectura responde a una restricción concreta del stack Shopify + Mercado Pago en Argentina.

<Accordion title="1. Mercado Pago solo entiende de dinero, sin productos ni inventario">
  **La restricción**: la API de MP conoce montos, tarjetas y frecuencias, pero no tiene el concepto de producto, variante, línea de pedido, inventario ni fulfillment.

  **La solución**: Shopify más la base de datos de Reval son dueños de todos los datos de producto. Cada cobro aprobado se espeja como un pedido real de Shopify con líneas, envío e impuestos.
</Accordion>

<Accordion title="2. Los mandatos atados a un plan de MP cobran solo un monto fijo">
  **La restricción**: si el mandato se crea atado a un plan de Mercado Pago, el monto queda fijo y no puede sumar envío, impuestos ni descuentos por cliente.

  **La solución**: Reval crea los mandatos con **monto libre** (sin plan de MP), lo que permite cobrar el monto exacto (producto + envío + impuestos) en cada ciclo.
</Accordion>

<Accordion title="3. En Argentina no se puede cobrar una tarjeta guardada sin el cliente presente">
  **La restricción**: cualquier cobro puntual fuera del ciclo del mandato requiere un token de tarjeta fresco generado en vivo en el navegador, con el titular presente.

  **La solución**: los **add-ons de una sola vez** se cobran en vivo con el cliente presente en el portal, y se empaquetan en el próximo pedido de la suscripción para que el cliente reciba una sola entrega.
</Accordion>

<Accordion title="4. MP no puede saltar un ciclo, mover la fecha ni cambiar la frecuencia">
  **La restricción**: el mandato de Mercado Pago, una vez creado, tiene una frecuencia y una programación de cobros que no se pueden alterar en vivo desde la API.

  **La solución**: Reval modela estos límites con honestidad en la UX. Para cambiar la frecuencia, el portal ofrece un **flujo guiado de cancelar y re-suscribir** que mantiene la tarjeta tokenizada del cliente.
</Accordion>

<Accordion title="5. El checkout de Shopify no puede correr un cobro recurrente de MP">
  **La restricción**: no existe forma de crear una autorización de pago recurrente de Mercado Pago desde el checkout hosteado de Shopify.

  **La solución**: una **página de checkout custom** embebida en el theme, con tokenización de tarjeta en el navegador y creación del mandato del lado del servidor de Reval.
</Accordion>

<Accordion title="6. Parte de la configuración del checkout de Shopify no es legible via API">
  **La restricción**: algunas opciones del checkout de Shopify (campos requeridos, validaciones) no están expuestas en la API, así que el checkout custom no puede espejarlas automáticamente.

  **La solución**: la configuración de los campos del checkout se **replica manualmente** en la configuración de la app de Reval para que el checkout custom coincida con lo que el merchant tiene configurado en su tienda.
</Accordion>

<Accordion title="7. Impuestos y envío deben coincidir siempre con los de la tienda">
  **La restricción**: si Reval calculara envío o impuestos por su cuenta, cualquier cambio en la configuración de la tienda generaría inconsistencias.

  **La solución**: envío e impuestos se **consultan en vivo** a la API de cálculo propia de Shopify en cada checkout y en cada ciclo de cobro. Lo que cobra Mercado Pago siempre refleja la configuración vigente de la tienda.
</Accordion>