Modelo de Dados — Carteira & Transacoes

Tres objetos relacionados: Wallet, Transaction e Withdrawal.

---

Wallet

Representa o saldo atual do motorista.

Campos

Campo	Tipo	Nullable	Descricao
id	UUID	nao	Identificador unico da carteira
driver_id	UUID	nao	ID do motorista proprietario
balance	string	nao	Saldo disponivel em BRL (decimal)
updated_at	datetime	nao	Ultima atualizacao do saldo

Exemplo

{
  "id": "wallet-550e8400-0001",
  "driver_id": "550e8400-e29b-41d4-a716-446655440001",
  "balance": "87.50",
  "updated_at": "2026-05-19T14:00:00Z"
}

---

Transaction

Cada movimentacao financeira na carteira (credito de entrega ou debito de saque).

Campos

Campo	Tipo	Nullable	Descricao
id	UUID	nao	Identificador unico
wallet_id	UUID	nao	Carteira relacionada
delivery_id	UUID	sim	Entrega que gerou o credito (null para saques)
type	string	nao	"credit" (entrega concluida) ou "debit" (saque)
amount	string	nao	Valor em BRL, sempre positivo
description	string	nao	Descricao legivel da movimentacao
created_at	datetime	nao	Data da transacao

Exemplo — credito

{
  "id": "txn-550e8400-0001",
  "wallet_id": "wallet-550e8400-0001",
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "credit",
  "amount": "29.00",
  "description": "Credito pela entrega: Entrega Centro",
  "created_at": "2026-05-19T11:45:00Z"
}

Exemplo — debito (saque)

{
  "id": "txn-550e8400-0002",
  "wallet_id": "wallet-550e8400-0001",
  "delivery_id": null,
  "type": "debit",
  "amount": "50.00",
  "description": "Saque Pix para carlos@motoboy.com",
  "created_at": "2026-05-19T15:00:00Z"
}

---

Withdrawal

Representa uma solicitacao de saque Pix.

Campos

Campo	Tipo	Nullable	Descricao
id	UUID	nao	Identificador unico do saque
wallet_id	UUID	nao	Carteira de origem
amount	string	nao	Valor solicitado em BRL
pix_key	string	nao	Chave Pix de destino
pix_key_type	string	nao	Tipo: cpf, phone, email, random
status	string	nao	pending, completed ou failed
asaas_transfer_id	string	sim	ID da transferencia no ASAAS
failure_reason	string	sim	Motivo de falha (preenchido se status=failed)
created_at	datetime	nao	Data da solicitacao
completed_at	datetime	sim	Data de conclusao (via webhook ASAAS)

Valores do campo status

Valor	Descricao
pending	Solicitado, aguardando processamento ASAAS
completed	Transferencia Pix confirmada
failed	Falha na transferencia — ver failure_reason

Exemplo

{
  "id": "withdrawal-550e8400-0001",
  "wallet_id": "wallet-550e8400-0001",
  "amount": "50.00",
  "pix_key": "carlos@motoboy.com",
  "pix_key_type": "email",
  "status": "completed",
  "asaas_transfer_id": "tra_xxxxxxxxxxxx",
  "failure_reason": null,
  "created_at": "2026-05-19T15:00:00Z",
  "completed_at": "2026-05-19T15:01:30Z"
}