Skip to content
Guia da Central de Ajuda · Agências e parceiros
4 min de leituraVerificado 2026-11-16

Marca própria e opções white-label

Ative módulos adicionais: domínio de download personalizado, SMTP dedicado e consola white-label opcional.

Neste guia

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. 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. 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. 3
    Temas do Portal e da Consola (request payload): Personalize esquemas de cores, logótipos claros/escuros, favicons e definições poweredByEnabled.
FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
VERIFICAÇÃO DE DOMÍNIO E E-MAIL WHITE-LABEL
ETAPA 01 FORNECEDOR DNS DO TENANT (Cloudflare / Route53 / DNS Personalizado)
1
CNAME de Domínio: wallet.yourbrand.comcname.passinstance.com
2
Registo TXT Prop.: _passinstance-verify.wallet.yourbrand.com
3
Registos Auth E-mail: SPF (v=spf1 include:spf.passinstance.com ~all) e DKIM
ETAPA 02 ENDPOINTS WHITE-LABEL (/api/v1/white-labeling/*)
Resolve registos DNS autoritativos e valida tokens de propriedade
Aprovisiona certificados TLS/SSL geridos (/domains/:id/certificate-ready)
Ativa identidade de remetente SES/SMTP personalizada (/email/verify)

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 EndpointMétodoAutenticaçãoFuncionalidade
/api/v1/white-labeling/configurationGETBearer (whitelabel:view)Obtém a configuração completa de marca do espaço de trabalho.
/api/v1/white-labeling/featuresGETBearer (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-urlsGETBearer (whitelabel:manage)Lista os domínios personalizados configurados e o respetivo estado de DNS/SSL.
/api/v1/white-labeling/vanity-urlsPOSTBearer (whitelabel:manage)Regista um novo domínio personalizado (request payload) e gera tokens de verificação DNS.
/api/v1/white-labeling/vanity-urls/:idDELETEBearer (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/refreshPOSTBearerAciona uma consulta imediata de DNS para os registos CNAME e TXT.
/api/v1/white-labeling/domains/:id/certificate-readyPOSTBearerConfirma a emissão do certificado SSL/TLS e ativa a terminação de tráfego HTTPS.
/api/v1/white-labeling/emailGET / POST / DELETEBearerLê, 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/refreshPOSTBearerVerifica novamente os registos DNS ativos para alinhamento de SPF e propagação do seletor DKIM.
/api/v1/white-labeling/email/verifyPOSTBearerConfirma o token de verificação de domínio e promove o remetente para o estado ativo.
/api/v1/white-labeling/themeGET / PUT / DELETEBearerLê, 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:

JSON
{
  "url": "wallet.yourbrand.com",
  "type": "PASS_DOWNLOAD",
  "homePageRedirect": "https://www.yourbrand.com/wallet",
  "isPrimary": true
}

Resposta (201 Created):

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

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

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.