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
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.
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:
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:
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:
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/tenantspara 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.





