Aparência

Fluxo de Saldo & Extrato (/consolidation) ​

Consulta de saldo, extrato (lista paginada de transações com saldo corrido), estatísticas do período e exportação de documentos.

  • Backend: fastgivr-api — App\Http\Controllers\Consolidation\{TransactionController, DataStatisticController}, App\Http\Controllers\ExportDownloadController
  • Rotas: routes/consolidation.php (prefixo /consolidation, name consolidation.), carregado por bootstrap/app.php
  • Middleware: auth:api,sanctum · SetActiveAccountMiddleware · InjectAccountIntoRequest (exceto exports/download/{id}, que é público e validado por link assinado)
  • Persistência: transactions (ledger), vw_balance / Balance
  • Ledger: cada crédito/débito é uma linha em transactions com type_id (TransactionType), value (± em BRL), status (1 confirmada, 2 liquidada com Pix, 4 conciliada) e balance (saldo corrido, recalculado na leitura).

Envelope padrão { code, success, data|<chave>, message? }. Alguns endpoints de gráfico devolvem JSON puro (sem envelope) — indicado abaixo.

1. Mapa de endpoints ​

MétodoRotaAção
GET/consolidation/balancesaldo atual da conta ativa
GET/consolidation/transactionsextrato — lista paginada + statistics (totais, saldos, by_type, daily_evolution)
GET/consolidation/transactions/{id}detalhe de uma transação
GET/consolidation/transactions/{id}/pdfcomprovante da transação em PDF (?download=0 inline)
POST/consolidation/transactions/exportexporta o extrato (mode=data planilha/CSV/PDF · mode=statement PDF de extrato, assíncrono)
GET/consolidation/transactions/dailyabertura/fechamento de saldo por dia (paginado por data)
GET/consolidation/transactions/by-typeagregado por tipo no período (contagem + soma)
GET/consolidation/transactions/time-seriessérie temporal de saldo/receitas/despesas (group_by=days|months)
GET/consolidation/transaction-typescatálogo de tipos de transação (cache 60 min)
GET/consolidation/methods-paymentmétodos de pagamento (PaymentMethod)
GET/consolidation/get-settlement-statementtotal recebido via Pix desde uma data (?start_date=)
POST/consolidation/statistic/cardscards de estatística (cards[] — ver §6)
GET/consolidation/statistic/boletoscontagem de boletos por status agrupada (group_by=day|month|year)
GET/consolidation/dashboardrelatório da Visão geral — saldo + totais (+ tendência) + contagens + by_type + daily_evolution + recent_transactions, numa chamada
GET/consolidation/exports/download/{id}download de uma exportação gerada (link assinado, sem auth)

Parâmetros de período aceitos pela maioria dos endpoints (o primeiro par presente vence): created_at_start/created_at_end, payment_date_start/_end, start_date/end_date, date_start/date_end, fromDate/toDate. Sem período ⇒ últimos 30 dias. Formato YYYY-MM-DD.

2. GET /consolidation/balance ​

Saldo atual da conta ativa (Balance::getBalance — soma de vw_balance por account_id + bank_code).

Resposta (JSON puro):

json
{ "balance": 1287.73 }

3. GET /consolidation/transactions — extrato ​

TransactionIndexRequest:

CampoRegra
searchnullable · string · max:100 — casa txid, end_to_end_id, description, nomes/documentos/bancos de pagador e recebedor
statusnullable · integer · in:-1,0,1,2,3
typenullable — um ou mais type_id (int) separados por vírgula ou array
type_id · type_ids[]nullable — filtro por id(s) de tipo
page · per_pagepaginação (per_page default 15)
order_by · order_dirin:created_at,payment_date,value,id · asc|desc
created_at_start · created_at_enddate_format:Y-m-d

Considera apenas status ∈ {1,2,4}. Ordena por created_at DESC, id DESC.

Resposta — PaginatedResourceCollection de TransactionResource + bloco statistics:

Cada linha segue o shape canônico de transação (trait SerializesTransaction, compartilhado por todos os resources de transação — público, QuickPay, consolidação e backoffice); a versão de consolidação acrescenta apenas status_description.

