Admin finance

Back-office finance reporting: a period summary, a unified income/expense ledger, single-transaction detail, and a CSV export. Paths are relative to the /api/v1 prefix; these are back-office endpoints that require an admin token.

Requires an admin bearer token (see Admin auth). Admin only. Results are scoped to the admin's assigned cities.

See Common errors and the order money breakdown.

Endpoints

Method URI Access Description
GET /admin/finance/summary Admin Aggregated income, expenses & net profit for a period
GET /admin/finance/transactions Admin Paginated income/expense ledger (page-based)
GET /admin/finance/transactions/export Admin CSV export of the ledger
GET /admin/finance/transactions/{transactionId} Admin Single transaction detail

GET /admin/finance/summary

Aggregated totals for a period. Either pass a named period or an explicit from/to range (a range overrides period). All money is reported in USD.

Query

Field Type Required Rules
period string no today, week, or month; defaults to the last 30 days
from date no start of a custom range (overrides period)
to date no end of the custom range; >= from

Response 200

{
  "period": {
    "from": "2026-05-30T00:00:00+00:00",
    "to": "2026-06-29T23:59:59+00:00",
    "label": "month"
  },
  "summary": {
    "ingresos_totales_usd": 4820.5,
    "pagos_pendientes_usd": 120.0,
    "fondo_solidario_usd": 48.2,
    "egresos_totales_usd": 3910.4,
    "utilidad_neta_usd": 802.1
  },
  "income_by_method": [
    { "method": "CASH_USD", "amount_usd": 3200.0, "count": 160 },
    { "method": "PAGO_MOVIL", "amount_usd": 1620.5, "count": 74 }
  ]
}

GET /admin/finance/transactions

Unified ledger of income (order payments) and expenses (driver payouts), newest first. Page-based; see Pagination → page-based.

Query

Field Type Required Rules
type string no income, expense, or all (default all)
from date no filter created_at >=
to date no filter created_at <=; >= from
q string no ≤ 120 chars; matches reference, provider ref, or involved name
method string no payment/payout method code
status string no PENDING, COMPLETED, or FAILED
limit integer no 1–100, default 25
page integer no ≥ 1, default 1

Response 200

{
  "items": [
    {
      "id": "TX-INC-512",
      "source_id": 512,
      "type": "income",
      "category": "ORDER_PAYMENT",
      "description": "Pago recibido por pedido #42",
      "reference": "REF-9001",
      "method": "PAGO_MOVIL",
      "status": "COMPLETED",
      "amount_usd": 20.2,
      "created_at": "2026-06-26T12:40:00+00:00",
      "involved": { "id": 1, "name": "Ana MartĂ­nez", "role": "client" }
    }
  ],
  "meta": { "total": 137, "per_page": 25, "current_page": 1, "last_page": 6 }
}

GET /admin/finance/transactions/export

Streams the filtered ledger as a CSV download (text/csv); there is no JSON body on success. Accepts the same filters as the ledger (no pagination). Capped at 10,000 rows.

Query

Field Type Required Rules
type string no income, expense, or all (default all)
from date no filter created_at >=
to date no filter created_at <=; >= from
q string no ≤ 120 chars
method string no payment/payout method code
status string no PENDING, COMPLETED, or FAILED

Response 200 — a text/csv stream (finance_export_<timestamp>.csv) with the columns ID, Tipo, Categoría, Descripción, Referencia, Método, Estado, Monto (USD), Fecha.

Errors

Status Body When
422 { "error": "TooManyResults", "message": "…" } More than 10,000 rows match the filters

GET /admin/finance/transactions/{transactionId}

Detail for a single transaction id. Income ids look like TX-INC-{number} and expense ids like TX-EXP-{number} (case-insensitive). The response is the transaction object itself (not wrapped); its shape differs slightly by type.

Response 200 (income example)

{
  "id": "TX-INC-512",
  "source_id": 512,
  "type": "income",
  "category": "ORDER_PAYMENT",
  "description": "Pago recibido por pedido #42",
  "reference": "REF-9001",
  "provider_ref": "pm_abc123",
  "method": "PAGO_MOVIL",
  "status": "COMPLETED",
  "amount_usd": 20.2,
  "aguita_revenue_usd": 3.6,
  "solidary_fund_usd": 0.36,
  "confirmed_at": "2026-06-26T12:40:00+00:00",
  "failure_reason": null,
  "created_at": "2026-06-26T12:38:00+00:00",
  "order": { "id": 42 },
  "involved": { "id": 1, "name": "Ana MartĂ­nez", "role": "client" }
}

Expense (TX-EXP-…) transactions replace the order/revenue fields with payout timestamps: scheduled_at, processed_at, completed_at, and an involved.role of driver.

Errors

Status Body When
422 { "error": "InvalidTransactionId" } Id does not match TX-(INC|EXP)-{number}
404 { "error": "TransactionNotFound" } No payment/payout for that id