Panoramica
L'emissione di singoli pass consente agli operatori e alle integrazioni backend di generare una singola tessera digitale personalizzata da qualsiasi modello PUBLISHED. Sia avviata manualmente dal pannello Crea pass nella Dashboard sia in modo programmatico tramite REST API, l'operazione assegna un serialNumber e un authenticationToken crittograficamente univoci, popola tutti i campi dinamici {variable}, firma il bundle Apple .pkpass e il JWT Google Wallet e restituisce subito uno smart link di distribuzione (passAccessUrl).

Architettura di sistema: emissione singolo pass e upsert idempotente
Emettere manualmente un singolo pass nella Dashboard
-
1
Acceda alla pagina panoramica del modello Pubblicato.
-
2
Clicchi su Crea pass nell'intestazione in alto (oppure sotto Azioni rapide).
-
3
Compili ogni Proprietà personalizzata obbligatoria indicata nel modulo (ad esempio nome cliente, e-mail/telefono se richiesti per l'invio, numero iniziale di timbri oppure
externalId). -
4
Invii il modulo per generare immediatamente il pass.
-
5
Copi l'URL di download univoco (
passAccessUrl), mostri il codice QR di installazione da scansionare con lo smartphone oppure invii direttamente un'e-mail di consegna dal pannello dei dettagli del pass.
Prerequisiti: Pubblichi il modello (
POST /api/v1/templates/:id/publish) con credenziali Apple Pass Type ID / Google Wallet valide prima di emettere pass attivi. Internamente,resolvePassCreationTemplateIdrisolvetemplateIdverso la sua revisione basePRODUCTION/PUBLISHEDe rifiuta modelliDELETING/DELETED(BadRequestException/NotFoundException).
Riferimento API di emissione programmatica
1. Creare un nuovo pass (POST /api/v1/passes)
Crea un nuovo record pass tramite request payload, rispettando un eventuale header HTTP Idempotency-Key (idempotencyKey, max 128 caratteri corrispondenti a [A-Za-z0-9._:-]+, protetto da digest SHA-256 della richiesta) e i parametri query opzionali ?includePassSource=apple|google e ?pin=.
Parametri della richiesta request payload
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
templateId | string (UUID) | Sì | UUID del modello (risolto automaticamente nella riga base attiva PRODUCTION/PUBLISHED). |
externalId | string | Opzionale | Identificativo CRM/POS/ordine univoco per tenant (max 255 caratteri; univoco per pass attivo non eliminato tramite @@unique([customerId, externalId])). |
serialNumber | string | Opzionale | Numero seriale univoco personalizzato (generato automaticamente se omesso). |
barcodeValue | string | Opzionale | Payload esplicito del codice a barre. Predefinito dalla configurazione modello o generato automaticamente. |
barcodeAltText / barcodeAlternativeText | string | Opzionale | Testo leggibile mostrato sotto il codice a barre per l'inserimento manuale in cassa. |
attributes | Record<string, any> | Opzionale | Dizionario structured JSON chiave-valore corrispondente alle chiavi delle Proprietà personalizzate del modello. |
expirationDate | string | Opzionale | Data/ora di scadenza (<= 10 anni nel futuro, interpretata nel fuso orario del workspace). |
validityAsOfDate / validAsOfDate | string | Opzionale | Data/ora di inizio validità (issuedDate). |
enableDownloadUntil | string | Opzionale | Termine ultimo per il download ("YYYY-MM-DD HH:mm" o timestamp ISO). |
sharingProhibited | boolean | Opzionale | Sovrascrive l'impostazione anti-condivisione del modello (limitToOneActivePerPass). |
validationPlaces | string[] | Opzionale | Override dei luoghi di validazione consentiti quando abilitati sul modello. |
skipDistributeOnCreate | boolean | Opzionale | Sopprime gli invii automatici post-creazione (e-mail/SMS) durante l'emissione via API. |
Esempio di richiesta
POST /api/v1/passes?includePassSource=google Header: X-API-Key: <API_KEY> | Content-Type: application/json | Idempotency-Key: crm_usr_44910_v1
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"barcodeValue": "PI-GOLD-2026-44910",
"barcodeAltText": "44910-GOLD",
"expirationDate": "2027-12-31 23:59",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 500,
"memberTier": "Gold"
}
}
Esempio di risposta (API response envelope)
{
"success": true,
"data": {
"id": "pass_01j8k9m2n3p4q5r6",
"templateId": "tmpl_01hxyz987654321",
"customerId": "cust_ws_88219",
"externalId": "crm_usr_44910",
"bundleId": null,
"idempotencyKey": "crm_usr_44910_v1",
"serialNumber": "PI-GOLD-2026-44910",
"authenticationToken": "a9f4e2c81b7d60359e12c4b8f7a6d5e0",
"downloadCode": "dl_94f8a1",
"barcodeValue": "PI-GOLD-2026-44910",
"barcodeAltText": "44910-GOLD",
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "NONE",
"appleArtifactStatus": "NOT_GENERATED",
"googleArtifactStatus": "READY",
"downloadUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 500,
"memberTier": "Gold"
},
"expirationDate": "2027-12-31T23:59:00.000Z",
"createdAt": "2026-11-15T15:04:12.000Z"
},
"description": "Pass created successfully",
"errors": [],
"statusCode": 201
}
Consiglio — Bundling multi-pass (
bundleId): Se si creano pass complementari per un nucleo familiare, una tratta di volo o un ordine VIP evento, li associ a unpass bundle(/api/v1/bundles/upsertoPassProject) in modo chePass.bundleIdraggruppi fino a10pass in un unico link.pkpasses/ link unificato multi-carta.
2. Upsert idempotente e ricerca tramite External ID (request payload)
Nelle integrazioni guidate da webhook (Shopify, HubSpot o casse POS), i retry di rete possono ripetere la stessa richiesta più volte. Passinstance offre endpoint dedicati a externalId delimitati ai pass attivi del tenant (archivedAt: null):
-
POST /api/v1/passes/upsert-by-external-id: Crea un pass se nessun pass attivo corrisponde aexternalId(action: "CREATED"), oppure fondeattributes,expirationDate,status(pass status) e l'opzionalechangeMessage(<=500caratteri) sul pass esistente (action: "UPDATED"). -
PUT /api/v1/passes/by-external-id/:externalId: Esegue l'upsert utilizzando il parametro di percorso:externalId(externalIdnel body deve corrispondere oppure può essere omesso). -
GET /api/v1/passes/by-external-id/:externalId: Recupera direttamente il pass attivo tramiteexternalIdsenza dover archiviare esternamente gli UUID interni.
Esempio di richiesta
POST /api/v1/passes/upsert-by-external-id Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"status": "ACTIVE",
"changeMessage": "Tier updated to Platinum (%@ pts)",
"attributes": {
"pointsBalance": 750,
"memberTier": "Platinum"
}
}
Esempio di risposta (200 OK)
{
"success": true,
"data": {
"pass": {
"id": "pass_01j8k9m2n3p4q5r6",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"status": "ACTIVE",
"walletVoidStatus": "QUEUED"
},
"action": "UPDATED"
},
"description": "Pass updated successfully",
"errors": [],
"statusCode": 200
}
Per l'acquisizione CSV ad alto volume o la generazione batch via array JSON, consulti Creazione massiva di pass e Operazioni di massa.
