- `docs/exports/01-vending-machine-setup-day-basico.es-ar.pdf`
  - versión corta
  - lossy, happy-path
  - para leer rápido el día de llegada
  - apunta a las mismas secciones numeradas del extendido si aparece un blocker

- `docs/exports/02-vending-machine-setup-day-manual-extendido.es-ar.pdf`
  - versión completa en español argentino
  - standalone
  - incluye contexto, conflictos no resueltos, red, cloud, catálogo, media, pago, vend y escalación
  - pensada para abrir cuando el `01` no alcanza

- `docs/exports/vending-machine-setup-day-manual-standalone.pdf`
  - versión standalone en inglés
  - mismo espíritu que el extendido, pero en inglés
  - útil si necesitás compartir con alguien no hispanohablante

- `docs/exports/vending-setup-day-pack.pdf`
  - pack combinado
  - junta el manual principal más docs de integración TCN/payments
  - sirve como bundle de referencia más amplio, no como guía rápida operativa

Recomendación práctica:
- operador: `01`
- si hay duda o problema: `02`
- ingeniería / referencia ampliada: `vending-setup-day-pack.pdf`


borra docs/exports/vending-machine-setup-day-manual-standalone.pdf e integra docs/exports/vending-setup-day-pack.pdf en castellano ar en docs/exports/02-vending-machine-setup-day-manual-extendido.es-ar.pdf. si tenes dudas como, dame opciones


**Considering PDF integration**

I need to regenerate the 02 PDF. The user asked to integrate the pack into the 02 Spanish PDF, which suggests I should keep the pack unless told otherwise. They also want to delete the English standalone version, so that part seems clear. I need to ensure that I'm committing to these changes properly while confirming I understand the user’s request. Let’s go ahead and keep the pack in this case!

todo

Fold TCN/payment pack into extended Spanish PDF and remove English standalone PDF

Delete the English standalone setup PDF and integrate the TCN/payment reference content from the combined pack into the extended Argentine Spanish manual/PDF so 02 becomes the main full reference.

folding payment pack into spanish manual


Created #9: Fold TCN/payment pack into extended Spanish PDF and remove English standalone PDF (pending)

Build vending machine setup manual from provided sources in isolated worktree

Create/update docs in a dedicated worktree using the provided links and local research file, then review whether the Payments Integration section still looks valid.

Audit existing setup-day docs and align vending manuals

Review repo documentation for existing setup-day manuals, especially remote vs on-site roles, then consolidate/index/update docs so all relevant manuals remain visible and non-duplicative.

Collapse setup-day docs into one manual with role sections

Remove redundant remote/on-site split docs if they duplicate the combined manual, and keep a single setup-day manual with clearly labeled role sections plus updated indexing.

Ingest laptop PDFs into setup-day manual

Read TECHNICAL_LEARNINGS.pdf and ARRIVAL_GUIDE.pdf from laptop, compare against current unified setup-day manual, and merge any missing high-signal content without reintroducing duplicate docs.

Improve PDF markdown rendering for setup manual

Update the PDF exporter so deeper markdown headings like #### render properly and the standalone setup PDF looks cleaner without changing the source manual structure.

Create Argentine Spanish copy of setup-day manual

Translate the standalone vending-machine setup-day manual into Argentine Spanish, keeping the same operational meaning and standalone behavior, then export a matching PDF copy.

Create basic happy-path Spanish setup manual with numbered progression

Add a short lossy happy-path Spanish manual for fast reading, and number both the basic and extended Spanish PDFs so operators can move from basic to extended if blocked or needing more detail.

Align section numbering between basic and extended Spanish manuals

Number the sections inside the basic and extended Spanish manuals so operators can jump from the basic guide to matching numbered sections in the extended guide, without relying on numbered filenames.


bash

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && sed -n '1,240p' docs/tcn-payments-integration-plan.md

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && sed -n '1,220p' docs/tcn-payments-open-questions.md

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && sed -n '1,220p' docs/tcn-payments-execution-plan.md


# TCN payments integration plan

## Decision
- Treat the current `/admin/payments` QR generator as an operator test harness, not the final production payment UX for vending machines.
- Production vending flow should integrate with the TCN machine protocol and let the machine render the buyer-facing QR on its own screen.

## Why
- TCN protocol `2.5V` states: `to scan QR codes additional hardware devices are necessary.`
- That wording applies to **machine-side QR scanning**, not to the machine displaying a QR on its screen for the buyer to scan with a phone.
- The payment section (`2.1.5 Integral exchange`, `FunCode=8000`) already defines a dynamic payment flow:
  - machine sends `MachineID`, `TradeNo`, `SlotNo`, `Price`, `NotityUrl`
  - server returns `CodeUrl`, `TradeNo`
- `CodeUrl` is described as the returned value used to generate the QR code.
- That is enough to proceed with integration planning without assuming extra scanner hardware.

## Intended production flow
1. Buyer selects product on TCN machine.
2. TCN machine requests Ballbox payment session using the TCN payment contract.
3. Ballbox creates a Mercado Pago QR order.
4. Ballbox maps the Mercado Pago output into the TCN response shape and returns `CodeUrl`.
5. TCN machine renders the QR on its screen.
6. Buyer scans with Mercado Pago app on phone.
7. Payment provider notifies Ballbox webhook.
8. Ballbox validates/persists approved payment.
9. TCN machine receives the success signal through the TCN-side notify/result path and dispenses product.

## Ballbox work now
### 1. Lock the machine-facing contract
- Define a Ballbox route for TCN `8000` payment-init requests.
- Define exact request/response mapping for:
  - `MachineID` -> Ballbox `vendingMachineId` or external machine identifier
  - `TradeNo` -> machine transaction id / canonical `externalReference`
  - `SlotNo`
  - `Price`
  - `NotityUrl`
  - response `CodeUrl`
- Confirm whether TCN expects raw payment URL, QR payload string, or a specific provider deep link in `CodeUrl`.

### 2. Define result/dispense handshake
- Map how Ballbox should signal payment success back into the TCN flow.
- Verify whether Ballbox must call `NotityUrl`, expose a callback endpoint, or rely on a polling/result interface in the broader TCN protocol set.
- Confirm how TCN links approved payment to dispense using `TradeNo` and/or `SlotNo`.

### 3. Normalize machine identity
- Decide the canonical mapping between TCN `MachineID` and Ballbox `VendingMachine`.
- Add any missing external-id field only if needed for clean lookup.

### 4. Keep admin QR page as a test tool
- `/admin/payments` remains useful for:
  - Mercado Pago config checks
  - live QR creation smoke tests
  - webhook validation
  - manual provider debugging
- Do not frame it as the final vending-machine payment UX.

## Unknowns still to close
- Exact payload expected inside TCN `CodeUrl`.
- Exact success callback / notify shape between Ballbox and TCN after payment approval.
- Whether machine-side polling (`4000`) participates in payment completion or only app-driven vend/load flows.
- Whether TCN needs additional payment-status endpoints beyond `8000` for a full dispense flow.

