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.

Use esta página em conjunto com:

• Mapa de endpoints da API — catálogo dos endpoints BFF (visão "back").
• Códigos de erro — contrato de classificação de falhas.

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, Sticker 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/logout-auto	POST	Logout automático (sessão expirada).	POST /auth/logout-auto
/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/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/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)

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/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/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 (Cactus Sportsbook First + Altenar + Betby)

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/cactus-sportbook/*	GET	Proxy transparente para qualquer subpath do Cactus Sportsbook (paridade com o legado Nuxt).	GET /cactus-sportbook/{subPath} (client.proxyRaw)

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}

Álbum de Figurinhas (Sticker Book)

Bate na Sticker API (STICKER_API_URL), separada do BFF Cactus. Handshake via POST /auth/token antes de cada chamada autenticada.

Front SSR	Método	O que faz	Sticker API target
/api/album/bootstrap	GET	Refetch do estado completo do álbum (CSR).	GET /campaigns/current, /users/me/progress, /users/me/stickers, /users/me/checkin
/api/album/checkin	POST	Claim do check-in (daily/completion).	POST /users/me/checkin/claim?claimType=…
/api/album/claim-featured	POST	Resgata featured card.	POST /users/me/featured/{featuredId}/redeem
/api/album/open-pack	POST	Abre um pacote.	POST /users/me/packs/open
/api/album/open-all-packs	POST	Abre todos os pacotes.	POST /users/me/packs/open-all
/api/album/mission-type	POST	Seleciona missionType (casino/sportbook).	GET /campaigns/current?missionType=… (mutação implícita via query param)

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/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

1. Toda rota nova em app/routes/api/** deve ser registrada em app/router/routes.ts e listada aqui.
2. Quando o endpoint BFF mudar, atualize as duas páginas: aqui e api-map.
3. 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/.

Última auditoria: 2026-06-02 — varredura completa de repos/front-web-base/app/routes/api/** + repos/front-cactus-core/packages/*/src/*service*.ts.