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:
| Canale | Ideale per | Funzionamento |
|---|---|---|
| Modulo pubblico PassFlow | Cartelli da banco, firme e-mail, volantini QR | Il 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 incorporato | Aree clienti web, pagine di conferma ordine | Incorpora un iframe interattivo o uno script widget Add-to-Wallet direttamente nell'HTML del sito web. |
| URL Wallet dinamico | E-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 NDEF | Espositori da tavolo, banchi cassa, smart poster | Codifica 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:
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 (
phoneoexternalId). I portali backend possono inoltre richiamare direttamentePOST /api/v1/passes/upsert-by-external-idper restituire il pass attivo esistente invece di generare un record duplicato.
Riferimento API pubbliche PassFlow e self-service
| Metodo | Percorso endpoint | Ambito Auth | Descrizione | ||
|---|---|---|---|---|---|
| GET | /api/v1/pass-flows/public/:url | Pubblico | Recupera 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-token | Pubblico | Emette il token anti-CSRF richiesto prima dell'invio della generazione pubblica del pass. | ||
| POST | /api/v1/pass-flows/public/:url/generate | Pubblico | Invia il payload di registrazione (request payload: userData, recaptchaToken?, botProtectionToken?) per creare o recuperare il pass. | ||
| POST | /api/v1/pass-flows/public/:url/otp/send | Pubblico (Rate-Limited) | Invia una password monouso OTP (POST .../otp/resend per reinviare) durante OtpStep. | ||
| POST | /api/v1/pass-flows/public/:url/otp/verify | Pubblico (Rate-Limited) | Verifica il codice OTP inserito e sblocca la generazione del pass. | ||
| POST | /api/v1/pass-flows/public/:url/payment-intent | Pubblico | Inizializza 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-id | Chiave 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:
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):
{
"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
Copi il proprio URL pubblico PassFlow (ad esempio
https://app.passinstance.com/f/coffee-club-vip). -
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
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.
