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:
- fazer login da revenda sem pedir os dados de novo;
- ler e salvar o cadastro comum da empresa;
- enviar as respostas da sua dimensão do Raio-X e mostrar o resultado;
- mostrar o Mapa de Evolução, a identidade, a estratégia e os próximos passos;
- 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
| Termo | O que é |
|---|---|
user_id | UUID da revenda no Hub. É a chave para tudo. |
app_id | Identificador do seu sistema (atraia, venda, gerencie…). Letras minúsculas, números, _ e -. |
entry_point | Por 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ão | Parte do Raio-X avaliada por um produto (ex.: atraia). Notas de 1 a 4 por pergunta. |
| Dono da dimensão | O único sistema que pode enviar respostas daquela dimensão. |
| Mapa de Evolução | Visã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
| Forma | Cabeçalhos | Quando usar |
|---|---|---|
| Token do Hub | Authorization: Bearer <access_token> | O usuário está logado com a identidade do Hub. Lê e grava só os dados dele. |
| Chave de serviço | x-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ública | nenhum | GET /api/public/profile-catalog e GET /api/public/raiox-catalog. |
Regras obrigatórias:
- A
HUB_SERVICE_KEYfica só no servidor. Nunca em código de navegador, app ou URL. - Nunca aceite um
user_idvindo 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.bre subdomínios, subdomínios delovable.appelovableproject.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_useRenovar e sair
POST /api/public/identity/refresh
{ "refresh_token": "<token do Hub>" }
→ 200 novos tokens (guarde os dois, eles giram) · 401 → pedir login de novoSair 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_nameecityobrigatórios. Comreferral_source: "outro",referral_othertambé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_completednem 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.
6.1 Catálogo
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
ownere aanswer_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_idprecisa ser o dono da dimensão. Outro valor recebe403 dimension_owner_only.current_plan:free,aprendaouvenda(plano atual da conta, vindo do Admin Core).
O que fazer com a resposta:
| Campo | Ação no seu sistema |
|---|---|
first_result: true | Concluir o passo "Responder a dimensão" nos Próximos Passos e gerar as primeiras recomendações do CMO. |
redo: true | Recalcular as recomendações da semana do CMO, mantendo as já feitas. |
new_achievements[] | Comemorar a conquista (ex.: "Visão Dupla"). |
result | Abrir a tela de resultado (6.4). |
6.4 Mostrar o resultado
GET /api/public/raiox-result?dimension=atraia[¤t_plan=venda]
→ { dimensions: [ { dimension, title, owner, answer_url, is_completed, attempts, first_answered_at, reminder_due_at, result } ] }Campos de result e como exibir:
| Campo | Exibição |
|---|---|
title, answered_at | "Resultado: Atraia" · "Respondido em DD/MM/AAAA" |
level, level_reading | Selo do nível (N1–N4) na cor do nível e a leitura |
percent | Barra 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) |
plan | text; 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 ele6.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.
| Bloco | Campos |
|---|---|
| Topo | company (nome, tipo, cidade, segmentos), overall.level, opportunity_total, completed_label ("2/7"), updated_at |
| 1 — Diagnóstico | dimensions[] (radar e barras: percent, level, median, product, product_url), impacts[] (valor e conta), blind_spots[], evolutions[], top_gaps[] |
| 2 — Sua identidade | identity.story, identity.perception, identity.tone, identity.speech, identity.channels, identity.applied_tone |
| 3 — Inteligência estratégica | strategy.market[], strategy.quadrants[], strategy.funnel (stages[], bottleneck), strategy.sequence[] |
| 4 — Próximo passo | next_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 faturamentoO 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: abriraction.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:
| Sistema | tela= | Deve abrir |
|---|---|---|
| Atraia | raiox_atraia | As perguntas da dimensão Atraia (com respostas anteriores marcadas) |
| Atraia | campanhas_sugeridas, biblioteca_guia_google, estrategia_cmo_virtual, criar_proposta, nova_arte, criar_proposta_roi_tco, propostas, campanhas, identidade_visual | Tela do passo recomendado para cada gap |
| Atraia | nova_arte + passo, titulo, tipo, vertical, conteudo | Nova Arte a partir de um conteúdo (7.2) |
| Venda, Gerencie e outros | raiox_<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
| Evento | Quem registra | Dados |
|---|---|---|
raiox_resultado_visto | Sistema, ao abrir o resultado | nivel |
raiox_passo_tocado | Sistema, ao tocar num passo | pergunta |
raiox_plano_tocado | Sistema, ao tocar no plano | plano |
raiox_historico_visto | Sistema, ao abrir o histórico | — |
raiox_conteudo_usado | Sistema, ao tocar em [Criar arte] | tipo |
raiox_produto_recomendado_tocado | Sistema, ao tocar em [Começar agora] | produto |
raiox_mapa_visto | Sistema informa; Hub calcula os dados | n_dimensoes, nivel_geral, impacto_total |
raiox_identidade_vista | Sistema informa | — |
raiox_funil_gargalo | Sistema informa; Hub calcula | etapa |
raiox_dimensao_refeita | Hub, ao salvar | variacao_mediana |
raiox_conquista | Hub, ao salvar | conquista |
raiox_tom_aplicado | Hub, ao aplicar o tom | tom |
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
| HTTP | error | Significado |
|---|---|---|
| 400 | invalid_request | Corpo ou parâmetros inválidos (campo faltando, nota fora de 1–4, opção inexistente) |
| 400 | identity_required | Chave de serviço sem user_id |
| 401 | unauthorized | Token inválido/expirado ou chave errada → renove ou faça login |
| 403 | forbidden | Token de um usuário pedindo dados de outro |
| 403 | dimension_owner_only | Sistema que não é dono da dimensão tentando responder/refazer |
| 404 | not_found | Usuário ou resultado inexistente |
| 409 | onboarding_required | Perfil antes do onboarding |
| 409 | revenue_required | Aplicar tom sem faturamento no perfil |
| 409 | ambiguous_phone | Mais de uma conta com o mesmo telefone |
| 429 | — | Reenvio de código antes de 60 s (veja Retry-After) |
| 500 | request_failed / read_failed / save_failed | Falha temporária: tente de novo com espera |
11. Checklist por sistema
Todos os sistemas
- Registrar o
app_ide a URL HTTPS de callback com o time do Hub. - Guardar a
HUB_SERVICE_KEYsó no servidor. - Login por SSO com PKCE (ou telas próprias) e vínculo da conta local ao
user_id. - Ler
stages.next_stepe 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-answerspara pré-marcar. POST raiox-resultcomapp_id: "atraia"e ocurrent_planda 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-artao criar a arte. - Usar
profile.brand_tonena 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_aprendaeurl_checkout_venda(configuradas no Hub comoURL_CHECKOUT_APRENDAeURL_CHECKOUT_VENDA). - Fornecer o plano atual de cada conta para o
current_plan.
12. Como testar
- Abra a demonstração: todas as telas com dados de exemplo e o painel com os eventos que cada ação dispara.
- Teste o catálogo sem login:
curl https://raio-x-revenda.lovable.app/api/public/raiox-catalog- 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.