## Recommendation
- Next implementation slice should be a TCN adapter spec + stub endpoints, not more work on the standalone admin QR page.
- Keep Mercado Pago-native Ballbox routes as the provider layer underneath that adapter.

## Evidence
- `test-results/tcn-payment-protocol/Protocol 2.5V English version.pdf`
- `test-results/tcn-payment-protocol/findings-2026-04-23.md`


# TCN payments open questions

## Goal
Close the remaining machine-integration unknowns before Ballbox implements the full TCN adapter.

## Questions for TCN sales / engineering
1. In `FunCode=8000`, what exact value should Ballbox return in `CodeUrl`?
   - raw URL
   - QR payload string
   - Mercado Pago deep link
   - other provider-specific format
2. After payment approval, how does the machine learn that the vend can proceed?
   - Ballbox calls the request `NotityUrl`
   - machine polls another TCN endpoint
   - cloud pushes through `4000`
   - other flow
3. Is `NotityUrl` always machine-provided per transaction, or is there also a machine-level configured callback?
4. What is the exact payload shape expected for the payment-success notify/result message?
5. Which field is the true dispense correlation key?
   - `TradeNo`
   - `SlotNo`
   - both
   - another internal machine field
6. Does the stock TCN app render the QR natively after a successful `8000` response, or is any machine-side UI configuration required?
7. Are there any timeout / expiry expectations for the QR payment window from the machine side?
8. What should Ballbox return to the machine when payment creation fails or times out?
9. Is there any machine retry behavior Ballbox must tolerate for duplicate `TradeNo` requests?
10. Are there additional payment-related endpoints beyond `8000` required for a production dispense flow?

## Questions for Mercado Pago / internal validation
1. Which returned value from Ballbox should be safest to map into TCN `CodeUrl` for dynamic QR display?
2. Does current Ballbox order creation produce the same QR/deeplink payload shape expected by a buyer using Mercado Pago app?
3. Is the current webhook exposure stable enough for real public notifications on the production-like Ballbox URL?
4. Are there provider-side expiry, duplicate-order, or idempotency constraints we should encode before machine rollout?

## Output expected from this doc
- A resolved field-mapping note added back into `docs/tcn-payments-integration-plan.md`
- A concrete implementation spec once answers arrive


# TCN payments execution plan

## Purpose
Ordered execution plan for getting from current Ballbox native Mercado Pago support to real TCN machine payments.

## Step 1. Finish provider-layer proof
- Goal: prove Ballbox native Mercado Pago flow works end to end without TCN hardware.
- Inputs:
  - `docs/implemented-payments.md`
  - `docs/mercadopago-webhook-replay-notes-2026-04-23.md`
- Tasks:
  - validate public webhook reachability for `/notification/mercadopago`
  - run one real approved payment
  - confirm local `PaymentSession` persistence in `/admin/payments`
  - document exact payload and public URL evidence
- Exit criterion:
  - one real approved payment persists locally through webhook flow

## Step 2. Ask TCN the machine-contract questions
- Goal: close the remaining machine-side unknowns before coding the adapter.
- Inputs:
  - `docs/tcn-payments-integration-plan.md`
  - `docs/tcn-payments-open-questions.md`
  - `test-results/tcn-payment-protocol/findings-2026-04-23.md`
- Tasks:
  - send the question list to the TCN sales contact
  - ask them to confirm with engineers
  - capture answers in repo docs
- Exit criterion:
  - `CodeUrl` meaning and payment-success handshake are confirmed

## Step 3. Freeze Ballbox-TCN contract
- Goal: convert answers into a concrete adapter spec.
- Inputs:
  - `docs/tcn-payments-integration-plan.md`
  - answers captured from Step 2
- Tasks:
  - define request/response schema for TCN `8000`
  - define success/failure callback or polling behavior
  - define duplicate/idempotency behavior for repeated `TradeNo`
  - define machine-id mapping rules
- Exit criterion:
  - implementation spec is precise enough to code without guesswork

## Step 4. Implement adapter layer
- Goal: add the TCN-facing Ballbox endpoints over existing Mercado Pago primitives.
- Inputs:
  - concrete contract spec from Step 3
- Tasks:
  - add machine-facing endpoint(s)
  - map TCN requests to Ballbox/Mercado Pago order creation
  - map approved-payment state back into TCN success flow
  - persist any extra machine correlation fields needed
- Exit criterion:
  - local/manual adapter flow works without real machine hardware

## Step 5. Hardware validation when machines arrive
- Goal: verify actual stock TCN machine behavior.
- Tasks:
  - test real QR render on machine screen
  - test payment approval -> vend path
  - capture timing, retries, and failure cases
- Exit criterion:
  - one real vend succeeds through Ballbox-backed payment flow

## Step 6. Only then revisit payout automation
- Goal: avoid solving club payout distribution before the machine path is stable.
- Current default:
  - scheduled manual settlements / bookkeeping
- Related docs:
  - `docs/payments-club-settlement-strategy.md`
  - `PAY-4` in `docs/next-steps-queue.md`


**Updating documentation structure**

I need to revise the document labeled 02, possibly by appending new sections 7A, 7B, and 7C. I'm thinking about removing any references to additional documents, which feels okay. The standalone English PDF might need to be deleted too, but perhaps we can keep the pack PDF. The user requested integration of the pack into the document, so I’ll update accordingly. I might also regenerate the Spanish extended PDF with regional specifics. Finally, let's decide on the export script's necessity.

edit

## 7. Pago y vend de prueba
### Estado de la integración de pagos
- `/admin/payments` queda como harness de test/debug de Ballbox.
- El flujo productivo de vending debería ir por protocolo TCN.
- La máquina debería mostrar el QR buyer-facing en su propia pantalla.
- Ballbox debería ser dueño de la creación del pago, validación del webhook, persistencia de aprobaciones y reconciliación.

### Por qué esto todavía parece válido
- La investigación actual sigue apoyando OurVend/TCN como capa de cloud + control del dispositivo, no como dueña de la lógica de negocio de Ballbox.
- La evidencia pública sigue apuntando a device-open access con secret/signature del lado proveedor.
- La investigación sigue apoyando QR dinámico controlado por backend más autorización de vend del lado proveedor como el default más seguro hasta que lleguen docs exactas del tenant.
- El login cloud de test por sí solo no cambia esa dirección.

### Lo que todavía hay que confirmar en el setup day
- payload exacto de payment-init desde máquina/cloud
- path exacto de callback / notify de vend-success
- expectativa exacta de `CodeUrl`: payload QR vs link vs deep link específico del proveedor
- si la finalización del pago depende de callback, polling o ambos
- shape exacto de auth/signature para endpoints del tenant productivo

