Reservei Docs
Referência da API

Wallet

Gerenciar carteira virtual para pagamentos de reservas

Wallet

A Wallet é sua carteira virtual para pagamento de reservas. Todas as transações de emissão de bilhetes são debitadas do saldo da wallet.

Como Funciona

  1. Você recarrega sua wallet via PIX, boleto ou cartão
  2. Ao criar reservas com type: instant, o valor é debitado automaticamente
  3. Para reservas hold, o débito ocorre na confirmação

Modo de Teste

Quando você usa uma chave de API de teste, a carteira funciona em modo sandbox:

  • Saldo fictício: R$ 5.000,00 disponível automaticamente
  • Transações simuladas: Depósitos e débitos não afetam o saldo real
  • Sem integração real: Não há cobranças reais via PIX/Boleto

Importante

O saldo de teste é sempre R$ 5.000,00 independente das transações de teste realizadas. Isso permite testar a integração sem se preocupar com saldo.

Todas as respostas incluem um campo _meta indicando o modo:

{
  "success": true,
  "data": { ... },
  "_meta": {
    "test_mode": true,
    "message": "Saldo fictício de R$ 5.000,00 para testes"
  }
}

GET /api/v1/wallet/balance

Obtém o saldo atual da carteira.

Response

{
  "success": true,
  "data": {
    "balance": "15750.00",
    "currency": "BRL",
    "available_credit": "15750.00",
    "pending_amount": "2500.00",
    "last_transaction_at": "2025-01-14T15:30:00Z"
  }
}

Campos

CampoTipoDescrição
balancestringSaldo total disponível
currencystringMoeda (sempre BRL)
available_creditstringCrédito disponível para uso imediato
pending_amountstringValor em reservas pendentes (hold)
last_transaction_atstringData da última movimentação

Exemplo

curl -X GET https://app.reservei.co/api/v1/wallet/balance \
  -H "Authorization: Bearer sua_chave_aqui"
const response = await fetch('https://app.reservei.co/api/v1/wallet/balance', {
  headers: {
    'Authorization': `Bearer ${process.env.RESERVEI_API_KEY}`
  }
});

const { data } = await response.json();
console.log(`Saldo disponível: R$ ${data.balance}`);
import requests

response = requests.get(
    'https://app.reservei.co/api/v1/wallet/balance',
    headers={'Authorization': f'Bearer {api_key}'}
)

data = response.json()['data']
print(f"Saldo disponível: R$ {data['balance']}")

GET /api/v1/wallet/transactions

Lista todas as transações da carteira com paginação e filtros.

Query Parameters

ParâmetroTipoPadrãoDescrição
pagenumber1Página atual
limitnumber20Itens por página (máx: 100)
typestring-Filtrar por tipo: credit ou debit
start_datestring-Data inicial (YYYY-MM-DD)
end_datestring-Data final (YYYY-MM-DD)

Response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_0000AbCdEf123456",
        "type": "debit",
        "amount": "7825.60",
        "currency": "BRL",
        "description": "Reserva de voo - XJ59L2",
        "reference_type": "booking",
        "reference_id": "ord_0000GhIjKl789012",
        "balance_after": "7924.40",
        "created_at": "2025-01-15T10:30:00Z"
      },
      {
        "id": "txn_0000MnOpQr345678",
        "type": "credit",
        "amount": "10000.00",
        "currency": "BRL",
        "description": "Recarga via PIX",
        "reference_type": "recharge",
        "reference_id": "rch_0000StUvWx901234",
        "balance_after": "15750.00",
        "payment_method": "pix",
        "created_at": "2025-01-14T15:30:00Z"
      },
      {
        "id": "txn_0000YzAbCd567890",
        "type": "credit",
        "amount": "1100.50",
        "currency": "BRL",
        "description": "Estorno - Cancelamento reserva ABC123",
        "reference_type": "refund",
        "reference_id": "ord_0000...",
        "balance_after": "5750.00",
        "created_at": "2025-01-12T09:15:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 127,
      "pages": 7
    },
    "summary": {
      "total_credits": "45000.00",
      "total_debits": "29250.00",
      "period_start": "2025-01-01",
      "period_end": "2025-01-15"
    }
  }
}

Campos da Transação

CampoTipoDescrição
idstringID único da transação
typestringcredit (entrada) ou debit (saída)
amountstringValor da transação
currencystringMoeda (sempre BRL)
descriptionstringDescrição da transação
reference_typestringTipo de referência (booking, recharge, refund)
reference_idstringID da entidade relacionada
balance_afterstringSaldo após a transação
payment_methodstringMétodo de pagamento (para recargas)
created_atstringData/hora da transação

POST /api/v1/wallet/recharge

Solicita uma recarga da carteira. Retorna dados para pagamento.

Request

{
  "amount": "5000.00",
  "currency": "BRL",
  "payment_method": "pix"
}

Parâmetros

CampoTipoObrigatórioDescrição
amountstringSimValor da recarga (mínimo: R$ 100,00)
currencystringSimMoeda (sempre BRL)
payment_methodstringSimMétodo: pix, boleto

Response (PIX)

