Skip to content
Torna al blog

Guida per sviluppatori: integrazione REST API per pass Wallet

Guida tecnica end-to-end per creare modelli, emettere pass dinamici per Apple Wallet e Google Wallet via API, gestire aggiornamenti e verificare i webhook.

Passinstance Team
Passinstance Team

Wallet pass platform team

2026-08-162 min di lettura
Immagine di copertina per Guida per sviluppatori: integrazione REST API per pass Wallet

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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
FLUSSO ARCHITETTURALE
FASE 01 Tua Applicazione / Backend
FASE 02 Motore API Passinstance
Compila .pkpass firmato PKCS#7 per Apple Wallet
Genera link di salvataggio JWT firmato per Google Wallet
FASE 03 Dispositivo Cliente (iOS / Android)
FASE 04 Gateway Webhook Passinstance
4. POST/webhooks/pass-installedTuo Backend

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.
BASH
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:

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, // 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:

TS
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:

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 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.
Demo interattiva dal vivo
Apple Wallet e Google Wallet

Prova un vero pass Wallet sul tuo smartphone

Prova in prima persona come funzionano i pass digitali. Scansiona con la fotocamera o tocca qui sotto per aggiungere il pass in Apple Wallet o Google Wallet.

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

Scansiona con la fotocamera

Correlato in questo argomento

API per sviluppatori e integrazioni

Apri hub di argomenti

Pronto a lanciare il tuo programma di carte wallet?

Crea il tuo account, progetta il tuo modello di carta e testa carta reali direttamente in Apple Wallet e Google Wallet.