Consolidação — Novos Endpoints de Extrato e Resumo Financeiro

Versão: v2 (grupo de rotas /v2/)
Autenticação: Bearer Token (Sanctum) — todos os endpoints exigem auth:sanctum.
Prefixo base: https://api.fastgivemoney.com/v2/

`GET /v2/transactions/balance-summary`

Retorna a evolução do saldo, receitas e despesas agrupados por dia ou mês em um único endpoint. Ideal para gráficos de linha e barras no dashboard financeiro.

Query Parameters

Parâmetro	Tipo	Obrigatório	Valores aceitos	Descrição
`group_by`	`string`	✅	`days` \| `months`	Granularidade do agrupamento
`date_start`	`date`	✅	`YYYY-MM-DD`	Início do período
`date_end`	`date`	✅	`YYYY-MM-DD`	Fim do período (≥ `date_start`)

Exemplo de Requisição

http

GET /v2/transactions/balance-summary?group_by=days&date_start=2024-01-01&date_end=2024-01-31
Authorization: Bearer \{token\}

Exemplo de Resposta — `200 OK`

json

{
  "data": [
    {
      "period": "2024-01-01",
      "sum": 1500.00,
      "running_balance": 1500.00,
      "income": 1800.00,
      "expenses": -300.00,
      "income_count": 3,
      "expenses_count": 1,
      "transactions_count": 4,
      "transactions_in": [...],
      "transactions_out": [...]
    },
    {
      "period": "2024-01-02",
      "sum": -200.00,
      "running_balance": 1300.00,
      "income": 0,
      "expenses": -200.00,
      "income_count": 0,
      "expenses_count": 1,
      "transactions_count": 1,
      "transactions_in": [],
      "transactions_out": [...]
    }
  ],
  "resume": {
    "period": "total",
    "sum": 1300.00,
    "running_balance": 1300.00,
    "income": 1800.00,
    "expenses": -500.00,
    "income_count": 3,
    "expenses_count": 2,
    "transactions_count": 5
  }
}

Campos da Resposta

`data[]`

Campo	Tipo	Descrição
`period`	`string`	Data (`YYYY-MM-DD`) ou mês (`YYYY-MM`) do agrupamento
`sum`	`float`	Variação líquida do período (entradas + saídas)
`running_balance`	`float`	Saldo acumulado relativo ao período filtrado (começa do zero)
`income`	`float`	Soma das entradas (value > 0)
`expenses`	`float`	Soma das saídas (value < 0, valor negativo)
`income_count`	`int`	Quantidade de transações de entrada
`expenses_count`	`int`	Quantidade de transações de saída
`transactions_count`	`int`	Total de transações no período
`transactions_in`	`array`	Lista de transações de entrada
`transactions_out`	`array`	Lista de transações de saída

`resume`

Totalização de todos os períodos retornados.

⚠️ Atenção: O running_balance começa do zero no início do período filtrado — ele representa a variação relativa, não o saldo absoluto da conta. Para o saldo absoluto real, use GET /balance.

`GET /v2/transactions/extract`

Retorna o extrato detalhado de transações com saldo acumulado por dia, abertura e fechamento, agrupado em dias. Inclui resumo por tipo de transação.

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`payment_date_start`	`date`	✅	Data de início do extrato (`YYYY-MM-DD`)
`payment_date_end`	`date`	✅	Data de fim do extrato (`YYYY-MM-DD`)
`type`	`string`	❌	ID ou lista de IDs (CSV) para filtrar por tipo
`type_id`	`int`	❌	Filtra por um `type_id` específico
`type_ids`	`int[]`	❌	Filtra por múltiplos `type_id` (array)

Exemplo de Requisição

http

GET /v2/transactions/extract?payment_date_start=2024-01-01&payment_date_end=2024-01-31
Authorization: Bearer \{token\}

Exemplo de Resposta — `200 OK`

json

{
  "data": [
    {
      "date": "2024-01-15",
      "transactions": [
        {
          "id": 1042,
          "datetime": "2024-01-15T10:30:00",
          "txid": "abc123",
          "endtoendid": "E123...",
          "value": 500.00,
          "balance": 1500.00,
          "status": 1,
          "description": "Recebimento Pix",
          "details": { ... },
          "created_at": "2024-01-15T10:30:00",
          "updated_at": "2024-01-15T10:30:00",
          "type": {
            "id": 1,
            "slug": "pix-in",
            "name": "Pix Recebido"
          }
        }
      ],
      "transactions_count": 1,
      "summary": {
        "day_total": 500.00,
        "balance_end_of_day": 1500.00
      }
    }
  ],
  "summary": {
    "balance": 4320.50,
    "total_transactions": 12,
    "by_type": [
      {
        "type_id": 1,
        "type_name": "Pix Recebido",
        "count": 8,
        "total": 5200.00
      },
      {
        "type_id": 3,
        "type_name": "Pix Enviado",
        "count": 4,
        "total": -880.50
      }
    ]
  }
}

Campos da Resposta

`data[]`

Campo	Tipo	Descrição
`date`	`string`	Data do grupo (`YYYY-MM-DD`)
`transactions`	`TransactionV2Resource[]`	Lista de transações do dia
`transactions_count`	`int`	Quantidade de transações
`summary.day_total`	`float`	Variação líquida do dia
`summary.balance_end_of_day`	`float`	Saldo ao final do dia (histórico acumulado)

`TransactionV2Resource` (campos de cada transação)

