Documentazione per sviluppatori Passinstance
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.
Introduzione — Panoramica dell'API
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.
https://api.passinstance.com/api/v1https://staging-api.passinstance.com/api/v1Autenticazione — 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.
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxxAuthorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxxx-scanner-key: scan_key_77a8b9c0d1e2f3a4...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.
export PASSINSTANCE_API_KEY="pi_test_..."POST /api/v1/passes con templateId e serialNumber
Estrai response.data.passAccessUrl dal payload 201 Created
Invia URL via SMS/email; l'utente tocca "Aggiungi ad Apple/Google Wallet"
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.
https://passinstance.com/api/docs/openapi.jsonFai clic su Import in Postman, Insomnia o Bruno e incolla /api/docs/openapi.json per caricare tutte le route
Imposta baseUrl = https://api.passinstance.com e PASSINSTANCE_API_KEY = pi_test_...
Esegui GET /api/v1/templates con X-API-Key: per testare il tuo workspace
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.
{
"success": true,
"data": { ... },
"errors": [],
"statusCode": 200
}Architettura e ciclo di vita del pass
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).
POST /api/v1/templatesLayout master, tipo di codice a barre, colori del brand e campi dello schema
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.
Firma crittografica PKCS#7 tramite certificato Apple Pass Type ID
Payload REST JWT dell'account di servizio Google Cloud
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_PROGRAMLOYALTY_PROGRAM e Livelli
Accumulo punti per scansione (defaultChangeValue) con avanzamento automatico di livello
STAMP_CARDSTAMP_CARD_ADD / DEDUCT
Traccia le posizioni timbro (0..maximumValue) con onCap ('noop' | 'reset') e rewardClaimBehavior
PREPAID_CARDLibro mastro PREPAID_CARD
Contabilità di registro prepagato in unità minime ISO 4217 con applicazione disallowNegativeBalance
VALID_ONCE_PER_DAYVALID_ONCE_PER_DAY e RENEW
Limiti giornalieri consapevoli del fuso orario ed estensione automatica di expirationDate alla scansione
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.
Tutto il necessario per iniziare rapidamente con Passinstance.
Scopri come impiegare le tessere Wallet digitali nelle diverse attività.
Progetta, emetti, organizza e mantieni aggiornati i tuoi pass digitali.
Consegna i pass ai clienti e mantieni i loro Wallet sempre aggiornati.
Configura provider Wallet, certificati e funzionalità NFC.
Convalida i pass, gestisci i check-in e registra le transazioni premio.
Collega Passinstance ai tuoi sistemi esistenti e automatizza i flussi.
Monitora le prestazioni, traccia le attività e analizza l'uso dei pass.
Gestisci organizzazione, utenti, abbonamento e impostazioni fiscali.
Trova risposte rapide, risolvi problemi e contatta l'assistenza.
