SSR Routes → BFF (mapa de proxies)
Lista de todas as rotas server-side (/api/*) expostas pelo template front-web-base (React Router 7 SSR), o que cada uma faz e qual rota do BFF (ou serviço externo) ela alvo.
Hoje são 101 rotas /api/*. A lista viva é o registro de rotas
app/router/routes.ts — pra recontar:
grep -cE 'route\("api/' app/router/routes.ts
Use esta página em conjunto com:
:::warning Esta página descreve a trunk main-7k
O front-web-base opera com várias trunks de marca em paralelo e features são
portadas, não mergeadas — então a superfície de rotas difere entre elas. Rotas
que existem em main e não existem em main-7k (álbum de figurinhas,
/api/auth/logout-auto, sweepstakes, bolão) não estão listadas aqui. Confira
sempre no seu working tree. Contexto em
Trunks de marca.
:::
Convenções
- Método = método HTTP que o cliente do front envia para a rota SSR.
- BFF target = caminho final que sai da rota SSR (resolvido contra
API_BASE_URL).
- Service ⇢ indica via qual service do core (
@cactus-agents/*) a chamada passa.
— = a rota não bate em nada externo (cache local, version check, etc.).- (externo) = não vai para o BFF Cactus (AWS Lambdas, AppsFlyer, refer-a-friend, Rogue API).
:::info Por que existe essa camada?
O front-end nunca chama o BFF diretamente do browser. As rotas /api/* lêem o JWT do cookie HttpOnly e proxam para o BFF, evitando vazar token, permitindo cache server-side e padronizando tratamento de erros (extractApiError + proxyErrorResponse).
:::
Auth
| Front SSR | Método | O que faz | BFF target |
|---|
/api/auth/login | POST | Login (credenciais + 2FA + captcha + Incognia). Faz login + getUserProfile, seta cookies HttpOnly. | POST /auth/login → GET /auth/user-profile |
/api/auth/register | POST | Cadastro. Endpoint final é resolvido por resolveRegisterEndpoint() conforme registerTypeVersion e flags da brand. | POST /bff/register-simplified ou POST /auth/register ou POST /auth/register/simplified ou POST /bff/social/{provider}/registerSimplified |
/api/auth/logout | POST | Logout do usuário. | POST /auth/logout (Service ⇢ accounts.AuthService.logout()) |
/api/auth/register/validate-phone | POST | Envia/reenvia OTP de telefone no cadastro. resend no body escolhe o endpoint. | POST /bff/otp/register/send ou POST /bff/otp/register/resend |
/api/auth/documents/validate | POST | Valida documento no fluxo Didit (CHL). | POST /documents/validate |
/api/auth/documents/confirm-birthdate | POST | Confirma data de nascimento no fluxo Didit (CHL). | POST /documents/confirm-birthdate |
/api/auth/profile | GET | Lê o profile cacheado (ou bate no BFF). | GET /auth/user-profile[?check_spa_again=1] |
/api/auth/recheck-spa | POST | Revalida sessão pós-navegação SPA. | GET /auth/user-profile?check_spa_again=1 |
/api/auth/refresh | POST | Renova JWT. | POST /users/refresh-token |
/api/auth/recovery | POST | Recuperação de senha (multi-step). Step é selecionado pelo body. | POST /auth/passwords/reset/options, …/by-email, …/by-sms, …/validate-code, …/confirm |
/api/auth/social/:provider | POST | Login social (troca token do provider por JWT Cactus). | POST /bff/social/:provider |
/api/auth/validate-document | POST | Valida CPF/documento antes do cadastro. | POST /documents/validate |
/api/logs/auth-logout | POST | Log estruturado de logout client-side. | — (apenas log local) |
Validation (e-mail, SMS, docs, address, termos)
| Front SSR | Método | O que faz | BFF target |
|---|
/api/validation/email/send | POST | Envia código de verificação por e-mail. | POST /bff/users/send-email |
/api/validation/email/verify | POST | Verifica código de e-mail. | POST /bff/users/validade-email-code (typo proposital no BFF) |
/api/validation/email/change | PATCH | Troca e-mail do usuário. | PATCH /bff/users/self-email |
/api/validation/sms/send | POST | Envia código SMS. | POST /bff/users/send-sms |
/api/validation/sms/verify | POST | Verifica código SMS. | POST /bff/users/validade-sms-code (typo proposital no BFF) |
/api/validation/sms/change | PATCH | Troca telefone do usuário. | PATCH /bff/users/self-phone |
/api/validation/docs/submit | PATCH | Submete dados iniciais (KYC nível 1). | PATCH /bff/users/add-initial-data |
/api/validation/address/submit | PATCH | Submete endereço do usuário. | PATCH /bff/users/add-address |
/api/validation/full-name/submit | POST | Submete o nome completo (step full_name de dados pendentes). | POST /users/update/{id} (Service ⇢ accounts.updateProfile) |
/api/validation/terms/accept | PATCH | Aceite de termos/contratos. | PATCH /bff/users/self-contracts |
/api/validation/link-confirm | POST | Confirma link de validação (e-mail). | POST /bff/validate-confirmation |
/api/address/lookup-by-postal-code | POST | Lookup de CEP/postal code. | POST /apicep |
User (perfil, preferências, segurança)
| Front SSR | Método | O que faz | BFF target |
|---|
/api/user/update-profile | PATCH | Atualiza dados do perfil. | POST /users/update/{id} (Service ⇢ userService.updateProfile) |
/api/user/update-address | PATCH | Atualiza endereço. | PATCH /bff/users/update-address |
/api/user/add-phone | PATCH | Adiciona telefone. | PATCH /bff/users/add-phone |
/api/user/check-password | POST | Verifica senha atual. | POST /bff/users/check-password |
/api/user/change-password | POST | Troca senha. | POST /users/change-password/{id} |
/api/user/two-factor | PATCH | Liga/desliga 2FA. | PATCH /bff/users/self-two-factor |
/api/user/store-document | POST | Upload de documento (KYC). | POST /documents/{endpoint} |
/api/user/documents/verify-identity | POST | Dispara verificação de identidade (CHL). | POST /documents/verify-identity |
/api/user/social-accounts | GET | Lista contas sociais vinculadas. | GET /bff/users/account-social |
/api/user/social-accounts/:id | DELETE | Desvincula uma conta social. | DELETE /bff/users/account-social/{id} |
/api/user/update-marketing | PATCH | Preferências de marketing. | PATCH /bff/users/self-mkt |
/api/user/update-preferences | PATCH | Preferências (metadata genérica — whitelist no core). | PATCH /bff/users/update-user-info-metadata |
/api/user/update-pending-data | PATCH | Atualiza dados pendentes (pós-login). | PATCH /bff/users/update-pending-data |
/api/user/update-limits | PATCH | Atualiza limites de jogo responsável. | PATCH /bff/users/update-limits |
/api/user/timeout-limits | PATCH | Pause/timeout de conta. | PATCH /bff/users/timeout-limits |
/api/user/self-exclusion | PATCH | Auto-exclusão. | PATCH /bff/users/self-exclusion |
/api/user/login-history | GET | Histórico de logins paginado. | GET /bff/users/login-history?page=N |
/api/user/last-casino-games | GET | Últimos jogos jogados pelo user. | GET /bff/games/user-last-casino-games-dl |
/api/user/zendesk-token | GET | Token Zendesk SSO. | GET /bff/users/zendesk/create-or-update-user |
/api/user/referrals | POST | Lista convidados do user. | POST /users/list-referrals |
/api/user/indication-stats | GET | Stats da campanha refer-a-friend v2. | GET {referralCustomV2.apiUrl}/indication-stats/{userId} (externo) |
/api/user/referral-indicator | GET | Indicator legado refer-a-friend v1. | GET {referralCustomV1.apiUrl}/refer-friend/indicator (externo) |
:::danger update-preferences — o whitelist vive no CORE, não aqui
PATCH /bff/users/update-user-info-metadata é endpoint de campo livre: o BFF
grava qualquer JSON sob a chave preferencies (typo do backend — não corrigir).
Por isso o contrato do que pode ser gravado mora no core, não no base:
- Guard:
ALLOWED_PREFERENCES em @cactus-agents/accounts, validado em
updateUserPreferences() — chave desconhecida ou valor fora da lista lança
antes de chegar na rede.
- A rota do base (
app/routes/api/user/update-preferences.ts) chama
createUserFromClient(client).updateUserPreferences(body) e nunca menciona o
path do BFF nem a lista de chaves. Não troque isso por um client.patch()
direto — seria contornar o único guard que existe.
- Adicionar uma preferência nova exige bump do core (nova entry em
ALLOWED_PREFERENCES + campo em UserPreferences). Não há como habilitar do
lado do base.
Detalhes em Mapa de endpoints.
:::
Wallet
| Front SSR | Método | O que faz | BFF target |
|---|
/api/wallet/refresh | POST | Recarrega wallet + rollover (graceful). | GET /users/wallet + GET /bonus/rollover + GET /bonus/rollover-accomplished |
/api/wallet/transactions | POST | Lista transações (filtro por tipo/período/página). | POST /bff/transactions ou GET /transactions/cashback?… (quando type=cashback) |
/api/wallet/action | POST | Ações de wallet: bonus-transfer ou cashback-transfer. | POST /bonus/transfer ou POST /cashback/transfer |
/api/wallet/receipt | POST | Comprovante de saque (HTML/PDF). | GET /withdraw/{id}/generate (client.proxyRaw) |
Payments (depósito, saque, métodos, contas)
| Front SSR | Método | O que faz | BFF target |
|---|
/api/payments/providers | GET | Lista provedores de pagamento. | GET /payment-providers |
/api/payments/deposit | POST | Cria depósito. | POST /wallet/add-credit |
/api/payments/deposit-status | GET | Status de uma transação de depósito (polling). | GET /wallet/charge/{transactionId} |
/api/payments/withdraw | POST | Saque. | POST /new-withdraws |
/api/payments/bank-list | GET | Lista de bancos. | GET /bff/users/bank-list |
/api/payments/coupon | GET | Resolve cupom. | GET /coupons/{code} |
/api/payments/pix-key | GET/POST | Lê/atualiza chave PIX do user (BR). | POST /pix-keys/user-key (get) / POST /pix-keys/update-user-key-v2 (update) |
/api/payments/bank-account | POST | Hub multi-ação por body.type: get-pix / update-pix / get-mex / save-mex / get-generic / save-generic. | POST /pix-keys/user-key, POST /pix-keys/update-user-key-v2, GET /mex-bank-accounts/user-account, POST /mex-bank-accounts/store, GET /generic-bank-accounts/user-account, POST /generic-bank-accounts/store |
Games (catálogo, busca, start, votos, stats)
| Front SSR | Método | O que faz | BFF target |
|---|
/api/games/list | GET | Catálogo paginado (category/provider/search). Cacheável (CDN + platform-cache). | GET /casino-games/list/?… |
/api/games/search | POST | Busca legada (delega para getListPage). | GET /casino-games/list/?… |
/api/games/category/:slug | GET | Lista de jogos de uma categoria (infinite-scroll, cache-first). | GET /casino-games/list/?categories[]=:slug&… |
/api/games/provider/:slug | GET | Lista de jogos de um provider (infinite-scroll, cache-first). | GET /casino-games/list/?providers[]=:slug&… |
/api/games/by-slugs | GET | Resolve N jogos por slug (catálogo cacheado + fallback getDetail). | GET /casino-games?slug={slug} (fallback) |
/api/games/start | GET | Inicia uma sessão de jogo (autenticado). | GET /start-game-v2?… |
/api/games/top-wins | GET | Top wins do dia (data-lake). | GET /bff/games/top-wins-dl |
/api/games/top-games | GET | High-payers da home (getTopGames()). Lista vazia nunca é cacheável. | GET /bff/games/game-high-payers-dl |
/api/games/statistics-dl | GET | Stats DL de um jogo. | GET /bff/games/statistics-dl?slug=… |
/api/games/stats-batch | POST | Stats de N slugs cache-only (zero BFF round-trip). | — (lê só do platform-cache) |
/api/games/suggestions | GET | Sugestões pra estados vazios (getSuggestions()) — cache-only. | — (lê só do platform-cache) |
/api/games/rows/:page | GET | Rows dos hubs cassino/live (getCasinoRows() / getCasinoLiveRows()). | — (monta do catálogo cacheado) |
/api/games/vote | GET/POST/DELETE | Votação em jogo (up/down). | GET /casino-game-votes?casinoGameId=…, POST /casino-game-votes/store/, DELETE /casino-game-votes/destroy/{gameId} |
/api/favorites | GET/PUT | Lê / toggle de favoritos. | GET /bff/favorite-games, PUT /bff/favorite-games/toggle |
:::note Endpoints de games consumidos só no SSR (sem /api/* correspondente)
O catálogo é montado server-side via GamesCacheService no _layout loader. Endpoints adicionais usados internamente: GET /casino-games/home, GET /casino-games/page/{page}, GET /casino-games/list/base, GET /bff/games/last-wins, GET /bff/games/game-high-payers-dl.
:::
Search
| Front SSR | Método | O que faz | BFF target |
|---|
/api/search/unified | POST | Busca unificada (casino + sportsbook). | GET /casino-games/list/?… + GET /cactus-sportbook/search?… |
Sports (First + Altenar + Betby + Rogue)
Os providers de sportsbook suportados são ["first", "altenar", "betby", "rogue"].
| Front SSR | Método | O que faz | BFF target |
|---|
/api/sports/search | GET | Busca no sportsbook Cactus First. | GET /cactus-sportbook/search?… |
/api/sports/launch | GET | Launch autenticado (First). | GET /cactus-sportbook/launch |
/api/sports/anonymous-launch | GET | Launch anônimo (First). | GET /cactus-sportbook/anonymous-launch |
/api/sports/betby-jwt | POST | Emite JWT do Betby. | POST /betby/get-jwt |
/api/sports/altenar-token | GET | Token do Altenar. | GET /alternar/token |
/api/sports/rogue-anonymous | GET | Token anônimo da Rogue. Devolve { access_token, api_url }. | GET /cactus-sportbook/auth/anonymous (+ x-api-key) |
/api/sports/rogue-login | GET | Token logado da Rogue. | GET /cactus-sportbook/auth/login (+ x-api-key) |
/api/sports/rogue-proxy/* | GET/POST/PUT/PATCH/DELETE | Proxy same-origin com streaming pra Rogue API real. | {api_url}/{subPath} (externo — fssb.io) |
/api/cactus-sportbook/* | GET | Proxy transparente para qualquer subpath do Cactus Sportsbook (paridade com o legado Nuxt). | GET /cactus-sportbook/{subPath} (client.proxyRaw) |
:::note O trio rogue-* não segue o padrão das outras linhas desta página
O SDK @cactus-agents/sports-rogue roda no browser e fala com a Rogue API
(fssb.io), que não tem CORS. Então:
rogue-anonymous / rogue-login buscam o token no BFF Cactus e devolvem
api_url apontando pro nosso proxy (/api/sports/rogue-proxy), não pro
upstream real — o api_url verdadeiro fica cacheado server-side por tenant.rogue-proxy/* encaminha tudo pro upstream real fazendo streaming do body
(SSE de eventos ao vivo não pode ser bufferizado) e repassa o
Authorization: Bearer que o SDK envia.
O x-api-key das rotas de token vem de SPORTS_ROGUE_API_KEY e é injetado via
extraHeaders — escopado só a esse client, nunca vaza pro browser nem pras
outras chamadas da plataforma. @cactus-agents/sports-rogue não mora no
front-cactus-core; é publicado de outro lugar.
:::
KYC
| Front SSR | Método | O que faz | BFF target |
|---|
/api/kyc/start | GET | Inicia KYC (normal ou recovery). | GET /bff/users/kyc?source=… ou GET /bff/users/kyc/recovery?… |
/api/kyc/status | GET | Polling de status do KYC. | GET /bff/users/kyc/status?kyc_id=… ou GET /bff/users/kyc/status/recovery?… |
Rewards / Gamification (REST)
| Front SSR | Método | O que faz | BFF target |
|---|
/api/rewards/list | POST | Lista rewards do user paginado. | GET /bff/gamification/rewards?page=…&per_page=…&type=… |
/api/rewards/redeem | POST | Resgata um reward. | POST /bff/gamification/redeem |
:::note Gamification ≠ Smartico
Os endpoints REST acima são da gamificação interna do Cactus (rewards/redeem). O Smartico é uma plataforma 3rd-party complementar que roda client-side via JS SDK — sem rotas SSR/BFF envolvidas.
:::
Income Report (BR)
| Front SSR | Método | O que faz | BFF target |
|---|
/api/income-report/available-years | GET | Anos disponíveis. | GET /income-report/available-years |
/api/income-report/generate | POST | Gera relatório do ano. | POST /income-report/generate |
/api/income-report/status/:id | GET | Polling de status do relatório. | GET /income-report/{id} |
FTD Cashback (AWS Lambdas)
| Front SSR | Método | O que faz | Target externo |
|---|
/api/ftd-cashback/verify | POST | Verifica elegibilidade FTD-cashback. | POST {dark-verifier}.execute-api.sa-east-1.amazonaws.com/dark-verifier (AWS) |
/api/ftd-cashback/send-cashback | POST | Dispara envio do cashback. | POST {dark-freedom}.execute-api.sa-east-1.amazonaws.com/dark (AWS) |
Tracking
| Front SSR | Método | O que faz | Target externo |
|---|
/api/tracking/appsflyer | POST | Encaminha evento S2S para o AppsFlyer. | POST {appsFlyerConfig.s2sUrl} (AppsFlyer) |
Infra / Dev / Cache
| Front SSR | Método | O que faz | BFF target |
|---|
/api/version | GET | Versão do app (build id) para cache-busting. | — |
/api/clear-cache | GET | Force-clear de cache do browser (compat legado Nuxt). | — |
/api/cache/purge | POST | Invalida cache do worker proxy. | POST {PROXY_CACHE_PURGE_URL} (worker interno) |
/api/cache/inspect | GET | Inspetor do platform-cache (irmã de /api/dev/cache-policy, que mostra as políticas). | — |
/api/dev/cache-clear | GET/POST | Limpa platform-cache local (só DEV). | — |
/api/dev/cache-policy | GET | Inspeciona políticas de cache (só DEV). | — |
/api/dev/proxy | * | Forwarder genérico para o BFF (dev tool — DevApiExplorer). | * /{path} arbitrário no BFF |
/api/dev/visitor-info | GET | Info do visitor (geo/headers, só DEV). | — |
Como manter essa página
- Toda rota nova em
app/routes/api/** deve ser registrada em app/router/routes.ts e listada aqui.
- Quando o endpoint BFF mudar, atualize as duas páginas: aqui e api-map.
- Para rotas que usam um service do core, o BFF target real está no
service.ts do package em front-cactus-core/packages/<pkg>/src/.
- Toda rota que faz proxy autenticado do BFF precisa dos helpers de
~/utils/proxy-error.server — ver Códigos de erro.
Pra conferir se a página divergiu, compare o registro com as linhas listadas aqui:
grep -oE 'route\("api/[^"]+"' app/router/routes.ts | sed 's/route("//;s/"$//' | sort