💳 Cartão de Crédito — Guia de Implementação do Dashboard

Este documento descreve como o front-end deve integrar o módulo de cartão de crédito no dashboard, incluindo estrutura de páginas, chamadas à API, estados da UI e exemplos de componentes.

Sumário

Visão Geral do Dashboard
Estrutura de Rotas do Front-end
Páginas e Componentes
Chamadas à API
Estados de UI
Fluxo Completo

Visão Geral do Dashboard

O módulo de cartão no dashboard é composto por duas seções principais:

Dashboard
└── Cartão de Crédito
    ├── Extrato de Transações    → card_transactions (entradas)
    │     └── Cards de Totais   → GET /card-transactions/summary
    ├── Histórico de Retiradas  → card_withdrawals
    └── Botão de Retirada       → POST /card-withdrawals

O saldo de cartão é independente do saldo global. O operador visualiza os valores acumulados e decide quando retirar (ou aguarda o job D+1 automático).

Estrutura de Rotas do Front-end

/dashboard/card                     → Página principal (extrato + totais + botão retirar)
/dashboard/card/withdrawals         → Histórico de retiradas
/dashboard/card/withdrawals/:id     → Detalhe de uma retirada

Páginas e Componentes

Extrato de Cartão

Rota: /dashboard/card

Esta é a página principal. Exibe:

Cards de totais (buscados via /summary)
Botão "Realizar Retirada"
Tabela de transações paginada

Layout sugerido

┌─────────────────────────────────────────────────────────────────┐
│  CARTÃO DE CRÉDITO                          [Realizar Retirada] │
├──────────────┬──────────────┬──────────────┬────────────────────┤
│  💰 A Receber │ ✅ Liquidado  │  📊 Total     │  📦 Transações     │
│  R$ 725,50   │ R$ 2.378,50  │ R$ 3.104,00  │  18 registros      │
├──────────────┴──────────────┴──────────────┴────────────────────┤
│  FILTROS: [Status ▼]  [Data início]  [Data fim]  [Buscar]       │
├─────────────────────────────────────────────────────────────────┤
│  Data        │ Pagador          │ Valor    │ Taxa  │ Líquido │ S │
│  05/04/2026  │ João Silva       │ R$150,00 │ R$4,50│ R$145,50│ ⏳│
│  04/04/2026  │ Maria Souza      │ R$300,00 │ R$9,00│ R$291,00│ ✅│
└─────────────────────────────────────────────────────────────────┘

Campos da tabela

Coluna	Campo da API	Formatação
Data	`payment_date.formatted`	`dd/mm/YYYY`
Adquirente	`acquirer`	uppercase
Bandeira	`brand`	ícone (visa/mastercard)
Pagador	`payer.name`	—
Parcelas	`installments`	`1x`, `2x`...
Bruto	`amounts.gross`	`R$ 0.000,00`
Taxa	`amounts.fee`	`R$ 0.000,00`
Líquido	`amounts.net`	`R$ 0.000,00`
Status	`status`	badge colorido

Badge de status

PENDING   → 🟡 Amarelo  → "Aguardando retirada"
WITHDRAWN → 🟢 Verde    → "Retirado"

Resumo (Cards de Totais)

Alimentado por GET /consolidation/card-transactions/summary.

javascript

// Exemplo de resposta
{
  "total":     { "count": 18, "gross": 3200.00, "fee": 96.00, "net": 3104.00 },
  "pending":   { "count": 5,  "net": 725.50 },
  "withdrawn": { "count": 13, "net": 2378.50 }
}

Mapeamento de cards:

Card	Campo	Cor
💰 A Receber	`pending.net`	Amarelo/Laranja
✅ Já Liquidado	`withdrawn.net`	Verde
📊 Total Recebido	`total.net`	Azul
📦 Nº de Transações	`total.count`	Cinza

Dica: Mostrar o card "A Receber" com destaque quando pending.count > 0, indicando ao operador que há valores prontos para retirada.

Histórico de Retiradas

Rota: /dashboard/card/withdrawals

Lista paginada dos card_withdrawals. Ao clicar em uma linha, abre o detalhe (/withdrawals/:id).

Layout da tabela

