Mapa de Endpoints da API

Base URL stage: https://stage1-api-new.bs2bet.com/v2

Catálogo dos endpoints do BFF consumidos pelo template front-web-base (direto ou via packages do core @cactus-agents/*). Para ver qual rota SSR (/api/*) chama cada um, consulte SSR Routes → BFF.

Auth (15 endpoints)

Metodo	Endpoint	Observacao
POST	/auth/login	Login por email/senha (+ 2FA, captcha, icg_token)
POST	/auth/logout	Invalida sessao
POST	/auth/logout-auto	Logout automatico (sessao expirada)
GET	/auth/user-profile[?check_spa_again=1&icg_token=…]	Perfil do usuario logado
POST	/users/refresh-token	Refresh JWT
POST	/auth/register	Registro completo (quando documento/telefone sao obrigatorios)
POST	/auth/register/simplified	Registro simplificado legado
POST	/bff/register-simplified	Registro single-step por email
POST	/bff/social/{provider}	Login social (troca token do provider por JWT Cactus)
POST	/bff/social/{provider}/registerSimplified	Registro social (provider dinamico)
POST	/auth/passwords/reset/options	Esqueci a senha — envia opcoes de recuperacao
POST	/auth/passwords/reset/by-email	Envia codigo por email
POST	/auth/passwords/reset/by-sms	Envia codigo por SMS
POST	/auth/passwords/reset/validate-code	Valida codigo de recuperacao
POST	/auth/passwords/reset/confirm	Confirma nova senha
POST	/documents/validate	Valida CPF (BR) ou CURP (MX)

O endpoint final de registro e resolvido por resolveRegisterEndpoint() no template em runtime conforme registerTypeVersion da brand + flags requestDocument/requestPhone/socialService.

Brand (4 endpoints)

Metodo	Endpoint	Observacao
GET	/appearance	Configuracao visual da marca (logo, cores, banners)
GET	/bff/features	Feature flags ativas
POST	/bookmaker-settings	Configuracoes do bookmaker (operador)
GET	/getlegalterm	Termos legais / contratos da marca

User (26 endpoints)

Metodo	Endpoint	Observacao
POST	/users/update/{id}	Atualiza dados do usuario
POST	/users/change-password/{id}	Troca senha
GET	/bff/users/address-by-user	Endereco cadastrado
PATCH	/bff/users/self-email	Atualiza email
PATCH	/bff/users/add-phone	Adiciona telefone
PATCH	/bff/users/update-address	Atualiza endereco
PATCH	/bff/users/self-contracts	Aceita contratos/termos
PATCH	/bff/users/self-mkt	Opt-in/out marketing
PATCH	/bff/users/update-user-info-metadata	Preferencias genericas (whitelist no core)
PATCH	/bff/users/update-pending-data	Atualiza dados pendentes pos-login
POST	/bff/users/check-password	Verifica senha atual
PATCH	/bff/users/self-two-factor	Habilita/desabilita 2FA
GET	/bff/users/account-social	Lista contas sociais vinculadas
POST	/bff/users/account-social/connect/{type}	Vincula conta social (google, apple)
DELETE	/bff/users/account-social/{id}	Remove conta social
GET	/bff/users/login-history?page={page}	Historico de logins paginado
GET	/bff/games/user-last-casino-games-dl	Ultimos jogos jogados pelo usuario (DL)
GET	/bff/users/zendesk/create-or-update-user	Token SSO do Zendesk
POST	/users/list-referrals	Lista convidados (refer-a-friend)
POST	/apicep	Lookup de CEP/codigo postal
PATCH	/bff/users/update-limits	Atualiza limites de deposito/aposta
PATCH	/bff/users/timeout-limits	Define timeout temporario
PATCH	/bff/users/self-exclusion	Autoexclusao
POST	/income-report/generate	Gera relatorio IRPF
GET	/income-report/{id}	Polling do relatorio (intervalo de 3s)
GET	/income-report/available-years	Anos disponiveis para relatorio

Wallet (7 endpoints)

Metodo	Endpoint	Observacao
GET	/users/wallet	Saldo atual
POST	/bff/transactions	Historico de transacoes (filtros no body)
GET	/transactions/cashback?page=...&per_page=10	Historico de cashback paginado
GET	/bonus/rollover	Rollover ativo
GET	/bonus/rollover-accomplished	Rollover concluido
POST	/bonus/transfer	Transfere saldo de bonus
POST	/cashback/transfer	Resgata cashback
GET	/withdraw/{id}/generate	Gera comprovante de saque

observação

Wallet tem 8 linhas na tabela, mas /withdraw/{id}/generate e operacao de saque — contabilizado aqui por proximidade funcional.

Payments (12 endpoints)

Metodo	Endpoint	Observacao
GET	/payment-providers	Lista de providers de pagamento disponiveis
POST	/wallet/add-credit	Deposito
GET	/wallet/charge/{transactionId}	Status do deposito (polling)
POST	/new-withdraws	Solicita saque
GET	/bff/users/bank-list	Lista de bancos
POST	/pix-keys/user-key	Le chave PIX cadastrada (BR)
POST	/pix-keys/update-user-key-v2	Atualiza chave PIX (BR)
GET	/mex-bank-accounts/user-account	Conta bancaria do usuario (MX)
POST	/mex-bank-accounts/store	Cadastra conta bancaria (MX)
GET	/generic-bank-accounts/user-account	Conta bancaria generica do usuario (CHL/NGA)
POST	/generic-bank-accounts/store	Cadastra conta bancaria generica (CHL/NGA)
GET	/coupons/{code}	Valida cupom promocional

Games (19 endpoints)

Metodo	Endpoint	Observacao
GET	/casino-games/home	Layout da homepage — rows com jogos por categoria
GET	/casino-games/page/{page}	Layout de pagina curada pelo BFF (alt. de /home)
GET	/casino-games/list/base	Categorias (custom_categories) + providers
GET	/casino-games/list/?…	Lista paginada: categories[]=slug&providers[]=slug&term=texto&page=1&per_page=24
GET	/casino-games?slug={slug}	Detalhe de um jogo
GET	/casino-games/filter	Legacy — substituido por /casino-games/list
GET	/start-game-v2?…	?slug=&platform=MOBILE|WEB&use_demo=0|1 — autenticado, abre jogo
GET	/bff/games/top-wins-dl	Maiores ganhos (data-lake)
GET	/bff/games/game-top-wins-dl?slug={slug}	Maiores ganhos por jogo (data-lake)
GET	/bff/games/last-wins	Ultimos ganhos
GET	/bff/games/game-high-payers-dl	High-payers (data-lake) — alimenta top-games na home
GET	/bff/games/statistics?slug={slug}	Estatisticas por periodo (5min, 1h, 24h, 7d, 15d, 30d)
GET	/bff/games/statistics-dl?slug={slug}	Estatisticas data-lake (usadas por /api/games/statistics-dl)
GET	/casino-game-votes?casinoGameId={id}	Voto do usuario (autenticado)
GET	/casino-game-votes/count/{gameId}	Contagem de likes/dislikes
POST	/casino-game-votes/store/	Body: { casinoGameId, is_like } — autenticado
DELETE	/casino-game-votes/destroy/{gameId}	Remove voto — autenticado
GET	/bff/favorite-games	Lista jogos favoritos do usuario
PUT	/bff/favorite-games/toggle	Toggle de favorito (body { slug_url })

Sports (6 endpoints)

Metodo	Endpoint	Observacao
GET	/cactus-sportbook/search	Busca no sportsbook
GET	/cactus-sportbook/launch	Launch autenticado
GET	/cactus-sportbook/anonymous-launch	Launch anonimo
GET	/cactus-sportbook/*	Proxy transparente para qualquer subpath (/api/cactus-sportbook/*)
POST	/betby/get-jwt	JWT para provider Betby
GET	/alternar/token	Token para provider Altenar

KYC (4 endpoints)

Metodo	Endpoint	Observacao
GET	/bff/users/kyc?source={source}	Inicia KYC
GET	/bff/users/kyc/recovery	Recovery do KYC
GET	/bff/users/kyc/status?kyc_id={id}	Status do KYC
GET	/bff/users/kyc/status/recovery	Status recovery do KYC

Validation (8 endpoints)

:::warning Typo no backend Os endpoints /bff/users/validade-email-code e /bff/users/validade-sms-code possuem typo no backend — "validade" ao inves de "validate". Nao corrigir no front; usar exatamente como esta. :::

Metodo	Endpoint	Observacao
POST	/bff/users/send-email	Envia codigo de verificacao por email
POST	/bff/users/validade-email-code	Valida codigo de email (typo: "validade")
POST	/bff/users/send-sms	Envia codigo de verificacao por SMS
POST	/bff/users/validade-sms-code	Valida codigo de SMS (typo: "validade")
PATCH	/bff/users/self-phone	Atualiza telefone apos validacao
PATCH	/bff/users/add-address	Adiciona endereco
PATCH	/bff/users/add-initial-data	Dados iniciais pos-registro
POST	/bff/validate-confirmation	Confirma link de validacao por email

Gamification (2 endpoints REST + Smartico SDK)

A gamificacao do Cactus expoe 2 endpoints REST pelo BFF (rewards / redeem). Alem disso, ha integracao client-side com Smartico (3rd party) via JS SDK, sem rotas BFF envolvidas.

Metodo	Endpoint	Observacao
GET	/bff/gamification/rewards?page=…&per_page=…&type=…	Lista paginada de rewards do usuario
POST	/bff/gamification/redeem	Resgata reward — body { reward_id }

Smartico: ver SmarticoInitializer no layout e o hook useSmartico().

---

Headers obrigatorios

Toda requisicao envia:

Header	Descricao
tenant	ID do tenant (marca)
lang	Idioma (ex: pt-BR)
language	Idioma alternativo
version	Versao da API
origin-domain	Dominio de origem
Authorization	Bearer token (quando logado)

Comportamentos por status HTTP

Status	Comportamento
401	Logout automatico
429	Abre challenge/captcha
202	Timeout limit (resolve, nao throw)

---

Rotas de proxy do template (/api/*)

O template front-web-base expõe ~90 rotas internas que atuam como proxies server-side: leem o JWT do cookie HttpOnly e delegam ao BFF. O front-end só chama essas rotas — nunca o BFF diretamente.

Consulte SSR Routes → BFF para o mapa completo /api/* → BFF, agrupado por dominio (Auth, Validation, User, Wallet, Payments, Games, Search, Sports, KYC, Rewards, Income Report, Album, FTD Cashback, Tracking, Infra).