Arquitetura Modular White-Label
O Passinstance disponibiliza a personalização de marca white-label como capacidades modulares geridas através de White-Label Domains API (/api/v1/white-labeling/* e no Painel de Controlo em Definições do Espaço de Trabalho -> Marca /settings/workspace/branding, bem como Mensagens -> SMTP /settings/workspace/messaging/smtp). As organizações e agências podem personalizar três pontos de contacto distintos por espaço de trabalho:
-
1
Domínios Personalizados de Passes e Portais (domain surface type): Sirva ligações inteligentes de distribuição (
/d/:slug,/s/:token), páginas de inscrição PassFlow, interface administrativa, portais de fluxos de trabalho, documentação ou portais de suporte a partir do seu próprio subdomínio (wallet.yourbrand.com) com terminação TLS automatizada. -
2
E-mail Transacional com Marca Própria: Entregue e-mails de distribuição e recuperação de passes a partir do seu domínio com assinaturas SPF e DKIM verificadas (
request payload). -
3
Temas do Portal e da Consola (
request payload): Personalize esquemas de cores, logótipos claros/escuros, favicons e definiçõespoweredByEnabled.
Referência da API de White-Labeling (White-Label Domains API)
Todos os endpoints de configuração white-label estão delimitados ao espaço de trabalho ativo do tenant:
| Caminho do Endpoint | Método | Autenticação | Funcionalidade |
|---|---|---|---|
/api/v1/white-labeling/configuration | GET | Bearer (whitelabel:view) | Obtém a configuração completa de marca do espaço de trabalho. |
/api/v1/white-labeling/features | GET | Bearer (whitelabel:view) | Devolve quais as capacidades extra white-label que estão desbloqueadas no plano do espaço de trabalho. |
/api/v1/white-labeling/vanity-urls | GET | Bearer (whitelabel:manage) | Lista os domínios personalizados configurados e o respetivo estado de DNS/SSL. |
/api/v1/white-labeling/vanity-urls | POST | Bearer (whitelabel:manage) | Regista um novo domínio personalizado (request payload) e gera tokens de verificação DNS. |
/api/v1/white-labeling/vanity-urls/:id | DELETE | Bearer (whitelabel:manage) | Remove um domínio personalizado e reverte as ligações inteligentes para o encaminhamento predefinido da plataforma. |
/api/v1/white-labeling/domains/:id/refresh | POST | Bearer | Aciona uma consulta imediata de DNS para os registos CNAME e TXT. |
/api/v1/white-labeling/domains/:id/certificate-ready | POST | Bearer | Confirma a emissão do certificado SSL/TLS e ativa a terminação de tráfego HTTPS. |
/api/v1/white-labeling/email | GET / POST / DELETE | Bearer | Lê, cria (request payload) ou remove definições de remetente de e-mail com marca própria e registos SPF/DKIM. |
/api/v1/white-labeling/email/refresh | POST | Bearer | Verifica novamente os registos DNS ativos para alinhamento de SPF e propagação do seletor DKIM. |
/api/v1/white-labeling/email/verify | POST | Bearer | Confirma o token de verificação de domínio e promove o remetente para o estado ativo. |
/api/v1/white-labeling/theme | GET / PUT / DELETE | Bearer | Lê, atualiza (request payload) ou repõe as cores e logótipos do portal. |
Configurar um Domínio Personalizado de Transferência (request payload e domain surface type)
Passo 1: Registar o Nome de Anfitrião e a Superfície de Destino
Envie um pedido POST /api/v1/white-labeling/vanity-urls especificando o url FQDN, o type de domain surface type (PASS_DOWNLOAD, PASS_FLOW, BACKEND_UI, WORKFLOW_ENGINE, API_DOCUMENTATION, SUPPORT_PORTAL), o homePageRedirect opcional e isPrimary:
{
"url": "wallet.yourbrand.com",
"type": "PASS_DOWNLOAD",
"homePageRedirect": "https://www.yourbrand.com/wallet",
"isPrimary": true
}
Resposta (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"
}
Passo 2: Configurar o DNS e Atualizar
Adicione o registo CNAME necessário a apontar para cname.passinstance.com e o registo de verificação TXT no seu fornecedor de DNS. Após a propagação, acione POST /api/v1/white-labeling/domains/:id/refresh seguido de POST /api/v1/white-labeling/domains/:id/certificate-ready para finalizar o aprovisionamento TLS.
Configurar Entrega de E-mail com Marca Própria e Temas do Portal
Para enviar e-mails de emissão e recuperação de passes a partir do seu próprio domínio, registe a identidade do seu remetente ({ senderEmail, senderName?, spfRecord?, dkimRecord?, dkimSelector? }) através de POST /api/v1/white-labeling/email e valide o alinhamento SPF/DKIM utilizando POST /api/v1/white-labeling/email/refresh e POST /api/v1/white-labeling/email/verify.
Para estilizar as suas páginas de distribuição voltadas para o cliente, atualize o tema através de PUT /api/v1/white-labeling/theme utilizando 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
}
}
Pré-requisitos: Ao configurar um domínio personalizado na Cloudflare ou em redes proxy semelhantes, defina o registo CNAME como Apenas DNS (nuvem cinzenta) durante a verificação inicial para que o Passinstance possa validar o registo de destino
cname.passinstance.come aprovisionar o seu certificado TLS gerido sem interferência de proxy.
Explore os detalhes arquitetónicos completos na página API de Passes de Carteira White-Label ou gira subscrições de extras em Preços.
