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

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