Entrada e identificação do parceiro

Resumo técnico

Esta entrega implementa no front a camada pública de identificação e apresentação do parceiro. Isso significa que o Site consegue resolver uma configuração pública a partir do host, aplicar marca, limitar produtos visíveis e encaminhar um contexto de início de jornada. Esta entrega não implementa a identificação operacional definitiva do lojista. Essa parte depende do backend, porque envolve allowlist de domínio, credenciais, códigos FortCard, persistência, auditoria e validação contra a API.

Fluxo operacional esperado

O fluxo abaixo é o contrato recomendado para produção. Ele separa apresentação pública no navegador de decisão operacional no backend.

A requisição chega por um domínio ou subdomínio.
O navegador usa o host apenas para resolver uma configuração pública de apresentação.
O Site aplica PublicTenantConfig, exibe a marca pública permitida e filtra enabledProducts.
Ao iniciar uma jornada, o front envia PublicFlowContext com origem pública, produto escolhido e valores do formulário.
O backend observa o host real recebido pelo servidor ou proxy confiável.
O backend normaliza o host, valida uma allowlist e resolve o parceiro comercial vigente.
O backend confirma se o produto público está habilitado para essa origem.
O backend mapeia selectedProductId para os códigos operacionais FortCard.
O backend persiste a correlação entre origem, lead, produto e proposta.
Se houver divergência entre host observado e contexto recebido, o backend registra auditoria e bloqueia a operação.

Essa separação permite que o Site seja white label sem transformar o browser em fonte de autorização.

O que já existe no front

Responsabilidade	Status no front	Arquivo principal
Normalizar o host recebido no navegador.	Implementado	`src/shared/marca/publicTenantRuntime.ts`
Resolver uma configuração pública de tenant por host.	Implementado	`src/shared/marca/publicTenantRuntime.ts`
Usar FORT como fallback visual em host desconhecido.	Implementado	`src/shared/marca/publicTenantRuntime.ts`
Aplicar logo, cores, favicon e largura da logo.	Implementado	`src/site/PublicBrandScope.tsx`
Filtrar produtos públicos habilitados.	Implementado	`src/site/landingEntryContent.ts`
Bloquear landing de produto desabilitado.	Implementado	`src/site/LandingEntryRoute.tsx`
Enviar contexto público ao iniciar uma jornada.	Implementado	`src/site/landingEntryContent.ts`
Converter produto público em código operacional.	Backend	Não deve ficar no navegador.
Resolver `strLojista`, `strLoja` e credenciais.	Backend	Não deve ficar no navegador.

Arquivos envolvidos

`src/shared/marca/publicTenantRuntime.ts`

Define o contrato público de tenant usado pelas páginas públicas. Campos principais:

Campo	Uso no front
`tenantId`	Identificador técnico público da configuração visual.
`partnerId`	Identificador público da origem comercial.
`sourceDomain`	Domínio ou subdomínio associado à configuração pública.
`displayName`	Nome público exibível.
`enabledProducts`	Lista de produtos que podem aparecer no Site daquele parceiro.
`publicBrand`	Logos, favicon, banners, cores públicas e largura da logo.

Também contém:

fortcardPublicTenant: fallback FORT para ambiente local ou host sem configuração.
fictitiousPublicTenant: exemplo demonstrativo usado na rota /exemplo-white-label.
resolvePublicTenant(hostname): função que normaliza o host e retorna a configuração pública correspondente.

Regra importante: este arquivo não contém credencial, token, usuário, senha, strLojista, strLoja, código interno de produto ou qualquer valor operacional.

`src/site/LandingEntryRoute.tsx`

É a entrada das páginas públicas. Fluxo executado:

Localiza o conteúdo da rota pública com findLandingEntryContent(route.publicPath).
Resolve o tenant público com resolveLandingEntryTenant(content, window.location.hostname).
Converte o tenant em marca visual com brandForPublicTenant(tenant).
Verifica se o produto está habilitado com isLandingEntryEnabled(content, tenant).
Renderiza home, landing de produto ou estado seguro de produto indisponível.

Se um produto não estiver habilitado para aquele tenant, a página não mostra a landing do produto e exibe uma mensagem segura de indisponibilidade.

`src/site/PublicBrandScope.tsx`

Aplica a marca pública nas páginas públicas por CSS variables. Variáveis principais:

Variável	Origem
`--fc-primary`	`tenant.publicBrand.colors.primary`
`--fc-public-primary`	`tenant.publicBrand.colors.primary`
`--fc-public-primary-soft`	derivada da cor primária
`--fc-public-secondary`	`tenant.publicBrand.colors.secondary`
`--fc-yellow-500`	`tenant.publicBrand.colors.secondary`

Esse escopo deve ser usado somente no Site, nas páginas de produto e nas páginas institucionais. Fluxos de Empréstimos e Área Logada continuam com marca FortCard.