Campo	Tipo	Descrição
`id`	`int`	ID da transação
`datetime`	`datetime`	Datetime da transação no banco parceiro
`txid`	`string`	ID da transação Pix (txid)
`endtoendid`	`string`	ID end-to-end do Pix
`value`	`float`	Valor (positivo = entrada, negativo = saída)
`balance`	`float`	Saldo no momento da transação (campo raw)
`status`	`int`	Status (1 = confirmada)
`description`	`string`	Descrição. Para Pix Out (type_id=3): gerada automaticamente com nome e documento do recebedor
`details`	`object`	Detalhes da transação. Para Pix Out: estrutura formatada com `payer` e `receiver`
`created_at`	`datetime`	Data de criação no sistema
`updated_at`	`datetime`	Data de atualização
`type`	`object`	Tipo da transação (`id`, `slug`, `name`)

`summary`

Campo	Tipo	Descrição
`balance`	`float`	Saldo total histórico da conta (todas as transações confirmadas)
`total_transactions`	`int`	Total de transações no período filtrado
`by_type`	`array`	Agrupamento por tipo: `type_id`, `type_name`, `count`, `total`

Comportamento do `balance_end_of_day`

O saldo de fechamento do dia é calculado de forma acumulativa:

saldo_inicial = Σ(todas as transações confirmadas ANTES de payment_date_start)
saldo_dia_N   = saldo_inicial + Σ(transações do dia 1 ao dia N)

Tipos de Transação (`type_id`)

ID	Slug	Nome
1	`pix-in`	PIX IN
2	`taxa`	TAXA
3	`pix-out`	PIX OUT
4	`estorno-pix-in`	ESTORNO PIX IN
5	`estorno-pix-out`	ESTORNO PIX OUT
6	`boleto`	BOLETO
8	`taxa-boleto`	Taxa Boleto
9	`taxa-pix-in`	Taxa Pix In
10	`taxa-pix-out`	Taxa Pix Out
11	`bolepix`	Bolepix
12	`taxa-bolepix`	Taxa BolePix
13	`taxa-fee`	Taxa Fee
14	(interno)	(filtrado em alguns endpoints)
15	`pagamento-boleto`	Pagamento Boleto
16	`liquidacao-cartao-de-credito`	Liquidação Cartão de Crédito

`GET /v2/transactions`

Retorna a listagem padrão de transações (formato ledger) com filtros de busca, período e tipo. É o endpoint base para o histórico de transações.

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`created_at_start`	`date`	❌	Data de início (`YYYY-MM-DD`). Padrão: 30 dias atrás.
`created_at_end`	`date`	❌	Data de fim (`YYYY-MM-DD`). Padrão: hoje.
`search`	`string`	❌	Busca por txid, endtoendid, descrição, pagador ou recebedor.
`type`	`string`	❌	ID ou lista de IDs (CSV) para filtrar por tipo.
`type_id`	`int`	❌	Filtra por um `type_id` específico.
`type_ids`	`int[]`	❌	Filtra por múltiplos `type_id` (array).
`per_page`	`int`	❌	Itens por página (padrão: 15).

Exemplo de Requisição

http

GET /v2/transactions?type_id=2&created_at_start=2024-01-01
Authorization: Bearer \{token\}

`GET /v2/transactions/statement`

Retorna um extrato financeiro consolidado (statement) com evolução diária do saldo e resumo por tipo de transação no período.

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`created_at_start`	`date`	❌	Data de início (`YYYY-MM-DD`). Padrão: 30 dias atrás.
`created_at_end`	`date`	❌	Data de fim (`YYYY-MM-DD`). Padrão: hoje.
`type`	`string`	❌	ID ou lista de IDs (CSV) para filtrar por tipo.
`type_id`	`int`	❌	Filtra por um `type_id` específico.
`type_ids`	`int[]`	❌	Filtra por múltiplos `type_id` (array).

Erros Comuns

HTTP	Situação
`422`	Parâmetro obrigatório ausente ou formato de data inválido
`401`	Token ausente ou expirado
`403`	Conta não autorizada para o usuário autenticado

Consolidação — Novos Endpoints de Extrato e Resumo Financeiro ​

GET /v2/transactions/balance-summary ​

Query Parameters ​

Exemplo de Requisição ​

Exemplo de Resposta — 200 OK ​

Campos da Resposta ​

data[] ​

resume ​

GET /v2/transactions/extract ​

Query Parameters ​

Exemplo de Requisição ​

Exemplo de Resposta — 200 OK ​

Campos da Resposta ​

data[] ​

TransactionV2Resource (campos de cada transação) ​

summary ​

Comportamento do balance_end_of_day ​

Tipos de Transação (type_id) ​

GET /v2/transactions ​

Query Parameters ​

Exemplo de Requisição ​

GET /v2/transactions/statement ​

Query Parameters ​

Erros Comuns ​

Consolidação — Novos Endpoints de Extrato e Resumo Financeiro

`GET /v2/transactions/balance-summary`

Query Parameters

Exemplo de Requisição

Exemplo de Resposta — `200 OK`

Campos da Resposta

`data[]`

`resume`

`GET /v2/transactions/extract`

Query Parameters

Exemplo de Requisição

Exemplo de Resposta — `200 OK`

Campos da Resposta

`data[]`

`TransactionV2Resource` (campos de cada transação)

`summary`

Comportamento do `balance_end_of_day`

Tipos de Transação (`type_id`)

`GET /v2/transactions`

Query Parameters

Exemplo de Requisição

`GET /v2/transactions/statement`

Query Parameters

Erros Comuns