Levantamiento · Discovery
Un bar configura 7 visitas → un trago gratis. El mesero escanea el QR de la wallet del cliente en cada visita y la tarjeta se actualiza sola en su teléfono. Sin app que instalar, de ninguno de los dos lados del mesón.
Este documento existe para alinear al equipo antes de escribir código. No hay nada construido. Lo que sí hay es un hallazgo que cambia el precio, el onboarding y la operación al mismo tiempo — y conviene discutirlo ahora y no después del primer cliente.
Parecen dos implementaciones de la misma idea. Para una plataforma que le vende a muchos negocios, son estructuralmente distintos, y la diferencia es contractual antes que técnica.
Google — lo permite explícitamente
“An Issuer ID might represent a platform that stores pass classes for many different merchants, also referred to as an Aggregator.”
Apple — apunta al lado contrario
Los passes deben ser “under your own trademark or brand”, y quien tiene el certificado acepta “not to use your Pass Type ID to sign a third party's pass”.
Leído en su sentido llano: Google permite que Stratos sea el emisor de todos los clientes bajo una sola cuenta. Apple, no. Cada negocio necesitaría su propia cuenta de Apple Developer y su propio certificado, con Stratos operando como su Service Provider.
Eso no se resuelve con ingeniería. Define cuánto cuesta cada cliente, cuánto demora en estar operativo, y qué secretos tenemos que custodiar. Es la decisión ADR-001, está abierta, y es una decisión de negocio: la investigación ya está hecha.
| Apple Wallet | Google Wallet | |
|---|---|---|
| Qué es un pase | un bundle .pkpass firmado que el cliente posee |
una LoyaltyClass + un LoyaltyObject que Google guarda |
| Modelo multi-comercio | no soportado como plataforma — un certificado por negocio | soportado y documentado — un Issuer ID para todos |
| Actualizar una tarjeta | push por APNs → el dispositivo llama de vuelta → re-firmamos el pase completo | PATCH al objeto; Google propaga |
| Infra que debemos operar | registro de dispositivos, cliente APNs, firma de pases, 5 endpoints públicos | un cliente de API |
| Riesgo operacional | certificados que expiran cada año, por cliente, y fallan en silencio | sin equivalente |
Todo el producto es un ciclo corto: el mesero escanea, el servidor decide, la tarjeta se re-dibuja. Lo importante es dónde vive la verdad y quién espera a quién.
La wallet es una vista, nunca el registro. El QR de la tarjeta lleva solo un identificador opaco — ni contador, ni saldo, nada que al cliente le convenga editar. Cada regla se responde en el servidor.
Si una regla necesita un deploy, está en el lugar equivocado. Todo lo siguiente es data, no código:
Una expectativa que hay que fijar temprano con el equipo y con los clientes: las dos wallets no se van a ver iguales. Apple permite una imagen libre detrás de los campos, así que el clásico “7 círculos, 3 marcados” se puede dibujar literal. La plantilla de Google es más rígida. Decidir la presentación en Google a propósito, y no descubrirla a mitad de implementación.
La amenaza real es un cliente habitual que quiere su trago y un mesero que aprecia a sus amigos. El diseño responde a eso, no a un atacante sofisticado.
| Riesgo | Respuesta |
|---|---|
| Varios stamps en una misma sentada | cooldown por tarjeta, configurable por cliente |
| Doble escaneo o red intermitente | clave de idempotencia en cada request |
| Screenshot de la tarjeta de otro | irrelevante por diseño — el QR solo identifica una tarjeta, y el stamp beneficia a su dueño |
| Mesero regalando stamps | no se impide en el protocolo: se hace visible. Cada stamp lleva mesero, local y hora |
| Referidos inflados con registros falsos | el referido tiene que juntar stamps reales para calificar |
| Cliente edita el pase | irrelevante — el servidor nunca lee estado desde la tarjeta |
El camino crítico no empieza con código. Empieza con trámites ante Apple y Google que dependen de terceros y no se aceleran poniendo más gente.
Inscripción en Apple, onboarding de emisor en Google.
empieza yaUn cliente hardcodeado: emitir, escanear, marcar, ver ambas wallets actualizarse.
Programas y marca como data, consola de administración, custodia de certificados.
la fase más grandeCódigos, calificación por stamps, topes.
Sucursales, niveles, analítica, pantalla de bloqueo.
Son unos formularios. Puede dejar al equipo detenido semanas si parte tarde, y nada de eso se acelera con más personas. Corre en paralelo con el diseño de la Fase 1.
Es un demo: rápido, vistoso, y hace parecer que queda poco. Pasar de “funciona para un bar” a “cualquier bar lo configura solo” es la mayoría del trabajo. Ojo con cotizar después de un demo exitoso.
Ninguna de estas cifras viene de una cotización. La línea de Apple es toda la historia comercial.
| Ítem | Quién paga | Monto |
|---|---|---|
| Apple Developer Program | por cliente, si ADR-001 cae en la opción (a) | ≈ US$99 / año |
| Google Wallet API | Stratos, una vez | sin costo por pase |
| Infraestructura | Stratos | absorbida por el VPS actual a escala piloto |
| Renovación de certificados | Stratos, anual y por cliente | tiempo de operación, no dinero |
Bajo la opción (a), cada cliente arrastra un costo de terceros y un trámite antes de que exista su primera tarjeta. Eso no es una línea del presupuesto: es una propiedad del embudo de ventas. Un prospecto que no va a crear una cuenta de Apple Developer no es cliente, y eso conviene descubrirlo en la primera llamada y no después de diseñarle la marca.
Hay algo que sí hay que hacer desde el primer commit: medir. Tarjetas activas, stamps, canjes, sucursales, y pases por plataforma. Cualquier modelo de precios va a necesitar historia, y la historia no se rellena hacia atrás.
(a) cada cliente con su cuenta y Stratos como Service Provider —
la lectura que cumple. (b) un Pass Type ID de Stratos para todos —
más simple, aparentemente contra los términos, y si Apple revoca el certificado
caen todos los clientes a la vez. (c) preguntarle a Apple
por un acuerdo de plataforma.
Recomendación: construir sobre (a) y abrir (c) en
paralelo. Y tratar la identidad de firma como propiedad por cliente desde la
primera línea de código, para que moverse a (b) sea configuración y no reescritura.
Degrada una falla de push de error de datos a problema estético. Es la razón de que el stamp sea síncrono y el render asíncrono.
La alternativa (el cliente escanea un código rotativo del local) es más fuerte contra colusión del mesero y le agrega un paso al cliente justo cuando lo están atendiendo. Se reabre si un cliente reporta inflación de stamps.
Premiar la creación de cuentas premia nada: una tarde y cinco correos compran el premio. El premio llega más tarde que la invitación, y eso hay que explicarlo en la tarjeta o se lee como roto.
Corre en el teléfono que el mesero ya tiene, sin instalación, y sobrevive a la rotación de personal. Se revisa si escanear falla en Android de gama baja con la luz real de un local — eso se prueba en la Fase 1.
Falla en silencio: las tarjetas simplemente dejan de actualizarse y el primer reporte llega de un cliente molesto semanas después. Alertas a 60 y 30 días. Es el incidente de producción más probable de este producto.
Todo esto vive en el vault stratos, en
projects/wallet-loyalty/. Si este documento y el vault se contradicen,
manda el vault.