WalletsApp Documentation

This documentation exists because each API's Swagger documents contract (route, schema, error code), but not business flow, decisions, and the why behind things. Swagger remains the source of truth for the exact request/response shape; here we explain how to use it, in the right order, with the context that's missing.

Content is split by who is going to use the API, because each profile only ever sees a slice of the system:

Profile	Where it operates	Authenticates as
Management	wallet-admin	principal_type=management
PDV	point-of-sale terminal at the event	principal_type=operator, operator_type=pdv
Cashier	wallet-cashier	principal_type=operator, operator_type=cashier
Participant	end-user app	principal_type=user

If you don't know where to start, read Architecture first — it explains how the four repositories (wallet-edge, wallet-control-api, wallet-api, plus the frontends) fit together and where each piece of data lives.

How this documentation is organized

Every profile section follows the same structure, in the order you'll actually need it:

1. Overview — what this profile can and can't do today.
2. Authentication — how to log in, what the token contains, cookies when they exist.
3. Feature-specific pages (profile, organizations, wallets...).

Endpoints are always referenced as METHOD /path, with a summary of what they do and a mental link to the Swagger of the service that owns that path:

• wallet-control-api → /docs (global identity, management, directories)
• wallet-api (regional) → /docs (wallets, balances, ledger)

Conventions that apply to every profile

• Every call goes through wallet-edge. No client ever calls wallet-control-api or wallet-api directly; the Edge decides whether a route is global or regional (by eventId) and signs the origin call internally.

• The JWT never carries balance, wallet, or a mutable permission. Only identity and stable context (principal_type, app_user_id/operator_account_id, session_id, and for operators also operator_type/event_id).

• Errors follow a stable envelope across every API:

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

• Cookies are isolated per profile. wallet_management_*, wallet_user_*, wallet_pdv_*, wallet_cashier_* never mix; a token from one profile against another profile's .../me route gets 401 AUTHENTICATION_PROFILE_MISMATCH.