# Pagos — Tienda VORTEX

## Estado actual (lo que existe hoy en este repo)

- **No hay backend ni funciones serverless en el repositorio.** El sitio es 100% estático (ver `STORE_AUDIT.md`).
- El checkout de la tienda usa el mismo patrón que ya usaba el sitio para el Desafío Mundial 2026: **enlaces de pago (Payment Links) de Wompi**, configurables por producto en `data/products.json` (campo `enlacePago`).
- Cuando el carrito tiene **un solo producto y cantidad 1**, `checkout/index.html` redirige al `enlacePago` de ese producto.
- Cuando el carrito tiene **más de un producto o cantidades mayores a 1**, no hay forma de cobrar un total dinámico sin integrar la API de Wompi — en ese caso el checkout ofrece **"Confirmar compra por WhatsApp"**, que arma un mensaje con el detalle del pedido al número de WhatsApp público de VORTEX. Un miembro del equipo confirma el pago manualmente. Esto está implementado en `assets/js/vortex-payment-adapter.js` y documentado ahí mismo en el comentario de cabecera.
- **Ningún pago se marca como aprobado por el simple hecho de llegar a `/pago-exitoso/`.** Esa página comunica que el pago está en verificación manual, no que ya se entregó nada (ver `politica-de-entrega-digital`).
- No hay ninguna llave, secreto ni token de Wompi (ni de ninguna pasarela) en el código. No se ha inventado ninguna credencial.

## Por qué no se integró la API de Wompi en este trabajo

Integrar la API de Wompi de forma segura requiere:
1. Una función serverless (por ejemplo, Netlify Functions) que genere la firma de integridad y cree la transacción — **la llave privada de Wompi nunca puede vivir en el cliente**.
2. Un webhook que reciba la confirmación de Wompi y actualice el estado real de la orden.
3. Un lugar donde registrar órdenes (base de datos o, como mínimo, una hoja de cálculo vía API) para poder verificar servidor-side antes de entregar un archivo digital.

Nada de eso existe hoy en el repo, y crearlo requiere decisiones del propietario (¿Netlify Functions? ¿qué base de datos? ¿qué cuenta de Wompi/qué comercio?) que no se pueden inventar. Por eso el brief pide explícitamente: *"Si todavía no existe backend seguro: 1) implementa primero enlaces de pago configurables por producto"* — que es exactamente lo que se hizo.

## Cómo activar un producto para la venta

Desde esta sesión, `estado: "activo"` **ya no basta por sí solo** para que un producto muestre "Comprar ahora" — ver `docs/STORE_DECISIONS.md` y `docs/MVP_LAUNCH_CHECKLIST.md`. El botón de compra solo aparece cuando se cumplen **las cuatro condiciones a la vez** (lógica centralizada en `VortexStore.canBuyNow()`, `assets/js/vortex-store.js`):

1. `"estado": "activo"`
2. `"entregaDisponible": true`
3. `"precio"` es un número válido
4. `"enlacePago"` no es `null`

Pasos para activar un producto de verdad:

1. En `data/products.json`, ubica el producto por su `id`.
2. Confirma que `"estado"` sea `"activo"` (o cámbialo si corresponde).
3. Crea un **Payment Link** en el panel de Wompi para ese producto (monto fijo, referencia del producto, sin envío físico, permitiendo múltiples pagos — ver checklist completo en `docs/WOMPI_LINKS_INPUT.md`) y pégalo en `"enlacePago"` — a mano, o con el script de la siguiente sección.
4. Si el producto no tiene aún imagen real, reemplaza `"imagenPrincipal"` (hoy `assets/store/placeholder.svg`) y pon `"imagenEsPlaceholder": false`.
5. **Solo cuando confirmes que el archivo/servicio entregable existe de verdad**, cambia `"entregaDisponible"` a `true`. Este campo nunca se activa automáticamente por ningún script — es una confirmación humana deliberada, separada de si el producto es "visible" (`estado`).

No hace falta tocar ningún archivo HTML: la tienda entera lee de este único JSON.

## Aplicar enlaces con el script

`scripts/apply-wompi-links.py` aplica varios `enlacePago` a la vez de forma segura, sin necesidad de editar el JSON a mano uno por uno:

1. Copia `docs/WOMPI_LINKS_INPUT.md` (o crea tu propio archivo) en formato JSON `{ "slug": "https://checkout.wompi.co/l/XXXXXX" }` y guárdalo como `wompi-links.local.json` en la raíz del repo (ese nombre ya está en `.gitignore`, nunca se sube a Git).
2. Ejecuta primero en modo simulación (no escribe nada):
   ```bash
   python3 scripts/apply-wompi-links.py
   ```
