Manual de integração — Hub Raio-X da Revenda

Este manual explica como outra plataforma do ecossistema Casa da Revenda (Atraia, RevendIA Venda, Gerencie, Aprenda, Entregue, Financie, Transforme, Admin Core) usa o Hub para:

  1. fazer login da revenda sem pedir os dados de novo;
  2. ler e salvar o cadastro comum da empresa;
  3. enviar as respostas da sua dimensão do Raio-X e mostrar o resultado;
  4. mostrar o Mapa de Evolução, a identidade, a estratégia e os próximos passos;
  5. registrar os eventos de medição.

Para ver cada função funcionando com dados de exemplo, abra a demonstração.

Resumo em 1 minuto

  • Endereço do Hub: https://raio-x-revenda.lovable.app
  • Identidade única: toda revenda tem um user_id (UUID) do Hub. Guarde esse UUID vinculado à conta local do seu sistema.
  • Três formas de chamar as APIs:
  • Token do Hub (Authorization: Bearer <access_token>): age em nome da revenda logada.
  • Chave de serviço (x-service-key: <HUB_SERVICE_KEY> + user_id): de servidor para servidor. Nunca no navegador.
  • Pública: só os catálogos.
  • O Hub calcula; o seu sistema mostra. Nível, gaps, comparação, Mapa, textos e conteúdos chegam prontos. Não recalcule nem copie regras.
  • Cada dimensão tem um dono. Só o produto dono responde ou refaz a própria dimensão (Atraia → atraia).

1. Conceitos

TermoO que é
user_idUUID da revenda no Hub. É a chave para tudo.
app_idIdentificador do seu sistema (atraia, venda, gerencie…). Letras minúsculas, números, _ e -.
entry_pointPor onde a revenda entrou pela primeira vez (ex.: cdr_evolua_atraia). Definido pelo sistema, nunca escolhido pelo usuário. Gravado só na primeira vez.
DimensãoParte do Raio-X avaliada por um produto (ex.: atraia). Notas de 1 a 4 por pergunta.
Dono da dimensãoO único sistema que pode enviar respostas daquela dimensão.
Mapa de EvoluçãoVisão que junta todas as dimensões concluídas. Libera com 2 ou mais.

Valores aceitos em entry_point: cdr_evolua, cdr_negocie, secplay, parceria, cdr_evolua_atraia, cdr_evolua_projete, cdr_evolua_venda, cdr_evolua_entregue, cdr_evolua_gerencie, cdr_evolua_financie, cdr_evolua_transforme.

2. Autenticação e segurança

FormaCabeçalhosQuando usar
Token do HubAuthorization: Bearer <access_token>O usuário está logado com a identidade do Hub. Lê e grava só os dados dele.
Chave de serviçox-service-key: <HUB_SERVICE_KEY> + user_id na query (GET) ou no corpo (POST)Servidor do seu sistema, depois de validar a própria sessão e vincular a conta ao UUID do Hub.
PúblicanenhumGET /api/public/profile-catalog e GET /api/public/raiox-catalog.

Regras obrigatórias:

  • A HUB_SERVICE_KEY fica só no servidor. Nunca em código de navegador, app ou URL.
  • Nunca aceite um user_id vindo do navegador como prova de identidade. Use o resultado da troca do SSO ou do login validado.
  • Não registre em log códigos, tokens nem a chave.
  • Todas as respostas têm Cache-Control: no-store. Respeite isso.
  • CORS só libera origens autorizadas (HTTPS de casadarevenda.com.br e subdomínios, subdomínios de lovable.app e lovableproject.com, http://localhost). CORS não substitui autenticação.

Padrão recomendado (BFF): o navegador fala só com o servidor do seu sistema. O servidor guarda o token do Hub em cookie HttpOnly; Secure; SameSite=Lax, renova quando precisa e chama o Hub.

3. Login da revenda no seu sistema

Escolha uma das opções.

Opção A — Entrar pelo Hub (SSO, recomendado)

A revenda é enviada ao Hub, entra (ou confirma "Continuar como"), completa o cadastro pendente e volta para o seu sistema já identificada.

1) Gerar o PKCE e o state e redirecionar (no navegador ou no servidor):

function base64url(bytes: Uint8Array) {
  return btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64url(
  new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))),
);
const state = crypto.randomUUID();
sessionStorage.setItem("hub_pkce", JSON.stringify({ verifier, state }));

const url = new URL("https://raio-x-revenda.lovable.app/auth");
url.searchParams.set("app_id", "atraia");
url.searchParams.set("redirect_to", "https://atraia.casadarevenda.com.br/callback");
url.searchParams.set("state", state);
url.searchParams.set("code_challenge", challenge);
location.assign(url.toString());

