Cómo emitir wallet passes personalizados por API

Una API de wallet passes le permite a tu backend crear un pase para cada cliente, con su propio nombre, saldo, código de barras y ubicaciones, y actualizarlo cada vez que cambian tus datos. Diseñas una plantilla una sola vez, envías los valores personales de cada usuario y recibes un link de instalación para Apple Wallet o un link de guardado (save link) para Google Wallet.

No todos los equipos la necesitan. Los ejemplos usan la API de Wallet passes de Pushwoosh, donde cada pase está ligado a un User ID que también mueve tus push, emails y journeys.

En LATAM, con alrededor del 85% de los usuarios en Android, el flujo de Google Wallet suele ser el que más volumen mueve, así que vale la pena integrarlo desde el día 1 y no como un agregado posterior. Las referencias de la API están en inglés, igual que los nombres de métodos y campos que verás abajo.

Cuándo la API le gana al constructor

El constructor es la herramienta correcta para diseñar un pase y para envíos pequeños o únicos. La API toma el control cuando los pases dependen de datos que viven en tus propios sistemas, como el core de una app FinTech o el catálogo de un e-commerce.

Revisa la columna del journey antes de escribir código. Si el disparador es una acción del cliente que Pushwoosh ya registra, el paso Issue Wallet Pass (emitir wallet pass) en Customer Journey muchas veces hace innecesario el código a medida.

Plantillas y valores personales

El patrón es el mismo en las 2 plataformas. Una plantilla contiene el diseño, la marca y la estructura de campos. Los valores de cada usuario la completan al momento de emitirla.

Los valores personales son lo que cambia de 1 cliente a otro: nombre, número de socio, puntos, nivel, valor del código de barras, vencimiento, tienda más cercana. Todo lo demás sale de la plantilla, así que un cambio de diseño se aplica a cada pase nuevo sin tocar tu integración. Si preparas una tarjeta especial para el Buen Fin o el Hot Sale, cambias la plantilla y no el código.

En un journey, el paso Issue Wallet Pass toma las campañas de pases de Apple y Google (apple_campaign_id, google_campaign_id) y los personal_values que hay que completar. 1 solo paso puede emitir las 2 versiones para el mismo User ID.

El flujo de Apple Wallet

Todo lo que hace el constructor de pases de Apple también está disponible en la Apple Wallet PassKit API: crear, actualizar, listar, descargar y borrar pases.

Una integración típica tiene 4 pasos.

Necesitas un certificado Pass Type ID (.p12) por aplicación y una cuenta de Apple Developer (US$99 al año). La configuración está en la documentación de configuración de wallet passes para iOS.

El flujo de Google Wallet

La Google Wallet API cubre el mismo ciclo de vida para los pases de Google.

Necesitas un Issuer ID de la Google Pay & Wallet Console, con la cuenta de servicio de Pushwoosh invitada a tu emisor, configurado una vez por aplicación. La configuración está en la documentación de configuración de Google Wallet.

Actualizar a escala

Las actualizaciones son donde la API se gana su lugar. Un registro de puntos o un sistema de reservas puede actualizar un pase en el momento en que cambia un valor, así que la tarjeta en el wallet del cliente coincide con tu fuente de verdad. En una app FinTech, eso puede ser el cashback acumulado; en un e-commerce, los puntos de la última compra.

3 reglas mantienen seguras las actualizaciones masivas:

• Parte del pase actual. La actualización de Apple recibe el objeto completo del pase, así que descarga el pase y cambia solo los valores que se movieron. La actualización de Google modifica parcialmente el objeto (patch).
• Decide las alertas campo por campo. En Apple, solo los campos con mensaje de cambio muestran una alerta en la pantalla de bloqueo. En Google, notifyOnUpdate le pide a Google su propia alerta, que solo se activa en tarjetas de lealtad, boletos de eventos y pases de abordar, con un máximo de 3 por pase en 24 horas. notifyMessage envía tu propio texto de notificación en Android en cualquier tipo de pase.
• Que las alertas hablen del pase. Apple y Google permiten notificaciones sobre el pase, no promociones.

Ejemplos de código

Las 2 APIs usan la URL base https://apple-passkit.svc-nue.pushwoosh.com y tu token de acceso a la API de Pushwoosh en un header Authorization: Token <api-token>. Los cuerpos de las solicitudes de abajo son los ejemplos de la referencia de la API.

Crear un pase de Apple Wallet: POST /api/pass/create. La respuesta devuelve el serialNumber del pase.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

Crear un pase de Google Wallet: POST /api/google/pass/create. La respuesta devuelve el serialNumber y un saveLink.

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

Para actualizar, envía el contenido nuevo con el número de serie: POST /api/pass/update/{serialNumber} para Apple, POST /api/google/pass/update/{serialNumber} para Google.

Constructor, API o journey: una regla rápida

Usa el constructor para diseñar y probar. Usa el paso del journey cuando el disparador es un evento del cliente que ya está en Pushwoosh, como un registro o una primera compra. Usa la API cuando el disparador o los datos viven en tu backend.

La mayoría de los equipos termina usando los 3, y está bien: el constructor para el diseño, los journeys para los momentos del ciclo de vida, la API para saldos y estados en tiempo real. El error es obligar a 1 de ellos a hacer el trabajo de los otros.

Personaliza cada pase a escala con Pushwoosh

Pushwoosh te da un constructor visual, un paso de journey y una API para pases nativos de Apple y Google Wallet, sin un proveedor de pases aparte en medio. Cada pase comparte un User ID con tus push, mensajes in-app, emails y SMS, así que 1 solo conjunto de datos mueve todos los canales.

Personalizar a escala no es cuestión de tener más plantillas. Es tener 1 fuente de verdad que se refleje en cada tarjeta de cada wallet.

FAQ