{
  "success": true,
  "data": {
    "id": "rch_0000AbCdEf123456",
    "amount": "5000.00",
    "currency": "BRL",
    "status": "pending",
    "payment_method": "pix",
    "payment": {
      "pix_copy_paste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540550005802BR5925RESERVEI TECNOLOGIA LTDA6009SAO PAULO62070503***6304ABCD",
      "pix_qrcode_url": "https://app.reservei.co/api/v1/pix/qr/rch_0000AbCdEf123456",
      "expires_at": "2025-01-15T12:00:00Z"
    },
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Response (Boleto)

{
  "success": true,
  "data": {
    "id": "rch_0000AbCdEf123456",
    "amount": "5000.00",
    "currency": "BRL",
    "status": "pending",
    "payment_method": "boleto",
    "payment": {
      "boleto_barcode": "23793.38128 60000.000003 00000.000400 1 84340000500000",
      "boleto_url": "https://app.reservei.co/api/v1/boleto/rch_0000AbCdEf123456",
      "boleto_pdf_url": "https://app.reservei.co/api/v1/boleto/rch_0000AbCdEf123456/pdf",
      "expires_at": "2025-01-18T23:59:59Z"
    },
    "created_at": "2025-01-15T10:00:00Z"
  }
}

GET /api/v1/wallet/recharge/:id

Verifica o status de uma recarga específica.

Response

{
  "success": true,
  "data": {
    "id": "rch_0000AbCdEf123456",
    "amount": "5000.00",
    "currency": "BRL",
    "status": "completed",
    "payment_method": "pix",
    "paid_at": "2025-01-15T10:05:32Z",
    "transaction_id": "txn_0000MnOpQr345678",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Status da Recarga

StatusDescrição
pendingAguardando pagamento
completedPagamento confirmado, crédito adicionado
expiredPrazo de pagamento expirado
failedFalha no processamento
cancelledCancelada pelo usuário

Métodos de Pagamento

MétodoTempo de ConfirmaçãoDisponibilidade
pixInstantâneo (< 1 min)24/7
boleto1-3 dias úteisDias úteis

PIX Recomendado

Para maior agilidade, recomendamos o uso de PIX. O crédito é adicionado automaticamente após a confirmação do pagamento.


Limites e Regras

RegraValor
Recarga mínimaR$ 100,00
Recarga máxima por transaçãoR$ 50.000,00
Recarga máxima por diaR$ 100.000,00
Validade do PIX30 minutos
Validade do Boleto3 dias úteis

Webhooks de Wallet

Configure webhooks para ser notificado sobre eventos da wallet:

EventoDescrição
wallet.creditCrédito adicionado (recarga, estorno)
wallet.debitDébito realizado (reserva)
wallet.recharge.completedRecarga confirmada
wallet.recharge.expiredRecarga expirada
wallet.low_balanceSaldo abaixo de R$ 500,00

Exemplos de Integração

// 1. Verificar saldo antes de criar reserva
const balanceResponse = await fetch('https://app.reservei.co/api/v1/wallet/balance', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});
const { data: wallet } = await balanceResponse.json();

const bookingAmount = 7825.60;

if (parseFloat(wallet.balance) < bookingAmount) {
  // 2. Solicitar recarga via PIX
  const rechargeResponse = await fetch('https://app.reservei.co/api/v1/wallet/recharge', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: '10000.00',
      currency: 'BRL',
      payment_method: 'pix'
    })
  });
  
  const { data: recharge } = await rechargeResponse.json();
  
  // 3. Exibir QR Code para o cliente
  console.log('PIX Copia e Cola:', recharge.payment.pix_copy_paste);
  console.log('QR Code:', recharge.payment.pix_qrcode_url);
  
  // 4. Aguardar confirmação via webhook ou polling
  // ...
}

// 5. Criar reserva após saldo suficiente
const bookingResponse = await fetch('https://app.reservei.co/api/v1/bookings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    offerId: 'off_xxx',
    type: 'instant',
    passengers: [...],
    payments: [{ type: 'balance', amount: '1250.50', currency: 'USD' }]
  })
});
// Verificar saldo e alertar se baixo
async function checkBalance() {
  const response = await fetch('https://app.reservei.co/api/v1/wallet/balance', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });
  
  const { data } = await response.json();
  const balance = parseFloat(data.balance);
  
  if (balance < 1000) {
    // Enviar alerta para admin
    await sendSlackAlert(`⚠️ Saldo baixo na wallet: R$ ${balance.toFixed(2)}`);
  }
  
  return balance;
}

// Executar a cada hora
setInterval(checkBalance, 60 * 60 * 1000);
// Gerar relatório de transações do mês
async function getMonthlyReport(year, month) {
  const startDate = `${year}-${String(month).padStart(2, '0')}-01`;
  const endDate = `${year}-${String(month).padStart(2, '0')}-${new Date(year, month, 0).getDate()}`;
  
  let allTransactions = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://app.reservei.co/api/v1/wallet/transactions?page=${page}&limit=100&start_date=${startDate}&end_date=${endDate}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    
    const { data } = await response.json();
    allTransactions = [...allTransactions, ...data.transactions];
    
    hasMore = page < data.pagination.pages;
    page++;
  }
  
  // Calcular totais
  const totals = allTransactions.reduce((acc, txn) => {
    const amount = parseFloat(txn.amount);
    if (txn.type === 'credit') {
      acc.credits += amount;
    } else {
      acc.debits += amount;
    }
    return acc;
  }, { credits: 0, debits: 0 });
  
  return {
    period: `${month}/${year}`,
    totalTransactions: allTransactions.length,
    totalCredits: totals.credits.toFixed(2),
    totalDebits: totals.debits.toFixed(2),
    netChange: (totals.credits - totals.debits).toFixed(2)
  };
}

Erros Comuns

CódigoErroCausaSolução
400Minimum amount is R$ 100.00Recarga abaixo do mínimoAumente o valor
400Invalid payment methodMétodo não suportadoUse pix ou boleto
422Insufficient balanceSaldo insuficiente para débitoRecarregue a wallet
422Daily limit exceededLimite diário atingidoAguarde próximo dia
404Recharge not foundID de recarga inválidoVerifique o ID