### Secuencia de test de pago del setup day
#### Remoto
1. Confirmar que la máquina aparezca online en cloud.
2. Confirmar que exista un producto vendible y esté bien mapeado.
3. Confirmar que el flujo de test de pagos de Ballbox siga pudiendo crear órdenes QR.
4. Confirmar que máquina/cloud puedan pedir payment init contra el adapter o stub de Ballbox.
5. Escanear y pagar el QR desde un teléfono.
6. Confirmar que Ballbox reciba el webhook del proveedor.
7. Confirmar que el pago aprobado se persista con correlación canónica de máquina.
8. Confirmar que el lado TCN reciba la señal de success/notify.
9. Reconciliar pago, resultado de vend y cambio de inventario.

#### En sitio
1. Confirmar que el producto vendible esté cargado físicamente.
2. Registrar la visualización del QR en la máquina.
3. Después de la aprobación, confirmar que cambie el estado de la máquina.
4. Confirmar que el vend físico ocurra con éxito.
5. Grabar video de prueba.
6. Reportar de inmediato cualquier mismatch entre pago exitoso y resultado de vend.

## 7. Pago y vend de prueba
### 7.1 Dirección actual de integración
- `/admin/payments` queda como harness de test/debug de Ballbox, no como UX final de pago de producción.
- El flujo productivo de vending debería ir por protocolo TCN.
- La máquina debería mostrar el QR buyer-facing en su propia pantalla.
- Ballbox debería ser dueño de la creación del pago, validación del webhook, persistencia de aprobaciones y reconciliación.

### 7.2 Por qué esta dirección todavía parece válida
- La investigación actual sigue apoyando OurVend/TCN como capa de cloud + control del dispositivo, no como dueña de la lógica de negocio de Ballbox.
- La evidencia pública sigue apuntando a device-open access con secret/signature del lado proveedor.
- El protocolo TCN `2.5V` dice que para escanear QR hacen falta dispositivos adicionales, pero eso aplica al escaneo desde la máquina, no a mostrar un QR en pantalla para que lo escanee el comprador con el teléfono.
- El flujo de pagos TCN (`FunCode=8000`) ya define un intercambio dinámico donde la máquina manda `MachineID`, `TradeNo`, `SlotNo`, `Price` y `NotityUrl`, y el servidor devuelve `CodeUrl` y `TradeNo`.
- Eso sigue apoyando QR dinámico controlado por backend más autorización de vend del lado proveedor como el default más seguro hasta que lleguen docs exactas del tenant.
- El login cloud de test por sí solo no cambia esa dirección.

### 7.3 Flujo productivo objetivo
1. El comprador elige el producto en la máquina TCN.
2. La máquina TCN pide una sesión de pago a Ballbox usando el contrato TCN de pagos.
3. Ballbox crea una orden QR en Mercado Pago.
4. Ballbox mapea esa respuesta al formato TCN y devuelve `CodeUrl`.
5. La máquina TCN muestra el QR en pantalla.
6. El comprador escanea con la app de Mercado Pago en el teléfono.
7. El proveedor notifica a Ballbox por webhook.
8. Ballbox valida y persiste el pago aprobado.
9. La máquina TCN recibe la señal de éxito por el path TCN de notify/result y despacha el producto.

### 7.4 Lo que Ballbox necesita cerrar
#### 7.4.1 Contrato machine-facing
- Definir una ruta de Ballbox para requests `8000` de init de pago TCN.
- Definir el mapping exacto de:
  - `MachineID` -> `vendingMachineId` de Ballbox o identificador externo de máquina
  - `TradeNo` -> id de transacción de máquina / `externalReference` canónico
  - `SlotNo`
  - `Price`
  - `NotityUrl`
  - respuesta `CodeUrl`
- Confirmar si TCN espera en `CodeUrl` una URL cruda, un payload QR o un deep link específico del proveedor.

#### 7.4.2 Handshake de success / dispense
- Mapear cómo debe señalar Ballbox el éxito de pago de vuelta al flujo TCN.
- Confirmar si Ballbox tiene que llamar al `NotityUrl`, exponer un callback, o apoyarse en polling / result dentro del protocolo TCN.
- Confirmar cómo TCN correlaciona pago aprobado y dispense usando `TradeNo`, `SlotNo` u otro campo.

#### 7.4.3 Identidad de máquina
- Definir el mapping canónico entre `MachineID` de TCN y la `VendingMachine` de Ballbox.
- Agregar un external id solo si hace falta para lookup limpio.

#### 7.4.4 Mantener admin QR como herramienta de test
- `/admin/payments` sigue siendo útil para:
  - chequeos de config de Mercado Pago
  - smoke tests de creación de QR live
  - validación de webhooks
  - debugging manual del proveedor
- No presentarlo como UX final de pago de vending.

### 7.5 Preguntas abiertas para TCN / ingeniería / validación interna
1. En `FunCode=8000`, ¿qué valor exacto tiene que devolver Ballbox en `CodeUrl`?
   - raw URL
   - string payload QR
   - deep link de Mercado Pago
   - otro formato específico del proveedor
2. Después de la aprobación del pago, ¿cómo se entera la máquina de que ya puede vender?
   - Ballbox llama al `NotityUrl` del request
   - la máquina hace polling a otro endpoint TCN
   - la cloud empuja por `4000`
   - otro flujo
3. ¿`NotityUrl` viene siempre por transacción desde la máquina o además existe un callback configurado a nivel máquina?
4. ¿Cuál es el payload exacto esperado para el mensaje de notify/result de pago exitoso?
5. ¿Cuál es la verdadera key de correlación para el dispense?
   - `TradeNo`
   - `SlotNo`
   - ambos
   - otro campo interno de máquina
6. ¿La app stock de TCN renderiza el QR de forma nativa después de una respuesta `8000` exitosa o requiere config adicional del lado máquina?
7. ¿Hay expectativas de timeout / expiración para la ventana de pago QR desde el lado máquina?
8. ¿Qué debe devolver Ballbox a la máquina cuando falla la creación del pago o hace timeout?
9. ¿Hay retries de máquina por `TradeNo` duplicado que Ballbox tenga que tolerar?
10. ¿Existen endpoints de pago adicionales además de `8000` para un flujo productivo completo de dispense?
11. Del lado Mercado Pago / validación interna:
   - qué valor conviene mapear en `CodeUrl`
   - si el payload QR/deeplink actual sirve para compradores usando Mercado Pago app
   - si el webhook público actual es estable para notificaciones reales
   - si hay restricciones de expiración, duplicados o idempotencia que haya que codificar antes del rollout

### 7.6 Plan de ejecución
#### Paso 1. Cerrar la prueba de capa proveedor
- Objetivo: probar que el flujo nativo de Mercado Pago en Ballbox funciona end-to-end sin hardware TCN.
- Tareas:
  - validar reachability pública del webhook `/notification/mercadopago`
  - correr un pago real aprobado
  - confirmar persistencia local en `/admin/payments`
  - documentar payload exacto y evidencia de URL pública
- Criterio de salida:
  - un pago real aprobado persiste localmente por webhook

