Status: Approved · v2 · SPEC-API-FINANCE-001

depends_on: SPEC-DOMAIN-WALLET-001, SPEC-DOMAIN-PAYMENT-001, SPEC-DOMAIN-SPONSOR-001

used_by: IS-MVP-09.1, IS-MVP-09.2, IS-MVP-09.3, IS-MVP-09.4, IS-MVP-10.1, IS-MVP-10.2

API de carteira, apoio, pagamentos e patrocínio

Fluxos financeiros rastreáveis, idempotentes e sem linguagem/semântica de aposta ou saque.

Princípios e padrões

• Base path /api/v1; JSON UTF-8; chaves em camelCase.
• Toda resposta usa ApiResponse<T> com ok, data|error e meta contendo requestId e timestamp.
• IDs são strings opacas; datas são ISO-8601 UTC; dinheiro é inteiro em centavos com moeda BRL.
• Listas usam page e pageSize no MVP; default 20, máximo 100; metadados ficam em meta.pagination.
• Endpoints públicos usam DTOs públicos específicos; entidades internas, memberships, saldos e dados privados nunca vazam.
• Erros de domínio são estáveis e acionáveis; stack traces e detalhes internos não são retornados.
• Alterações sensíveis usam Idempotency-Key, confirmação recente quando necessário e audit log.
• Uploads usam fluxo presigned; o backend valida propósito, MIME, tamanho e ownership antes de confirmar o asset.

Endpoints

Método	Rota	Acesso	Request	Response	Regras principais
GET	/wallets/:ownerType/:ownerId	wallet.view	—	WalletResponse	Saldo disponível/a expirar; sem float.
GET	/wallets/:ownerType/:ownerId/entries	wallet.viewLedger	LedgerQuery	WalletEntriesResponse	Extrato privado.
POST	/wallets/:ownerType/:ownerId/use	wallet.useCredits	UseCreditsRequest	WalletTransactionResponse	Ação paga interna.
POST	/wallets/:ownerType/:ownerId/transfers	wallet.transfer	TransferCreditsRequest	WalletTransferResponse	Apenas team↔torcida vinculada.
POST	/support	Público	CreateSupportRequest	PaymentResponse	Anônimo ou identificado.
POST	/payments/pix	Público/contextual	CreatePixPaymentRequest	PaymentResponse	Purpose validado.
GET	/payments/:paymentId	Público com secure token ou owner	—	PaymentResponse	Status/expiração.
POST	/payments/:paymentId/check-status	Contextual	—	PaymentResponse	Não confirma pelo cliente.
POST	/webhooks/pix/:provider	Provider signed	ProviderWebhookPayload	OperationResponse	Idempotente e autenticado.
GET	/:entityType/:entityId/sponsorship/availability	Público	—	SponsorAvailabilityResponse	3 slots incluindo reservas pending.
POST	/sponsorships	Público	CreateSponsorshipRequest	PaymentResponse	Pacote e conteúdo.
PATCH	/sponsorships/:id/content	sponsor/manage entity	UpdateSponsorContentRequest	SponsorshipResponse	Dados visuais; não pausa/remove ativo no MVP.

Autenticação e autorização

• Wallet e ledger exigem permissions.
• Support/sponsor checkout pode ser anônimo; identified support exige auth.
• Webhook usa assinatura/provider allowlist.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
INSUFFICIENT_CREDITS	409	Saldo disponível menor	Mostrar necessidade.
TRANSFER_NOT_ALLOWED	422	Entidades não vinculadas/direção inválida	Bloquear.
PAYMENT_EXPIRED	410	Pix expirado	Gerar novo.
PAYMENT_ALREADY_PROCESSED	409	Efeito já aplicado	Exibir status.
SPONSOR_LIMIT_REACHED	409	3 slots ativos/pending	Não abrir checkout.
INVALID_SUPPORT_AMOUNT	422	Fora dos valores/regras	Corrigir.

Idempotência e concorrência

• Todas as POST financeiras exigem key.
• Webhook event ID único; payment transition monotônica.
• Credits consumption usa FIFO em transação.

Auditoria e efeitos colaterais

• Ledger é audit trail financeiro; audit log cobre actor/admin changes.
• Paid support/sponsor cria credit lots com splits; campeonato não cria wallet credit.

Exemplos

support

{
  "targetType": "team",
  "targetId": "team_001",
  "amount": {
    "amountInCents": 2000,
    "currency": "BRL"
  },
  "identityMode": "anonymous"
}

payment

{
  "id": "payment_001",
  "purpose": "donation_support",
  "status": "waiting_payment",
  "amount": {
    "amountInCents": 2000,
    "currency": "BRL"
  },
  "pix": {
    "copyPasteCode": "000201...",
    "expiresAt": "2026-07-12T18:30:00.000Z"
  }
}

Mocks

• Fake provider permite waiting/paid/expired/failed.
• Clock control para expiração e credit lots.
• Ledger stateful e resetável.

Testes obrigatórios

• 95/5 support split.
• 80/20 sponsor split.
• Champ publication no wallet.
• FIFO expiration.
• Webhook duplicate.
• Slot reservation.
• Anonymous privacy.

Critérios de aceite

• Nenhum fluxo permite saque.
• Valores e splits corretos.
• Cliente nunca confirma pagamento.
• Máximo de 3 sponsors.

Machine summary

spec: SPEC-API-FINANCE-001
api_group: API de carteira, apoio, pagamentos e patrocínio
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents