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
Avvio rapido in 5 minutiOttieni chiave API

Crea il tuo primo pass Wallet in meno di 5 minuti

Emetti, firma crittograficamente e distribuisci pass Apple Wallet (.pkpass) e Google Wallet con una semplice chiamata REST.

Studio Pass dal vivo — modifica i campi per aggiornare codice e carta
Genera Apple Wallet (.pkpass) e Google Wallet
Anteprima output
ARAcme Rewards
Punti
450
Membro
Jane Doe
Gold VIP
MEMBER-2024-8891
PKCS#7 · .pkpassHTTP 201
POST/api/v1/passes
curl --max-time 30 -X POST https://api.passinstance.com/api/v1/passes \
  -H "X-API-Key: $PASSINSTANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "externalId": "CRM-CUST-99201",
    "name": "Acme VIP Customer Pass",
    "attributes": {
      "guestName": "Jane Doe",
      "tier": "Gold VIP",
      "points": "450"
    },
    "storedValue": "50.00",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z"
  }'
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

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

Esempio: pi_live_98a7b6c5d4e3f2a1
Parametri di query3 opzionali

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/templates/{id}Chiave API
Gestione modelli

Ottieni dettagli del modello

Recupera tutti i dettagli di un modello di pass inclusi colori, impostazioni codice a barre, campi layout e regole meccaniche.

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

Identificatore univoco del modello.

Esempio: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/templates/{id}/fieldsChiave API
Gestione modelli

Ottieni campi del modello

Recupera le definizioni dei campi dinamici e le chiavi personalizzate compilabili per ogni pass di un determinato modello.

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 univoco del modello.

Esempio: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Parametri di query1 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/templatesChiave API
Gestione modelli

Crea un modello di pass

Progetta e registra un nuovo modello riutilizzabile con branding visivo, tipo di codice a barre, configurazione NFC e campi di layout.

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

Configurazione della creazione modello conforme allo schema JSON OpenAPI.

Corpo della richiesta6 obbligatori • 4 opzionali
namestring
Obbligatorio

Nome visualizzato del modello.

Esempio: VIP Loyalty Card Template
descriptionstring
Obbligatorio

Descrizione dettagliata dello scopo del pass e dei vantaggi del livello.

Esempio: Exclusive loyalty and rewards card for VIP customers
organizationNamestring
Obbligatorio

Nome dell'organizzazione o brand stampato nell'intestazione.

Esempio: Acme Rewards
kindstring (enum)
Obbligatorio

storeCard, coupon, eventTicket, generic, boardingPass o membership.

Esempio: storeCard
statusstring (enum)
Obbligatorio

DRAFT, PUBLISHED, ARCHIVED, DEPRECATED o UNDER_REVIEW.

Esempio: PUBLISHED
preferredStyleSchemestring (enum)
Obbligatorio

DARK, posterGeneric, posterEventTicket, bannerEventTicket o semanticBoardingPass.

Esempio: DARK

Codici di stato della risposta

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.

Corpo della richiesta4 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/templates/{id}/copyChiave API
Gestione modelli

Duplica modello

Clona un modello di pass esistente inclusi layout, colori, immagini e meccaniche all'interno dello stesso workspace.

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 di origine da duplicare.

Esempio: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Optional name, description, and ISO 4217 currency override for the duplicated template.

Corpo della richiesta3 opzionali

Codici di stato della risposta

DELETEhttps://api.passinstance.com/api/v1/templates/{id}Chiave API
Gestione modelli

Elimina modello

Elimina un modello di pass e avvia un job asincrono per revocare e disattivare i pass associati su Apple Wallet e Google Wallet.

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

Esempio: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Codici di stato della risposta

Notifiche modello

3 endpoint
POSThttps://api.passinstance.com/api/v1/push-notifications/templates/{id}/sendChiave API
Notifiche modello

Trasmetti push a tutti i pass di un modello

Invia una notifica push immediata sulla schermata di blocco a tutti i pass attivi Apple Wallet e Google Wallet emessi da un modello.

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 i cui dispositivi registrati riceveranno la trasmissione.

Esempio: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Payload Payload della richiesta con pushNotificationText (max 85 caratteri) e testo intestazione opzionale.