jsonc
{
  "data": [
    {
      "id": 128,
      "txid": "9c7b5073-...",
      "end_to_end_id": "E2026090208510224242962",
      "type_id": 1,
      "type": { "id": 1, "slug": "pix-in", "name": "Pix Recebido" },
      "description": null,
      "value": 42.50,            // + crédito · − débito
      "balance": 1287.73,        // saldo corrido APÓS esta transação
      "currency": "BRL",
      "status": 1,
      "status_description": "Confirmada",   // extra da consolidação
      "origin": "teste",
      "account_id": 3,
      "webhook_id": null,
      "payment_date": null,
      "payer_name": "Pagador Pix",
      "payer_document": null, "payer_bank_name": null,
      "payer_agency": null, "payer_account": null,
      "receiver_name": null,
      "receiver_document": null, "receiver_bank_name": null,
      "receiver_agency": null, "receiver_account": null,
      "metadata": { },
      "created_at": "2026-09-02T08:51:02-03:00",  // ISO 8601
      "updated_at": "2026-09-02T08:51:02-03:00"
    }
  ],
  "meta": { "total": 42, "page": 1, "limit": 15, "total_pages": 3, "has_next_page": true, "has_prev_page": false },
  "statistics": {
    "total_received": 2122.50,
    "total_paid": 834.77,
    "initial_balance": 0.0,        // saldo antes do período
    "final_balance": 1287.73,      // saldo ao fim do período
    "current_balance": 1287.73,    // saldo atual (Balance)
    "period": { "start_date": "2026-08-04", "end_date": "2026-09-02" },
    "by_type": [
      { "type_id": 1, "type_name": "Pix Recebido", "type_slug": "pix-in", "quantity": 6, "total_value": 2122.50 }
    ],
    "daily_evolution": [
      { "date": "2026-08-04", "balance": 0.0, "change": 0.0 },
      { "date": "2026-09-02", "balance": 1287.73, "change": 42.50 }
    ]
  }
}

created_at / updated_at / payment_date são strings ISO 8601. No frontend, dateValue() de src/lib/format.ts aceita string ou o objeto { full, formatted, human } (formato legado de outros resources).

O saldo corrido (balance por item) é calculado em memória na leitura: parte do final_balance (página 1, sem filtros) ou de uma soma pontual, e vai subtraindo value item a item.

4. Detalhe e comprovante ​

GET /consolidation/transactions/{id} ​

{id} restrito a [0-9]+. Devolve o TransactionResource da transação (escopo: conta ativa). 404 se não pertencer à conta.

GET /consolidation/transactions/{id}/pdf ​

Renderiza pdfs.transaction (dompdf, A4). Content-Type: application/pdf; Content-Disposition: attachment por padrão, inline com ?download=0. É o comprovante usado também pelo Pix Out (/pix/transfers/{id}/receipt?format=pdf aponta para a mesma view).

5. Exportação ​

POST /consolidation/transactions/export ​

modeComportamento
data (default)format=xlsx|csv|pdf. Com download=1 gera o arquivo na hora e devolve o binário. Sem download, enfileira ExportTransactionsJob/ExportTransactionsPdf e devolve { message } — o usuário recebe notificação in-app (DocumentExported) com o link.
statementExige start_date + end_date (YYYY-MM-DD, intervalo ≤ 60 dias). Enfileira ExportTransactionsPdf (PDF de extrato) e devolve { message }. Assíncrono.

Filtros de período/tipo/busca são os mesmos do extrato.

GET /consolidation/exports/download/{id} ​

Baixa uma exportação já gerada. Rota pública protegida por URL::temporarySignedRoute() — o link vem na notificação DocumentExported. O id é o identificador do documento; o formato é inferido do próprio registro.

6. Estatísticas e gráficos ​

POST /consolidation/statistic/cards ​

DataStatisticController::getStatisticBalanceData. Body:

json
{ "cards": ["PIXS_COUNT", "PIX_IN_SUM"], "start_date": "2026-08-01", "end_date": "2026-09-02" }

cards (required · array) — quais métricas calcular. Chaves suportadas:

ChaveValor
PIXS_COUNTnº de cobranças Pix no período
BOLETOS_COUNTnº de boletos emitidos
CLIENTS_COUNTnº de clientes cadastrados
CHARGE_COUNT_PAIDnº de cobranças pagas
CHARGE_SUM_PAIDsoma paga das cobranças
PIX_IN_SUMsoma dos créditos pix-in confirmados
PIX_OUT_SUMsoma dos débitos pix-out confirmados
TOTAL_CHARGE_EXPECTED_TO_RECEIVEsoma das cobranças pendentes

Resposta (JSON puro) — só as chaves pedidas:

json
{ "PIXS_COUNT": 6, "PIX_IN_SUM": 2122.5 }