2) Receber o retorno. O Hub volta para redirect_to com os dados no fragmento (#): sso_code, user_id, app_id e state. O código vale 60 segundos e só pode ser usado uma vez.

const params = new URLSearchParams(location.hash.slice(1));
history.replaceState(null, "", location.pathname); // limpa o fragmento
const saved = JSON.parse(sessionStorage.getItem("hub_pkce") ?? "{}");
if (params.get("state") !== saved.state) throw new Error("state inválido");
// O user_id do fragmento NÃO prova identidade: use o resultado da troca.
await fetch("/api/hub/callback", {
  method: "POST",
  body: JSON.stringify({ code: params.get("sso_code"), verifier: saved.verifier }),
});

3) Trocar o código por tokens (no servidor do seu sistema):

const res = await fetch("https://raio-x-revenda.lovable.app/api/public/sso-exchange", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    code, // sso_code (64 caracteres hexadecimais)
    app_id: "atraia",
    redirect_to: "https://atraia.casadarevenda.com.br/callback", // exatamente o mesmo da ida
    code_verifier: verifier, // com PKCE não envie a chave de serviço
  }),
});
// 200 → { access_token, refresh_token, expires_at, token_type: "bearer", user_id }

Sem PKCE, a troca só pode ser feita no servidor, com x-service-key. Se o código foi criado com PKCE, a chave não dispensa o code_verifier. Erros: 401 proof_required, 401/400 para código expirado, usado ou destino diferente.

Opção B — Telas próprias de login

WhatsApp (código de 6 dígitos):

POST /api/public/identity/request-code
{ "phone": "19999990000" }
→ 200 { "ok": true, "phone": "5519999990000", "retryIn": 60, "expires_in": 900 }
→ 429 com Retry-After (reenvio antes de 60 s)
POST /api/public/identity/verify-code
{ "phone": "19999990000", "code": "123456", "entry_point": "cdr_evolua_atraia" }
→ 200 { "ok": true, "access_token", "refresh_token", "expires_at", "token_type", "user_id", "profile", "stages", "modules", "raiox_dimensions" }
→ 401 código incorreto, expirado, já usado ou 5 tentativas (sem tokens)

O código vale 15 minutos. Um novo pedido invalida o anterior.

E-mail e senha:

POST /api/public/identity/password
{ "mode": "login" | "signup", "email": "...", "password": "mín. 6", "entry_point": "cdr_evolua_atraia" }
→ 200 mesmo formato do verify-code
→ 401 invalid_credentials · 409 email_in_use

Renovar e sair

POST /api/public/identity/refresh
{ "refresh_token": "<token do Hub>" }
→ 200 novos tokens (guarde os dois, eles giram) · 401 → pedir login de novo

Sair do seu sistema = apagar cookies e tokens do Hub guardados por você. Não existe cookie compartilhado automaticamente entre sistemas: para trocar de sistema sem novo login, use o SSO.

4. Cadastro comum (Onboarding e Perfil)

Os dados da empresa são preenchidos uma vez e valem para todos os sistemas.

Saber o que pedir:

GET /api/public/common-profile            (Bearer)
GET /api/public/common-profile?user_id=…  (x-service-key)
→ { user_id, profile, stages, modules, raiox_dimensions }

Mostre só a etapa de stages.next_step: onboarding, perfil ou modulos. Etapas concluídas podem ser editadas, mas não devem ser pedidas de novo.

Montar o formulário: GET /api/public/profile-catalog (público) devolve as opções, os códigos e os campos obrigatórios. O formulário mostra os rótulos e a API grava os códigos.

Salvar:

POST /api/public/common-profile
{ "stage": "onboarding", "data": { "business_name": "Prime Segurança", "city": "Campinas", "document": null, "referral_source": "google", "entry_point": "cdr_evolua_atraia" } }

POST /api/public/common-profile
{ "stage": "perfil", "data": { "company_type": "instaladora", "monthly_revenue": "30k_100k", "verticals": ["condominial", "varejo"], "product_lines": ["seguranca"], "team_size": "2_5", "bottlenecks": ["marketing"], "ai_usage": "ocasional", "social_url": "@prime", "website_url": null } }
  • Onboarding: business_name e city obrigatórios. Com referral_source: "outro", referral_other também é obrigatório.
  • Perfil: exige onboarding concluído (senão 409 onboarding_required), de 1 a 5 verticais, ao menos uma linha de produto, equipe e ao menos um gargalo.
  • Não envie is_completed nem datas: o servidor calcula.
  • Com chave de serviço, inclua "user_id" no corpo.

