Skip to content
Volver al blog

Guía de integración API de pases Wallet: arquitectura de extremo a extremo

Guía técnica completa para integrar la generación de pases de Apple Wallet y Google Wallet, webhooks y actualizaciones push en su backend SaaS o empresarial.

Passinstance Team
Passinstance Team

Wallet pass platform team

2026-02-012 min de lectura
Imagen de portada para Guía de integración API de pases Wallet: arquitectura de extremo a extremo

Integrar pases de billetera móvil en la arquitectura de su producto permite automatizar la emisión, activar notificaciones de actualización admitidas por cada plataforma y gestionar el ciclo de vida de cada tarjeta directamente desde su backend, CRM o TPV.

Esta guía ofrece una visión técnica completa para integrar las API REST de Passinstance, los SDK oficiales, la autenticación, la idempotencia y el procesamiento de eventos mediante webhooks.


1. Arquitectura del sistema y flujo de datos de alto nivel

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
FLUJO DE ARQUITECTURA
ETAPA 01 Su aplicación / Backend
ETAPA 02 Motor API Passinstance
Compila archivo .pkpass firmado con PKCS#7 para Apple Wallet
Genera enlace JWT firmado para guardar en Google Wallet
ETAPA 03 Dispositivo del cliente (iOS / Android)
ETAPA 04 Pasarela de Webhooks Passinstance
4. POST/webhooks/pass-installedSu backend

2. Autenticación y credenciales de entorno

Passinstance admite autenticación mediante clave de API (X-API-Key) para integraciones servidor a servidor (junto con tokens de sesión JWT cuando corresponde) sobre HTTPS/TLS. Las claves se generan en el panel con ámbitos de entorno separados:

  • pi_test_... — Entorno sandbox para probar diseños de plantillas, emitir pases de prueba y validar webhooks.
  • pi_live_... — Entorno de producción para emitir pases reales firmados en Apple Wallet y Google Wallet.
BASH
curl -X GET https://api.passinstance.com/api/v1/templates \
  -H "X-API-Key: pi_live_99481203948123"

3. Creación y emisión programática de pases

Utilice el SDK oficial @passinstance/sdk (Node.js / TypeScript) o peticiones HTTP REST directas para emitir pases desde su backend:

TS
import { Passinstance } from "@passinstance/sdk";

const client = new Passinstance({
  apiKey: process.env.PASSINSTANCE_API_KEY!,
});

export async function handleCustomerSignup(user: { id: string; email: string; name: string }) {
  const pass = await client.passes.create({
    templateId: "tpl_membership_gold",
    externalId: user.id, // Idempotencia y referencia cruzada con su base de datos
    data: {
      memberName: user.name,
      memberId: `MEM-${user.id.slice(0, 8)}`,
      joinDate: new Date().toISOString().split("T")[0],
      status: "Active",
    },
  });

  return {
    appleUrl: pass.appleWalletUrl,
    googleUrl: pass.googleWalletUrl,
    qrCodeImageUrl: pass.qrCodeUrl,
  };
}

4. Envío de actualizaciones en tiempo real a pantalla de bloqueo

Para actualizar datos de un pase (por ejemplo, incremento de saldo de puntos, ascenso de categoría o cambio de puerta en un evento), envíe una petición de actualización:

TS
await client.passes.update("pass_9842011", {
  data: {
    pointsBalance: 2500,
    tier: "Platinum",
  },
  pushNotification: {
    message: "¡Enhorabuena! Has ascendido al nivel Platinum 🎉",
  },
});

Esta única llamada a la API dispara de forma simultánea tanto las actualizaciones push APNs en pantalla de bloqueo para Apple Wallet como las actualizaciones de estado mediante la API de Google Wallet para Android.


5. Escucha de eventos mediante webhooks

Passinstance entrega webhooks en tiempo real para los eventos clave del ciclo de vida del pase, manteniendo su base de datos sincronizada sin sondeos periódicos.

Tipos de evento admitidos:

  • pass.created — El paquete del pase ha sido compilado.
  • pass.installed — El usuario añadió el pase a Apple Wallet o Google Wallet.
  • pass.updated — Los campos del pase fueron actualizados.
  • pass.scanned — La aplicación escáner validó el código del pase en caja o acceso.
  • pass.removed — El usuario eliminó el pase de la billetera de su dispositivo.

Verificación de firmas de webhooks:

TS
import { verifyWebhookSignature } from "@passinstance/sdk/crypto";

export async function handleWebhookRequest(req: Request) {
  const signature = req.headers.get("x-passinstance-signature")!;
  const payload = await req.text();

  const isValid = verifyWebhookSignature({
    payload,
    signature,
    secret: process.env.PASSINSTANCE_WEBHOOK_SECRET!,
  });

  if (!isValid) {
    return new Response("Firma no válida", { status: 401 });
  }

  const event = JSON.parse(payload);
  if (event.type === "pass.installed") {
    console.log(`Pase ${event.data.passId} instalado en ${event.data.platform}`);
  }

  return new Response("OK", { status: 200 });
}

6. Arquitectura multiinquilino empresarial y dominios propios

Para plataformas SaaS que integran la emisión de pases dentro de su propio software:

  • Utilice /v1/admin/tenants para aprovisionar suborganizaciones mediante programación.
  • Configure registros CNAME de dominio personalizado (p. ej., wallet.su-saas.com) para las URL de distribución.
  • Segmente webhooks y credenciales de API de forma aislada por cada espacio de trabajo cliente.
Demo interactiva en vivo
Apple Wallet y Google Wallet

Pruebe un pase real de Wallet en su teléfono

Compruebe cómo funcionan los pases digitales. Escanee con la cámara de su teléfono o pulse abajo para añadirlo directamente a Apple Wallet o Google Wallet.

Artisan RoastersCafé & F&B
Test QR code for Artisan Roasters

Escanear con la cámara del móvil

Relacionado en este tema

API para desarrolladores e integraciones

Abrir centro de temas

¿Listo para lanzar su programa de tarjetas de billetera?

Cree su cuenta, diseñe su plantilla de tarjeta y pruebe tarjetas reales directamente en Apple Wallet y Google Wallet.