> ## 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.
# Glosario Técnico de Reval: Diez Términos Esenciales
> Los diez términos técnicos clave del ecosistema Reval: mandatos, tokenización, idempotencia, ciclos, MRR, add-ons y links firmados con HMAC.
Reval opera en la intersección de Shopify y Mercado Pago, dos plataformas con vocabularios propios. Este glosario unifica los términos clave que aparecen en la documentación, los logs y las conversaciones técnicas sobre la app.
El **mandato de cobro recurrente** (preapproval en la API de Mercado Pago) es la primitiva de MP que autoriza cobros periódicos sobre una tarjeta tokenizada. Conoce monto, frecuencia y tarjeta, pero **no conoce productos, inventario ni fulfillment**.
En Reval, cada suscripción activa tiene exactamente un mandato asociado. El mandato almacena el `preapproval_id` que el servidor utiliza para ejecutar cada ciclo de cobro.
El mandato se crea durante el checkout custom, inmediatamente después de que el SDK de MP tokeniza la tarjeta en el navegador del suscriptor.
Cancelar una suscripción en Reval cancela el mandato en MP. No se pueden reactivar mandatos cancelados — el suscriptor debe crear una nueva suscripción.
Un **mandato con monto libre** es una variante del preapproval de Mercado Pago donde el campo `auto_recurring.transaction_amount` se deja libre (sin fijar un monto específico al crear el mandato).
Esto permite que el servidor de Reval especifique el monto exacto en el momento de ejecutar cada cobro, en lugar de cobrar siempre el mismo importe.
**Por qué Reval lo requiere**: el total de cada ciclo varía porque incluye el precio actual del producto (que puede cambiar), el costo de envío calculado en vivo por Shopify, los impuestos vigentes y cualquier add-on que el suscriptor haya agregado. Un monto fijo haría imposible reflejar estos cambios.
La alternativa sería usar planes fijos de MP (monto establecido al crear el mandato), lo que obligaría a cancelar y recrear el mandato cada vez que el precio cambia.
**Tokenización** es el proceso de convertir los datos sensibles de una tarjeta de crédito o débito (número, CVV, vencimiento) en un **token**: un string opaco de un solo uso generado por el SDK de Mercado Pago en el navegador del cliente.
En el checkout de Reval:
1. El suscriptor ingresa los datos de su tarjeta en el formulario.
2. El SDK JS de MP, ejecutándose en el navegador, envía los datos directamente a los servidores de MP y recibe un token.
3. El frontend envía **solo el token** al servidor de Reval — los datos de la tarjeta nunca tocan el servidor de Reval.
4. El servidor usa el token para crear el mandato en MP.
El token es de **uso único** y expira en minutos. Si el usuario recarga la página antes de confirmar, debe ingresar los datos de la tarjeta nuevamente.
Esto significa que Reval nunca almacena ni procesa datos de tarjetas. La responsabilidad de PCI DSS recae en Mercado Pago.
**Idempotencia** es la propiedad de una operación que produce el mismo resultado aunque se ejecute múltiples veces con los mismos parámetros.
En Reval, los webhooks de pago de Mercado Pago son procesados de forma idempotente:
1. Cuando MP aprueba un pago, envía un webhook con el `payment_id` único del cobro.
2. Antes de crear el pedido en Shopify, el servidor verifica si ya existe un pedido con ese `payment_id` (guardado en los metafields del pedido).
3. Si el pedido ya existe, el webhook se ignora (respuesta `200 OK` sin acción adicional).
4. Si no existe, el servidor crea el pedido y guarda el `payment_id` como metafield.
Esto protege contra la recepción duplicada de webhooks (que puede ocurrir si la red falla antes de que MP reciba la confirmación de entrega) y garantiza que cada cobro genera exactamente un pedido en Shopify.
En sistemas distribuidos, la **fuente de verdad** es el sistema que tiene la versión autoritativa de un dato determinado.
En Reval, la responsabilidad está dividida de forma clara:
| Dato | Fuente de verdad |
| ------------------------------ | ---------------------------- |
| Productos, variantes, precios | Shopify |
| Inventario y stock | Shopify |
| Clientes y direcciones | Shopify |
| Impuestos y envíos | Shopify (calculados en vivo) |
| Pedidos y fulfillment | Shopify |
| Analítica de ventas | Shopify |
| Estado del mandato | Mercado Pago |
| Historial de pagos | Mercado Pago |
| Planes y ciclos de suscripción | Base de datos de Reval |
Este diseño permite que el equipo de fulfillment, el contador y las integraciones de terceros (ERP, CRM) sigan trabajando con Shopify sin modificaciones.
**MRR** (Ingreso Mensual Recurrente) es la suma de los ingresos mensuales recurrentes proyectados de todas las suscripciones activas en un momento dado.
**Cómo lo calcula Reval**:
* Para suscripciones mensuales: suma directa del monto del último ciclo cobrado.
* Para otras frecuencias: el monto se normaliza al equivalente mensual. Por ejemplo, una suscripción trimestral de $3.000 ARS aporta $1.000 ARS al MRR.
**Qué excluye el MRR**:
* Suscripciones pausadas (no generan ingresos mientras están pausadas).
* Add-ons de una vez (son ingresos no recurrentes).
* Cobros fallidos pendientes de recuperación.
El MRR es la métrica principal del dashboard de Reval para medir la salud del negocio de suscripciones.
Un **add-on de una vez** es un artículo extra que el suscriptor puede agregar a su próximo envío, fuera de los productos incluidos en su plan regular.
**Mecánica**:
1. El suscriptor selecciona el producto y la cantidad desde el portal.
2. El servidor ejecuta un cobro inmediato e independiente del ciclo regular, usando el mandato existente.
3. El artículo queda vinculado al próximo ciclo de la suscripción.
4. En el próximo despacho, el add-on se incluye en el mismo envío que los productos del plan.
**Diferencias respecto al ciclo regular**:
* El cobro ocurre en el momento de la solicitud, con el cliente presente en el navegador, no en la fecha del ciclo.
* El precio es el precio completo del producto: no aplica el descuento del plan.
* Se **empaqueta en el pedido del próximo ciclo** (misma entrega), para que el suscriptor reciba una sola caja con todo junto.
Una vez confirmado, el add-on no puede cancelarse. El cobro ya fue procesado por Mercado Pago.
Un **ciclo** es una unidad completa de la suscripción: un período de cobro + creación de pedido + fulfillment.
Cada ciclo tiene:
* **Fecha programada**: cuándo se ejecuta el cobro.
* **Monto**: calculado en el momento del cobro (producto + envío + impuestos, consultados en vivo a Shopify).
* **Estado**: `scheduled` → `executing` → `completed` / `failed`.
* **Pedido asociado**: el pedido de Shopify creado tras el cobro exitoso.
Los ciclos se crean al activar la suscripción y se encadenan automáticamente: al completarse un ciclo, el siguiente queda programado según la frecuencia del plan.
El **buy box** es el widget de suscripción que aparece en la página de producto de la tienda Shopify, implementado como una Shopify Theme Extension.
Muestra las opciones de plan disponibles para ese producto (frecuencia + descuento), permite al visitante seleccionar un plan, y redirige al checkout custom de Reval con un link firmado que contiene el plan y el producto seleccionados.
El buy box coexiste con el botón de compra normal de Shopify — el visitante puede elegir comprar una vez (flujo estándar de Shopify) o suscribirse (flujo de Reval).
El merchant activa o desactiva el buy box por producto desde el admin embebido de Reval.
Un **link firmado** es una URL que incluye un parámetro de firma generado con HMAC (Hash-based Message Authentication Code) para garantizar que no fue alterada y que expira en un tiempo determinado.
Reval usa links firmados para el checkout custom y el portal del cliente porque:
* Evitan que un tercero acceda al portal de otra persona fabricando una URL.
* Garantizan que los parámetros (plan, productos, customer\_id) no fueron modificados por el cliente.
* Tienen un tiempo de expiración, reduciendo la ventana de ataque.
La firma se calcula sobre el contenido de la URL (parámetros + timestamp) usando una clave secreta que solo conoce el servidor de Reval. Cualquier modificación a la URL invalida la firma y el servidor rechaza la solicitud.