Rascunhos por sistema: POST /api/public/system-module com { "system_id": "atraia", "schema_version": 1, "answers": { … } }. Aceita até 100 campos, sempre como rascunho.

5. Contexto da empresa

GET /api/public/user-context                       (Bearer: só o próprio usuário)
GET /api/public/user-context?user_id=<UUID>        (x-service-key)
GET /api/public/user-context?whatsapp_number=<tel> (x-service-key; 409 ambiguous_phone se houver mais de um)
→ { user, profile, stages, modules, raio_x, raiox_dimensions, recommended_solutions }

Use para personalizar o seu sistema (nome, cidade, verticais, faturamento, nível nas dimensões, soluções recomendadas com motivo).

6. Raio-X da sua dimensão (para o produto dono)

Hoje só a dimensão Atraia está ativa, com dono atraia. As outras seguem o mesmo contrato quando forem definidas.

GET /api/public/raiox-catalog (público) devolve, por dimensão:

  • os códigos das perguntas que pontuam (scored[].code) e a recomendação e a tela de cada gap;
  • o owner e a answer_screen;
  • os textos do lembrete;
  • as faixas de nível, a matriz de planos e os nomes dos eventos.

6.2 Abrir as perguntas

Ao refazer, as perguntas abrem com as respostas anteriores marcadas:

GET /api/public/raiox-answers?dimension=atraia
→ { answers: { scores: { "ATR.ORIGEM": 2, … }, concern: "…", answered_at } | null }

Use as notas só para pré-marcar o formulário. Nunca mostre as notas no resultado.

6.3 Enviar as respostas

Quando a revenda terminar as 10 perguntas (primeira vez ou refazendo):

POST /api/public/raiox-result
{
  "dimension": "atraia",
  "schema_version": 1,
  "app_id": "atraia",
  "scores": { "ATR.ORIGEM": 2, "ATR.GOOGLE": 2, "ATR.ORCAMENTO": 2, "ATR.CONTRATO": 1, "ATR.PRESENCA": 2, "ATR.CONVERSAO": 2, "ATR.FOLLOWUP": 1, "ATR.ROI": 1, "ATR.DIGITAL": 2 },
  "concern": "Resultado: já tentei divulgar e não deu retorno",
  "current_plan": "free"
}
→ { first_result, redo, new_achievements, result }
  • As 9 notas são obrigatórias, inteiras de 1 a 4. concern é a pergunta 10, obrigatória e fora do cálculo.
  • app_id precisa ser o dono da dimensão. Outro valor recebe 403 dimension_owner_only.
  • current_plan: free, aprenda ou venda (plano atual da conta, vindo do Admin Core).

O que fazer com a resposta:

CampoAção no seu sistema
first_result: trueConcluir o passo "Responder a dimensão" nos Próximos Passos e gerar as primeiras recomendações do CMO.
redo: trueRecalcular as recomendações da semana do CMO, mantendo as já feitas.
new_achievements[]Comemorar a conquista (ex.: "Visão Dupla").
resultAbrir a tela de resultado (6.4).

6.4 Mostrar o resultado

GET /api/public/raiox-result?dimension=atraia[&current_plan=venda]
→ { dimensions: [ { dimension, title, owner, answer_url, is_completed, attempts, first_answered_at, reminder_due_at, result } ] }

Campos de result e como exibir:

CampoExibição
title, answered_at"Resultado: Atraia" · "Respondido em DD/MM/AAAA"
level, level_readingSelo do nível (N1–N4) na cor do nível e a leitura
percentBarra de 0 a 100%
comparison"N3 ▲ (era N2)", "67% ▲ +34 pontos", "2 perguntas melhoraram: Follow-up ▲ e Retorno do marketing ▲" (null na primeira vez)
gaps[]"Seus 3 primeiros passos": recommendation + botão screen.label que abre screen.url
strengths[]"Ponto forte" (só se houver)
plantext; se covered: false e houver checkout_url, botão para o checkout

Nunca mostre as notas de cada pergunta. current_plan na consulta atualiza o cartão de plano sem regravar respostas.

6.5 Histórico

GET /api/public/raiox-history?dimension=atraia
→ { history: [ { id, answered_at, level, percent, is_latest } ] }   // do mais recente para o mais antigo

GET /api/public/raiox-result?result_id=<id>
→ { result }   // aquele resultado, somente leitura, comparado ao anterior a ele

6.6 Lembrete de 90 dias