Corpo della richiesta1 obbligatori • 1 opzionali
pushNotificationTextstring
Obbligatorio

Messaggio sulla schermata di blocco inviato ai pass attivi (max 85 caratteri; supporta segnaposto).

Esempio: Flash Sale starts now! Show your VIP pass at checkout for 2x points.

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/templates/{id}/notificationChiave API
Notifiche modello

Elenca notifiche pianificate

Elenca tutte le campagne di notifiche push pianificate ed eseguite di recente per uno specifico modello di 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
Parametri di percorso1 obbligatori
idstring (UUID)
Obbligatorio

Template UUID.

Esempio: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Codici di stato della risposta

DELETEhttps://api.passinstance.com/api/v1/templates/notification/{notificationId}Chiave API
Notifiche modello

Annulla notifica pianificata

Annulla una notifica push pianificata in sospeso prima che venga inviata ai dispositivi wallet registrati.

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
notificationIdstring (UUID)
Obbligatorio

UUID della notifica pianificata restituito durante la pianificazione o l'elenco.

Esempio: f1e2d3c4-b5a6-4987-8765-43210fedcba9

Codici di stato della risposta

Integrazioni modello

2 endpoint
POSThttps://api.passinstance.com/api/v1/integration-connections/embed-widgetsChiave API
Integrazioni modello

Crea integrazione incorporata (iFrame)

Crea una configurazione widget iFrame incorporabile per un modello pubblicato per integrare la registrazione dei pass sul tuo sito web.

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

Configuration for the embedded download widget including templateId and allowed host domains.

Corpo della richiesta3 obbligatori • 1 opzionali
namestring
Obbligatorio

Nome visualizzato per l'integrazione del widget incorporato.

Esempio: Checkout Loyalty Embed Widget
templateIdstring (UUID)
Obbligatorio

UUID del modello di pass di destinazione.

Esempio: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
allowedDomainsstring[]
Obbligatorio

Elenco delle origini (domini) autorizzate a incorporare il widget.

Esempio: ["shop.yourbrand.com", "app.yourbrand.com"]

Codici di stato della risposta

Gestione pass

11 endpoint
POSThttps://api.passinstance.com/api/v1/passesChiave API
Gestione pass

Emetti un nuovo pass

Crea ed emetti un nuovo pass Apple Wallet (.pkpass) e Google Wallet da un modello con campi cliente, codice a barre e valori dinamici.

Intestazioni2 obbligatori • 1 opzionali
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Obbligatorio

Deve essere application/json.

Esempio: application/json
Parametri di query2 opzionali

Payload Payload della richiesta contenente ID modello, numero di serie univoco, campi cliente e configurazione opzionale del codice a barre.

Corpo della richiesta1 obbligatori • 15 opzionali
templateIdstring (UUID)
Obbligatorio

ID del modello per il pass.

Esempio: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idChiave API
Gestione pass

Crea o aggiorna pass per ID esterno (Upsert)

Crea o aggiorna in modo idempotente un pass con chiave (customerId, externalId) per una sincronizzazione continua con CRM, POS ed e-commerce.

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 templateId, externalId e attributi dinamici del pass.

Corpo della richiesta2 obbligatori • 3 opzionali
templateIdstring (UUID)
Obbligatorio

UUID del modello di destinazione.

Esempio: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Obbligatorio

Identificatore esterno CRM/POS stabile e univoco nel tuo workspace.

Esempio: CRM-CUST-99201

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/batch-pass-operations/createChiave API
Gestione pass

Emissione massiva di pass

Emetti più pass wallet in un'operazione batch atomica con validazione e segnalazione degli errori.

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 un array di configurazioni pass.

Corpo della richiesta1 obbligatori
passesarray of objects
Obbligatorio

Array di elementi pass con templateId, barcodeValue e additionalData.

