Skip to content

Carteiras & Transacoes

Gerencia a carteira financeira de cada motorista, historico de transacoes e saques via Pix.

Fluxo de saque

Driver solicita saque
        |
        v
POST /wallets/withdraw
        |
        v
ASAAS processa transferencia Pix
        |
     sucesso?
    /        \
  sim         nao
   |           |
   v           v
TRANSFER_DONE  TRANSFER_FAILED
(webhook)      (webhook)
   |           |
   v           v
withdrawal.status = completed
             withdrawal.status = failed

GET /api/v1/wallets/me

Retorna o saldo atual da carteira do motorista autenticado.

Auth: Bearer token — role driver

Response 200 OK

Campo Tipo Descricao
id UUID ID da carteira
driver_id UUID ID do motorista proprietario
balance string Saldo disponivel em BRL (formato decimal: "29.00")
updated_at datetime Ultima atualizacao

Exemplo de response

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

import requests
from decimal import Decimal

BASE_URL = "https://fast-deliv-backend.vercel.app"
headers = {"Authorization": f"Bearer {TOKEN}"}

resp = requests.get(f"{BASE_URL}/api/v1/wallets/me", headers=headers)
resp.raise_for_status()
wallet = resp.json()

balance = Decimal(wallet["balance"])
print(f"Saldo atual: R$ {balance:.2f}")

const resp = await fetch(`${BASE_URL}/api/v1/wallets/me`, { headers });
const wallet = await resp.json();
console.log(`Saldo atual: R$ ${parseFloat(wallet.balance).toFixed(2)}`);

curl -s "${BASE_URL}/api/v1/wallets/me" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq '{balance, updated_at}'

uri = URI("#{BASE_URL}/api/v1/wallets/me")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{TOKEN}"
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
wallet = JSON.parse(http.request(req).body)
puts "Saldo: R$ #{wallet['balance']}"

GET /api/v1/wallets/me/transactions

Lista o historico de transacoes da carteira do motorista.

Auth: Bearer token — role driver

Response 200 OK

Array de objetos Transaction:

Campo Tipo Descricao
id UUID ID da transacao
wallet_id UUID ID da carteira
delivery_id UUID ou null Entrega relacionada (se for credito de entrega)
type string credit (entrega concluida) ou debit (saque)
amount string Valor em BRL (sempre positivo)
description string Descricao da transacao
created_at datetime Data da transacao 
resp = requests.get(
    f"{BASE_URL}/api/v1/wallets/me/transactions",
    headers=headers,
)
transactions = resp.json()

total_creditos = sum(
    float(t["amount"]) for t in transactions if t["type"] == "credit"
)
print(f"Total de creditos: R$ {total_creditos:.2f}")

const resp = await fetch(
  `${BASE_URL}/api/v1/wallets/me/transactions`,
  { headers }
);
const transactions = await resp.json();

const totalCredits = transactions
  .filter((t) => t.type === "credit")
  .reduce((sum, t) => sum + parseFloat(t.amount), 0);

console.log(`Total de creditos: R$ ${totalCredits.toFixed(2)}`);

curl -s "${BASE_URL}/api/v1/wallets/me/transactions" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq '[.[] | select(.type == "credit")] | length'

uri = URI("#{BASE_URL}/api/v1/wallets/me/transactions")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{TOKEN}"
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
transactions = JSON.parse(http.request(req).body)

total = transactions
  .select { |t| t['type'] == 'credit' }
  .sum { |t| t['amount'].to_f }
puts "Total de creditos: R$ #{'%.2f' % total}"

POST /api/v1/wallets/withdraw

Solicita um saque Pix para a conta do motorista. A transferencia e processada via ASAAS.

Auth: Bearer token — role driver

Request body

Campo Tipo Obrigatorio Descricao
amount string sim Valor a sacar em BRL (ex: "50.00")
pix_key string sim Chave Pix de destino
pix_key_type string sim Tipo da chave: cpf, phone, email, random

Tipos de chave Pix aceitos

Tipo Formato Exemplo
cpf 11 digitos numericos "12345678901"
phone +55 + DDD + numero "+5562999990001"
email Email valido "motorista@email.com"
random UUID gerado pelo banco "550e8400-e29b-41d4..."

Response 202 Accepted

{
  "id": "withdrawal-uuid-0001",
  "wallet_id": "wallet-uuid-0001",
  "amount": "50.00",
  "pix_key": "motorista@email.com",
  "pix_key_type": "email",
  "status": "pending",
  "asaas_transfer_id": "tra_xxxxxxxxxxxx",
  "created_at": "2026-05-19T15:00:00Z"
}

Erros

Codigo Causa
422 Saldo insuficiente
422 Tipo de chave Pix invalido
502 ASAAS indisponivel 
resp = requests.post(
    f"{BASE_URL}/api/v1/wallets/withdraw",
    headers=headers,
    json={
        "amount": "50.00",
        "pix_key": "motorista@email.com",
        "pix_key_type": "email",
    },
)
resp.raise_for_status()
withdrawal = resp.json()
print(f"Saque solicitado: {withdrawal['id']} — status: {withdrawal['status']}")

const resp = await fetch(`${BASE_URL}/api/v1/wallets/withdraw`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    amount: "50.00",
    pix_key: "motorista@email.com",
    pix_key_type: "email",
  }),
});
const withdrawal = await resp.json();
console.log(`Saque solicitado: ${withdrawal.id} — ${withdrawal.status}`);

curl -s -X POST "${BASE_URL}/api/v1/wallets/withdraw" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "50.00",
    "pix_key": "motorista@email.com",
    "pix_key_type": "email"
  }' | jq '{id, status, amount}'

uri = URI("#{BASE_URL}/api/v1/wallets/withdraw")
req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Bearer #{TOKEN}"
req['Content-Type'] = 'application/json'
req.body = JSON.dump(
  amount: '50.00',
  pix_key: 'motorista@email.com',
  pix_key_type: 'email'
)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
withdrawal = JSON.parse(http.request(req).body)
puts "Saque: #{withdrawal['id']} — #{withdrawal['status']}"

Status do saque

O saque inicia com status pending. A confirmacao chega via webhook ASAAS quando a transferencia Pix e processada.