#### Paso 2. Mandar preguntas a TCN
- Objetivo: cerrar los unknowns machine-side antes de codear el adapter.
- Tareas:
  - mandar la lista de preguntas al contacto comercial de TCN
  - pedir confirmación con ingeniería
  - capturar respuestas en la documentación
- Criterio de salida:
  - queda confirmado el significado de `CodeUrl` y el handshake de success de pago

#### Paso 3. Congelar contrato Ballbox-TCN
- Objetivo: convertir respuestas en una spec concreta del adapter.
- Tareas:
  - definir schema request/response para TCN `8000`
  - definir success/failure callback o comportamiento de polling
  - definir comportamiento ante duplicados/idempotencia para `TradeNo`
  - definir reglas de mapping de machine id
- Criterio de salida:
  - la spec queda lo bastante precisa como para codear sin adivinar

#### Paso 4. Implementar capa adapter
- Objetivo: agregar endpoints TCN-facing de Ballbox sobre las primitivas actuales de Mercado Pago.
- Tareas:
  - agregar endpoint(s) machine-facing
  - mapear requests TCN a creación de órdenes Ballbox/Mercado Pago
  - mapear estado de pago aprobado de vuelta al flujo de success TCN
  - persistir cualquier campo extra de correlación de máquina que haga falta
- Criterio de salida:
  - el flujo local/manual del adapter funciona sin hardware real

#### Paso 5. Validación con hardware cuando lleguen las máquinas
- Objetivo: verificar el comportamiento real de la máquina TCN stock.
- Tareas:
  - probar render real de QR en pantalla
  - probar path pago aprobado -> vend
  - capturar timings, retries y fallas
- Criterio de salida:
  - un vend real sale bien a través del flujo de Ballbox

#### Paso 6. Recién después revisar automatización de payouts
- Objetivo: no resolver reparto/payout a clubes antes de estabilizar el camino de máquina.
- Default actual:
  - liquidaciones programadas manuales / bookkeeping manual

### 7.7 Secuencia de test de pago del setup day
#### Remoto
1. Confirmar que la máquina aparezca online en cloud.
2. Confirmar que exista un producto vendible y esté bien mapeado.
3. Confirmar que el flujo de test de pagos de Ballbox siga pudiendo crear órdenes QR.
4. Confirmar que máquina/cloud puedan pedir payment init contra el adapter o stub de Ballbox.
5. Escanear y pagar el QR desde un teléfono.
6. Confirmar que Ballbox reciba el webhook del proveedor.
7. Confirmar que el pago aprobado se persista con correlación canónica de máquina.
8. Confirmar que el lado TCN reciba la señal de success/notify.
9. Reconciliar pago, resultado de vend y cambio de inventario.

#### En sitio
1. Confirmar que el producto vendible esté cargado físicamente.
2. Registrar la visualización del QR en la máquina.
3. Después de la aprobación, confirmar que cambie el estado de la máquina.
4. Confirmar que el vend físico ocurra con éxito.
5. Grabar video de prueba.
6. Reportar de inmediato cualquier mismatch entre pago exitoso y resultado de vend.


Could not find the exact text in /mnt/rpi/worktrees/ballbox/docs-vending-manual/docs/02-vending-machine-setup-day-manual.es-ar.md. The old text must match exactly including all whitespace and newlines.


bash

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && sed -n '180,320p' docs/02-vending-machine-setup-day-manual.es-ar.md


## 5. Catálogo, tracks y sync
### Remoto
1. Cargar primero los productos en el catálogo global.
2. Subir fotos y nombres de producto antes de mapear tracks.
3. En `Products > Track Management`, mapear cada slot/track a un producto del catálogo.
4. Definir precios en ARS o en la unidad configurada.
5. Si existe, usar clone/copy para acelerar el mapeo entre máquinas del mismo modelo.
6. Disparar sync y confirmar que la máquina se actualice.

### En sitio
1. Cargar el producto físico según el planograma.
2. Confirmar que el mapping track-producto coincida con la carga física.
3. Confirmar que precios y fotos se actualicen en pantalla luego del sync.

### Notas
- El catálogo global debería ir primero y después el mapping por máquina.
- Los cambios en cloud pueden requerir `Sync` explícito o esperar el heartbeat de la máquina.
- El sync remoto de tracks/precios puede estar VIP-gated; verificar en vivo.

### 5A. Diagnóstico mecánico
### En sitio
1. Si el diagnóstico admin está accesible, correr motor test antes de cargar stock vendible.
2. Preferir pruebas con tracks vacíos primero para detectar daños de transporte.
3. Chequear estado de puerta, comportamiento del sensor de caída y alarmas visibles de hardware si aparecen.
4. Si pide código admin, `888888` es solo un código comúnmente mencionado, no uno confirmado para estas unidades.

### Remoto
- Registrar si se pudo entrar o no a diagnósticos.
- Si diagnósticos está bloqueado, anotar si el bloqueo fue por PIN desconocido, menú ausente o limitación de tenant/rol.

## 6. Media
Fuente: video público `How to upload videos to the vending machine`.
- Tratar esta sección como checklist operativo, no como click-path exacto ya verificado.

### Remoto
1. Encontrar la sección de device-management / media / advertising.
2. Subir primero un video corto de prueba.
3. Asignarlo a la máquina o grupo correcto.
4. Publicar/sincronizar.
5. Si sale bien, subir el pack final de producción.

Registrar:
- tipo de archivo
- tamaño del archivo
- target de asignación
- si hizo falta sync o reboot

### En sitio
1. Confirmar que la máquina reciba la media actualizada.
2. Reiniciar solo si hace falta o si se pide.
3. Confirmar reproducción en pantalla.
4. Confirmar que la reproducción sea full-screen y que el flujo touch siga funcionando.
5. Grabar video corto como prueba.

Puntos a confirmar en la UI del tenant:
- path exacto del menú de media upload
- tipos de archivo soportados / límites de tamaño
- si la media se asigna por máquina, por grupo o por playlist
- si hace falta sync/reboot manual después de publicar

## 7. Pago y vend de prueba
### Estado de la integración de pagos
### Posición actual de Ballbox
- `/admin/payments` queda como harness de test/debug de Ballbox.
- El flujo productivo de vending debería ir por protocolo TCN.
- La máquina debería mostrar el QR buyer-facing en su propia pantalla.
- Ballbox debería ser dueño de la creación del pago, validación del webhook, persistencia de aprobaciones y reconciliación.

### Por qué esto todavía parece válido
- La investigación actual sigue apoyando OurVend/TCN como capa de cloud + control del dispositivo, no como dueña de la lógica de negocio de Ballbox.
- La evidencia pública sigue apuntando a device-open access con secret/signature del lado proveedor.
- La investigación sigue apoyando QR dinámico controlado por backend más autorización de vend del lado proveedor como el default más seguro hasta que lleguen docs exactas del tenant.
- El login cloud de test por sí solo no cambia esa dirección.