Esempio: [ { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-001", "additionalData": { "name": "Member #001" } }, { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-002", "additionalData": { "name": "Member #002" } } ]

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/passesChiave API
Gestione pass

Elenca tutti i pass

Recupera un elenco paginato di pass per il workspace cliente autenticato con filtri di ricerca e stato.

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 query13 opzionali

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/passes/{id}Chiave API
Gestione pass

Recupera un pass

Ottieni tutti i dettagli, lo stato di installazione e i link di download per un singolo pass tramite il suo ID univoco.

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

Identificatore UUID univoco del pass.

Esempio: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Codici di stato della risposta

PATCHhttps://api.passinstance.com/api/v1/passes/{id}Chiave API
Gestione pass

Aggiorna pass e invia push

Aggiorna campi dinamici, colori o codice a barre del pass e trasmetti automaticamente notifiche push APNs e Google Wallet ai dispositivi installati.

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 univoco del pass da aggiornare.

Esempio: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Campi Payload della richiesta da modificare sul pass. I dispositivi installati riceveranno aggiornamenti istantanei in background.

Corpo della richiesta13 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/passes/voiding/{id}/voidChiave API
Gestione pass

Disattiva un pass

Contrassegna un pass come revocato o riattivato su Apple Wallet e Google Wallet con propagazione push istantanea.

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

ID univoco dell'istanza pass da revocare o riattivare.

Esempio: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Payload Payload della richiesta che controlla stato revocato, motivo di audit e opzioni di propagazione wallet.

Corpo della richiesta1 obbligatori • 1 opzionali
voidedboolean
Obbligatorio

Imposta su true per revocare il pass o false per riattivarlo.

Esempio: true

Codici di stato della risposta

DELETEhttps://api.passinstance.com/api/v1/passes/{id}Chiave API
Gestione pass

Elimina pass

Elimina definitivamente un pass dal tuo workspace e revoca qualsiasi installazione attiva su Apple Wallet e Google Wallet.

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 univoco del pass da eliminare.

Esempio: b1d972dc-eccf-4f87-ab21-25939d9213d8

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/passes/{id}/useChiave API
Gestione pass

Applica azione meccanica

Esegui un'operazione atomica sulla meccanica del pass: INCREMENT (carta timbri), DECREMENT, DEBIT (saldo prepagato), CREDIT o VALIDATE (coupon monouso).

Intestazioni3 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_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Obbligatorio

Deve essere application/json.

Esempio: application/json
Idempotency-Keystring
Obbligatorio

UUID obbligatorio per garantire l'esecuzione atomica ed evitare doppie detrazioni di saldo o timbri.

Esempio: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Parametri di percorso1 obbligatori
idstring (UUID)
Obbligatorio

UUID univoco del pass su cui operare.

Esempio: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Payload della richiesta contenente l'azione meccanica, importo decimale opzionale, ID operatore e sede.

Corpo della richiesta1 obbligatori • 4 opzionali
actionstring (enum)
Obbligatorio

INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE o NOOP.

Esempio: INCREMENT

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-valueChiave API
Gestione pass

Regola saldo del pass

Accredita (aggiungi) o addebita (detrai) manualmente saldo o punti premio su un pass con registro di audit delle transazioni.

Intestazioni3 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_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Obbligatorio

Deve essere application/json.

Esempio: application/json
Idempotency-Keystring
Obbligatorio

UUID obbligatorio per garantire regolazione atomica ed evitare doppi accrediti.

Esempio: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Parametri di percorso1 obbligatori
idUUID
Obbligatorio

ID dell'istanza pass di destinazione.

Esempio: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Payload di rettifica che specifica operazione CREDIT o DEBIT, importo e motivo.

Corpo della richiesta2 obbligatori • 2 opzionali
actionstring
Obbligatorio

Azione di transazione: 'CREDIT' per aggiungere valore o 'DEBIT' per detrarlo.

Esempio: CREDIT
amountstring
Obbligatorio

Importo numerico da accreditare o addebitare come stringa.

Esempio: 25.00

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/mechanics/redeemChiave API
Gestione pass

Riscatta premio di meccanica pass

Riscatta un premio fedeltà o tessera timbri maturato su un pass usando la sua meccanica configurata con protezione di idempotenza.

Intestazioni1 obbligatori • 1 opzionali
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx

Richiesta di riscatto che specifica passId, mechanicId e opzionalmente idempotencyKey.

Corpo della richiesta2 obbligatori • 3 opzionali
passIdstring (UUID)
Obbligatorio

UUID del pass che riscatta il premio.

Esempio: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
mechanicIdstring (UUID)
Obbligatorio

UUID della regola della meccanica pass collegata al modello.

Esempio: mech_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

Codici di stato della risposta

Ricerca e analitica

4 endpoint
GEThttps://api.passinstance.com/api/v1/passes/searchChiave API
Ricerca e analitica

Cerca pass

Esegui una ricerca full-text sui pass emessi per numero di serie, ID esterno, email, titolare o attributi personalizzati.

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 query1 obbligatori
querystring
Obbligatorio

Stringa di ricerca (fino a 500 caratteri).

Esempio: Jane Doe

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/passes/statistics/{templateId}Chiave API
Ricerca e analitica

Ottieni statistiche dei pass

Ottieni statistiche aggregate di emissione, attivazione, installazione su wallet e riscatti per uno specifico modello di 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
Parametri di percorso1 obbligatori
templateIdstring (UUID)
Obbligatorio

UUID del modello di destinazione.

Esempio: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Parametri di query2 opzionali

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/passes/{id}/historyChiave API
Ricerca e analitica

Ottieni cronologia stato del pass

Recupera la cronologia di audit dei cambiamenti di stato, aggiornamenti punti/saldo, scansioni e annullamenti di un 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
Parametri di percorso1 obbligatori
idstring (UUID)
Obbligatorio

Pass UUID.

Esempio: b1d972dc-eccf-4f87-ab21-25939d9213d8
Parametri di query1 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/passes/exportChiave API
Ricerca e analitica

Esporta i pass in CSV

Trasmetti in streaming un'esportazione CSV UTF-8 (text/csv; charset=utf-8) delle istanze pass selezionate tramite 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

Payload della richiesta che specifica da 1 a 2.000 UUID pass e il formato di esportazione.

Corpo della richiesta2 obbligatori
passIdsstring[] (UUID v4)
Obbligatorio

Array da 1 a 2.000 UUID pass da includere nell'esportazione CSV.

Esempio: ["pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"]
formatstring (enum)
Obbligatorio

Formato di output esportazione ('csv').

Esempio: csv

Codici di stato della risposta

Consegna pass

4 endpoint
GEThttps://api.passinstance.com/api/v1/passes/{id}/urisChiave API
Consegna pass

Ottieni URL delle risorse del pass

Ottieni gli URL diretti di download e distribuzione di un pass, inclusi pagina PassFlow, .pkpass, JWT Google Wallet e codice QR.

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

Pass UUID.

Esempio: b1d972dc-eccf-4f87-ab21-25939d9213d8

Codici di stato della risposta

GEThttps://api.passinstance.com/d/{slug}/infoPubblico
Consegna pass

Ottieni pagina di download personalizzata

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.

Esempio: acme-vip-2026
Parametri di query2 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/passes/{id}/enabledownloadChiave API
Consegna pass

Abilita download del pass

Riattiva o sblocca il link di download di un pass quando il modello è configurato con il blocco dei download multipli.

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 pass di cui sbloccare il download.

Esempio: b1d972dc-eccf-4f87-ab21-25939d9213d8

Optional timestamp specifying how long re-download remains unlocked.

Corpo della richiesta1 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/passes/{id}/send-emailChiave API
Consegna pass

Invia pass via email

Invia un'email transazionale al titolare con il link diretto di installazione per Apple Wallet e Google Wallet.

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 pass da inviare tramite email.

Esempio: b1d972dc-eccf-4f87-ab21-25939d9213d8

Recipient email address(es) and optional custom subject and message body.

Corpo della richiesta4 opzionali

Codici di stato della risposta

Notifiche push

2 endpoint
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.

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/passes/sendpushnotificationsChiave API
Notifiche push

Invia notifiche push massive

Invia una notifica push sulla schermata di blocco simultaneamente a un elenco selezionato di ID pass tramite APNs e Google Wallet.

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

Target pass UUID array (up to 500 passes) and notification message text supporting {attribute} placeholders.

Corpo della richiesta2 obbligatori
listOfPassesstring[] (UUID)
Obbligatorio

Array da 1 a 500 UUID di pass.

Esempio: ["b1d972dc-eccf-4f87-ab21-25939d9213d8"]
pushNotificationTextstring
Obbligatorio

Messaggio di notifica su schermata di blocco (supporta segnaposto dinamici come {holderName}).

Esempio: Hi {holderName}, you unlocked a new reward!

Codici di stato della risposta

Gestione pacchetti

4 endpoint
POSThttps://api.passinstance.com/api/v1/bundles/upsertChiave API
Gestione pacchetti

Crea o aggiorna pacchetto pass

Crea o aggiorna un pacchetto multi-pass (.pkpasses) che consente agli utenti di installare più pass correlati con un solo tocco.

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

Array of pass UUIDs (up to 10) and optional existing bundleId.

Corpo della richiesta1 obbligatori • 1 opzionali
passesstring[] (UUID)
Obbligatorio

Array da 1 a 10 UUID di pass da raggruppare nel pacchetto.

Esempio: ["b1d972dc-eccf-4f87-ab21-25939d9213d8", "c2e083ed-fddf-4a98-bc32-36040e0324e9"]

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/bundles/{id}/passesChiave API
Gestione pacchetti

Elenca pass nel pacchetto

Elenca tutti i singoli pass attualmente associati a un pacchetto di pass, inclusi stato e numeri di serie.

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 pacchetto pass.

Esempio: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b
Parametri di query3 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/bundles/{id}/voidChiave API
Gestione pacchetti

Annulla pass del pacchetto

Annulla o riattiva tutti i pass appartenenti a un pacchetto di pass in un'unica operazione.

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 pacchetto pass.

Esempio: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Confirmation flag and optional audit reason for voiding all passes in the bundle.

Corpo della richiesta1 obbligatori • 1 opzionali
voidedboolean
Obbligatorio

Deve essere impostato su true per annullare tutti i pass nel pacchetto.

Esempio: true

Codici di stato della risposta

DELETEhttps://api.passinstance.com/api/v1/bundles/{id}Chiave API
Gestione pacchetti

Elimina pacchetto pass

Elimina un contenitore di pacchetto pass dal tuo workspace.

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 pacchetto pass da eliminare.

Esempio: e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b

Codici di stato della risposta

Sicurezza

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

Pipeline a 14 regole

PassStatus → Expiration → TimeWindow → Geofencing → Mechanics → RateLimit → AntiReplay

Sincronizzazione offline

GET /api/v1/scans/offline-dataset fornisce snapshot paginati tramite cursore per terminali offline

Abbinamento chiave scanner

POST /api/v1/scanner-keys/from-link scambia un token di abbinamento + PIN con una x-scanner-key

Configurazione scanner

3 endpoint
GEThttps://api.passinstance.com/api/v1/validation/configsChiave API
Configurazione scanner

Elenca configurazioni scanner

Elenca tutti i profili di configurazione scanner (app mobile, web scanner, POS) e i relativi permessi sui modelli.

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 query2 opzionali

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/validation/configs/{id}Chiave API
Configurazione scanner

Ottieni configurazione scanner

Ottieni i dettagli di una specifica configurazione scanner, inclusi modelli consentiti, messaggio post-scansione e regole.

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 della configurazione scanner.

Esempio: 7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/validation/configsChiave API
Configurazione scanner

Crea configurazione scanner

Crea un nuovo profilo di configurazione scanner con modelli associati, azione di scansione predefinita e messaggio di conferma.

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

Scanner configuration profile name, allowed template UUIDs, scan mode, and optional cooldown window.

Corpo della richiesta2 obbligatori • 2 opzionali
namestring
Obbligatorio

Nome descrittivo per la configurazione dello scanner.

Esempio: Main Entrance Gate Scanners
templateIdsstring[] (UUID)
Obbligatorio

UUID dei modelli autorizzati alla validazione con questo profilo.

Esempio: ["8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"]

Codici di stato della risposta

Operazioni di scansione

4 endpoint
GEThttps://api.passinstance.com/api/v1/validation/scansChiave API
Operazioni di scansione

Elenca registri di scansione

Consulta il registro di audit paginato delle scansioni pass filtrando per modello, pass, configurazione scanner, esito e periodo.

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 query3 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/scansChiave scanner
Operazioni di scansione

Elabora scansione codice a barre / NFC

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.

Esempio: PI-8891-JD-VIP

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/scans/prepareChiave scanner
Operazioni di scansione

Prepara nonce di scansione anti-replay

Emetti un nonce crittografico anti-replay temporaneo legato al codice a barre di un pass prima di eseguire POST /api/v1/scans.

Intestazioni1 obbligatori
x-scanner-keystring
Obbligatorio

Chiave di configurazione scanner generata nella Dashboard o tramite link di associazione scanner.

Esempio: scan_key_77a8b9c0d1e2f3a4b5c6d7e8

Payload della richiesta contenente il valore del codice a barre scansionato a cui associare il nonce crittografico.

Corpo della richiesta1 obbligatori
scannedBarcodeValuestring
Obbligatorio

Stringa di codice a barre o token NFC a cui associare il nonce anti-replay.

Esempio: PI-8891-JD-VIP

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/scans/offline-datasetChiave scanner
Operazioni di scansione

Scarica dataset offline dello scanner

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.

Esempio: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Parametri di query3 opzionali

Codici di stato della risposta

Panoramica ed endpoint

4 endpoint
Webhook

Panoramica Webhook e verifica della firma

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.

Eventi supportati

PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED

Risposta attesa

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

Esempio: https://your-server.com/webhooks/passinstance
eventsstring[] (enum)
Obbligatorio

Valori tipi di evento webhook: PASS_CREATED, PASS_UPDATED, PASS_VOIDED, PASS_DOWNLOADED, APP_SCAN_CREATED, LOCATION_ENTERED, NOTIFICATION_SENT, DEVICE_REGISTERED, DEVICE_UNREGISTERED, TEMPLATE_PUBLISHED.

Esempio: ["PASS_CREATED", "PASS_UPDATED", "APP_SCAN_CREATED"]

Codici di stato della risposta

DELETEhttps://api.passinstance.com/api/v1/webhooks/subscriptions/{id}Chiave API
Panoramica ed endpoint

Annulla sottoscrizione Webhook

Elimina una sottoscrizione webhook attiva tramite il suo ID e interrompi l'invio di eventi futuri a quell'endpoint.

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 della sottoscrizione webhook da rimuovere.

Esempio: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/webhooks/subscriptionsChiave API
Panoramica ed endpoint

Elenca sottoscrizioni webhook

Recupera tutte le sottoscrizioni webhook attive registrate per il tuo workspace cliente.

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

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/webhooks/public-keyPubblico
Panoramica ed endpoint

Ottieni chiave pubblica firma Webhook

Ottieni la chiave pubblica PEM attiva di Passinstance per verificare crittograficamente le firme dei webhook in uscita.

Codici di stato della risposta

Webhook basati su Pull

2 endpoint
Webhook

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

Trigger Workflow

PASS_CREATED, APP_SCAN_CREATED, PASS_INSTALLED, TIER_CHANGED, BALANCE_CHANGED, SCHEDULED

Azioni Workflow

SEND_PUSH_NOTIFICATION, UPDATE_PASS_FIELDS, SEND_EMAIL, WEBHOOK, MOVE_TO_SEGMENT

GEThttps://api.passinstance.com/api/v1/webhook-payloadChiave API
Webhook basati su Pull

Interroga gli eventi pull-webhook in coda

Recupera i payload degli eventi webhook in attesa tramite HTTPS GET in uscita per reti private o protette da firewall senza esporre porte in ingresso.

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 query3 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/webhook-payload/acknowledgeChiave API
Webhook basati su Pull

Conferma ricezione eventi pull-webhook

Conferma i payload pull-webhook elaborati fino a un ID specifico in modo che siano contrassegnati come consegnati e rimossi dalla coda.

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 che specifica l'ID limite superiore elaborato (upTo).

Corpo della richiesta1 obbligatori • 1 opzionali
upTostring (UUID)
Obbligatorio

Ultimo ID payload webhook elaborato; tutti gli eventi fino a questo ID vengono confermati.

Esempio: whp_55a4b3c2-1d0e-9f8a-7b6c-5d4e3f2a1b0c

Codici di stato della risposta

Eventi Webhook

4 guide
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.

Apri Centro assistenza

Tutto il necessario per iniziare rapidamente con Passinstance.