O sistema dono chama uma vez por dia, do servidor:

POST /api/public/raiox-reminders        (somente x-service-key)
{ "dimension": "atraia", "app_id": "atraia", "limit": 100 }
→ { reminders: [ { user_id, result_id, push_message, cmo_recommendation, claimed_at } ] }

Para cada item: envie o push com push_message e crie a recomendação cmo_recommendation no CMO. Cada lembrete é devolvido uma única vez, mesmo com chamadas simultâneas. Quem refez nos últimos 90 dias não aparece.

7. Mapa de Evolução (qualquer sistema)

GET /api/public/raiox-map            (Bearer)
GET /api/public/raiox-map?user_id=…  (x-service-key)
→ { user_id, map }

O Mapa é recalculado a cada leitura. Ele muda quando uma dimensão é concluída ou refeita, ou quando o perfil muda. Se map.available for false (menos de 2 dimensões), mostre completed/min_dimensions ("1 de 2 dimensões") e map.dimensions com os botões para responder.

BlocoCampos
Topocompany (nome, tipo, cidade, segmentos), overall.level, opportunity_total, completed_label ("2/7"), updated_at
1 — Diagnósticodimensions[] (radar e barras: percent, level, median, product, product_url), impacts[] (valor e conta), blind_spots[], evolutions[], top_gaps[]
2 — Sua identidadeidentity.story, identity.perception, identity.tone, identity.speech, identity.channels, identity.applied_tone
3 — Inteligência estratégicastrategy.market[], strategy.quadrants[], strategy.funnel (stages[], bottleneck), strategy.sequence[]
4 — Próximo passonext_steps.contents[], projection, achievements[], recommended_product, remaining[]

Valores em reais sem centavos ("R$ 19.500"). Todos os textos já vêm montados; campos vazios já vêm trocados por termos genéricos.

7.1 Tom de voz nas artes

[Usar este tom nas minhas artes]:

POST /api/public/raiox-tone
{}                         → aplica o tom sugerido pelo faturamento
{ "tone": "consultivo" }   → direto | consultivo | acessivel
→ { brand_tone, label }    · 409 revenue_required se o perfil não tiver faturamento

O tom fica em profile.brand_tone (em common-profile e user-context). O Atraia deve usar brand_tone na identidade visual e nas próximas artes.

7.2 Conteúdos e [Criar arte]

Cada item de next_steps.contents[] tem key, type, title, art_type, vertical, create_art_url e art_created_at.

create_art_url abre a Nova Arte do Atraia:

https://atraia.casadarevenda.com.br/?tela=nova_arte&passo=texto&titulo=<tema>&tipo=<case_sucesso|cenario_vertical|campanha_propria|oferta>&vertical=<vertical>&conteudo=<key>

O Atraia abre a Nova Arte no passo do texto, com o tema como título, e segue o fluxo normal, inclusive o limite do plano. Ao criar a arte, o Atraia avisa o Hub:

POST /api/public/raiox-content-art
{ "content_key": "<conteudo>", "content_type": "dor", "title": "Síndico: 3 erros…", "app_id": "atraia" }
→ { content_key, art_created_at }

A partir daí o conteúdo mostra "Arte criada em DD/MM" e continua na lista.

7.3 Produto recomendado

recommended_product.action.kind:

  • dimension_result: abrir a tela de resultado da dimensão (no Atraia, o resultado Atraia).
  • product: abrir action.url, o app do produto.

8. Endereços que o Hub abre no seu sistema

O Hub monta links para as telas dos outros sistemas. Até cada sistema informar suas rotas, o formato é https://<sistema>.casadarevenda.com.br/?tela=<chave>. Trate estas chaves:

Sistematela=Deve abrir
Atraiaraiox_atraiaAs perguntas da dimensão Atraia (com respostas anteriores marcadas)
Atraiacampanhas_sugeridas, biblioteca_guia_google, estrategia_cmo_virtual, criar_proposta, nova_arte, criar_proposta_roi_tco, propostas, campanhas, identidade_visualTela do passo recomendado para cada gap
Atraianova_arte + passo, titulo, tipo, vertical, conteudoNova Arte a partir de um conteúdo (7.2)
Venda, Gerencie e outrosraiox_<dimensão>As perguntas da dimensão daquele produto

Quando tiver as rotas definitivas, envie-as ao time do Hub. Elas entram em screen.path / answer_screen.path e os links passam a usá-las.

9. Eventos de medição

