API Reference

A API do ProCases segue os principios REST e esta documentada usando OpenAPI 3.1 (Scalar).

Base URL

Producao: https://api.procases.example/api
Desenvolvimento: http://localhost:3000/api

Documentacao Interativa

• Scalar UI: /api/docs
• OpenAPI JSON: /api/docs-json

Autenticacao

A API usa autenticacao baseada em sessoes. O sessionId e enviado via cookie.

Cookie: sessionId=abc123...

Headers Padrao

Content-Type: application/json
Accept: application/json

Respostas

Sucesso

{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Erro

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "amountCents",
      "message": "must be a positive number"
    }
  ]
}

Codigos de Status

Codigo	Significado
200	OK
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity
429	Too Many Requests
500	Internal Server Error

Rate Limiting

Tipo	Limite	Janela
Global	100 req	1 min
Auth endpoints	10 req	1 min
Case open	5 req	1 min

Headers de rate limit:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

Endpoints por Modulo

Autenticacao (/auth)

Metodo	Endpoint	Descricao	Auth
GET	/auth/steam/login	Iniciar login Steam	Publico
GET	/auth/steam/callback	Callback Steam OAuth	Publico
GET	/auth/me	Dados do usuario logado	Requer
POST	/auth/logout	Logout da sessao atual	Requer
POST	/auth/logout-all	Logout de todas as sessoes	Requer
GET	/auth/sessions	Listar sessoes ativas	Requer
DELETE	/auth/sessions/:sessionId	Revogar sessao especifica	Requer

Usuarios (/user)

Metodo	Endpoint	Descricao	Auth
GET	/user/profile	Perfil do usuario	Requer
GET	/user/stats	Estatisticas do usuario	Requer
GET	/user/balance	Saldo do usuario	Requer
PATCH	/user/trade-url	Atualizar trade URL Steam	Requer

Caixas (/cases)

Metodo	Endpoint	Descricao	Auth
GET	/cases	Listar todas as caixas	Publico
GET	/cases/categories	Listar categorias	Publico
GET	/cases/:id	Detalhes da caixa	Publico
GET	/cases/:id/items	Itens de uma caixa	Publico
GET	/cases/:id/probabilities	Probabilidades de drop	Publico

Abertura de Caixas (/cases)

Metodo	Endpoint	Descricao	Auth
POST	/cases/:id/open	Abrir caixa (single ou multi)	Requer
GET	/cases/openings	Historico de aberturas do usuario	Requer
POST	/cases/openings/:id/verify	Verificar provably fair	Requer
GET	/cases/openings/recent	Drops recentes (live drops)	Publico

Batalhas (/battles)

Metodo	Endpoint	Descricao	Auth
GET	/battles/list	Listar batalhas (paginado)	Publico
POST	/battles/create	Criar nova batalha	Requer
POST	/battles/:id/join	Entrar em batalha	Requer
GET	/battles/active	Batalhas ativas do usuario	Requer
GET	/battles/:id	Detalhes da batalha	Requer
POST	/battles/:id/add-bots	Adicionar bots e iniciar	Requer

Upgrade (/upgrade)

Metodo	Endpoint	Descricao	Auth
GET	/upgrade/targets	Itens disponiveis para upgrade	Publico
POST	/upgrade/calculate	Calcular chance de sucesso	Requer
POST	/upgrade/perform	Executar upgrade	Requer
GET	/upgrade/history	Historico de upgrades	Requer
POST	/upgrade/:id/verify	Verificar provably fair	Requer

Swap (/swap)

Metodo	Endpoint	Descricao	Auth
GET	/swap/targets	Itens disponiveis para swap (Waxpeer)	Publico
POST	/swap	Criar oferta de swap	Requer
PUT	/swap/:id/accept	Aceitar oferta	Requer
PUT	/swap/:id/cancel	Cancelar oferta propria	Requer
PUT	/swap/:id/decline	Recusar oferta	Requer
GET	/swap/my-swaps	Minhas ofertas (criadas/recebidas)	Requer
GET	/swap/public	Ofertas publicas	Requer
POST	/swap/site	Swap por item Waxpeer (site swap)	Requer

Sorteios (/raffle)

Metodo	Endpoint	Descricao	Auth
GET	/raffle/active	Listar sorteios ativos	Publico
GET	/raffle/completed	Listar sorteios finalizados	Publico
GET	/raffle/:id	Detalhes do sorteio	Publico
POST	/raffle/:id/buy	Comprar tickets	Requer
POST	/raffle/:id/draw	Sortear vencedor (Admin)	Admin