`src/site/landingEntryContent.ts`

Centraliza o conteúdo das páginas públicas e a fronteira de início de jornada. Funções importantes:

Função	Responsabilidade
`findLandingEntryContent`	Encontra a configuração de conteúdo para uma rota pública.
`resolveLandingEntryTenant`	Resolve o tenant público pela rota e pelo host.
`filterLandingEntryProducts`	Remove produtos não habilitados para aquele tenant.
`isLandingEntryEnabled`	Confirma se a landing do produto pode ser exibida.
`beginPublicFlow`	Dispara o evento de início de jornada e navega para o fluxo React correspondente.

O evento disparado por beginPublicFlow usa o nome:

fort:begin-public-flow

Payload público enviado:

type PublicFlowContext = {
  readonly tenantId: string;
  readonly partnerId: string;
  readonly sourceDomain: string;
  readonly selectedProductId: PublicProductId;
  readonly formValues: {
    readonly cpf: string;
    readonly requestedAmount: string;
  };
  readonly targetPath: string;
};

Esse payload serve como contexto de navegação e intenção comercial pública. Ele não deve ser usado pelo backend como autorização.

Campos visíveis e campos operacionais

Grupo	Pode aparecer no navegador?	Quem valida ou resolve	Observação
`tenantId`, `partnerId` e `sourceDomain`	Sim	Backend revalida pelo host observado	Identificam apresentação pública e origem comercial declarada.
`selectedProductId`	Sim	Backend mapeia para produto FortCard	Usa IDs públicos como `personal-loan`, `clt-loan` e `salary-advance`.
CPF e valor informado no formulário inicial	Sim	Backend valida antes de simular	São dados da pessoa e intenção de contratação, não aprovação de crédito.
`strLojista`, `strLoja`, filial e ponto de atendimento	Não	Backend resolve por configuração	Nunca devem entrar em campo oculto, query string ou fixture do navegador.
`strProduto`, `strPlano`, tipo de operação e seguro	Não	Backend resolve por regra operacional	O front recebe somente produto público, ranges e resultado de negócio.
Usuário, senha, token FortCard e segredo de sessão	Não	Backend ou cofre de segredos	São segredos técnicos e nunca participam do contrato público da interface.
Status, pendência, oferta, assinatura e documentos seguros	Sim, em formato normalizado	Backend normaliza e mascara	O front renderiza estados legíveis e ações permitidas.

Checklist para backend

Antes de aceitar a criação ou retomada de uma proposta, o backend deve confirmar:

o host observado está na allowlist;
o parceiro comercial está ativo;
o produto público está habilitado para o parceiro;
o produto público foi mapeado para um código operacional válido;
campos FortCard operacionais foram resolvidos fora do navegador;
CPF, valor, prazo e dados informados foram validados;
a proposta foi vinculada a uma origem comercial auditável;
mensagens técnicas foram convertidas para erros seguros de tela.

`src/site/pagina-inicial/HomeLandingView.tsx`

Usa tenant.enabledProducts para:

filtrar os cards de solução exibidos na home;
filtrar banners vinculados a produtos;
usar banners públicos do tenant quando existirem;
manter um banner genérico FORT como apoio visual.

`src/site/landings/ProductLandingView.tsx`

Nas páginas de produto, o formulário inicial coleta CPF e valor desejado. Ao enviar, chama beginPublicFlow com:

tenantId;
partnerId;
sourceDomain;
selectedProductId;
cpf;
requestedAmount;
targetPath.

Exemplo de destino por produto:

Produto público	`selectedProductId`	`targetPath` inicial
Empréstimo pessoal	`personal-loan`	`/emprestimo/dados-pessoais`
Consignado CLT	`clt-loan`	`/consignado/clt-estimativa`
Antecipação salarial	`salary-advance`	`/antecipacao/ant-identificacao`

O que o backend precisa assumir

O backend deve tratar o contexto público como uma dica de origem, não como fonte de verdade. Ao receber uma intenção de jornada, o backend deve:

observar o host real recebido pelo servidor ou proxy confiável;
normalizar o host;
validar o host em allowlist;
resolver o parceiro comercial vigente;
confirmar se o produto está habilitado para o parceiro;
mapear selectedProductId para o código operacional FortCard;
resolver strLojista, strLoja, strProduto, strPlano e demais campos exigidos pela API;
persistir origem comercial, produto escolhido e vínculo com a proposta;
registrar auditoria quando houver divergência entre host observado e contexto recebido.

Relação com a API FortCard

O front trabalha com IDs públicos estáveis:

ID público	Significado visual
`personal-loan`	Empréstimo pessoal
`clt-loan`	Consignado CLT
`salary-advance`	Antecipação salarial