┌──────────────────────────────────────────────────────────────────┐
│  HISTÓRICO DE RETIRADAS                                          │
├──────────┬───────────┬───────────┬──────────┬────────┬──────────┤
│  Data    │  Tipo     │  Período  │  Transaç.│ Líquido│  Status  │
│ 06/04    │ MANUAL    │ 01-05/04  │  7 itens │R$1.164 │ ✅ OK    │
│ 05/04    │ AUTOMATIC │ 04/04     │  3 itens │R$  450 │ ✅ OK    │
└──────────┴───────────┴───────────┴──────────┴────────┴──────────┘

Detalhe de uma retirada (`/withdrawals/:id`)

Exibe:

Header com totais (gross, fee, net)
Informações da transaction global gerada (txid, balance após)
Lista das cardTransactions incluídas nesta retirada

javascript

// Dados do detalhe
{
  "id": 4,
  "type": "MANUAL",
  "status": "COMPLETED",
  "transactions_count": 7,
  "amounts": { "gross": 1200, "fee": 36, "net": 1164 },
  "period": {
    "start": { "formatted": "30/03/2026" },
    "end":   { "formatted": "05/04/2026" }
  },
  "transaction": {
    "txid": "CC-WITHDRAW-F5E4D3C2",
    "value": 1164.00,
    "balance": 12988.00   // ← saldo global após a retirada
  }
}

Realizar Retirada

Modal acionado pelo botão "Realizar Retirada" na página de extrato.

1. Usuário clica em "Realizar Retirada"
2. Modal abre mostrando o saldo pendente disponível
3. Usuário define (opcional) até qual data retirar
4. Usuário adiciona observação (opcional)
5. Confirmação com resumo dos valores
6. POST /consolidation/card-withdrawals
7. Sucesso → toast de confirmação + atualiza totais + atualiza tabela

Campos do formulário

Campo	Tipo	Obrigatório	Descrição
`payment_date_until`	date picker	Não	Padrão: ontem. Retira tudo até esta data
`notes`	textarea	Não	Observação da retirada

Estados do botão de confirmação

[Confirmar Retirada]  → estado normal
[⏳ Processando...]   → durante a requisição (disabled)
[✅ Retirado!]        → sucesso (fecha modal após 1,5s)
[❌ Tentar novamente] → erro

Chamadas à API

Configuração base

javascript

// api/card.js
import axios from 'axios'

const BASE_URL = '/consolidation'

export const cardApi = {

  // Extrato de transações de cartão
  getTransactions: (params = \{\}) =>
    axios.get(`$\{BASE_URL\}/card-transactions`, { params }),

  // Totalizador (pending vs withdrawn)
  getSummary: (params = \{\}) =>
    axios.get(`$\{BASE_URL\}/card-transactions/summary`, { params }),

  // Histórico de retiradas
  getWithdrawals: (params = \{\}) =>
    axios.get(`$\{BASE_URL\}/card-withdrawals`, { params }),

  // Detalhe de uma retirada
  getWithdrawal: (id) =>
    axios.get(`$\{BASE_URL\}/card-withdrawals/$\{id\}`),

  // Criar retirada manual
  createWithdrawal: (data = \{\}) =>
    axios.post(`$\{BASE_URL\}/card-withdrawals`, data),
}

Parâmetros de filtro das transações

javascript

// Listagem com filtros
const params = {
  status: 'PENDING',               // ou 'WITHDRAWN'
  payment_date_start: '2026-04-01',
  payment_date_end:   '2026-04-06',
  per_page: 20,
  page: 1,
}

const { data } = await cardApi.getTransactions(params)
// data.data      → array de transações
// data.total     → total de registros
// data.last_page → total de páginas

Criar retirada (com tratamento de erro)

javascript

async function realizarRetirada() {
  try {
    isLoading.value = true
    const { data } = await cardApi.createWithdrawal({
      payment_date_until: dateUntil.value,   // 'YYYY-MM-DD' ou null
      notes: notes.value,
    })

    if (data.data === null) {
      // Sem saldo pendente
      toast.info(data.message)
      return
    }

    // Sucesso
    toast.success('Retirada realizada com sucesso!')
    emit('withdrawal-created', data.data)
    refreshSummary()
    refreshTransactions()
    closeModal()

  } catch (err) {
    const msg = err.response?.data?.message || 'Erro ao realizar retirada.'
    toast.error(msg)
  } finally {
    isLoading.value = false
  }
}

Estados de UI

