Documentação do WalletsApp

Esta documentação existe porque o Swagger de cada API documenta contrato (rota, schema, código de erro), mas não documenta fluxo de negócio, decisões e o porquê das coisas. O Swagger continua sendo a fonte de verdade para o formato exato de request/response; aqui explicamos como usá-lo, na ordem certa, com o contexto que falta.

O conteúdo está separado por quem vai usar a API, porque cada perfil só enxerga uma fatia do sistema:

Perfil	Onde opera	Autentica como
Gestão	wallet-admin	principal_type=management
PDV	terminal de venda no evento	principal_type=operator, operator_type=pdv
Caixa	wallet-cashier	principal_type=operator, operator_type=cashier
Participante	app do usuário final	principal_type=user

Se você não sabe por qual perfil começar, veja Arquitetura primeiro — explica como os quatro repositórios (wallet-edge, wallet-control-api, wallet-api, mais os frontends) se encaixam e onde cada dado mora.

Como esta documentação é organizada

Cada seção de perfil segue a mesma estrutura, na ordem em que você realmente vai precisar:

1. Visão geral — o que esse perfil pode e não pode fazer hoje.
2. Autenticação — como logar, o que o token contém, cookies quando existem.
3. Páginas específicas por funcionalidade (perfil, organizações, wallets...).

Endpoints são sempre referenciados como MÉTODO /caminho, com um resumo do que fazem e um link mental pro Swagger do serviço dono daquele caminho:

• wallet-control-api → /docs (identidade global, gestão, diretórios)
• wallet-api (regional) → /docs (wallets, saldos, ledger)

Convenções que valem para todos os perfis

• Toda chamada passa pela wallet-edge. Nenhum cliente chama wallet-control-api ou wallet-api diretamente; a Edge decide se a rota é global ou regional (por eventId) e assina a chamada internamente.

• JWT nunca carrega saldo, wallet ou permissão mutável. Só identidade e contexto estável (principal_type, app_user_id/operator_account_id, session_id, e para operadores também operator_type/event_id).

• Erros seguem um envelope estável em toda API:

  {
    "error": {
      "code": "STABLE_MACHINE_CODE",
      "message": "Human-readable message",
      "correlationId": "uuid"
    }
  }

• Cookies são isolados por perfil. wallet_management_*, wallet_user_*, wallet_pdv_*, wallet_cashier_* nunca se misturam; um token de um perfil contra a rota .../me de outro perfil recebe 401 AUTHENTICATION_PROFILE_MISMATCH.