Inventario (/inventory)

Metodo	Endpoint	Descricao	Auth
GET	/inventory	Listar itens do inventario	Requer
DELETE	/inventory/:id/sell	Vender item	Requer
POST	/inventory/sell-multiple	Vender multiplos itens	Requer
POST	/inventory/sell-all	Vender todos os itens	Requer
POST	/inventory/:id/withdraw	Solicitar saque de skin (Waxpeer)	Requer
GET	/inventory/withdrawals/active	Saques de skin ativos	Requer
POST	/inventory/withdrawals/:id/refresh	Atualizar status do saque	Requer
GET	/inventory/withdrawals/history	Historico de saques de skin	Requer

Pagamentos (/payment)

Metodo	Endpoint	Descricao	Auth
POST	/payment/deposit/initiate	Iniciar deposito	Requer
POST	/payment/deposit/webhook/:provider	Webhook de confirmacao	Publico
GET	/payment/deposits	Historico de depositos	Requer
POST	/payment/withdraw/request	Solicitar saque BRL	Requer
POST	/payment/withdraw/:id/confirm	Confirmar saque com 2FA	Requer
GET	/payment/withdrawals	Historico de saques BRL	Requer
GET	/payment/transactions	Historico de transacoes	Requer
POST	/payment/2fa/setup	Gerar secret e QR code 2FA	Requer
POST	/payment/2fa/enable	Ativar 2FA	Requer
POST	/payment/2fa/disable	Desativar 2FA	Requer
POST	/payment/2fa/verify	Verificar token 2FA	Requer

Evento / Passe (/event)

Metodo	Endpoint	Descricao	Auth
GET	/event/active	Eventos ativos	Publico
GET	/event/:id/progress	Progresso do usuario no evento	Requer
POST	/event/:id/claim	Resgatar recompensa de nivel	Requer

Event Shoot (/event-shoot)

Metodo	Endpoint	Descricao	Auth
POST	/event-shoot/shoot	Atirar em caixa do evento (250-5000 tickets)	Requer

Live Drops (/live-drops)

Metodo	Endpoint	Descricao	Auth
GET	/live-drops/recent	Drops recentes globais	Publico
GET	/live-drops/top	Top drops (chance <= 2%)	Publico

Provably Fair (/provably-fair)

Metodo	Endpoint	Descricao	Auth
POST	/provably-fair/generate-seeds	Gerar seeds	Publico
POST	/provably-fair/verify-seed	Verificar hash do server seed	Publico
POST	/provably-fair/calculate-result	Calcular resultado	Publico
POST	/provably-fair/verify-result	Verificar resultado	Publico

Notificacoes (/notifications)

Metodo	Endpoint	Descricao	Auth
GET	/notifications	Listar notificacoes	Requer
GET	/notifications/unread-count	Contagem de nao lidas	Requer
POST	/notifications/:id/read	Marcar como lida	Requer
POST	/notifications/read-all	Marcar todas como lidas	Requer

Auditoria (/audit)

Metodo	Endpoint	Descricao	Auth
GET	/audit/my-logs	Logs do usuario atual	Requer
GET	/audit/verify-chain	Verificar integridade da chain	Admin
GET	/audit/entity/:type/:id	Logs de uma entidade	Admin

Itens Publicos (/items)

Metodo	Endpoint	Descricao	Auth
GET	/items	Listar itens Waxpeer (20% margem)	Publico
GET	/items/categories	Categorias de armas	Publico
GET	/items/rarities	Raridades disponiveis	Publico
GET	/items/cheap	Itens baratos ($0 - $0.50)	Publico
GET	/items/stats	Estatisticas de itens	Publico
GET	/items/exchange-rate	Taxa USD/BRL atual	Publico
POST	/items/sync	Sincronizar itens do Waxpeer	Admin

Admin (/admin)

Todos os endpoints admin requerem AdminGuard.

Dashboard

Metodo	Endpoint	Descricao
GET	/admin/dashboard/stats	Estatisticas gerais
GET	/admin/dashboard/revenue-chart	Grafico de receita
GET	/admin/dashboard/overview	Overview com GGR
GET	/admin/dashboard/recent-activity	Atividade recente

Usuarios

