Architettura modulare White-Label
Passinstance fornisce funzionalità di branding white-label sotto forma di moduli gestiti tramite White-Label Domains API (/api/v1/white-labeling/* e nella Dashboard in Impostazioni del workspace -> Branding /settings/workspace/branding più Messaggistica -> SMTP /settings/workspace/messaging/smtp). Le organizzazioni e le agenzie possono personalizzare tre punti di contatto distinti per ciascun workspace:
-
1
Domini vanity per pass e portali (domain surface type): eroghi link di distribuzione intelligenti (
/d/:slug,/s/:token), pagine di iscrizione PassFlow, interfaccia utente di backoffice, portali di flussi di lavoro, documentazione o portali di supporto dal Suo sottodominio (wallet.yourbrand.com) con terminazione TLS automatizzata. -
2
Email transazionali personalizzate: invii email di distribuzione e recupero dei pass dal Suo dominio con firme SPF e DKIM verificate (
request payload). -
3
Temi del portale e della console (
request payload): personalizzi schemi di colori, loghi chiari/scuri, favicon e le impostazionipoweredByEnabled.
Riferimento API White-Labeling (White-Label Domains API)
Tutti gli endpoint di configurazione white-label sono associati all'ambito del workspace tenant attivo:
| Percorso Endpoint | Metodo | Autenticazione | Funzionalità |
|---|---|---|---|
/api/v1/white-labeling/configuration | GET | Bearer (whitelabel:view) | Recupera la configurazione completa del branding del workspace. |
/api/v1/white-labeling/features | GET | Bearer (whitelabel:view) | Restituisce quali funzionalità aggiuntive white-label sono sbloccate sul piano del workspace. |
/api/v1/white-labeling/vanity-urls | GET | Bearer (whitelabel:manage) | Elenca i domini vanity configurati e il relativo stato DNS/SSL. |
/api/v1/white-labeling/vanity-urls | POST | Bearer (whitelabel:manage) | Registra un nuovo dominio vanity (request payload) e genera i token di verifica DNS. |
/api/v1/white-labeling/vanity-urls/:id | DELETE | Bearer (whitelabel:manage) | Rimuove un dominio vanity e ripristina gli smart link al routing predefinito della piattaforma. |
/api/v1/white-labeling/domains/:id/refresh | POST | Bearer | Avvia una ricerca DNS immediata per i record CNAME e TXT. |
/api/v1/white-labeling/domains/:id/certificate-ready | POST | Bearer | Conferma l'emissione del certificato SSL/TLS e attiva la terminazione del traffico HTTPS. |
/api/v1/white-labeling/email | GET / POST / DELETE | Bearer | Legge, crea (request payload) o rimuove le impostazioni del mittente email personalizzato e i record SPF/DKIM. |
/api/v1/white-labeling/email/refresh | POST | Bearer | Ricontrolla i record DNS attivi per verificare l'allineamento SPF e la propagazione del selettore DKIM. |
/api/v1/white-labeling/email/verify | POST | Bearer | Conferma il token di verifica del dominio e promuove il mittente allo stato attivo. |
/api/v1/white-labeling/theme | GET / PUT / DELETE | Bearer | Legge, aggiorna (request payload) o ripristina i colori e i loghi del portale. |
Configurazione di un dominio di download vanity (request payload e domain surface type)
Passaggio 1: registrare l'hostname e la superficie di destinazione
Invii una richiesta POST /api/v1/white-labeling/vanity-urls specificando il FQDN url, il type da domain surface type (PASS_DOWNLOAD, PASS_FLOW, BACKEND_UI, WORKFLOW_ENGINE, API_DOCUMENTATION, SUPPORT_PORTAL), il parametro opzionale homePageRedirect e isPrimary:
{
"url": "wallet.yourbrand.com",
"type": "PASS_DOWNLOAD",
"homePageRedirect": "https://www.yourbrand.com/wallet",
"isPrimary": true
}
Risposta (201 Created):
{
"id": "dom_94a1c02b",
"url": "wallet.yourbrand.com",
"type": "PASS_DOWNLOAD",
"status": "PENDING_DNS",
"cnameTarget": "cname.passinstance.com",
"txtRecordName": "_passinstance-verify.wallet.yourbrand.com",
"txtRecordValue": "pi-verify=7f8e9a10b2c3d4e5f6",
"sslStatus": "PENDING"
}
Passaggio 2: configurare il DNS e aggiornare
Aggiunga il record CNAME richiesto che punta a cname.passinstance.com e il record di verifica TXT presso il Suo provider DNS. Una volta propagati, avvii POST /api/v1/white-labeling/domains/:id/refresh seguito da POST /api/v1/white-labeling/domains/:id/certificate-ready per finalizzare il provisioning TLS.
Configurazione del recapito email personalizzato e dei temi del portale
Per inviare le email di emissione e recupero dei pass dal Suo dominio, registri l'identità del mittente ({ senderEmail, senderName?, spfRecord?, dkimRecord?, dkimSelector? }) tramite POST /api/v1/white-labeling/email e convalidi l'allineamento SPF/DKIM utilizzando POST /api/v1/white-labeling/email/refresh e POST /api/v1/white-labeling/email/verify.
Per personalizzare lo stile delle pagine di distribuzione rivolte ai clienti, aggiorni il tema tramite PUT /api/v1/white-labeling/theme utilizzando request payload:
{
"logoUrl": "https://cdn.yourbrand.com/assets/logo.png",
"logoLightUrl": "https://cdn.yourbrand.com/assets/logo-light.png",
"logoDarkUrl": "https://cdn.yourbrand.com/assets/logo-dark.png",
"faviconUrl": "https://cdn.yourbrand.com/assets/favicon.ico",
"colorScheme": {
"primary": "#0F172A",
"secondary": "#2563EB",
"background": "#F8FAFC",
"text": "#020617",
"appName": "YourBrand Wallet",
"poweredByEnabled": false
}
}
Prerequisiti: Quando configura un dominio vanity in Cloudflare o reti proxy simili, imposti il record CNAME su DNS Only (nuvola grigia) durante la verifica iniziale, in modo che Passinstance possa convalidare il record di destinazione
cname.passinstance.comed emettere il certificato TLS gestito senza interferenze del proxy.
Esplori tutti i dettagli architetturali nella pagina API per pass Wallet White-Label o gestisca gli abbonamenti ai componenti aggiuntivi nella pagina Prezzi.