GET /consolidation/transactions/time-series ​

group_by=days (default) ou months. Saldo/receitas/despesas acumulados por período no intervalo.

GET /consolidation/transactions/by-type ​

Agregado por type_id no período: total_transactions + total_value, ordenado pela quantidade.

GET /consolidation/transactions/daily ​

Uma linha por dia com movimentação: saldo de abertura, total de entradas, total de saídas e saldo de fechamento. Paginado por data (per_page).

GET /consolidation/get-settlement-statement ​

?start_date=YYYY-MM-DD (default: fim do mês anterior). Soma dos créditos Pix (type_id ∈ {1,7}, status=1) desde a data. Resposta: { total_received, start_date }.

GET /consolidation/statistic/boletos ​

group_by=day|month|year. Contagem de boletos por status (pending, paid, cancelled, expired, failed, deleted, paidwithpix) por grupo de data.

7. GET /consolidation/dashboard — relatório da Visão geral ​

Uma única chamada que compõe, com os mesmos números dos endpoints acima, tudo que a tela DashboardPage mostra. Consolidation\DashboardController. Cache de 2 min por (conta, período, recent_limit).

Query

CampoRegra
periodsometimes · integer · in:7,30,90 (default 30) — atalho de período
start_date · end_datedate_format:Y-m-d — período customizado (tem prioridade sobre period)
recent_limitsometimes · integer · 1..30 (default 8) — nº de transações em recent_transactions

Resposta — data sob a chave dashboard:

jsonc
{
  "dashboard": {
    "period": {
      "start_date": "2026-08-04", "end_date": "2026-09-02", "days": 30,
      "previous": { "start_date": "2026-07-05", "end_date": "2026-08-03" }
    },
    "balance": { "available": 1153.43, "opening": 0.0, "closing": 1153.43 },
    "totals": {
      "received": 2155.00, "paid": 1001.57, "net": 1153.43,
      "received_trend_pct": 12.4,   // vs. período anterior (mesma duração); 100 quando o anterior foi 0
      "paid_trend_pct": -3.1
    },
    "counts": {
      "transactions": 14,
      "pix_in": 2, "pix_out": 3,
      "boletos_paid": 0,            // BoletoWithdraw status=completed no período
      "boletos_issued": 3,          // Boleto emitidos no período
      "charges": 4, "charges_paid": 2,
      "transactions_trend_pct": 100
    },
    "by_type": [
      { "type_id": 1, "type_slug": "pix-in", "type_name": "Pix Recebido", "quantity": 2, "total_value": 425.00 }
    ],
    "daily_evolution": [
      { "date": "2026-08-04", "balance": 0.0, "change": 0.0 },
      { "date": "2026-09-02", "balance": 1153.43, "change": 1153.43 }
    ],
    "recent_transactions": [ /* TransactionResource[] — mesmas linhas de GET /consolidation/transactions */ ]
  }
}

Regras dos números:

  • balance.available = Balance::getBalance (idêntico a GET /consolidation/balance).
  • totals.received / totals.paid = soma de value > 0 / |value| (value < 0) no período, considerando status ∈ {1,2,4} — idêntico ao bloco statistics de GET /consolidation/transactions.
  • daily_evolution = mesma série do daily_evolution daquele endpoint (saldo acumulado por dia).
  • *_trend_pct = (atual − anterior) / anterior × 100, arredondado a 1 casa; 100 quando o período anterior foi 0 e o atual > 0; 0 quando ambos 0.

8. Frontend ​

fastgivr-internet-bank/src/services/consolidation.ts — consolidationApi: balance, transactions, transaction, transactionPdf, exportTransactions, downloadExport, daily, byType, timeSeries, transactionTypes, paymentMethods, settlementStatement, statisticCards, statisticBoletos, dashboard (tipo DashboardReport).

Telas: StatementPage (/extrato · /saldo) consome balance + transactions (com statistics); DashboardPage (/dashboard) consome apenas dashboard — os stat cards (com indicador de tendência), o gráfico de evolução, o breakdown por tipo e a atividade recente vêm todos dessa chamada; ReportsPage (/relatorios) consome o mesmo dashboard com período rápido ou start_date/end_date (recent_limit=1, ignora recent_transactions) e adiciona um gráfico de fluxo diário (daily_evolution[].change), barras de composição por tipo e botão de exportação (export mode=data, PDF/XLSX/CSV).

FastGivr API Documentation

Copyright © 2026 FASTGIVR. Todos os direitos reservados.