Crea integrazioni su larga scala per Apple Wallet (.pkpass) e Google Wallet. Emetti, aggiorna, scansiona e invia notifiche in tempo reale tramite API REST pronte per la produzione.
L'API di Passinstance consente agli sviluppatori di emettere, distribuire, aggiornare e convalidare dinamicamente pass digitali per Apple Wallet (iOS) e Google Wallet (Android). Tutte le richieste API devono avvenire tramite HTTPS e restituiscono una busta di risposta API standardizzata con codici di stato leggibili automaticamente.
URL di base Produzione
Attivo
https://api.passinstance.com/api/v1
URL di base Sandbox Staging
https://staging-api.passinstance.com/api/v1
Formato richiesta e rispostaapplication/json (UTF-8) con busta di risposta standard
Fuso orario server backendEurope/Berlin (timestamp ISO 8601)
Sicurezza
Autenticazione — Chiavi API e autorizzazione
Usa X-API-Key: <key> o Authorization: ApiKey <key> per gli endpoint che supportano le chiavi API. Bearer è riservato ai JWT di accesso. Conserva le credenziali sul server.
Invariante di sicurezza:Solo server-to-server. Non incorporare mai chiavi segrete nei bundle frontend.
Avvio rapido
Avvio rapido — Prima richiesta API
Crea il tuo primo pass utilizzabile in meno di 5 minuti. Imposta l'intestazione della chiave API, chiama POST /api/v1/passes con un templateId valido e invia la passAccessUrl restituita al tuo utente finale.
Passo 1: Imposta la chiave
export PASSINSTANCE_API_KEY="pi_test_..."
Passo 2: Emetti il pass
POST /api/v1/passes con templateId e serialNumber
Passo 3: Ottieni l'URL
Estrai response.data.passAccessUrl dal payload 201 Created
Passo 4: Distribuisci
Invia URL via SMS/email; l'utente tocca "Aggiungi ad Apple/Google Wallet"
Risorse
Collezione Postman — Importa e testa richieste API
Importa la specifica OpenAPI 3.0 di Passinstance (/api/docs/openapi.json) direttamente in Postman, Insomnia o Bruno per testare gli endpoint, ispezionare gli schemi e generare client HTTP tipizzati.
Fai clic su Import in Postman, Insomnia o Bruno e incolla /api/docs/openapi.json per caricare tutte le route
3. Configura ambiente
Imposta baseUrl = https://api.passinstance.com e PASSINSTANCE_API_KEY = pi_test_...
4. Verifica connettività
Esegui GET /api/v1/templates con X-API-Key: per testare il tuo workspace
Operazioni e FAQ
FAQ — Domande frequenti e gestione degli errori
Ogni risposta utilizza la busta di risposta API standard. Correggi gli errori 4xx prima di riprovare; attendi su 5xx e 429 utilizzando l'intestazione Retry-After.
La gestione dei pass segue un ciclo di vita in 6 fasi: 1. Modello (progetto visivo) → 2. Pass (record firmato crittograficamente) → 3. Distribuzione (passAccessUrl sicura) → 4. Registrazione Wallet (il dispositivo si registra su APNs / Google Push) → 5. Aggiornamenti in tempo reale (notifiche su schermata di blocco) → 6. Telemetria di scansione e riscatto (validazione e webhook).
1. ModelloPOST /api/v1/templates
Layout master, tipo di codice a barre, colori del brand e campi dello schema
Guide piattaforma
Matrice Apple Wallet vs. Google Wallet
Passinstance firma automaticamente i pacchetti .pkpass per iOS e genera oggetti JWT firmati per Google Wallet. Risorse grafiche, codici a barre e trigger della schermata di blocco si adattano perfettamente a entrambi i sistemi.
Apple WalletiOS · .pkpass
Firma Apple Wallet
Firma crittografica PKCS#7 tramite certificato Apple Pass Type ID
Google WalletAndroid · JWT
Emittente Google Wallet
Payload REST JWT dell'account di servizio Google Cloud
Parità multipiattaforma (singola chiamata REST)iOS + Android
Codici a barre universaliCodice QR e PDF417 supportati nativamente su entrambe le piattaforme mobili
Concetti chiave
Meccaniche dei pass e motore di fidelizzazione
Collega meccaniche aziendali con stato ai modelli su 8 soluzioni pronte all'uso (Fedeltà, Carte timbri, Coupon, Carte regalo/prepagate, Biglietti eventi, Abbonamenti, Badge dipendenti, Carte VIP). Le regole vengono eseguite in modo atomico alla scansione o chiamata API.
LOYALTY_PROGRAM
LOYALTY_PROGRAM e Livelli
Accumulo punti per scansione (defaultChangeValue) con avanzamento automatico di livello
STAMP_CARD
STAMP_CARD_ADD / DEDUCT
Traccia le posizioni timbro (0..maximumValue) con onCap ('noop' | 'reset') e rewardClaimBehavior
PREPAID_CARD
Libro mastro PREPAID_CARD
Contabilità di registro prepagato in unità minime ISO 4217 con applicazione disallowNegativeBalance
VALID_ONCE_PER_DAY
VALID_ONCE_PER_DAY e RENEW
Limiti giornalieri consapevoli del fuso orario ed estensione automatica di expirationDate alla scansione
Gestione modelli
7 endpoint
GEThttps://api.passinstance.com/api/v1/templatesChiave API
Gestione modelli
Elenca tutti i modelli
Recupera un elenco paginato di modelli di pass appartenenti al contesto cliente autenticato.
Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio
Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.
POSThttps://api.passinstance.com/api/v1/templates/{id}/publishChiave API
Gestione modelli
Pubblica bozza del modello
Promuovi una revisione in bozza (rowKind: DRAFT) a PUBLISHED, imposta changesToPush: true e accoda aggiornamenti APNs e Google Wallet in background per tutti i pass attivi.
Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio
Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.
Esempio: pi_live_98a7b6c5d4e3f2a1
Parametri di percorso1 obbligatori
idstring (UUID)
Obbligatorio
UUID del modello da pubblicare.
Esempio: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Payload della richiesta che controlla la pubblicazione immediata o pianificata e la propagazione push ai wallet.
Risolvi una pagina pubblica personalizzata di download pass tramite slug (senza prefisso GET /d/{slug}/info). Per la ricerca gestionale autenticata usa GET /api/v1/download-pages/slug/{slug}.
Parametri di percorso1 obbligatori
slugstring
Obbligatorio
Slug vanity univoco della pagina di download ospitata.
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsChiave API
Notifiche push
Invia notifica su schermata di blocco
Invia una notifica push immediata sulla schermata di blocco a un pass Apple Wallet (.pkpass) o Google Wallet installato. Per invii programmati o personalizzazione intestazione, usa POST /api/v1/push-notifications/passes/{id}.
Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio
Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.
Esempio: pi_live_98a7b6c5d4e3f2a1
Parametri di percorso1 obbligatori
idUUID
Obbligatorio
UUID univoco dell'istanza pass destinataria della notifica.
Esempio: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
Payload della richiesta con corpo del messaggio e titolo d'intestazione opzionale.
Corpo della richiesta1 obbligatori • 1 opzionali
messagestring
Obbligatorio
Messaggio testuale da mostrare sulla schermata di blocco dell'utente.
Esempio: Your reward points have been updated! You now have 250 points.
Panoramica — Come funziona la validazione dei pass
Ogni scansione di codice a barre o NFC esegue una pipeline deterministica di 14 regole (stato, scadenza, fasce orarie, geofencing, meccaniche, rate limit, anti-replay) con nonce crittografici opzionali e sincronizzazione dataset offline.
Nonce anti-replay
POST /api/v1/scans/prepare rilascia un nonce crittografico anti-replay temporaneo legato al codice a barre
Convalida un codice a barre ottico, QR o una scansione NFC Apple VAS / Google Smart Tap da un terminale o scanner mobile tramite il motore a 14 regole.
Intestazioni2 obbligatori • 2 opzionali
x-scanner-keystring
Obbligatorio
Chiave di configurazione scanner generata nella Dashboard o tramite link di associazione scanner.
Esempio: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Obbligatorio
Deve essere application/json.
Esempio: application/json
Payload Payload della richiesta con stringa codice a barre letta, nonce anti-replay opzionale, metadati canale/protocollo e contesto operatore.
Corpo della richiesta1 obbligatori • 8 opzionali
scannedBarcodeValuestring
Obbligatorio
La stringa grezza letta da QR code, PDF417, CODE128, AZTEC o tap NFC.
Scarica un dataset di snapshot pass paginato con cursore limitato alla x-scanner-key chiamante per convalida locale offline in caso di assenza di rete.
Intestazioni1 obbligatori
x-scanner-keystring
Obbligatorio
Chiave di configurazione scanner generata nella Dashboard o tramite link di associazione scanner.
Verifica X-Webhook-Signature come HMAC-SHA256 del corpo originale esatto della richiesta con il segreto della sottoscrizione. Usa un confronto a tempo costante ed elabora gli eventi in modo idempotente.
Intestazione firma
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Intestazione timestamp
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Protezione dai replay
Verifica che X-Webhook-Id corrisponda a eventId firmato, deduplica gli eventi e convalida il timestamp firmato secondo la tua politica di replay.
Restituisci HTTP 200 OK entro 5.000 ms per confermare la ricezione
Chiave pubblica di verifica
GET /api/v1/webhooks/public-key restituisce la chiave pubblica attiva per la verifica delle firme
POSThttps://api.passinstance.com/api/v1/webhooks/subscriptionsChiave API
Panoramica ed endpoint
Crea sottoscrizione webhook
Registra un endpoint HTTPS per ricevere notifiche di eventi in tempo reale firmate HMAC per emissione, aggiornamento, scansione e disinstallazione pass.
Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio
Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.
Esempio: pi_live_98a7b6c5d4e3f2a1
Payload della richiesta contenente URL HTTPS di destinazione ed elenco di elementi tipi di evento webhook.
Corpo della richiesta2 obbligatori • 5 opzionali
urlstring (HTTPS URL)
Obbligatorio
URL del tuo server (deve iniziare con https://, max 2048 caratteri).
Come funzionano i Pull Webhook e relative limitazioni
Ricevi eventi di pass e scansioni in tempo reale tramite webhook Push firmati HMAC-SHA256 (con backoff esponenziale e circuit breaker) o polling Pull Webhook per reti protette da firewall, oltre a Workflow no-code.
Resilienza Push Webhook
5 tentativi con backoff esponenziale con jitter; il circuit breaker si apre dopo 10 errori consecutivi
Polling Pull Webhook
GET /api/v1/webhook-payload e POST /api/v1/webhook-payload/acknowledge per reti private
Eventi WebhookNotifica Webhook HTTP POST in uscita
Eventi modello (Template Events)
Notifiche webhook HTTP POST inviate quando un modello di pass viene creato, aggiornato, pubblicato o eliminato.
Modello creato
POST
TEMPLATE_CREATED
Generato alla creazione di un nuovo modello di pass
Modello aggiornato
POST
TEMPLATE_UPDATED
Generato alla modifica di campi, layout o meccaniche del modello
Modello pubblicato
POST
TEMPLATE_PUBLISHED
Generato alla pubblicazione di una bozza sui pass attivi
Modello eliminato
POST
TEMPLATE_DELETED
Generato all'avvio dell'eliminazione del modello e revoca nei wallet
Eventi WebhookNotifica Webhook HTTP POST in uscita
Eventi pass (Pass Events)
Notifiche webhook HTTP POST che tracciano ogni fase del ciclo di vita di un pass dalla creazione alla rimozione dal dispositivo.
Pass creato
POST
PASS_CREATED
Generato immediatamente quando un nuovo pass viene emesso tramite API REST o PassFlow
Pass aggiornato
POST
PASS_UPDATED
Generato quando attributi, punti fedeltà, livello o saldo del pass cambiano
Pass annullato
POST
PASS_VOIDED
Generato quando un pass viene annullato o disattivato su Apple Wallet e Google Wallet
Primo download del pass
POST
PASS_FIRST_DOWNLOAD
Generato la prima volta che un cliente riscatta o scarica il pass
Pass scaricato
POST
PASS_DOWNLOADED
Generato a ogni download successivo del pacchetto o link Google Wallet
Pass rimosso dal dispositivo
POST
PASS_REMOVED
Generato quando il cliente elimina il pass da Apple Wallet o Google Wallet
Eventi WebhookNotifica Webhook HTTP POST in uscita
Eventi di scansione (Scan Events)
Notifiche webhook HTTP POST inviate in tempo reale ogni volta che il codice a barre o NFC di un pass viene scansionato e convalidato.
Scansione pass creata
POST
APP_SCAN_CREATED
Generato quando POST /api/v1/scans o uno scanner registra una scansione
Metadati esito scansione
Include passId, serialNumber, templateId, configId, decisione di validazione e variazione saldo
Garanzia di consegna
Consegna HTTPS POST at-least-once con header X-Webhook-Id e X-Webhook-Signature
Compatibilità coda Pull
Disponibile anche tramite GET /api/v1/webhook-payload per POS protetti da firewall
Eventi WebhookNotifica Webhook HTTP POST in uscita
Eventi messaggio e riferimento stati (Message Events)
Notifiche webhook HTTP POST e codici di stato di consegna per notifiche push wallet, invii email e SMS.
Messaggio inviato
POST
MESSAGE_SENTNOTIFICATION_SENT
Generato all'invio di un messaggio o aggiornamento push
Consegna fallita
POST
MESSAGE_FAILED
Generato quando un'email, SMS o notifica push non viene recapitata
Riferimento stati messaggio
QUEUED -> SENT -> DELIVERED (o FAILED / BOUNCED con codice diagnostico)
Correlazione idempotente
Abbina eventId e passId nel consumer webhook per deduplicare eventuali ritentativi
Documentazione completa Piattaforma & API
Centro assistenza Passinstance: Esplora tutti i 10 temi e le 94 guide
Esplora guide passo-passo, diagrammi di architettura dei flussi, schemi payload JSON e risorse di risoluzione dei problemi per ogni area della piattaforma.