### Lo que todavía hay que confirmar en el setup day
- payload exacto de payment-init desde máquina/cloud
- path exacto de callback / notify de vend-success
- expectativa exacta de `CodeUrl`: payload QR vs link vs deep link específico del proveedor
- si la finalización del pago depende de callback, polling o ambos
- shape exacto de auth/signature para endpoints del tenant productivo

### Secuencia de test de pago del setup day
#### Remoto
1. Confirmar que la máquina aparezca online en cloud.
2. Confirmar que exista un producto vendible y esté bien mapeado.
3. Confirmar que el flujo de test de pagos de Ballbox siga pudiendo crear órdenes QR.
4. Confirmar que máquina/cloud puedan pedir payment init contra el adapter o stub de Ballbox.
5. Escanear y pagar el QR desde un teléfono.
6. Confirmar que Ballbox reciba el webhook del proveedor.
7. Confirmar que el pago aprobado se persista con correlación canónica de máquina.
8. Confirmar que el lado TCN reciba la señal de success/notify.
9. Reconciliar pago, resultado de vend y cambio de inventario.

#### En sitio
1. Confirmar que el producto vendible esté cargado físicamente.
2. Registrar la visualización del QR en la máquina.
3. Después de la aprobación, confirmar que cambie el estado de la máquina.
4. Confirmar que el vend físico ocurra con éxito.
5. Grabar video de prueba.
6. Reportar de inmediato cualquier mismatch entre pago exitoso y resultado de vend.

## 8. Escalación y blockers
### Paquete de escalación para proveedor / TCN
Si algo bloquea el setup, mandar todo esto junto:
- serial de máquina
- etiqueta de modelo
- familia de pantalla
- modelo del módulo de pagos
- versión actual de firmware/build
- nombre/url del tenant cloud
- screenshots/video del problema
- timestamps con zona horaria
- si estaba por Ethernet o Wi-Fi
- última acción exitosa
- si el problema parece de Ballbox, de cloud o de machine-side

## 9. Criterio de listo
- máquina online y estable
- zona horaria correcta
- touch OK en toda la pantalla
- al menos un sync de producto OK
- sync de precio OK
- sync de media OK
- test de pago OK
- test de vend OK
- observado al menos un path de retry/error
- todos los ids y credenciales archivados en la nota interna de ops

## Regla standalone
- Este manual debería alcanzar para operar el día de llegada sin depender de otros documentos.


edit

## 7. Pago y vend de prueba
### Estado de la integración de pagos
### Posición actual de Ballbox
- `/admin/payments` queda como harness de test/debug de Ballbox.
- El flujo productivo de vending debería ir por protocolo TCN.
- La máquina debería mostrar el QR buyer-facing en su propia pantalla.
- Ballbox debería ser dueño de la creación del pago, validación del webhook, persistencia de aprobaciones y reconciliación.

### Por qué esto todavía parece válido
- La investigación actual sigue apoyando OurVend/TCN como capa de cloud + control del dispositivo, no como dueña de la lógica de negocio de Ballbox.
- La evidencia pública sigue apuntando a device-open access con secret/signature del lado proveedor.
- La investigación sigue apoyando QR dinámico controlado por backend más autorización de vend del lado proveedor como el default más seguro hasta que lleguen docs exactas del tenant.
- El login cloud de test por sí solo no cambia esa dirección.

### Lo que todavía hay que confirmar en el setup day
- payload exacto de payment-init desde máquina/cloud
- path exacto de callback / notify de vend-success
- expectativa exacta de `CodeUrl`: payload QR vs link vs deep link específico del proveedor
- si la finalización del pago depende de callback, polling o ambos
- shape exacto de auth/signature para endpoints del tenant productivo

### Secuencia de test de pago del setup day
#### Remoto
1. Confirmar que la máquina aparezca online en cloud.
2. Confirmar que exista un producto vendible y esté bien mapeado.
3. Confirmar que el flujo de test de pagos de Ballbox siga pudiendo crear órdenes QR.
4. Confirmar que máquina/cloud puedan pedir payment init contra el adapter o stub de Ballbox.
5. Escanear y pagar el QR desde un teléfono.
6. Confirmar que Ballbox reciba el webhook del proveedor.
7. Confirmar que el pago aprobado se persista con correlación canónica de máquina.
8. Confirmar que el lado TCN reciba la señal de success/notify.
9. Reconciliar pago, resultado de vend y cambio de inventario.

#### En sitio
1. Confirmar que el producto vendible esté cargado físicamente.
2. Registrar la visualización del QR en la máquina.
3. Después de la aprobación, confirmar que cambie el estado de la máquina.
4. Confirmar que el vend físico ocurra con éxito.
5. Grabar video de prueba.
6. Reportar de inmediato cualquier mismatch entre pago exitoso y resultado de vend.

## 7. Pago y vend de prueba
### 7.1 Dirección actual de integración
- `/admin/payments` queda como harness de test/debug de Ballbox, no como UX final de pago de producción.
- El flujo productivo de vending debería ir por protocolo TCN.
- La máquina debería mostrar el QR buyer-facing en su propia pantalla.
- Ballbox debería ser dueño de la creación del pago, validación del webhook, persistencia de aprobaciones y reconciliación.

### 7.2 Por qué esta dirección todavía parece válida
- La investigación actual sigue apoyando OurVend/TCN como capa de cloud + control del dispositivo, no como dueña de la lógica de negocio de Ballbox.
- La evidencia pública sigue apuntando a device-open access con secret/signature del lado proveedor.
- El protocolo TCN `2.5V` dice que para escanear QR hacen falta dispositivos adicionales, pero eso aplica al escaneo desde la máquina, no a mostrar un QR en pantalla para que lo escanee el comprador con el teléfono.
- El flujo de pagos TCN (`FunCode=8000`) ya define un intercambio dinámico donde la máquina manda `MachineID`, `TradeNo`, `SlotNo`, `Price` y `NotityUrl`, y el servidor devuelve `CodeUrl` y `TradeNo`.
- Eso sigue apoyando QR dinámico controlado por backend más autorización de vend del lado proveedor como el camino más seguro hasta que lleguen docs exactas del tenant.
- El login cloud de test por sí solo no cambia esa dirección.

### 7.3 Flujo productivo objetivo
1. El comprador elige el producto en la máquina TCN.
2. La máquina TCN pide una sesión de pago a Ballbox usando el contrato TCN de pagos.
3. Ballbox crea una orden QR en Mercado Pago.
4. Ballbox mapea esa respuesta al formato TCN y devuelve `CodeUrl`.
5. La máquina TCN muestra el QR en pantalla.
6. El comprador escanea con la app de Mercado Pago en el teléfono.
7. El proveedor notifica a Ballbox por webhook.
8. Ballbox valida y persiste el pago aprobado.
9. La máquina TCN recibe la señal de éxito por el path TCN de notify/result y despacha el producto.

