Skip to content
Guida del Centro assistenza · Distribuzione pass
4 min di letturaVerificato 2026-11-16

Distribuzione self-service

Pubblica URL PassFlow pubblici, widget incorporabili, URL Wallet dinamici e tag NFC NDEF in punto vendita.

In questa guida

Consentire ai clienti di iscriversi autonomamente 24/7

Oltre al caricamento di elenchi CSV o alle chiamate API backend, Passinstance consente di pubblicare punti di iscrizione self-service non autenticati presso casse fisiche, pagine di checkout e-commerce, scontrini e packaging di prodotto:

CanaleIdeale perFunzionamento
Modulo pubblico PassFlowCartelli da banco, firme e-mail, volantini QRIl cliente compila un modulo di registrazione ottimizzato per mobile (/p/:url), verifica l'OTP e-mail/SMS se abilitato, completa l'eventuale pagamento e salva subito il pass.
Pulsante / Widget Wallet incorporatoAree clienti web, pagine di conferma ordineIncorpora un iframe interattivo o uno script widget Add-to-Wallet direttamente nell'HTML del sito web.
URL Wallet dinamicoE-mail transazionali, dashboard SaaS, portali fedeltàFirma o passa attributi cliente parametrici nell'URL oppure tramite upsert-by-external-id affinché gli utenti autenticati ottengano una tessera precompilata con un solo tocco.
Tag / Sticker smart NFC NDEFEspositori da tavolo, banchi cassa, smart posterCodifica un URL pubblico PassFlow su qualsiasi tag NFC NDEF standard (NTAG213/215) in modo che avvicinando un iPhone o un telefono Android si apra il flusso d'iscrizione senza scansionare un codice QR.

Architettura pubblica di auto-iscrizione PassFlow

Il motore PassFlow (PassFlow API su /api/v1/pass-flows/public/:url, con alias /api/v1/passflows/public/:url e rotta UI /f/:url) orchestra l'acquisizione multi-step non autenticata (PassFlowType, PassFlowSubmissionStatus) con protezione anti-bot integrata (SpamProtectionMode), verifica OTP, prevenzione duplicati (externalId) e consegna immediata nel Wallet:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
AUTO-ISCRIZIONE PUBBLICA PASSFLOW
FASE 01 PUNTO D'INGRESSO CLIENTE (QR / URL / TAP NDEF)
GET/api/v1/pass-flows/public/:url (Carica schema del flusso)
FASE 02 FASE 1: FormStep (Attributi cliente e validazione consenso)
Recupera token CSRF (/csrf-token) e valida request payload
FASE 03 FASE 2 e 3: EmailStep / OtpStep (Verifica identità opzionale)
Invia codice di verifica via POST/api/v1/pass-flows/public/:url/otp/send
Verifica il token OTP via POST/api/v1/pass-flows/public/:url/otp/verify
FASE 04 FASE 4: PaymentStep (Abbonamenti a pagamento, Gift Card e Biglietti opzionali)
Supporta Stripe PaymentIntent, PayPal Orders, Paystack, MTN MoMo, Orange Money
FASE 05 FASE 5: PassStep (Upsert idempotente e consegna immediata al Wallet)
Deduplica per email/phone/externalId (semantica upsert-by-external-id)
Renderizza pulsante .pkpass Apple, JWT Save Google Wallet e codice QR

Importante: Per evitare la creazione di pass duplicati quando un socio già iscritto invia nuovamente un modulo self-service, configuri le Regole di deduplicazione / External ID sul modello o PassFlow (email, phone o externalId). I portali backend possono inoltre richiamare direttamente POST /api/v1/passes/upsert-by-external-id per restituire il pass attivo esistente invece di generare un record duplicato.

Riferimento API pubbliche PassFlow e self-service

MetodoPercorso endpointAmbito AuthDescrizione
GET/api/v1/pass-flows/public/:urlPubblicoRecupera configurazione dei passaggi PassFlow (PassFlowStepType), schema modulo, tema (page theme: `LIGHT \DARK \CUSTOM`) e metadati di anteprima del modello.
GET/api/v1/pass-flows/public/:url/csrf-tokenPubblicoEmette il token anti-CSRF richiesto prima dell'invio della generazione pubblica del pass.
POST/api/v1/pass-flows/public/:url/generatePubblicoInvia il payload di registrazione (request payload: userData, recaptchaToken?, botProtectionToken?) per creare o recuperare il pass.
POST/api/v1/pass-flows/public/:url/otp/sendPubblico (Rate-Limited)Invia una password monouso OTP (POST .../otp/resend per reinviare) durante OtpStep.
POST/api/v1/pass-flows/public/:url/otp/verifyPubblico (Rate-Limited)Verifica il codice OTP inserito e sblocca la generazione del pass.
POST/api/v1/pass-flows/public/:url/payment-intentPubblicoInizializza un PaymentIntent Stripe (GET .../payment-config, /paypal-order, /paystack/initialize, /mtn-momo/request-to-pay, /orange-money/initiate).
POST/api/v1/passes/upsert-by-external-idChiave API (passes)request payload — crea (CREATED) o aggiorna (UPDATED) in modo idempotente il pass del cliente tramite externalId.

Esempio: iscrizione idempotente da portale tramite upsert-by-external-id

Quando si integra un pulsante Aggiungi al Wallet nel proprio portale clienti autenticato o applicazione web, richiami POST /api/v1/passes/upsert-by-external-id dal proprio backend e reindirizzi l'utente a passAccessUrl:

JSON
POST /api/v1/passes/upsert-by-external-id
{
  "templateId": "7b9e4c12-3f81-4a90-b8d2-19c48a70e112",
  "externalId": "USR-90214",
  "status": "ACTIVE",
  "attributes": {
    "firstName": "Elena",
    "lastName": "Rostova",
    "email": "elena.rostova@example.com",
    "tier": "Gold",
    "points": 1250
  }
}

Risposta (200 OK):

JSON
{
  "success": true,
  "data": {
    "pass": {
      "id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
      "serialNumber": "PI-8849-2026-X9",
      "externalId": "USR-90214",
      "bundleId": null,
      "status": "ACTIVE",
      "walletVoidStatus": "QUEUED",
      "passAccessUrl": "https://app.passinstance.com/p/c41a8d20-6e11-4f3b-9a81-0029d81a4f10"
    },
    "action": "UPDATED"
  },
  "description": "Pass updated successfully",
  "errors": [],
  "statusCode": 200
}

Codifica di tag NFC NDEF da banco

Per distribuire espositori fisici tap-to-enroll in cassa senza dover installare lettori hardware Apple VAS o Google Smart Tap:

  1. 1
    Copi il proprio URL pubblico PassFlow (ad esempio https://app.passinstance.com/f/coffee-club-vip).
  2. 2
    Utilizzi qualsiasi app standard di scrittura tag NFC (come NFC Tools) per scrivere un record URI NDEF su uno sticker NTAG213, NTAG215 o NTAG216 e abiliti Blocca tag (Sola lettura) affinché i clienti non possano sovrascrivere l'URL.
  3. 3
    Quando un cliente avvicina il proprio iPhone o smartphone Android sbloccato all'espositore sul banco, il sistema operativo apre automaticamente la pagina di registrazione PassFlow in Safari o Chrome.

Consulti la Guida Moduli di registrazione e PassFlow e la Guida alle integrazioni per i parametri di incorporamento e i trigger webhook.

Documentazione prodotto e API correlata

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.