3. Revisa el resumen impreso (producto, slug, precio, enlace actual → nuevo). Si todo se ve bien, aplica los cambios:
   ```bash
   python3 scripts/apply-wompi-links.py --apply
   ```
4. El script crea automáticamente un respaldo con fecha en `data/_backups/` antes de escribir, valida que cada URL sea `https://checkout.wompi.co/...`, y falla sin modificar nada si cualquier entrada es inválida (dominio incorrecto, slug inexistente, o algo que parezca una llave/secreto pegado por error).
5. El script **nunca** toca `precio`, `estado` ni `entregaDisponible` — solo escribe `enlacePago`. Sigue siendo necesario activar `entregaDisponible` a mano (paso 5 de la sección anterior).

## Migración futura a checkout con API + webhook

`assets/js/vortex-payment-adapter.js` expone un único punto de entrada, `resolveCheckout(items, products)`. El día que exista una función serverless:

1. Crear `netlify/functions/crear-transaccion.js` (o similar) que reciba el carrito, genere una referencia única y la firma de integridad (`SHA256(referencia + monto + moneda + secreto de integridad)`, según la documentación oficial de Wompi), y devuelva los datos necesarios para abrir el Web Checkout de Wompi.
2. Crear `netlify/functions/webhook-wompi.js` que reciba el evento de Wompi, valide la firma del evento, y marque la orden como `aprobada`/`rechazada`/`pendiente` en el almacenamiento que se elija.
3. Reemplazar la lógica interna de `resolveCheckout()` para que llame a la función serverless en vez de resolver un `enlacePago` estático. El resto de la tienda (carrito, UI de checkout, páginas de resultado) no debería requerir cambios porque ya consume `resolveCheckout()` como caja negra.
4. Solo entonces automatizar la entrega digital (ver más abajo) contra el estado verificado en servidor — nunca antes.

## Variables de entorno necesarias (cuando exista backend)

Ver `.env.example` en la raíz del repo. Ninguna de estas credenciales existe todavía; las debe crear el propietario en su cuenta de Wompi y configurarlas como variables de entorno en Netlify (Site settings → Environment variables), **nunca en el código**.

| Variable | Dónde se usa | Sandbox / Producción |
|---|---|---|
| `WOMPI_PUBLIC_KEY` | Cliente (Web Checkout) — es pública por diseño | Ambas |
| `WOMPI_PRIVATE_KEY` | Solo en función serverless, para crear transacciones vía API | Ambas — **nunca en el cliente** |
| `WOMPI_INTEGRITY_SECRET` | Solo en función serverless, para firmar cada transacción | Ambas — **nunca en el cliente** |
| `WOMPI_EVENTS_SECRET` | Solo en función serverless, para validar la firma de los webhooks | Ambas — **nunca en el cliente** |
| `WOMPI_ENV` | Selecciona `sandbox` o `production` en la función serverless | — |

Wompi provee llaves de sandbox independientes de las de producción en el mismo panel de comercio; no se necesita una cuenta distinta para probar.

## Pruebas de aprobación, rechazo y pendiente (cuando exista integración API)

Wompi documenta tarjetas y referencias de prueba específicas para sandbox que simulan cada resultado (aprobada, rechazada, pendiente) sin mover dinero real. El propietario debe consultarlas en su panel de desarrollador de Wompi al momento de implementar la función serverless — no se listan aquí números de tarjeta para evitar que queden desactualizados.

Mientras tanto (fase actual de Payment Links), la validación es manual:
- **Aprobado**: el Payment Link de Wompi confirma el pago en su propia interfaz; VORTEX lo verifica en el panel de Wompi antes de entregar.
- **Rechazado**: Wompi muestra el rechazo en su propia página; el usuario puede reintentar o escribir por WhatsApp.
- **Pendiente**: aplica sobre todo a PSE/transferencias; Wompi notifica por correo al comercio cuando se confirma.

## Entrega digital — limitación actual

No existe todavía backend seguro que verifique un pago y sirva un archivo automáticamente. Por eso:
- Los archivos digitales **no se publican en ninguna carpeta pública del repo** con URL permanente.
- La entrega es manual: VORTEX confirma el pago y envía el archivo por correo o WhatsApp (ver `politica-de-entrega-digital`).
- La ruta `/mi-compra` pedida en el brief **no se implementó** porque requeriría autenticar al comprador y asociarlo a una compra verificada en servidor — no existe esa capa hoy. Queda documentada como pendiente en `STORE_NEXT_TASKS.md`.

Cuando exista la función serverless de verificación de pago (ver arriba), la recomendación es servir los archivos mediante **URLs firmadas y temporales** (por ejemplo, Netlify Large Media / un bucket privado con URLs pre-firmadas de corta duración generadas por la función serverless tras verificar el pago), nunca desde `/assets/` público.