Metodo	Endpoint	Descricao
GET	/admin/users	Listar usuarios (filtros)
GET	/admin/users/:id	Detalhes do usuario
PUT	/admin/users/:id/status	Atualizar status
POST	/admin/users/:id/balance	Ajustar saldo
POST	/admin/users/:id/ban	Banir usuario
POST	/admin/users/:id/unban	Desbanir usuario
GET	/admin/users/:userId/case-openings	Aberturas do usuario
GET	/admin/users/:userId/battles	Batalhas do usuario
GET	/admin/users/:userId/transactions	Transacoes do usuario

Caixas

Metodo	Endpoint	Descricao
GET	/admin/cases	Listar caixas (filtros)
GET	/admin/cases/:id	Caixa com itens
POST	/admin/cases	Criar caixa
PATCH	/admin/cases/:id	Atualizar caixa
DELETE	/admin/cases/:id	Deletar caixa
POST	/admin/cases/:caseId/items	Adicionar item a caixa
DELETE	/admin/cases/:caseId/items/:itemId	Remover item da caixa

Itens

Metodo	Endpoint	Descricao
GET	/admin/items	Listar itens (filtros)
GET	/admin/items/:id	Detalhes do item
POST	/admin/items	Criar item
PATCH	/admin/items/:id	Atualizar item
DELETE	/admin/items/:id	Deletar item

Batalhas

Metodo	Endpoint	Descricao
GET	/admin/battles	Listar batalhas (filtros)
GET	/admin/battles/:id	Detalhes da batalha
POST	/admin/battles/:id/cancel	Cancelar e reembolsar

Depositos

Metodo	Endpoint	Descricao
GET	/admin/deposits	Listar depositos (filtros)
POST	/admin/deposits/:id/confirm	Confirmar deposito
POST	/admin/deposits/:id/reject	Rejeitar deposito

Saques

Metodo	Endpoint	Descricao
GET	/admin/withdrawals	Listar saques (filtros)
POST	/admin/withdrawals/:id/approve	Aprovar saque
POST	/admin/withdrawals/:id/reject	Rejeitar e reembolsar
POST	/admin/withdrawals/:id/complete	Marcar como concluido

Transacoes

Metodo	Endpoint	Descricao
GET	/admin/transactions	Listar transacoes (filtros)

Analytics

Metodo	Endpoint	Descricao
GET	/admin/analytics/rtp-by-case	RTP por caixa
GET	/admin/analytics/battle-rtp	RTP de batalhas
GET	/admin/analytics/upgrade-stats	Estatisticas de upgrades
GET	/admin/analytics/bot-profitability	Lucratividade dos bots
GET	/admin/analytics/user-stats	Aquisicao/retencao
GET	/admin/analytics/financial-overview	Overview financeiro
GET	/admin/analytics/ggr	GGR com breakdown
GET	/admin/analytics/ggr-by-user	GGR por usuario

Integracao de Itens - Admin (/admin/items)

Metodo	Endpoint	Descricao	Auth
POST	/admin/items/sync-steam-database	Sincronizar itens do Steam Database	Admin
POST	/admin/items/update-prices	Atualizar precos via Waxpeer	Admin
GET	/admin/items/items	Listar itens Waxpeer (raw)	Admin
GET	/admin/items/steam-database/items	Listar itens Steam Database	Admin
GET	/admin/items/steam-database/collections	Listar colecoes	Admin
POST	/admin/items/steam-database/clear-cache	Limpar cache	Admin
GET	/admin/items/weapon-categories	Mapeamento de categorias	Admin

Health (/health)

Metodo	Endpoint	Descricao	Auth
GET	/health	Health check	Publico
GET	/health/ready	Readiness check	Publico
GET	/health/live	Liveness check	Publico

Exemplo - Abrir Caixa

curl -X POST https://api.procases.example/api/cases/123/open \
  -H "Cookie: sessionId=abc123" \
  -H "Content-Type: application/json"

Response:

{
  "openingId": "789012345678901234",
  "item": {
    "id": "456",
    "name": "AWP | Dragon Lore",
    "rarity": "EXTRAORDINARY",
    "valueCentsBrl": 70765,
    "imageUrl": "https://..."
  },
  "roll": 9845230,
  "serverSeedHash": "abc123...",
  "isFlip": false
}

Exemplo - Sacar Skin via Inventario

curl -X POST https://api.procases.example/api/inventory/456/withdraw \
  -H "Cookie: sessionId=abc123" \
  -H "Content-Type: application/json"

Response:

{
  "withdrawalId": "wd123456789",
  "itemName": "AWP | Dragon Lore",
  "status": "PENDING",
  "provider": "WAXPEER",
  "requestedAt": "2024-01-15T10:30:00Z"
}