Monthly financial summary (KPIs)

GEThttps://api.veriko.mx/v1/finance/summary

Audience: public
Auth: API key
Permission: finance:generate_self

Returns the user's monthly KPIs for the /finanzas panel:

counts by Banxico verdict
monetary aggregates (total / verified / unverified volume, average ticket, median, min, max, verified share)
success rate
average processing time
daily breakdown
top 5 counterparties + sender/receiver banks
verdict distribution
comparison with the previous month (percentage deltas, null when the previous month had a zero base)

"Verified" means Banxico returned valid and the CEP XML downloaded. Any other verdict counts as unverified. Scope: self by default. Admins with finance:generate_all may target another user via ?user_id=<uuid> (audited as a security event). Accepts API key. Response is briefly cached client-side: Cache-Control: private, max-age=60, stale-while-revalidate=60. To download the monthly statement (PDF/XLSX/CSV/HTML) use GET /v1/finance/statement; for the ZIP of CEPs in a range use GET /v1/finance/ceps.

Parameters
Parameter	In	Type	Required	Description
`month`*	query	`string`	required	Month to query in `YYYY-MM` format. e.g. `2026-04`
`user_id`	query	`string (uuid)`	optional	Admins with `finance:generate_all` only. UUID of the user to query; cross-user reads are logged in `/admin/security`. e.g. `f47ac10b-58cc-4372-a567-0e02b2c3d479`

Request

cURLPython•JavaScript•PHP•

curl -X GET 'https://api.veriko.mx/v1/finance/summary' \
  -H 'Authorization: Bearer veriko_••••'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200**`FinanceSummaryResponse` — Monthly KPI blob for the user, including comparison against the previous month.
Field	Type	Description
`data`	`object`	Main response payload. Shape varies by endpoint (object, array, or JSON:API envelope with `type`, `id`, `attributes`).
`type`	`string`	JSON:API resource type (always `finance_summary`). e.g. `finance_summary`
`attributes`	`object`	User financial KPIs for a calendar month. Includes counts by Banxico verdict, monetary aggregates, daily breakdown, top counterparties and banks, verdict distribution, and comparison with the previous month.
`period`	`object`	Time range of the summary (full calendar month).
`month`	`string`	Month in YYYY-MM format. e.g. `2026-04`
`from_utc`	`string (date-time)`	Start of the month in UTC (ISO 8601). e.g. `2026-04-01T06:00:00Z`
`to_utc`	`string (date-time)`	End of the month in UTC (ISO 8601, exclusive). e.g. `2026-05-01T06:00:00Z`
`counts`	`object`	Validation counts by Banxico verdict plus soft-deletes for the period (informational).
`total`	`integer`	Total validations completed in the period (excludes `pending`). e.g. `287`
`valid`	`integer`	Validations with Banxico verdict `valid` in the period. e.g. `228`
`invalid`	`integer`	Validations with Banxico verdict `invalid` in the period. e.g. `4`
`not_found`	`integer`	Validations with Banxico verdict `not_found` in the period. e.g. `32`
`cep_unavailable`	`integer`	Validations with Banxico verdict `cep_unavailable` in the period. e.g. `18`
`error`	`integer`	Validations that ended with a technical error (Banxico did not respond, timeout, etc.) in the period. e.g. `3`
`pending`	`integer`	Validations still in progress (async ones awaiting Banxico response) at the end of the period. e.g. `2`
`deleted`	`integer`	Soft-deleted validations in the period. e.g. `6`
`amounts`	`object`	Monetary aggregates for the period. `verified_volume` sums only validations with `valid` result.
`total_volume`	`number`	Total volume in MXN. e.g. `1234567.89`
`verified_volume`	`number`	Volume in MXN of validations with `valid` result. e.g. `980123.45`
`unverified_volume`	`number`	Difference between total and verified volume. e.g. `254444.44`
`avg_ticket`	`number`	Average amount per validation in MXN. e.g. `4302.32`
`median_ticket`	`number`	Median amount per validation in MXN. e.g. `3100`
`max_ticket`	`number`	Largest individual amount in the month in MXN. e.g. `250000`
`min_ticket`	`number`	Smallest individual amount in the month in MXN. e.g. `50`
`verified_share_pct`	`number`	Percentage of total volume from verified validations, expressed from 0 to 100. e.g. `79.4`
`success_rate`	`number`	Success rate: percentage of validations with `valid` result out of all completed, expressed from 0 to 100. e.g. `79.4`
`avg_processing_ms`	`integer`	Average processing time in milliseconds for the period. e.g. `412`
`daily_breakdown`	`array`	Daily breakdown for days with activity. Days with no validations are omitted.
`top_counterparties`	`array`	Top 5 user beneficiary accounts by verified volume in the month.
`top_banks_receptor`	`array`	Top 5 receiving banks by verified volume.
`top_banks_emisor`	`array`	Top 5 sending banks by verified volume.
`verdict_distribution`	`object`	Validation count by Banxico verdict value. Missing values imply zero. e.g. `{"valid":228,"not_found":32,"cep_unavailable":18,"invalid":4,"error":3}`
`comparison_prev_month`	`object`	Comparison against the previous month. Deltas are `null` when the previous month had a zero base (growth not defined).
`prev_month`	`string`	Previous month in YYYY-MM format. e.g. `2026-03`
`total`	`integer`	Total validations in the previous month. e.g. `251`
`verified_volume`	`number`	Verified volume in the previous month in MXN. e.g. `880000`
`total_delta_pct`	`number \| null`nullable	Percentage change in total count vs. the previous month. `null` when the previous month had zero validations. e.g. `14.3`
`volume_delta_pct`	`number \| null`nullable	Percentage change in verified volume vs. the previous month. `null` when the previous month had zero verified volume. e.g. `11.4`
`folio`	`string`	Deterministic statement folio for the month, identical to the value returned in the `X-Finance-Folio` header of the export endpoint. e.g. `A3F12B9C0D4E`
`meta`	`object`	Response metadata including API version, route prefix, unique request identifier, and the server timestamp in UTC.
`version`	`string`	API version that processed the request. e.g. `1.47.0`
`api_version`	`string`	API route prefix version (e.g. `v1`). e.g. `v1`
`request_id`	`string`	Unique request identifier (hex). e.g. `a1b2c3d4e5f6`
`datetime`	`object`	Companion descriptor present in every response's meta block (and in outgoing webhook payloads). Lets clients assert the timezone contract without re-reading the spec. e.g. `{"timezone":"UTC","format":"ISO 8601"}`
`timezone`*	`string`	Always `UTC` — the canonical timezone for every datetime field in the body. e.g. `UTC`
`format`*	`string`	Always `ISO 8601` — explicit `Z` suffix on every datetime. e.g. `ISO 8601`
`links`	`object`	Pagination or related links, present only when the endpoint returns a paginated collection.

**Response status codes**`GET /v1/finance/summary`
Status	Class	Description	Body
200	`2xx`	Monthly KPI blob for the user, including comparison against the previous month.	`FinanceSummaryResponse`
400	`4xx`	Invalid or missing `month` parameter	`ErrorResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Insufficient permissions.	`ErrorResponse`

**Response headers**`200`
Header	Type	Description
`Cache-Control`	`string`	Private cache directive with stale-while-revalidate.

**Errors from `GET /v1/finance/summary`**
Status	Code	Example
400	`invalid_month`	'month' is required and must be YYYY-MM. Envelope meta.request_id `d5e6f7a8b9c1`
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`