Tela de carregamento

┌─────────────────────────┐
│  [████████░░░░░░] 60%   │  ← skeleton loader nos cards de total
│  Carregando extrato...  │
└─────────────────────────┘

Sem transações pendentes

┌─────────────────────────────────────┐
│       💳 Sem pagamentos pendentes   │
│                                     │
│   Todos os recebíveis de cartão     │
│   já foram transferidos para o      │
│   saldo global da conta.            │
│                                     │
│   [Ver histórico de retiradas]      │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  💳 Confirmar Retirada              │
│  ─────────────────────────────────  │
│  Transações incluídas:     7        │
│  Período:         01 a 05/04        │
│  Valor bruto:        R$ 1.200,00    │
│  Taxas:              R$    36,00    │
│  ─────────────────────────────────  │
│  Valor líquido:      R$ 1.164,00   │
│                                     │
│  Nota (opcional):                   │
│  [ Retirada quinzenal...          ] │
│                                     │
│  [Cancelar]        [Confirmar ✅]   │
└─────────────────────────────────────┘

Fluxo Completo

Usuário entra em /dashboard/card
    │
    ├─► GET /card-transactions/summary
    │       └─► Renderiza cards de totais
    │
    └─► GET /card-transactions?per_page=15&page=1
            └─► Renderiza tabela de transações

Usuário aplica filtro de data
    └─► GET /card-transactions?payment_date_start=...&payment_date_end=...

Usuário clica em "Realizar Retirada"
    │
    ├─► Modal exibe saldo pendente (usa dado já carregado do summary)
    ├─► Usuário preenche data e nota
    └─► POST /card-withdrawals { payment_date_until, notes }
            │
            ├─► 201 Created → Atualiza summary + tabela + toast sucesso
            └─► 200 (vazio) → toast info "Sem saldo pendente"

Usuário acessa /dashboard/card/withdrawals
    └─► GET /card-withdrawals?per_page=15&page=1
            └─► Tabela de retiradas

Usuário clica em uma linha da tabela
    └─► GET /card-withdrawals/:id
            └─► Exibe detalhe + transações incluídas

Dicas de UX

Polling leve: como o job D+1 roda às 06:00, não é necessário atualização em tempo real. Recarregue o summary uma vez ao entrar na página.
Destaque visual: quando pending.net > 0, exiba um badge na navegação lateral (ex: 💳 Cartão (1)) para alertar o operador.
Ordenação da tabela: padrão payment_date DESC, com opção de inverter clicando no header da coluna.
Formatação de moeda: sempre use Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }).
Paginação: carregar 15 itens por página com cursor paginado; ao rolar para baixo (infinite scroll) ou via controles numéricos.

💳 Cartão de Crédito — Guia de Implementação do Dashboard ​

Sumário ​

Visão Geral do Dashboard ​

Estrutura de Rotas do Front-end ​

Páginas e Componentes ​

Extrato de Cartão ​

Layout sugerido ​

Campos da tabela ​

Badge de status ​

Resumo (Cards de Totais) ​

Histórico de Retiradas ​

Layout da tabela ​

Detalhe de uma retirada (/withdrawals/:id) ​

Realizar Retirada ​

Fluxo do modal ​

Campos do formulário ​

Estados do botão de confirmação ​

Chamadas à API ​

Configuração base ​

Parâmetros de filtro das transações ​

Criar retirada (com tratamento de erro) ​

Estados de UI ​

Tela de carregamento ​

Sem transações pendentes ​

Confirmação de retirada (modal) ​

Fluxo Completo ​

Dicas de UX ​

💳 Cartão de Crédito — Guia de Implementação do Dashboard

Sumário

Visão Geral do Dashboard

Estrutura de Rotas do Front-end

Páginas e Componentes

Extrato de Cartão

Layout sugerido

Campos da tabela

Badge de status

Resumo (Cards de Totais)

Histórico de Retiradas

Layout da tabela

Detalhe de uma retirada (`/withdrawals/:id`)

Realizar Retirada

Fluxo do modal

Campos do formulário

Estados do botão de confirmação

Chamadas à API

Configuração base

Parâmetros de filtro das transações

Criar retirada (com tratamento de erro)

Estados de UI

Tela de carregamento

Sem transações pendentes

Confirmação de retirada (modal)

Fluxo Completo

Dicas de UX