Ballbox / TCN docs

# Guía de Onboarding: TCN-CSC-8C(V49)

## 📌 Pre-Arrival Prep (Sebas Remoto)

- ☐ Adaptadores: Confirmar si el enchufe es EU. Si es así, comprar 5 adaptadores (EU hembra -> AR macho). Si es SAA, no hace falta (mismo que AR).
- ☐ Conectividad: SIM local opcional (Personal/Movistar/Claro) con plan de datos mínimo si hiciera falta.
- ☐ Documentación API: Pedir a Justin (TCN) el "External Payment Integration Protocol" o "Remote Vend API".
- ☐ Assets: Cargar en `OurVend > Product Catalog` las fotos (JPG livianos, <500kb) y nombres de los productos.

## 🚚 Arrival Day: Checklist Presencial (En sitio)

1. Energía: Enchufar y encender. Verificar que el compresor de frío arranque.
2. SIM (opcional): Si hace falta, insertar SIM local. Entrar a Settings de Android -> Network -> APN y configurar según la operadora (Personal/Claro/Movistar).
3. ID de Máquina: Capturar foto de la etiqueta trasera (S/N) y de la pantalla `System Info` dentro del launcher de TCN. Pasar el `Machine Number` (ej. P0256...) a Sebas.
4. Prueba Mecánica: Ir al menú de administrador (usualmente código 888888) -> `Diagnóstico > Motor Test`. Hacer girar todos los motores vacíos para descartar daños de transporte.
5. Carga: Cargar productos físicos siguiendo el planograma.

## 💻 Arrival Day: Checklist Remoto (Sebas)

1. Vincular: En OurVend, asegurar que los 5 nuevos `Machine Numbers` aparezcan en la lista bajo la institución `cc一级机构`.
2. Configurar Tracks: En `Products > Track Management`, mapear cada slot al producto correspondiente del catálogo y setear precios en ARS (o la unidad configurada).
3. Sincronizar: Presionar el botón `Sync` en el panel de OurVend y confirmar con la persona en sitio que los precios/fotos se actualizaron en la pantalla.
4. Test de Pago: Realizar una compra real de $1 o monto mínimo para validar que el callback de despacho (vend) funcione correctamente.

## ✅ Estado del sistema Ballbox para pagos

### Ya está

- Backend para crear QR / order.
- Webhook de MercadoPago.
- Persistencia de pagos aprobados.
- Admin para vending machines.
- Correlación base por `vendingMachineId` / txn.
- Modelo base para que Ballbox sea el cerebro de pago.

### Falta crítico

- Conseguir de TCN / OurVend el `External Payment Integration Protocol` o `Remote Vend API`.
- Confirmar el contrato real de request de QR desde la máquina.
- Confirmar el callback o comando real de `release` / `vend`.
- Confirmar si `Remote Track Configuration` o features VIP son requisito para esto.
- Cerrar el mapping real `machine ↔ slot ↔ product ↔ price`.
- Hacer prueba end-to-end real: elegir producto → generar QR → pagar → recibir webhook → disparar vend → confirmar dispense.

### Veredicto

- Preparado para integrar: sí.
- Preparado para operar en producción: todavía no.

### Mínimo para decir “sí, estamos”

1. Pedir a Justin el doc/API real.
2. Identificar endpoint/callback exacto de vend.
3. Hacer una prueba real con una máquina.
4. Confirmar que no hay bloqueo VIP/licencia.