### 7.4 Lo que Ballbox necesita cerrar
#### 7.4.1 Contrato machine-facing
- Definir una ruta de Ballbox para requests `8000` de init de pago TCN.
- Definir el mapping exacto de:
  - `MachineID` -> `vendingMachineId` de Ballbox o identificador externo de máquina
  - `TradeNo` -> id de transacción de máquina / `externalReference` canónico
  - `SlotNo`
  - `Price`
  - `NotityUrl`
  - respuesta `CodeUrl`
- Confirmar si TCN espera en `CodeUrl` una URL cruda, un payload QR o un deep link específico del proveedor.

#### 7.4.2 Handshake de success / dispense
- Mapear cómo debe señalar Ballbox el éxito de pago de vuelta al flujo TCN.
- Confirmar si Ballbox tiene que llamar al `NotityUrl`, exponer un callback, o apoyarse en polling / result dentro del protocolo TCN.
- Confirmar cómo TCN correlaciona pago aprobado y dispense usando `TradeNo`, `SlotNo` u otro campo.

#### 7.4.3 Identidad de máquina
- Definir el mapping canónico entre `MachineID` de TCN y la `VendingMachine` de Ballbox.
- Agregar un external id solo si hace falta para un lookup limpio.

#### 7.4.4 Mantener admin QR como herramienta de test
- `/admin/payments` sigue siendo útil para:
  - chequeos de config de Mercado Pago
  - smoke tests de creación de QR live
  - validación de webhooks
  - debugging manual del proveedor
- No presentarlo como UX final de pago de vending.

### 7.5 Preguntas abiertas para TCN / ingeniería / validación interna
1. En `FunCode=8000`, ¿qué valor exacto tiene que devolver Ballbox en `CodeUrl`?
   - raw URL
   - string payload QR
   - deep link de Mercado Pago
   - otro formato específico del proveedor
2. Después de la aprobación del pago, ¿cómo se entera la máquina de que ya puede vender?
   - Ballbox llama al `NotityUrl` del request
   - la máquina hace polling a otro endpoint TCN
   - la cloud empuja por `4000`
   - otro flujo
3. ¿`NotityUrl` viene siempre por transacción desde la máquina o además existe un callback configurado a nivel máquina?
4. ¿Cuál es el payload exacto esperado para el mensaje de notify/result de pago exitoso?
5. ¿Cuál es la verdadera key de correlación para el dispense?
   - `TradeNo`
   - `SlotNo`
   - ambos
   - otro campo interno de máquina
6. ¿La app stock de TCN renderiza el QR de forma nativa después de una respuesta `8000` exitosa o requiere config adicional del lado máquina?
7. ¿Hay expectativas de timeout / expiración para la ventana de pago QR desde el lado máquina?
8. ¿Qué debe devolver Ballbox a la máquina cuando falla la creación del pago o hace timeout?
9. ¿Hay retries de máquina por `TradeNo` duplicado que Ballbox tenga que tolerar?
10. ¿Existen endpoints de pago adicionales además de `8000` para un flujo productivo completo de dispense?
11. Del lado Mercado Pago / validación interna:
   - qué valor conviene mapear en `CodeUrl`
   - si el payload QR/deeplink actual sirve para compradores usando Mercado Pago app
   - si el webhook público actual es estable para notificaciones reales
   - si hay restricciones de expiración, duplicados o idempotencia que haya que codificar antes del rollout

### 7.6 Plan de ejecución
#### Paso 1. Cerrar la prueba de capa proveedor
- Objetivo: probar que el flujo nativo de Mercado Pago en Ballbox funciona end-to-end sin hardware TCN.
- Tareas:
  - validar reachability pública del webhook `/notification/mercadopago`
  - correr un pago real aprobado
  - confirmar persistencia local en `/admin/payments`
  - documentar payload exacto y evidencia de URL pública
- Criterio de salida:
  - un pago real aprobado persiste localmente por webhook

#### Paso 2. Mandar preguntas a TCN
- Objetivo: cerrar los unknowns machine-side antes de codear el adapter.
- Tareas:
  - mandar la lista de preguntas al contacto comercial de TCN
  - pedir confirmación con ingeniería
  - capturar respuestas en la documentación
- Criterio de salida:
  - queda confirmado el significado de `CodeUrl` y el handshake de success de pago

#### Paso 3. Congelar contrato Ballbox-TCN
- Objetivo: convertir respuestas en una spec concreta del adapter.
- Tareas:
  - definir schema request/response para TCN `8000`
  - definir success/failure callback o comportamiento de polling
  - definir comportamiento ante duplicados/idempotencia para `TradeNo`
  - definir reglas de mapping de machine id
- Criterio de salida:
  - la spec queda lo bastante precisa como para codear sin adivinar

#### Paso 4. Implementar capa adapter
- Objetivo: agregar endpoints TCN-facing de Ballbox sobre las primitivas actuales de Mercado Pago.
- Tareas:
  - agregar endpoint(s) machine-facing
  - mapear requests TCN a creación de órdenes Ballbox/Mercado Pago
  - mapear estado de pago aprobado de vuelta al flujo de success TCN
  - persistir cualquier campo extra de correlación de máquina que haga falta
- Criterio de salida:
  - el flujo local/manual del adapter funciona sin hardware real

#### Paso 5. Validación con hardware cuando lleguen las máquinas
- Objetivo: verificar el comportamiento real de la máquina TCN stock.
- Tareas:
  - probar render real de QR en pantalla
  - probar path pago aprobado -> vend
  - capturar timings, retries y fallas
- Criterio de salida:
  - un vend real sale bien a través del flujo de Ballbox

#### Paso 6. Recién después revisar automatización de payouts
- Objetivo: no resolver reparto/payout a clubes antes de estabilizar el camino de máquina.
- Default actual:
  - liquidaciones programadas manuales / bookkeeping manual

### 7.7 Secuencia de test de pago del setup day
#### Remoto
1. Confirmar que la máquina aparezca online en cloud.
2. Confirmar que exista un producto vendible y esté bien mapeado.
3. Confirmar que el flujo de test de pagos de Ballbox siga pudiendo crear órdenes QR.
4. Confirmar que máquina/cloud puedan pedir payment init contra el adapter o stub de Ballbox.
5. Escanear y pagar el QR desde un teléfono.
6. Confirmar que Ballbox reciba el webhook del proveedor.
7. Confirmar que el pago aprobado se persista con correlación canónica de máquina.
8. Confirmar que el lado TCN reciba la señal de success/notify.
9. Reconciliar pago, resultado de vend y cambio de inventario.

#### En sitio
1. Confirmar que el producto vendible esté cargado físicamente.
2. Registrar la visualización del QR en la máquina.
3. Después de la aprobación, confirmar que cambie el estado de la máquina.
4. Confirmar que el vend físico ocurra con éxito.
5. Grabar video de prueba.
6. Reportar de inmediato cualquier mismatch entre pago exitoso y resultado de vend.