EventoQuem registraDados
raiox_resultado_vistoSistema, ao abrir o resultadonivel
raiox_passo_tocadoSistema, ao tocar num passopergunta
raiox_plano_tocadoSistema, ao tocar no planoplano
raiox_historico_vistoSistema, ao abrir o histórico—
raiox_conteudo_usadoSistema, ao tocar em [Criar arte]tipo
raiox_produto_recomendado_tocadoSistema, ao tocar em [Começar agora]produto
raiox_mapa_vistoSistema informa; Hub calcula os dadosn_dimensoes, nivel_geral, impacto_total
raiox_identidade_vistaSistema informa—
raiox_funil_gargaloSistema informa; Hub calculaetapa
raiox_dimensao_refeitaHub, ao salvarvariacao_mediana
raiox_conquistaHub, ao salvarconquista
raiox_tom_aplicadoHub, ao aplicar o tomtom
POST /api/public/raiox-event
{ "event": "raiox_passo_tocado", "dimension": "atraia", "pergunta": "ATR.CONTRATO", "app_id": "atraia" }
{ "event": "raiox_conteudo_usado", "dimension": "mapa", "tipo": "dor", "app_id": "atraia" }
{ "event": "raiox_mapa_visto", "app_id": "venda" }

10. Erros

HTTPerrorSignificado
400invalid_requestCorpo ou parâmetros inválidos (campo faltando, nota fora de 1–4, opção inexistente)
400identity_requiredChave de serviço sem user_id
401unauthorizedToken inválido/expirado ou chave errada → renove ou faça login
403forbiddenToken de um usuário pedindo dados de outro
403dimension_owner_onlySistema que não é dono da dimensão tentando responder/refazer
404not_foundUsuário ou resultado inexistente
409onboarding_requiredPerfil antes do onboarding
409revenue_requiredAplicar tom sem faturamento no perfil
409ambiguous_phoneMais de uma conta com o mesmo telefone
429—Reenvio de código antes de 60 s (veja Retry-After)
500request_failed / read_failed / save_failedFalha temporária: tente de novo com espera

11. Checklist por sistema

Todos os sistemas

  • Registrar o app_id e a URL HTTPS de callback com o time do Hub.
  • Guardar a HUB_SERVICE_KEY só no servidor.
  • Login por SSO com PKCE (ou telas próprias) e vínculo da conta local ao user_id.
  • Ler stages.next_step e pedir só a etapa pendente do cadastro.
  • Mostrar o Mapa (raiox-map) e registrar os eventos de tela.
  • Tratar ?tela=raiox_<sua dimensão> e as demais chaves da seção 8.

Atraia (dono da dimensão Atraia)

  • Formulário das 10 perguntas com raiox-answers para pré-marcar.
  • POST raiox-result com app_id: "atraia" e o current_plan da conta.
  • first_result → concluir o passo e gerar recomendações do CMO. redo → recalcular a semana.
  • Tela de resultado (6.4), histórico (6.5) e "1 de 2 dimensões" (RX-07).
  • Rotina diária de raiox-reminders → push + recomendação no CMO.
  • Nova Arte pelos parâmetros da URL e raiox-content-art ao criar a arte.
  • Usar profile.brand_tone na identidade visual.

Venda, Gerencie e demais produtos donos de dimensão

  • Enviar ao Hub as perguntas, os códigos (VEN.*, GER.*…), a fórmula de impacto financeiro e o ponto cego da dimensão.
  • Depois de ativada, seguir os mesmos passos do Atraia com o próprio app_id.

Admin Core

  • Informar as URLs url_checkout_aprenda e url_checkout_venda (configuradas no Hub como URL_CHECKOUT_APRENDA e URL_CHECKOUT_VENDA).
  • Fornecer o plano atual de cada conta para o current_plan.

12. Como testar

  1. Abra a demonstração: todas as telas com dados de exemplo e o painel com os eventos que cada ação dispara.
  2. Teste o catálogo sem login:
curl https://raio-x-revenda.lovable.app/api/public/raiox-catalog
  1. Teste com a chave de serviço, sempre do servidor:
curl -H "x-service-key: $HUB_SERVICE_KEY" \
  "https://raio-x-revenda.lovable.app/api/public/raiox-map?user_id=<UUID>"

13. O que ainda depende de definição

  • Enunciados e opções das 10 perguntas da Atraia (os códigos já estão fixos).
  • Rotas definitivas das telas de cada sistema (seção 8).
  • Perguntas, impacto e ponto cego das outras 6 dimensões.
  • Textos de leitura dos níveis N1, N3 e N4 e a "dor" de cada dimensão restante.
  • Valores de mercado (raiox_market_params) e URLs de checkout.