A API FortCard pode exigir campos operacionais como strLojista, strLoja, strProduto e strPlano. Esses campos devem ser resolvidos pelo backend a partir da configuração comercial validada. Não exponha esses códigos no front. Se algum deles precisar aparecer em logs, use logs de backend com controle de acesso.

Cenários esperados

Cenário	Comportamento no front	Comportamento esperado no backend
Host reconhecido	Aplica marca pública e produtos habilitados.	Valida host e resolve parceiro operacional.
Host local ou desconhecido	Exibe FORT como fallback visual.	Não presume lojista operacional.
Produto desabilitado	Oculta produto na home e bloqueia landing direta.	Recusa criação de proposta ou retorna regra de negócio.
Contexto divergente	Mantém navegação segura sem revelar dados internos.	Registra auditoria e impede uso da origem divergente.
Cliente com só um produto	Mostra apenas o produto habilitado em `enabledProducts`.	Aplica a mesma regra antes de simulação ou proposta.

Como evoluir para produção

O front atual tem uma resolução local suficiente para demonstração e contrato técnico. Para produção, a recomendação é substituir a fonte local por uma configuração pública controlada pelo backend ou por arquivo gerado no deploy. Opções aceitáveis:

Modelo	Quando usar
Configuração por build	Poucos clientes e deploy separado por cliente.
Configuração pública por host em backend	Vários domínios apontando para o mesmo ambiente.
Arquivo JSON público gerado no deploy	Ambientes estáticos com configuração controlada.

Independentemente do modelo, o contrato visual pode continuar igual: o Site recebe PublicTenantConfig, aplica marca pública e envia PublicFlowContext ao iniciar uma jornada.

Exemplo de configuração pública

Este exemplo mostra o formato conceitual de uma configuração pública. Ele pode vir do backend, de um arquivo gerado no deploy ou de configuração por build.

{
  "tenantId": "solarcred",
  "partnerId": "solarcred",
  "sourceDomain": "credito.solarcred.com.br",
  "displayName": "SolarCred",
  "enabledProducts": ["personal-loan", "salary-advance"],
  "publicBrand": {
    "logos": {
      "lightSurface": "/assets/clientes/solarcred/logo-azul.svg",
      "darkSurface": "/assets/clientes/solarcred/logo-branca.svg"
    },
    "favicon": "/assets/clientes/solarcred/favicon.svg",
    "colors": {
      "primary": "#075e54",
      "secondary": "#ffb020",
      "action": "#ffb020"
    }
  }
}

O backend ainda precisa revalidar sourceDomain pelo host observado. O exemplo acima não substitui allowlist, configuração operacional ou credenciais.

Limite de confiança

Dados no browser ajudam a experiência, mas não definem autorização. Marca, banner, origem comercial pública e produto escolhido são contexto. Comissão, credencial, acesso, regras de crédito e códigos FortCard são sempre resolvidos e validados no backend.

Começando

Arquitetura

Site e white label

Fluxos de Empréstimos

Integração backend

Qualidade e componentes

Entrada e identificação do parceiro

Resumo técnico

Fluxo operacional esperado

O que já existe no front

Arquivos envolvidos

`src/shared/marca/publicTenantRuntime.ts`

`src/site/LandingEntryRoute.tsx`

`src/site/PublicBrandScope.tsx`

`src/site/landingEntryContent.ts`

Campos visíveis e campos operacionais

Checklist para backend

`src/site/pagina-inicial/HomeLandingView.tsx`

`src/site/landings/ProductLandingView.tsx`

O que o backend precisa assumir

Relação com a API FortCard

Cenários esperados

Como evoluir para produção

Exemplo de configuração pública

Limite de confiança

​Resumo técnico

​Fluxo operacional esperado

​O que já existe no front

​Arquivos envolvidos

​src/shared/marca/publicTenantRuntime.ts

​src/site/LandingEntryRoute.tsx

​src/site/PublicBrandScope.tsx

​src/site/landingEntryContent.ts

​Campos visíveis e campos operacionais

​Checklist para backend

​src/site/pagina-inicial/HomeLandingView.tsx

​src/site/landings/ProductLandingView.tsx

​O que o backend precisa assumir

​Relação com a API FortCard

​Cenários esperados

​Como evoluir para produção

​Exemplo de configuração pública

​Limite de confiança

Resumo técnico

Fluxo operacional esperado

O que já existe no front

Arquivos envolvidos

`src/shared/marca/publicTenantRuntime.ts`

`src/site/LandingEntryRoute.tsx`

`src/site/PublicBrandScope.tsx`

`src/site/landingEntryContent.ts`

Campos visíveis e campos operacionais

Checklist para backend

`src/site/pagina-inicial/HomeLandingView.tsx`

`src/site/landings/ProductLandingView.tsx`

O que o backend precisa assumir

Relação com a API FortCard

Cenários esperados

Como evoluir para produção

Exemplo de configuração pública

Limite de confiança