Successfully replaced 1 block(s) in /mnt/rpi/worktrees/ballbox/docs-vending-manual/docs/02-vending-machine-setup-day-manual.es-ar.md.

     ...
 237 - si la media se asigna por máquina, por grupo o por playlist
 238 - si hace falta sync/reboot manual después de publicar
 239
 240 ## 7. Pago y vend de prueba
-241 ### Estado de la integración de pagos
-242 ### Posición actual de Ballbox
-243 - `/admin/payments` queda como harness de test/debug de Ballbox.
+241 ### 7.1 Dirección actual de integración
+242 - `/admin/payments` queda como harness de test/debug de Ballbox, no como UX final de pago de producción.
 244 - El flujo productivo de vending debería ir por protocolo TCN.
 245 - La máquina debería mostrar el QR buyer-facing en su propia pantalla.
 246 - Ballbox debería ser dueño de la creación del pago, validación del webhook, persistencia de aprobaciones y reconciliación.
 247
-248 ### Por qué esto todavía parece válido
+247 ### 7.2 Por qué esta dirección todavía parece válida
 249 - La investigación actual sigue apoyando OurVend/TCN como capa de cloud + control del dispositivo, no como dueña de la lógica de negocio de Ballbox.
 250 - La evidencia pública sigue apuntando a device-open access con secret/signature del lado proveedor.
-251 - La investigación sigue apoyando QR dinámico controlado por backend más autorización de vend del lado proveedor como el default más seguro hasta que lleguen docs exactas del tenant.
+250 - El protocolo TCN `2.5V` dice que para escanear QR hacen falta dispositivos adicionales, pero eso aplica al escaneo desde la máquina, no a mostrar un QR en pantalla para que lo escanee el comprador con el teléfono.
+251 - El flujo de pagos TCN (`FunCode=8000`) ya define un intercambio dinámico donde la máquina manda `MachineID`, `TradeNo`, `SlotNo`, `Price` y `NotityUrl`, y el servidor devuelve `CodeUrl` y `TradeNo`.
+252 - Eso sigue apoyando QR dinámico controlado por backend más autorización de vend del lado proveedor como el camino más seguro hasta que lleguen docs exactas del tenant.
 252 - El login cloud de test por sí solo no cambia esa dirección.
 253
-254 ### Lo que todavía hay que confirmar en el setup day
-255 - payload exacto de payment-init desde máquina/cloud
-256 - path exacto de callback / notify de vend-success
-257 - expectativa exacta de `CodeUrl`: payload QR vs link vs deep link específico del proveedor
-258 - si la finalización del pago depende de callback, polling o ambos
-259 - shape exacto de auth/signature para endpoints del tenant productivo
+255 ### 7.3 Flujo productivo objetivo
+256 1. El comprador elige el producto en la máquina TCN.
+257 2. La máquina TCN pide una sesión de pago a Ballbox usando el contrato TCN de pagos.
+258 3. Ballbox crea una orden QR en Mercado Pago.
+259 4. Ballbox mapea esa respuesta al formato TCN y devuelve `CodeUrl`.
+260 5. La máquina TCN muestra el QR en pantalla.
+261 6. El comprador escanea con la app de Mercado Pago en el teléfono.
+262 7. El proveedor notifica a Ballbox por webhook.
+263 8. Ballbox valida y persiste el pago aprobado.
+264 9. La máquina TCN recibe la señal de éxito por el path TCN de notify/result y despacha el producto.
 260
-261 ### Secuencia de test de pago del setup day
+266 ### 7.4 Lo que Ballbox necesita cerrar
+267 #### 7.4.1 Contrato machine-facing
+268 - Definir una ruta de Ballbox para requests `8000` de init de pago TCN.
+269 - Definir el mapping exacto de:
+270   - `MachineID` -> `vendingMachineId` de Ballbox o identificador externo de máquina
+271   - `TradeNo` -> id de transacción de máquina / `externalReference` canónico
+272   - `SlotNo`
+273   - `Price`
+274   - `NotityUrl`
+275   - respuesta `CodeUrl`
+276 - Confirmar si TCN espera en `CodeUrl` una URL cruda, un payload QR o un deep link específico del proveedor.
+277
+278 #### 7.4.2 Handshake de success / dispense
+279 - Mapear cómo debe señalar Ballbox el éxito de pago de vuelta al flujo TCN.
+280 - Confirmar si Ballbox tiene que llamar al `NotityUrl`, exponer un callback, o apoyarse en polling / result dentro del protocolo TCN.
+281 - Confirmar cómo TCN correlaciona pago aprobado y dispense usando `TradeNo`, `SlotNo` u otro campo.
+282
+283 #### 7.4.3 Identidad de máquina
+284 - Definir el mapping canónico entre `MachineID` de TCN y la `VendingMachine` de Ballbox.
+285 - Agregar un external id solo si hace falta para un lookup limpio.
+286
+287 #### 7.4.4 Mantener admin QR como herramienta de test
+288 - `/admin/payments` sigue siendo útil para:
+289   - chequeos de config de Mercado Pago
+290   - smoke tests de creación de QR live
+291   - validación de webhooks
+292   - debugging manual del proveedor
+293 - No presentarlo como UX final de pago de vending.
+294
+295 ### 7.5 Preguntas abiertas para TCN / ingeniería / validación interna
+296 1. En `FunCode=8000`, ¿qué valor exacto tiene que devolver Ballbox en `CodeUrl`?
+297    - raw URL
+298    - string payload QR
+299    - deep link de Mercado Pago
+300    - otro formato específico del proveedor
+301 2. Después de la aprobación del pago, ¿cómo se entera la máquina de que ya puede vender?
+302    - Ballbox llama al `NotityUrl` del request
+303    - la máquina hace polling a otro endpoint TCN
+304    - la cloud empuja por `4000`
+305    - otro flujo
+306 3. ¿`NotityUrl` viene siempre por transacción desde la máquina o además existe un callback configurado a nivel máquina?
+307 4. ¿Cuál es el payload exacto esperado para el mensaje de notify/result de pago exitoso?
+308 5. ¿Cuál es la verdadera key de correlación para el dispense?
+309    - `TradeNo`
+310    - `SlotNo`
+311    - ambos
+312    - otro campo interno de máquina
+313 6. ¿La app stock de TCN renderiza el QR de forma nativa después de una respuesta `8000` exitosa o requiere config adicional del lado máquina?
+314 7. ¿Hay expectativas de timeout / expiración para la ventana de pago QR desde el lado máquina?
+315 8. ¿Qué debe devolver Ballbox a la máquina cuando falla la creación del pago o hace timeout?
+316 9. ¿Hay retries de máquina por `TradeNo` duplicado que Ballbox tenga que tolerar?
+317 10. ¿Existen endpoints de pago adicionales además de `8000` para un flujo productivo completo de dispense?
+318 11. Del lado Mercado Pago / validación interna:
+319    - qué valor conviene mapear en `CodeUrl`
+320    - si el payload QR/deeplink actual sirve para compradores usando Mercado Pago app
+321    - si el webhook público actual es estable para notificaciones reales
+322    - si hay restricciones de expiración, duplicados o idempotencia que haya que codificar antes del rollout
+323
+324 ### 7.6 Plan de ejecución
+325 #### Paso 1. Cerrar la prueba de capa proveedor
+326 - Objetivo: probar que el flujo nativo de Mercado Pago en Ballbox funciona end-to-end sin hardware TCN.
+327 - Tareas:
+328   - validar reachability pública del webhook `/notification/mercadopago`
+329   - correr un pago real aprobado
+330   - confirmar persistencia local en `/admin/payments`
+331   - documentar payload exacto y evidencia de URL pública
+332 - Criterio de salida:
+333   - un pago real aprobado persiste localmente por webhook
+334
+335 #### Paso 2. Mandar preguntas a TCN
+336 - Objetivo: cerrar los unknowns machine-side antes de codear el adapter.
+337 - Tareas:
+338   - mandar la lista de preguntas al contacto comercial de TCN
+339   - pedir confirmación con ingeniería
+340   - capturar respuestas en la documentación
+341 - Criterio de salida:
+342   - queda confirmado el significado de `CodeUrl` y el handshake de success de pago
+343
+344 #### Paso 3. Congelar contrato Ballbox-TCN
+345 - Objetivo: convertir respuestas en una spec concreta del adapter.
+346 - Tareas:
+347   - definir schema request/response para TCN `8000`
+348   - definir success/failure callback o comportamiento de polling
+349   - definir comportamiento ante duplicados/idempotencia para `TradeNo`
+350   - definir reglas de mapping de machine id
+351 - Criterio de salida:
+352   - la spec queda lo bastante precisa como para codear sin adivinar
+353
+354 #### Paso 4. Implementar capa adapter
+355 - Objetivo: agregar endpoints TCN-facing de Ballbox sobre las primitivas actuales de Mercado Pago.
+356 - Tareas:
+357   - agregar endpoint(s) machine-facing
+358   - mapear requests TCN a creación de órdenes Ballbox/Mercado Pago
+359   - mapear estado de pago aprobado de vuelta al flujo de success TCN
+360   - persistir cualquier campo extra de correlación de máquina que haga falta
+361 - Criterio de salida:
+362   - el flujo local/manual del adapter funciona sin hardware real
+363
+364 #### Paso 5. Validación con hardware cuando lleguen las máquinas
+365 - Objetivo: verificar el comportamiento real de la máquina TCN stock.
+366 - Tareas:
+367   - probar render real de QR en pantalla
+368   - probar path pago aprobado -> vend
+369   - capturar timings, retries y fallas
+370 - Criterio de salida:
+371   - un vend real sale bien a través del flujo de Ballbox
+372
+373 #### Paso 6. Recién después revisar automatización de payouts
+374 - Objetivo: no resolver reparto/payout a clubes antes de estabilizar el camino de máquina.
+375 - Default actual:
+376   - liquidaciones programadas manuales / bookkeeping manual
+377
+378 ### 7.7 Secuencia de test de pago del setup day
 262 #### Remoto
 263 1. Confirmar que la máquina aparezca online en cloud.
 264 2. Confirmar que exista un producto vendible y esté bien mapeado.
 265 3. Confirmar que el flujo de test de pagos de Ballbox siga pudiendo crear órdenes QR.
     ...


