Skip to content
Riferimento API REST e SDK

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.

Ottieni chiavi API
Workbench live — gli snippet si aggiornano mentre digiti
Panoramica

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.

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.

Chiavi di produzione (Live)
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Chiavi Sandbox (Test)
Authorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxx
Chiavi scanner hardware
x-scanner-key: scan_key_77a8b9c0d1e2f3a4...
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.

Apri specifica JSON OpenAPI 3.0
1. URL specifica OpenAPI 3.0
https://passinstance.com/api/docs/openapi.json
2. Importa in Postman / Bruno

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.

200 OK / 201 CreatedSuccesso
{
  "success": true,
  "data": { ... },
  "errors": [],
  "statusCode": 200
}
Concetti chiave

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).

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
Grafica Hero / StripApple: 375×123 px (3:1) | Google: 1032×336 px (circa 3:1)
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

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.

Apri Centro assistenza

Tutto il necessario per iniziare rapidamente con Passinstance.