Skip to content
Guida del Centro assistenza · Emissione passFase di onboarding 3
4 min di letturaVerificato 2026-11-16

Creare pass individuali

Genera un singolo pass da modello pubblicato con dati cliente e link o codice QR immediato per il test.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito
Elementi chiave dell'interfaccia

Crea singolo pass e Azioni rapide (Zoom)

Clicca su «+ Create pass» nell'intestazione o su «Create single pass» nelle Azioni rapide per generare un pass di prova dal modello pubblicato.

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

Azioni rapide del modello per creare un singolo pass
Azioni rapide del modello per creare un singolo pass

Architettura di sistema: emissione singolo pass e upsert idempotente

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
EMISSIONE SINGOLO PASS E UPSERT IDEMPOTENTE
FASE 01 PANNELLO DASHBOARD / BACKEND CRM / POS
Emissione standard: POST/api/v1/passes (request payload)
Upsert idempotente: POST/api/v1/passes/upsert-by-external-id
FASE 02 SERVIZIO EMISSIONE PASS (Pass Issuance Engine)
1
Verifica che il Template target sia PUBLISHED e del tenant (customerId)
2
Valuta la chiave composta (customerId, externalId) per deduplicazione
3
Genera serialNumber univoco e authenticationToken hex a 32 byte
4
Valida attributes structured JSON rispetto allo schema Proprietà personalizzate
5
Salva la riga Pass (status: ACTIVE) e inizializza il ledger pass mechanic
FASE 03 FIRMA WALLET E IMPACCHETTAMENTO SMART LINK
Genera smart link di download (passAccessUrl) ed endpoint codice QR
Prepara lo stream Apple .pkpass firmato e il JWT Save di Google Wallet
Restituisce API response (request payload) con 201 Created o 200 OK

Emettere manualmente un singolo pass nella Dashboard

  1. 1
    Acceda alla pagina panoramica del modello Pubblicato.
  2. 2
    Clicchi su Crea pass nell'intestazione in alto (oppure sotto Azioni rapide).
  3. 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. 4
    Invii il modulo per generare immediatamente il pass.
  5. 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, resolvePassCreationTemplateId risolve templateId verso la sua revisione base PRODUCTION/PUBLISHED e rifiuta modelli DELETING/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

CampoTipoObbligatorioDescrizione
templateIdstring (UUID)SìUUID del modello (risolto automaticamente nella riga base attiva PRODUCTION/PUBLISHED).
externalIdstringOpzionaleIdentificativo CRM/POS/ordine univoco per tenant (max 255 caratteri; univoco per pass attivo non eliminato tramite @@unique([customerId, externalId])).
serialNumberstringOpzionaleNumero seriale univoco personalizzato (generato automaticamente se omesso).
barcodeValuestringOpzionalePayload esplicito del codice a barre. Predefinito dalla configurazione modello o generato automaticamente.
barcodeAltText / barcodeAlternativeTextstringOpzionaleTesto leggibile mostrato sotto il codice a barre per l'inserimento manuale in cassa.
attributesRecord<string, any>OpzionaleDizionario structured JSON chiave-valore corrispondente alle chiavi delle Proprietà personalizzate del modello.
expirationDatestringOpzionaleData/ora di scadenza (<= 10 anni nel futuro, interpretata nel fuso orario del workspace).
validityAsOfDate / validAsOfDatestringOpzionaleData/ora di inizio validità (issuedDate).
enableDownloadUntilstringOpzionaleTermine ultimo per il download ("YYYY-MM-DD HH:mm" o timestamp ISO).
sharingProhibitedbooleanOpzionaleSovrascrive l'impostazione anti-condivisione del modello (limitToOneActivePerPass).
validationPlacesstring[]OpzionaleOverride dei luoghi di validazione consentiti quando abilitati sul modello.
skipDistributeOnCreatebooleanOpzionaleSopprime 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

JSON
{
  "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)

JSON
{
  "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 un pass bundle (/api/v1/bundles/upsert o PassProject) in modo che Pass.bundleId raggruppi fino a 10 pass 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 a externalId (action: "CREATED"), oppure fonde attributes, expirationDate, status (pass status) e l'opzionale changeMessage (<=500 caratteri) sul pass esistente (action: "UPDATED").
  • PUT /api/v1/passes/by-external-id/:externalId: Esegue l'upsert utilizzando il parametro di percorso :externalId (externalId nel body deve corrispondere oppure può essere omesso).
  • GET /api/v1/passes/by-external-id/:externalId: Recupera direttamente il pass attivo tramite externalId senza 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

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)

JSON
{
  "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.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.