bash

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && rm -f docs/exports/vending-machine-setup-day-manual-standalone.pdf && python scripts/export-setup-manual-standalone-es-ar-pdf.py && git status --short


/mnt/rpi/worktrees/ballbox/docs-vending-manual/docs/exports/02-vending-machine-setup-day-manual-extendido.es-ar.pdf
 M docs/02-vending-machine-setup-day-manual.es-ar.md
 M docs/exports/02-vending-machine-setup-day-manual-extendido.es-ar.pdf
 D docs/exports/vending-machine-setup-day-manual-standalone.pdf
?? scripts/__pycache__/


**Removing pycache**

I think I need to remove the pycache generated from the script run. It’s a common step, especially if old bytecode files are causing issues or not being aligned with the latest changes in the code. Making sure only the necessary files are there can help keep things clean and organized. Okay, let's get that sorted out and ensure everything is running smoothly without any clutter!

cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && rm -rf scripts/__pycache__ && git add docs/02-vending-machine-setup-day-manual.es-ar.md docs/exports/02-vending-machine-setup-day-manual-extendido.es-ar.pdf docs/exports/vending-machine-setup-day-manual-standalone.pdf && git commit -m "docs: fold payment pack into extended spanish manual"


[docs-vending-manual 3378b99] docs: fold payment pack into extended spanish manual
 3 files changed, 227 insertions(+), 265 deletions(-)
 delete mode 100644 docs/exports/vending-machine-setup-day-manual-standalone.pdf


Updated #9 (pending → completed)


Hecho.

Cambios:
- borré `docs/exports/vending-machine-setup-day-manual-standalone.pdf`
- integré el contenido útil del pack TCN/payments dentro de:
  - `docs/02-vending-machine-setup-day-manual.es-ar.md`
  - `docs/exports/02-vending-machine-setup-day-manual-extendido.es-ar.pdf`

Qué quedó adentro del `02`:
- dirección de integración TCN
- flujo productivo objetivo
- contrato machine-facing a cerrar
- handshake success/dispense
- mapping de identidad de máquina
- preguntas abiertas para TCN / ingeniería / validación interna
- plan de ejecución paso a paso
- secuencia de test de pago del setup day

PDF extendido actualizado:
- https://ballbox-first.emperor-ratio.ts.net/files/mnt/rpi/worktrees/ballbox/docs-vending-manual/docs/exports/02-vending-machine-setup-day-manual-extendido.es-ar.pdf

Commit:
- `3378b99` — `docs: fold payment pack into extended spanish manual`

Entregables PDF finales ahora, en práctica:
- `docs/exports/01-vending-machine-setup-day-basico.es-ar.pdf`
- `docs/exports/02-vending-machine-setup-day-manual-extendido.es-ar.pdf`

Sigue existiendo además:
- `docs/exports/vending-setup-day-pack.pdf`
pero ya quedó más redundante. Si querés, lo borro también.


si borra ese


cd /mnt/rpi/worktrees/ballbox/docs-vending-manual && rm -f docs/exports/vending-setup-day-pack.pdf && git add docs/exports/vending-setup-day-pack.pdf && git commit -m "docs: remove redundant setup pdf pack"


[docs-vending-manual a9b78bc] docs: remove redundant setup pdf pack
 1 file changed, 328 deletions(-)
 delete mode 100644 docs/exports/vending-setup-day-pack.pdf


Hecho.

Borré:
- `docs/exports/vending-setup-day-pack.pdf`

Commit:
- `a9b78bc` — `docs: remove redundant setup pdf pack`

Entregables PDF finales:
- `docs/exports/01-vending-machine-setup-day-basico.es-ar.pdf`
- `docs/exports/02-vending-machine-setup-day-manual-extendido.es-ar.pdf`