Hoseg Cash (Hoseg Rewards) — Proyecto
Estado
🟢 APROBADO POR EL CLIENTE (2026-08-25) — Cindy confirmó aprobación; hoy pagan Apple Developer ($99/año). Proyecto ACTIVO.
- Sistema: https://hoseg-cash.disoftx.solutions (container hoseg-cash, puerto 3010, Zeta)
- Presentación: https://hoseg-cash-presentacion.disoftx.solutions (21 slides, 4 partes)
- Demo PWA: https://hosegcash-demo.disoftx.solutions
- TAREA ACTUAL: Google Wallet a producción — el issuer configurado (3388000000023168817) es de PRUEBA (Disoftx, límite ~10 testers).
- ⏸️ Apple Wallet PAUSADO (2026-09-08): Daniel decidió dejarlo por ahora. Implementado y en producción (pase .pkpass storeCard firmado, endpoint /api/wallet/:token/apple, botón 🍎 en wallet PWA). Pendiente único: prueba real en iPhone (agregar pase desde /w/
- ✅ 2026-08-26: PRODUCCIÓN ACTIVADA — Google aprobó la publicación del issuer (el mismo ID 3388000000023168817 con datos 14 Diez SAC/Hösėg). Verificado: 4 clases activas approved (HOSEG_CASH + 3 tiers Social Heater/Changemaker/Heart Warmer), geofencing 5 sucursales reales, fix desplegado (sin reviewStatus UNDER_REVIEW en ensure/sync para no revertir). Detalle: memory/2026-08-26.md
- Detalle técnico completo: wiki/proyectos/hoseg-cash-arquitectura.md
Concepto
Loyalty rewards con dinero (cashback) para cliente Höseg.
- POS: Odoo v19
- Web: Shopify
- Entregable: Tarjetas virtuales que se añaden a un wallet y muestran puntos/saldo
Requerimientos del cliente (2026-08-05)
- Programa de lealtad con recompensas en dinero (no solo puntos de descuento)
- Integración con POS Odoo v19 (ellos lo usan en punto de venta)
- Integración con web Shopify
- Tarjetas virtuales que se agregan a un wallet del cliente
- El cliente debe poder ver sus puntos/saldo desde el wallet
Idea inicial de Daniel (2026-08-05)
- Odoo tiene opción de tarjetas rewards → usarla como base
- Script para Shopify que llame/lea la API de Odoo
- Tarjeta virtual: duda si puede leer APIs
Contexto previo (importante)
- Existe propuesta comercial previa:
wiki/proyecto-fidelidad-hosegcafe.md - Era Google Wallet API + Node.js/Express + SQLite (julio 2026, "en espera de aprobación")
- Presentación: https://proyectofidelidad-hosegcafe.disoftx.solutions
- Cliente ahora pide versión evolucionada con dinero + Odoo + Shopify
- Cliente: Höseg Café — cafetería de especialidad, Cusco
- Infra existente: hosegcafe PWA en Zeta (pedidos.hosegcafe.com, Node+Express+SQLite)
Análisis técnico de Nexus (2026-08-05)
Odoo 19 — SÍ tiene lo necesario
- Módulo Loyalty (Fidelización): programas de puntos, tarjetas de fidelidad con código/QR propio, reglas de acumulación/canje
- Gift Card / eWallet integrado en loyalty (Odoo 17+): funciona como monedero con saldo en dinero
- Portal de cliente de Odoo muestra la tarjeta con puntos
- API completa vía XML-RPC/JSON-RPC (leer/crear tarjetas, sumar puntos, registrar transacciones)
Shopify — SÍ, pero vía middleware
- NO conectar Shopify directo a Odoo (frágil, expone credenciales, sin logging)
- Shopify webhook
orders/paid→ middleware → Odoo (suma puntos) - Opcional: metafields en cuenta Shopify para mostrar saldo
Tarjeta virtual — SÍ puede leer APIs
- Recomendación: PWA wallet (instalable) como wallet principal:
- Login (teléfono/email), tarjeta virtual con QR (código de tarjeta Odoo)
- Saldo en tiempo real, historial de transacciones, canje
- QR escaneado en POS Odoo para identificar/canjear
- Google Wallet queda como add-on opcional (pase estático actualizable), no como wallet principal
Arquitectura propuesta
Shopify (web) ──webhook──▶ MIDDLEWARE (nuestro) ◀──▶ Odoo v19 (POS/ERP)
│ ▲ (fuente de verdad)
Wallet PWA (cliente) ──────────┘ └── API REST
- Odoo = fuente de verdad (puntos, tarjetas, contabilidad)
- Middleware (Node.js o Python/FastAPI) = pegamento: webhooks Shopify ↔ Odoo XML-RPC ↔ API wallet
- Wallet PWA = tarjeta virtual del cliente
Pendientes / Preguntas a Daniel
- [ ] ¿Cómo se acumula el dinero? (S/ gastado → puntos, ¿% cashback?)
- [ ] ¿Canje = descuento en próxima compra o saldo retirable?
- [ ] ¿Registro del cliente: autónomo (web/PWA) o staff en tienda?
- [ ] ¿Aplica solo a Höseg Café o a más tiendas del grupo?
- [ ] ¿Odoo v19 ya instalado/operativo? ¿Acceso a API disponible?
- [ ] ¿Apple Wallet requerido o basta Android/Google?
Referencias
- Creado: 2026-08-05
- Nota diaria: memory/2026-08-05.md
- Propuesta previa: wiki/proyecto-fidelidad-hosegcafe.md
🔍 Aclaración del flujo (2026-08-05 10:26 — Daniel)
Reglas de acumulación (cashback por umbrales)
- Compra > S/ 299 → acumula S/ 10
- Compra > S/ 699 → acumula S/ 30
- Acumulable entre compras (sale para próxima compra)
Flujo en tienda (POS)
- Cliente compra (ej: casaca)
- Vendedor busca cashback por DNI o teléfono
- Ve cuánto tiene acumulado
- Pregunta al cliente si quiere consumir ese cashback
- Descuenta del total
Flujo en web (Shopify)
- Cliente compra en Shopify
- Tiene cashback acumulado → lo descuenta desde el checkout
📊 Análisis de viabilidad (Nexus, 2026-08-05)
✅ VIABLE
| Ítem | Cómo |
|---|---|
| Reglas de acumulación por umbrales | Configuración nativa en Odoo Loyalty (sin desarrollo) |
| Búsqueda por DNI/teléfono en POS | Nativo en Odoo POS (búsqueda de cliente) |
| Canje en tienda (descuento del total) | Nativo: gift card como método de pago en POS |
| Contabilidad del cashback | Odoo maneja gift cards como pasivo (cuenta Gift Card) |
| Shopify con middleware | Webhook order/paid → middleware → Odoo suma cashback |
| Descuento en checkout Shopify | Middleware valida saldo en Odoo → genera discount code en Shopify |
⚠️ PARCIALMENTE VIABLE
| Ítem | Detalle |
|---|---|
| Gift card Odoo reemplaza tarjeta virtual | Reemplaza el motor (backend del dinero) pero NO la vista del cliente. Odoo tiene portal pero UX pobre y requiere usuarios portal. Se necesita capa simple para que el cliente vea saldo. |
❌ NO VIABLE / NO RECOMENDADO
- Sincronización nativa Odoo ↔ Shopify de gift cards: no existe, hay que construir el middleware sí o sí
- App wallet completa (login, historial, notificaciones, push): imposible en 1 semana
- Apple Wallet / Google Wallet como wallet principal: fuera de alcance por ahora
- Shopify checkout nativo con gift card Odoo: Shopify no acepta códigos de Odoo, requiere discount code generado por middleware
⏱️ Viabilidad en 1 SEMANA
Factible SI Odoo v19 ya está instalado y hay acceso a API + acceso admin a Shopify.
- El flujo POS es 100% configuración de Odoo (rápido)
- El trabajo real: middleware + integración Shopify + página de saldo simple
- La "tarjeta virtual" en semana 1 = página web móvil (sin login complejo): cliente ingresa DNI/teléfono + código → ve saldo. No app instalable.
🗓️ Plan MVP (1 semana)
| Día | Tarea |
|---|---|
| 1-2 | Confirmar Odoo v19 operativo + configurar Loyalty (reglas 299/699) + Gift Card |
| 2-3 | Middleware: API de consulta saldo + creación gift card (XML-RPC Odoo) |
| 3-4 | Shopify: webhook order/paid → sumar cashback; endpoint checkout → discount code |
| 4-5 | Página wallet simple (saldo vía DNI/teléfono) |
| 5-6 | Pruebas integradas POS + Shopify + datos reales |
| 6-7 | Buffer + demo al cliente |
🚧 BLOQUEANTES — necesito respuesta YA
- [ ] ¿Odoo v19 ya está instalado y funcionando? ¿Dónde (on-prem, Odoo.sh, hosting)? ¿Acceso a API?
- [ ] ¿Acceso admin a la tienda Shopify (API keys)?
- [ ] ¿En Shopify el cliente se identifica por DNI, teléfono o código de tarjeta?
- [ ] ¿Los montos 299/699 son con o sin IGV? ¿Cashback en soles reales?
- [ ] ¿Una sola tienda o varias?
✅ Respuestas de Daniel (2026-08-05 10:35) — Bloqueantes resueltos
- Odoo v19 Enterprise ✅ — ya instalado y funcionando, alojado en Odoo Cloud (nube oficial de Odoo)
- Acceso admin Shopify ✅ — sí
- Precios con IGV — umbrales 299/699 son montos con impuesto incluido
- Cashback = dinero virtual — no es dinero retirable, es saldo/crédito para próximas compras (simplifica contabilidad: es gift card, no pasivo de caja)
- Tienda Hoseg principal (casacas) + varias sucursales
⚠️ Implicación clave: Odoo Cloud (SaaS)
- Al ser la nube oficial de Odoo (Odoo Online): NO se pueden instalar módulos custom
- No los necesitamos: Loyalty + Gift Card son nativos de Enterprise
- Acceso vía XML-RPC con API key (generar desde usuario admin)
- Rate limits de API aplican pero sobran para este volumen
- POS nativo cubre: búsqueda por DNI/teléfono + gift card como pago
- Gift card válida entre sucursales si usan una sola compañía (verificar)
🗓️ Plan MVP 1 semana (ajustado)
| Día | Tarea |
|---|---|
| 1 | Odoo: programa Loyalty "Hoseg Cash" (reglas 299→10, 699→30, monto con IGV) + programa Gift Card + API key |
| 2 | Middleware (Node.js): conexión XML-RPC, endpoints saldo + crear/creditar gift card → Zeta + Caddy |
| 3 | Shopify app custom: webhook order/paid → sumar cashback; checkout DNI → discount code |
| 4 | Página wallet móvil: DNI/teléfono → saldo + historial → publicar |
| 5 | Pruebas integradas: POS canje + Shopify acumular/canjear + casos borde |
| 6 | Datos reales + pruebas con cliente |
| 7 | Demo + entrega |
🚧 Preguntas finales pendientes
- [ ] ¿En Shopify el cliente se identifica con DNI, teléfono o código? (propuesta: DNI o teléfono)
- [ ] Compra de S/800 → ¿acumula 30 (solo tope superior) o 40 (10+30 acumulativo)?
- [ ] ¿Una compra pagada con cashback también genera nuevo cashback?
- [ ] ¿Todas las sucursales usan UNA sola compañía en Odoo?
- [ ] ¿Dominio para wallet/middleware? (ej: wallet.hosegcafe.com)
✅ Respuestas finales (2026-08-05 10:40)
- Identificación en Shopify: cuenta de usuario del cliente en Shopify (customer account)
- Acumulación acumulativa o tope: ⏳ PENDIENTE — Daniel preguntará a Cindy
- Compra pagada con cashback genera cashback: NO
- Compañía: única ✅ — razón social: 14 Diez SAC
Sucursales: Larcomar, Marriott Lima, Marriott Cusco, Casa Hoseg, Cusco Plaza - Dominio: aún no definido (se decide después)
🔧 Implicaciones técnicas
- Shopify customer account → vincular customer_id de Shopify con partner de Odoo (por email/teléfono)
- Metafield en cliente Shopify con código de gift card Odoo (opcional)
- Regla no-acumulativa configurable en Odoo (regla A: 299-698 → 10, regla B: ≥699 → 30) — funciona de ambas formas, esperar respuesta de Cindy
- Excluir pago con cashback del cálculo de nuevo cashback: verificar configuración Odoo (pagos con gift card en POS)
- 5 sucursales en 1 compañía → gift card válida en todas (nativo)
🔑 ACCESOS NECESARIOS PARA ARRANCAR
- Odoo Cloud: URL de la base (xxx.odoo.com), usuario admin, API key (generar en odoo.com → My Account → Security → API Keys)
- Shopify: Custom app (admin → Settings → Apps → Develop apps) con scopes: read_orders, write_discounts, read_customers, write_customers + webhook orders/paid. Entregar API key + secret + admin access token
♻️ 2026-09-23 — Diferenciación de créditos: compra vs reciclaje (PEDIDO DE CINDY)
- Cindy (WhatsApp, 12:26) pidió diferenciar de forma natural los Créditos Hoseg entre compras orgánicas y reciclaje (iniciativa nueva). Pidió analizar alternativas y medir viabilidad SIN tocar programación. Reunión hoy 5:00 pm.
- Análisis de opciones (A etiqueta
credit_typeen el ledger ⭐ recomendada · B dos programas · C bolsillos con reglas propias · D vouchers aparte) + preguntas de negocio para la reunión:wiki/proyectos/hoseg-creditos-reciclaje.md. - Estado: análisis entregado. Nada implementado.
🧭 OPCIÓN 1 (actual) — DISEÑO COMPLETO
Todo lo documentado arriba (Odoo Loyalty+GiftCard + middleware + Shopify + wallet) es la OPCIÓN 1.
⏳ Esperando que Daniel describa la OPCIÓN 2 para comparar y elegir.
🧭 OPCIÓN 2 — App de loyalty de Shopify como motor (2026-08-05 10:46)
Propuesta de Daniel: app tipo "Cash Rewards"/cashback de Shopify como motor de todo.
Shopify = motor · Odoo se conecta a la API de Shopify · Wallet se conecta a Shopify.
Análisis de viabilidad (Nexus + verificación web)
❌ NO VIABLE como "motor de todo" — la razón de fondo:
- El motor vive en el mundo Shopify, pero el POS es Odoo. Las apps de loyalty (Angle, Redeemly, Shopwaive, Koin, Dollarback, Appstle) funcionan online + Shopify POS. El cliente usa Odoo POS en 5 sucursales → las ventas en tienda son invisibles para la app.
- Shopify tiene Store Credit nativo ahora (API + Shopify POS 10.2+) — pero SOLO funciona en Shopify POS, no en Odoo POS. No aplica a este cliente.
- El flujo en tienda no se resuelve: el cajero no puede ver saldo ni canjear desde Odoo POS sin integración custom vía API de la app (muchas apps no tienen API pública o es de paga/limitada). Y aunque tuvieran API, canjear en Odoo POS = custom igual o más trabajo que Opción 1.
- Reglas de negocio: umbrales con IGV, no acumulativo, excluir compras pagadas con cashback → dependen del motor de reglas de la app; casi seguro no calzan exacto.
- Costo + lock-in: suscripción mensual + datos de clientes y saldos en SaaS de terceros. Si dejan de pagar, muere el programa. Riesgo Ley 29733 (datos personales).
- Sincronización doble: el saldo viviría en la app → Odoo POS consultaría en tiempo real (latencia, dependencia uptime, rate limits). Frágil.
✅ CUÁNDO SERÍA VIABLE la opción 2:
- Si el POS en tienda fuera Shopify POS (no lo es, es Odoo)
- Si fuera solo canal online (no es el caso — el flujo en tienda es el corazón del negocio)
- Reglas simples sin umbrales/exclusiones estrictas
✅ Lo rescatable de la opción 2: el widget de wallet que ve el cliente viene de fábrica. Pero eso también lo damos con la página wallet propia.
🏁 Veredicto
Opción 1 (Odoo = motor) es la correcta. Además Odoo Enterprise tiene Shopify Connector nativo (sincroniza pedidos web a Odoo), lo que reduce trabajo de integración. La opción 2 costaría MÁS (suscripción + integración custom) y sería MÁS frágil, con lock-in.
🧭 OPCIÓN 3 — BD externa como motor (2026-08-05 11:00)
Propuesta de Daniel: Base de datos externa (estilo hosegcafe original: SQLite/PG propia).
Odoo y Shopify se conectan POR API a esa BD externa = fuente de verdad del loyalty.
Análisis de viabilidad (Nexus)
✅ LO BUENO (es la mejor arquitectura a largo plazo):
- Control TOTAL de reglas de negocio: umbrales con IGV, no acumulativo, excluir compras pagadas con cashback — todo en código nuestro
- Resuelve la regla que Odoo nativo quizá NO deja configurar en SaaS: "compra pagada con cashback no genera cashback" (Odoo calcula puntos sobre el total del pedido, no resta pagos con gift card)
- Sin lock-in: datos portables, se puede migrar de Odoo/Shopify sin perder el programa
- Analytics, campañas, notificaciones, wallet: todo sobre nuestra BD
- Familiar: mismo patrón del proyecto hosegcafe original (SQLite + servicio propio)
⚠️ EL PROBLEMA CLAVE (Odoo Cloud SaaS = sin módulos custom):
- El canje en POS necesita un mecanismo NATIVO de Odoo para descontar valor → obligatorio usar gift card de Odoo como "token"
- Eso crea DOBLE CONTABILIDAD: ledger externo (verdad) + gift card Odoo (token gastable) → sincronización bidireccional + script de reconciliación
- Acumulación en tienda: Odoo Online no deja hookear eventos del POS con código custom → hay que polling de pedidos (consultar pos.order cada X min) → lag de minutos entre sucursales (un cashback de hace 2 min en Larcomar puede no estar disponible aún en Cusco Plaza)
- Más superficie de error: divergencia de saldos, reconciliación, mantenimiento
📊 COMPARACIÓN RÁPIDA
| Criterio | Op1 (Odoo motor) | Op2 (app Shopify) | Op3 (BD externa) |
|----------|-----------------|-------------------|------------------|
| Esfuerzo semana 1 | ⭐ Mínimo | Medio (pero no cubre POS) | 🔴 Alto |
| Reglas custom | Parcial | Limitado | ✅ Total |
| Canje POS nativo | ✅ Sí | ❌ No | ⚠️ Vía gift card token |
| Lock-in | Bajo (Odoo ya es su ERP) | 🔴 Alto (SaaS 3ro) | ✅ Ninguno |
| Riesgo entrega 1 semana | Bajo | Medio-alto | 🔴 Alto |
🏁 Veredicto
Opción 3 = mejor a largo plazo, inviable como build completo en 1 semana.
Recomendación: MVP semana 1 con Opción 1 (Odoo = ledger + canje nativo + auditoría nativa; middleware = Shopify + wallet). Fase 2: evolucionar a Opción 3 (mover ledger a BD externa, Odoo gift card queda como token) — se gana control total de reglas sin arriesgar la entrega.
🔧 OPCIÓN 3 — Lado SHOPIFY (complemento, 2026-08-05 11:06)
Shopify en Opción 3 es la parte FÁCIL — y sin doble contabilidad:
- Acumular (compras online): webhook
orders/paid→ servicio propio → suma al ledger externo (reglas en código nuestro: umbrales IGV, exclusiones). Tiempo real, limpio. - Canjear en checkout: NO usar Shopify Store Credit / gift cards nativas (eso crearía OTRO ledger paralelo → mismo problema de doble contabilidad del lado Odoo). En su lugar: el servicio genera un discount code efímero por
min(saldo, total)→ se aplica en el checkout → el código se consume y no persiste saldo en Shopify → el ledger externo sigue siendo el único. - Identificación: cuenta de usuario Shopify (email) → se vincula/crea el cliente en el ledger externo (match por email/teléfono).
- Wallet: lee directo del ledger externo (misma API para clientes de tienda y de web).
ASIMETRÍA CLAVE de la Opción 3:
- Shopify: ✅ limpio (códigos efímeros, sin saldo persistente en Shopify)
- Odoo: ⚠️ doble contabilidad (ledger externo + gift card token nativo) + polling + reconciliación
- El único punto frágil de Opción 3 es el lado Odoo/POS, no Shopify.
Extra Opción 3: el staff (cajero) usa panel propio (buscar DNI/teléfono → ver saldo en ledger externo) y aplica el gift card Odoo (sincronizado) en el POS.
🔄 OPCIÓN 3 REVISADA — Canje MANUAL en tienda (2026-08-05 11:11) ⭐
Decisión de Daniel: el descuento NO tiene que ser automático en Odoo.
- Vendedor abre web externa (panel staff) → busca DNI/teléfono → ve saldo → pregunta al cliente cuánto descontar → aplica descuento manual en Odoo POS → marca el canje en el panel.
💥 IMPACTO CLAVE: al no necesitar descuento automático en Odoo, se elimina el gift card token → NO hay doble contabilidad → la Opción 3 pasa a ser la MEJOR opción.
Flujo operativo (con menos filtros — 2 toques)
- Vender en tienda: vendedor selecciona/crea cliente en Odoo POS (DNI/teléfono) — 1 paso, lo haría igual
- Acumular: automático — poller consulta pedidos de Odoo (XML-RPC) → credita ledger (sin acción del vendedor)
- Canjear: panel staff → buscar → ver saldo → vendedor aplica descuento manual en POS → marca canje (1 click)
Shopify (canal online)
- Acumular: automático vía webhook
orders/paid→ ledger. Cero fricción. - Canjear: self-service — cliente logueado ve su saldo → botón "usar cashback" → sistema genera código efímero
min(saldo,total)→ se aplica en checkout. Sin staff.
🏷️ Liquidación (colección Shopify) — exclusión de cashback
- Fuente de verdad: colección "Liquidación" en Shopify
- Sync periódico: colección → lista de SKUs → ledger (API Shopify)
- Online: al calcular cashback, se excluyen del monto base las líneas con SKU en liquidación (o tasa reducida — configurable)
- Tienda: el poller usa la misma lista de SKUs → excluye esas líneas
- Canje NO se afecta (usar cashback en productos en liquidación = decisión de negocio, confirmar)
Regla "no cashback sobre cashback"
- Base de cálculo = monto neto pagado (después de todos los descuentos) → el cashback usado ya queda excluido automáticamente
- Variante estricta ("si usó cashback, cero") = flag configurable en código
🗓️ Scope semana 1 (Opción 3 revisada)
- Ledger externo (SQLite/PG): clientes, saldos, transacciones, reglas
- Servicio Node.js: webhook Shopify + poller Odoo + códigos checkout + APIs
- Panel staff (web): buscar → ver saldo → canjear (mínimo)
- Wallet cliente (web móvil): saldo + historial
- Shopify: custom app + webhook + saldo en cuenta + "usar cashback"
- Sync colección Liquidación → SKUs
- Pruebas integradas
📱 DEMO WALLET (2026-08-05 11:20) ✅
- URL: https://hosegcash-demo.disoftx.solutions
- Tipo: PWA instalable en Android (datos ficticios, modo demo)
- Muestra: tarjeta virtual (titular, N°, DNI, QR), saldo disponible, acumulado total, canjes, reglas (299→10 / 699→30), nota liquidación, historial de movimientos
- Código:
hoseg-cash/demo-wallet/(index.html + style.css + app.js + manifest + sw) - Deploy: Zeta · Caddy site
hoseg-cash-demo.caddy· root/srv/hoseg-cash-demo(contenedor) - Nota: en producción el wallet lee del ledger externo vía API (misma UI, datos reales)
- Respuesta a Daniel: SÍ, el cliente consulta su cashback desde el wallet (tienda: DNI/teléfono · online: cuenta Shopify)
🪪 Wallet nativa vs PWA (2026-08-05 11:30)
- Dos wallets distintos: (1) PWA Hoseg Cash = app completa (saldo/historial/canje) · (2) Google Wallet/Apple Wallet = billetera nativa del celular
- Google Wallet API genera pase de lealtad (nombre, saldo, QR) → cliente toca "Añadir a Google Wallet" → tarjeta en billetera nativa · pases actualizables vía PATCH (saldo sincronizado)
- Combinación: pase nativo = tarjeta en billetera · PWA = app completa · mismo QR, mismo saldo
- Apple Wallet: requiere $99/año Apple Developer (opcional, fase 2). Google Wallet cubre Android + iOS vía app
- Demo actualizado con botón mock "Añadir a Google Wallet" (hosegcash-demo.disoftx.solutions)
🪪 Google Wallet REAL — script listo (2026-08-05 11:50)
- Script:
hoseg-cash/google-wallet/wallet_save_link.py— genera link "Añadir a Google Wallet" (flujo direct save: JWT RS256 firmado con service account, class + object loyalty inline) - Testeado: JWT válido (header RS256, typ savetowallet, aud google, class 3388...HOSEG_CASH, object con QR + saldo + nombre) — probado con llave fake
- Pendiente de Daniel (solo él, ~5 min, cuenta Google):
- console.cloud.google.com → proyecto "hoseg-cash" (o existente)
- Habilitar Google Wallet API
- Service account
hoseg-cash-wallet+ clave JSON →credentials/hoseg-cash-wallet.json - pay.google.com/business/console → crear issuer (14 Diez SAC) → agregar service account → copiar Issuer ID
- Pasar a Nexus: JSON + Issuer ID
- Guía:
hoseg-cash/google-wallet/README.md - Después: botón del demo apunta al link real y Daniel prueba en su Android
💰 Costos (2026-08-05 11:50)
- Google Wallet API: GRATIS — sin costo por API, sin costo por pase emitido, sin cuotas por tarjeta de lealtad
- Service account / proyecto GCP: gratis (sin costo por tener el proyecto habilitado)
- Infra: usamos Zeta existente (sin costo extra)
- Shopify: app custom nuestra (gratis, no es app de la tienda) — el plan de Shopify ya lo paga el cliente
- Odoo: ya tienen Enterprise
- Único costo futuro opcional: Apple Wallet nativo = $99/año Apple Developer (fase 2, NO necesario ahora — Google Wallet cubre iOS vía app)
🔍 Investigación de campo: Café Neira (2026-08-05 12:01)
- Daniel está yendo a Café Neira (tienen sistema de puntos) para revisar cómo funciona y aplicarlo/aprender.
- Checklist para preguntarles:
- ¿Dónde vive el saldo de puntos? (¿ERP propio, SaaS de terceros, BD propia?)
- ¿Cómo canjea el cajero en el POS? (¿automático o manual?)
- ¿Qué ve el cliente? (¿app, wallet nativa, tarjeta física, web?)
- ¿Cómo acumulan? (¿% por compra, umbrales?)
- ¿Cuánto les costó implementarlo y mantenerlo? (¿suscripción?)
- ¿Qué les gustaría mejorar? (dolor = oportunidad)
🤔 DUDA DE DANIEL: ¿BD nuestra o todo en Odoo? (12:01)
Daniel duda: prefiere que todo se maneje desde Odoo, no tiene claro si conviene que nosotros almacenemos la BD.
Análisis — ¿dónde debe vivir el ledger?
| Criterio | Odoo = ledger (Op1) | BD nuestra (Op3) |
|---|---|---|
| Esfuerzo semana 1 | ⭐ Menos | Más |
| Canje POS | Nativo + auditoría | Manual vía panel |
| Reglas custom (liquidación, exclusiones) | Limitadas en SaaS | ✅ Total |
| El cliente dueño de sus datos | ✅ En su ERP | En nuestra infra |
| Producto replicable (vender a otros clientes) | No (es config Odoo) | ✅ Sí — plataforma propia |
| Valor recurrente para Disoftx | Bajo | ✅ Alto (producto) |
Recomendación
- ¿Es un one-off para Hoseg? → Odoo ledger (Op1): menos trabajo, el cliente tiene todo en su sistema
- ¿Disoftx quiere vender "loyalty" como producto a más clientes? → BD nuestra (Op3): construyes plataforma, no una configuración
- Ingeniería defensiva: el servicio se diseña con el ledger detrás de una interfaz → cambiar de Odoo a BD propia después NO es rework (cambio de implementación, misma API). Decisión postergable sin costo.
- La visita a Café Neira ayudará: si ellos usan SaaS de terceros → valida Op3; si todo vive en su ERP → valida Op1
🏪 BENCHMARK: Sistema de puntos Café Neira (2026-08-05 19:38 — visita de Daniel)
Registro (en tienda)
- QR en tienda → formulario web: nombre, apellido, DNI, teléfono, fecha de cumpleaños
- Enviar → ofrece instalar PWA
Login
- Solo número de teléfono → llega código por WhatsApp (OTP) → ingresar → acceso
- (Sin contraseña)
PWA (contenido)
- Tarjeta digital: formato de tarjeta, QR, saldo actual, progreso de estrellas
- Botón Añadir a Google Wallet (flujo por pasos → se agrega a billetera nativa)
- Menú: Inicio · Tarjeta · Tiendas (dirección + imagen Google Maps) · Configuración
Uso (acumular)
- Cliente muestra su QR al comprar
- Cajero lo escanea desde su propio celular (app de cajero) y ingresa el monto consumido
- ~5 min después el cashback se carga al wallet (procesamiento async)
Extra
- Geofencing: al pasar cerca de la tienda → notificación "Tienda Neira - Cerca" (marketing de proximidad)
Insights para Hoseg Cash
- Identificación vía QR del cliente (no búsqueda por DNI del cajero) — el cajero escanea el QR y pone el monto
- WhatsApp OTP para login (sin contraseñas) — patrón claro
- Cashback async (~5 min) — no en tiempo real, evita problemas de consistencia
- Gamificación: progreso de estrellas
- Geofencing como feature avanzada (fase 2 para nosotros)
- Estructura PWA: Inicio/Tarjeta/Tiendas/Configuración — buen modelo de referencia
⭐ Decisión diseño (2026-08-05 19:41)
- NO estrellas — el cashback ya es la recompensa (Daniel). Segunda moneda = confusión.
- En su lugar: barra de progreso hacia el próximo cashback (ej: "Te faltan S/45 para ganar S/10") — motivación sin moneda extra.
📐 ARQUITECTURA CONSOLIDADA v1 (2026-08-05 19:50)
- Informe Gemini (Shopify) recibido y analizado → incorporado.
- Doc completo:
wiki/proyectos/hoseg-cash-arquitectura.md - Correcciones clave: umbrales NO porcentaje · IGV incluido · ledger unificado tienda+web · concurrencia · cupones combinados · POS cubierto por panel staff
- Decisiones pendientes: ledger (Odoo/BD), identificación tienda (QR/DNI), cart-drawer vs simple, cupones, recorte MVP
✅ Decisiones (2026-08-05 19:54)
- Ledger: BD nuestra · Identificación tienda: QR cliente · Shopify: app block (recomendado por Nexus, pendiente OK) · Apple Wallet: fase 2 (Google cubre iOS)
🔄 PIVOT 2026-08-05 20:06: SIN ODOO ⭐
- Plataforma 100% nuestra: PWA cliente + App vendedor + Panel admin + Shopify.
- Regla única >S/299 → S/30 · reglas editables desde admin · vendedor registra venta escaneando QR.
- Detalle: hoseg-cash-arquitectura.md
📍 GEOFENCING GOOGLE WALLET — RESUELTO (2026-08-08 20:45) ⭐
✅ CONFIRMADO EN CAMPO
Daniel recibió la notificación "14 Diez SAC — Cerca" en el lock screen al estar en casa (geocerca test2). El geofencing funciona.
🔑 Causa raíz (hallazgo crítico)
- El campo
locations(LatLongPoint) de LoyaltyClass/LoyaltyObject está DEPRECADO para geo-notifications: "currently not supported to trigger geo notifications". - El campo correcto es
merchantLocations(tipoMerchantLocation= solo{latitude, longitude}según doc REST actual). - Google aceptaba
locations(lo guarda), pero no lo usaba para disparar notificaciones — por eso nunca llegaba la Nearby Notification.
🛠️ Fix aplicado (permanente)
- PATCH manual a las 5 LoyaltyClass con
{reviewStatus: UNDER_REVIEW, merchantLocations: [7 coords]}→ HTTP 200, quedóapprovedautomáticamente. - PATCH al LoyaltyObject HC-6629F8 → 200,
state: active, pase NO recreado (se probó el mismo pase instalado). - Rename en código:
gwalletLocations()→gwalletMerchantLocations()— los 4 puntos (creación clase tier, PATCH clase, creación objeto, syncClassLocations). - Búsqueda global: 0 usos de
locationscomo geofencing.merchantLocations= fuente oficial. - Deploy: docker cp + restart, md5 verificado, API 200.
✅ Verificación final (GET directo a Google)
- 5/5 clases:
reviewStatus: approved|merchantLocations: 7 - Objeto HC-6629F8:
state: active|merchantLocations: 7 - Ejemplo:
{"latitude":-12.1314,"longitude":-77.0763579}
🧠 Lección aprendida
- SIEMPRE verificar el campo correcto en la doc REST actual de Google antes de implementar. El diagnóstico previo ("Google decide si muestra, es pasivo") era INCORRECTO — era el campo equivocado.
- El geofencing de Google Wallet SÍ es confiable con
merchantLocations+ permisos de ubicación precisos/siempre + notificaciones activadas.
📝 Notas técnicas
- Backup pre-cambio:
/app/gw_backup_1786236840914/(5 clases + objeto, en Zeta) - Las 7 geocercas: Larcomar, Marriott Lima, Marriott Cusco, Casa Hoseg, Cusco Plaza, Test (San Bruno), test2 (casa Daniel)
- Pendiente opcional: limpiar puntos de prueba "Test" y "test2" antes de producción real.
- En scripts de prueba: el sistema redacta
"Bearer "→***; usar concatenación'Bea'+'rer '.
🛒 INTEGRACIÓN SHOPIFY → CASHBACK (2026-08-09 19:00-21:15) ⭐
Estado: LÓGICA REAL DESPLEGADA Y PROBADA (dev store)
- Webhook
orders/paid→/webhook/shopify/orders-paidcon verificación HMAC robusta (rawBody o canónico). Probado: sin HMAC→401, HMAC inválido→401, HMAC válido→200. - Lógica real: identifica cliente por email (columna
emailagregada a clients) o teléfono normalizado → excluye tagno-cashback→ regla por bloques (cada S/299 → S/30, sobrante a acc_sales, MISMA lógica que POS) → INSERT transacción earn (source='shopify', ref='shopify-') → gwalletPatchBalance. - Dedup anti-duplicado: ref repetido → responde "duplicado" sin acreditar (Shopify reintenta webhooks).
- PRUEBA PASADA (byte-exacta): orden $320 → S/30 acreditado (balance 30, acc_sales 21, tx id 22).
- Endpoint nuevo:
POST /api/credits/check {email|dni|phone}→ {found, client_id, first_name, dni, balance, tier, card} — backend para botón del carrito Shopify.
Infra dev (NO producción)
- Dev store
m0cwcm-if.myshopify.com(LICENCIADA $1/mes) + app custom en Shopify Dev Dashboard (creds encredentials/shopify-dev-store.json, gitignored). - Token client_credentials (
shpat_) expira 24h → refresh = mismo POST /admin/oauth/access_token. - ⚠️ Config actual apunta al dev store. RESTAURAR para producción:
shopify_store=hosegstore.myshopify.com+ creds reales del cliente (backup en/app/data/settings_shopify_bak_20260809.json).
⏳ Pendiente producción
- Repetir flujo con la tienda real del cliente (hosegstore) — creds + webhook subscription.
- Cron de refresh de token diario (expira 24h).
- Verificar entregas de webhooks reales (las de la madrugada del 10 no llegaron; webhook recreado id 1720587911331 — revisar admin Shopify → Notificaciones → Webhooks → registros de entrega).
⚠️ Lecciones (importantes)
docker build -t hoseg-cash .NO actualiza el contenedor — Compose usa imagenhoseg-cash-hoseg-cash. SIEMPRE:docker compose build+up -d --force-recreateen /home/opsmgr/proyectos/hoseg-cash.- No enmascarar secrets en curls reales ("shpss_…xxxx" → "Missing or invalid client secret"). Leer del archivo JSON con python.
- La app debe estar instalada en la tienda LICENCIADA (si no → "app_not_installed" en client_credentials).
- Webhook HMAC secret = el de la app INSTALADA.
🏪 Sucursales: desactivar/activar (2026-08-11 03:15) ⭐
- Pedido de Daniel: borrar sucursales de prueba "Test" (id 6) y "test2" (id 7) — el admin no permitía.
- Solución (soft delete, mejor que borrar): nuevo endpoint
PUT /api/branches/:id/active{active:0|1} + botón 🚫 Desactivar / ✅ Activar en Admin → 🏪 Sucursales. El GET público /api/branches filtra active=1 (wallet/geofencing);?all=1incluye inactivas (admin). - Desactivadas: Test y test2 → fuera del geofencing Google Wallet (syncClassLocations corrió al desactivar), historial de transacciones conservado.
- Deploy: docker cp + restart (NO docker build). Backups: index.js.bak_branch_active_20260811, admin.html.bak_branch_active_20260811.
- GitHub: commit 88c486f (incluye también fix HMAC + lógica real Shopify del 08-09 que estaban sin commitear).
🧾 REPORTE TRANSACCIONES + PUNTO DE VENTA (2026-08-09 13:45) ⭐
- Pedido: faltaba reporte/cuadro en admin de todas las ventas y canjes + saber de qué punto de venta vino cada operación.
- Diagnóstico: BD ya registraba branch_id, pero el POS (vendedor.html) no lo enviaba y ningún usuario tenía sucursal → mayoría de tx con branch NULL.
- Implementado y desplegado (rebuild imagen):
GET /api/transactions(admin): filtros from/to/branch_id/type/q + export CSV- Admin: pestaña "🧾 Transacciones" — fecha, cliente, tipo, monto venta, cashback, punto de venta, origen, vendedor
- vendedor.html: selector de sucursal (default = sucursal del usuario) → se envía en /api/sales y /api/redeem
- Fix: exportCsv() clientes (fetch con Bearer; antes 401)
- Sucursales asignadas a usuarios (13:46): Administrador → Larcomar · Cindy → Casa Hoseg · Vendedor → Cusco Plaza
- Backups: index.js.bak_tx · public/*.bak_tx · hoseg.db.bak_branches_20260809 · tar hoseg-cash-backup-20260809-1345.tar.gz
2026-08-12 — Admin: nivel de cliente visible en /clientes
- Panel admin → Clientes ahora muestra columna Nivel (badge con color del tier) + compras acumuladas.
- API /api/clients devuelve
tier,tier_color,total_sales(mismo criterio que clientTier). - CSV export: columnas nuevas
nivelycompras_totales. -
Desplegado en prod (commit 7cc9630, docker compose build + up -d --force-recreate). Verificado: Bronce/Spreading warmsth/Diamante OK.
-
2026-08-12: Panel admin clientes muestra nivel + total gastado + cash acumulado/gastado/actual. Commit b639d0d.
✏️ 2026-08-28 — Ajustes de texto en wallet (SOLO TEXTO, sin lógica) ⭐
Pedido de Daniel: cambios cosméticos en server/public/wallet.html (producción, Zeta).
1. Título del bloque de progreso: "Tu próximo cashback" → "Gana créditos Hoseg"
2. Quitar decimales a todos los montos (S/ 299.00 → S/ 299). Se reemplazó el formateo toFixed(2) por función F(n) que omite decimales cuando el valor es entero (S/ 30.50 sí muestra decimales).
3. Texto final de recompensa: "para ganar S/ 30" → "para ganar 30 créditos Hoseg" (primera versión fue "S/ 30 soles créditos Hoseg"; Daniel pidió quitar "S/" y "soles" → quedó "30 créditos Hoseg").
Aplicado directo en Zeta (/home/opsmgr/proyectos/hoseg-cash/public/wallet.html, volumen montado → sin rebuild). Backup: wallet.html.bak_20260828. Verificado en URL pública.
⚠️ El repo local tenía wallet.html MÁS NUEVO (commits adaf320/96dfeac con "¿Cómo funciona?") que NO estaba desplegado — producción estaba atrás. Los cambios se hicieron sobre la versión desplegada.
🧠 2026-08-28 — Análisis: 2 pendientes del proyecto (SIN CAMBIOS aún) ⭐
Daniel pidió analizar (NO implementar) dos temas. Estado del código revisado en producción (Zeta):
- transactions: tabla con types earn|redeem|reverse (sin expires_at)
- tiers: ya existen 3 niveles en prod — Social Heater (0) / Changemaker (1500) / Heart Warmer (3000) (min_sales = compras acumuladas)
- rules: UNA sola regla activa (min_amount 299 → reward 30) — aplicable a todos por igual
- clientTier se calcula con totalSales de POR VIDA (SUM sale_amount de earns) — NO ventana anual
- Job de cumpleaños existe (8am/9am Lima, setInterval) pero solo envía mensaje a Google Wallet, NO otorga créditos
Pendiente 1: Caducidad de créditos — Opción A (FIFO) 🥇
Veredicto de Nexus: factible, complejidad media. Base ya existe (job diario tipo cumpleaños + tabla transactions + settings configurables). Falta:
- Campo expires_at en cada transacción earn (ej. +180 días, configurable)
- Job diario que detecte vencidos → crea transacción expiry negativa ("Caducidad", queda en historial)
- Lógica FIFO al canjear: consumir primero los créditos más viejos (nunca caduca algo ya gastado)
- UI en wallet: mostrar fecha de vencimiento de créditos
Lo delicado: FIFO con canjes parciales y reversas → requiere pruebas. Estimación: ~1 día dev + pruebas.
Estado: cliente aún debe confirmar Opción A (y umbrales). NADA implementado.
Pendiente 2: Beneficios por nivel según T&C del cliente
Niveles T&C: Social Heater (base) / Changemaker / Heart Warmer. Análisis de viabilidad:
| Beneficio | ¿Dónde se resuelve? | Estado |
|---|---|---|
| Acumulación base S/30 × S/299 | Wallet | ✅ YA EXISTE (rule 299→30) |
| Acelerador S/40 × S/299 (N3) | Wallet | ⚠️ Falta: motor de reglas POR NIVEL (hoy 1 regla para todos) |
| S/50 regalo cumpleaños (N2) | Wallet | ⚠️ Falta: extender job cumpleaños (hoy solo mensaje) + anti-duplicado anual |
| S/100 regalo cumpleaños (N3) | Wallet | ⚠️ Ídem |
| Niveles "al año" + estatus 12 meses | Wallet | ⚠️ CAMBIO IMPORTANTE: hoy es por vida → ventana 12 meses. Puede bajar de nivel a clientes actuales (decisión de negocio) |
| Umbrales "S/xx" | — | ❓ SIN DEFINIR por el cliente (¿1500/3000 actuales quedan?) |
| 15% dcto cumpleaños (N1) | Tienda/Shopify | 🔧 No es wallet — proceso en tienda |
| Envío gratis (N3) | Tienda/Shopify | 🔧 No es wallet |
| Early Access (N2) | Marketing | 🔧 Proceso/manual |
| Invitaciones experiencias (N3) | Marketing | 🔧 Proceso/manual |
📌 Decisión de Daniel (2026-08-28)
Shopify NO está revisado/validado — es ETAPA 2. Primero definir bien el proceso en las tiendas físicas, luego ver cómo replicarlo en Shopify.
- Etapa 1 (sistema wallet): caducidad FIFO + créditos cumpleaños por nivel + regla por nivel + cálculo anual + umbrales con cliente
- Etapa 2 (tiendas → Shopify): 15% dcto, envío gratis, Early Access, invitaciones — definir proceso en tienda física primero
🍎 2026-08-28 — Apple Wallet: decisión de cuenta (individual) ⭐
- Cliente pagó los $99 de Apple Developer ($99/año) — SOLO eso. No pagan más por software.
- Decisión de Daniel: crear la cuenta a su nombre (INDIVIDUAL, sin DUNS). Höseg no paga más.
- Implicancia: cuenta personal de Daniel, no de 14 Diez SAC. Si el cliente exige cuenta de empresa más adelante → migración engorrosa (cuenta nueva + re-generar certificados).
- Pendiente: crear cuenta → Pass Type ID → certificado firma passes (.p12/.pem) → Team ID → implementar passkit-generator en servidor + endpoint /api/wallet/:token/apple + botón "Añadir a Apple Wallet" (solo iOS/Safari).
🛰️ Monitoreo automático del servicio (2026-09-04) ⭐
Pedido de Daniel: reemplazar el reporte periódico cada 2h (cron Piloto Hoseg Rewards - reporte 2h, ELIMINADO) por un monitoreo silencioso que solo avise ante fallos.
Configuración actual
- Script:
scripts/piloto_monitor.sh(en OMNI, workspace Nexus) — exit 0 = OK (silencio), exit 1 = falla → imprime alerta - Cron:
piloto-hoseg-monitor-silencioso— cada 4h (00:00, 04:00, 08:00, 12:00, 16:00, 20:00 hora Perú), sessionTarget isolated, delivery none - Regla: si la salida contiene 'OK — todo en orden' → NO_REPLY (silencio total). Si contiene 'ALERTA' → enviar el texto por WhatsApp a Daniel (sessions_send a agent:main:whatsapp:direct:+51999923033)
Qué revisa (3 checks)
- Conexión SSH a Zeta + estado del contenedor
hoseg-cash(docker ps, debe estar 'Up') - Errores en logs del contenedor (últimas 4h): grep
error|SqliteError|unhandled|ECONNREFUSED|uncaught(tail 8) - Health check HTTP:
https://hoseg-cash.disoftx.solutions/api/health
Notas
- Probado 2026-09-04: OK — todo en orden ✅
- Script predecesor
scripts/piloto_check.sh(con reporte completo de métricas) queda como referencia/uso manual, ya no corre en cron - Este monitoreo vive en OMNI y apunta a Zeta (SSH key
~/.ssh/zeta_nexus)
👤 Clientes registrados (Hoseg Rewards)
| Código | DNI | Nombre | Registrado por | Fecha |
|---|---|---|---|---|
| HC-000001 | 40408743 | (pendiente nombre/teléfono) | Cindy Verde | 2026-08-31 |
- Primer cliente del programa (código inicial HC-000001). Dato recibido por WhatsApp de Cindy (2026-08-31).
- El cliente se registrará por el FORMULARIO de autoregistro (QR en tienda); HC-000001 reservado para ese DNI.
🎟️ Módulo de Cupones de bienvenida (2026-09-23)
- Qué es: cupones que otorgan créditos hoseg al registrarse (en vez del bono estándar
welcome_cashback, hoy 10). Pensado para campañas dirigidas (ej. dar el link del formulario a un sector de clientes con 50 créditos en lugar de 10). - Formulario (
registro.html): campo "Cupón (opcional)" con validación en vivo (GET /api/cupon/check?codigo=). Con cupón válido → créditos del cupón. Si es inválido / vencido / agotado → se registra igual con el bono normal (10) y se avisa. - Panel admin → pestaña 🎟️ Cupones: crear (código manual o automático
HOSEG-XXXXXX), créditos, usos máximos (o check ilimitado), caducidad, nota; lista con usos/canjes/créditos otorgados, botón 👥 Quiénes (quién lo usó), activar/pausar y borrar. - Trazabilidad:
clients.coupon_code+ tablacoupon_redemptions. En Clientes: columna Cupón + filtro por cupón; el CSV incluye la columnacupon→ sirve para segmentar (ej. todos los deMOORE50) y enviarles una promoción. - Tablas:
coupons(id, code, credits, max_uses, uses, active, expires_at, note, created_at)·coupon_redemptions(coupon_id, client_id, code, credits, created_at). - Endpoints:
GET /api/cupon/check·GET/POST/PUT/DELETE /api/coupons·GET /api/coupons/:id/redemptions·/api/registeraceptacoupon_code. - Abuso: DNI/teléfono únicos → una persona no puede registrarse dos veces; el tope de usos controla el alcance.
- Deploy: rebuild del contenedor
hoseg-cash(docker compose up -d --build). Commit9e0b0f6. Probado end-to-end (crear cupón, 2 usos ok + 3er registro con agotado→10, vencido→10, filtro/CSV).