Integrare i pass Wallet nella propria architettura applicativa consente di automatizzare l'emissione, inviare aggiornamenti supportati dalle piattaforme Wallet e gestire programmaticamente l'intero ciclo di vita delle tessere da backend, CRM o POS.
Questa guida offre una panoramica tecnica completa per integrare le API REST di Passinstance, l'SDK TypeScript, l'autenticazione, l'idempotenza e la verifica dei webhook.
1. Architettura di sistema e flusso dei dati
2. Autenticazione e credenziali per ambiente
Passinstance supporta l'autenticazione tramite chiave API (X-API-Key) per le richieste server-to-server (oltre ai token JWT di sessione per console utente) su connessione HTTPS/TLS. Le chiavi API vengono generate in dashboard con ambito separato per ambiente:
-
pi_test_...— Ambiente sandbox per collaudare modelli, pass di test e webhook. -
pi_live_...— Ambiente di produzione per emettere pass Apple Wallet e Google Wallet firmati dal vivo.
curl -X GET https://api.passinstance.com/api/v1/templates \
-H "X-API-Key: pi_live_99481203948123"
3. Creazione ed emissione programmatica dei pass
Utilizza il pacchetto ufficiale @passinstance/sdk (Node.js / TypeScript) oppure chiamate HTTP REST dirette dal 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, // Idempotenza e riferimento incrociato su database
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. Invio di aggiornamenti sui pass su schermata di blocco
Per aggiornare i dati di un pass (ad esempio incremento punti, promozione di livello o cambio varco evento), invia una richiesta di aggiornamento:
await client.passes.update("pass_9842011", {
data: {
pointsBalance: 2500,
tier: "Platinum",
},
pushNotification: {
message: "Complimenti! Sei passato al livello Platino",
},
});
Questa singola chiamata attiva contemporaneamente gli aggiornamenti push APNs per Apple Wallet e gli aggiornamenti di stato tramite API REST Google Wallet per Android.
5. Ascolto degli eventi webhook
Passinstance invia webhook per gli eventi principali del ciclo di vita del pass, mantenendo sincronizzato il tuo database senza polling continuo.
Tipi di eventi supportati:
-
pass.created— Il payload del pass è stato generato. -
pass.installed— L'utente ha aggiunto il pass ad Apple Wallet o Google Wallet. -
pass.updated— I campi del pass sono stati aggiornati. -
pass.scanned— Lo scanner ha convalidato il codice a barre alla cassa o all'ingresso. -
pass.removed— L'utente ha rimosso il pass dal Wallet del proprio dispositivo.
Verifica delle firme webhook:
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 non valida", { status: 401 });
}
const event = JSON.parse(payload);
if (event.type === "pass.installed") {
console.log(`Pass ${event.data.passId} installato su ${event.data.platform}`);
}
return new Response("OK", { status: 200 });
}
6. Multi-tenancy e domini personalizzati
Per piattaforme SaaS e agenzie che integrano l'emissione di pass per i propri clienti:
-
Provisioning programmatico di sotto-organizzazioni tramite gli endpoint amministrativi di gestione tenant (
/v1/admin/tenants). -
Configura record CNAME per domini personalizzati (es.
wallet.tuo-saas.com) per gli URL di distribuzione ospitati. -
Separa webhook, modelli, certificati e credenziali API per ciascuno spazio di lavoro tenant.





