Consultar el resumen financiero del mes

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

Audiencia: public
Autenticación: API key
Permiso: finance:generate_self

Devuelve los KPIs del mes para el panel /finanzas:

conteos por veredicto Banxico
agregados monetarios (volumen total / verificado / no verificado, ticket promedio, mediana, mínimo, máximo, share verificado)
tasa de éxito
tiempo de procesamiento promedio
desglose diario
top 5 contrapartes y bancos emisores + receptores
distribución de veredicto y comparativa con el mes anterior (deltas porcentuales, null cuando el mes previo tuvo base cero)

"Verificado" significa que Banxico devolvió valid y el XML del CEP se descargó. Cualquier otro veredicto cuenta como no verificado. Alcance: propio por defecto. Administradores con permiso finance:generate_all pueden consultar otro usuario vía ?user_id=<uuid> (auditado como evento de seguridad). Acepta API key. Respuesta cacheada brevemente en cliente: Cache-Control: private, max-age=60, stale-while-revalidate=60. Para descargar el estado de cuenta mensual (PDF/XLSX/CSV/HTML) usa GET /v1/finance/statement; para el ZIP con los CEPs del rango usa GET /v1/finance/ceps.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`month`*	query	`string`	obligatorio	Mes a consultar en formato `YYYY-MM`. p. ej. `2026-04`
`user_id`	query	`string (uuid)`	opcional	Solo para administradores con `finance:generate_all`. UUID del usuario a consultar; cross-user reads se registran en `/admin/security`. p. ej. `f47ac10b-58cc-4372-a567-0e02b2c3d479`

Petición

cURLPython•JavaScript•PHP•

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

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200**`FinanceSummaryResponse` — KPIs mensuales del usuario con comparativa al mes anterior.
Campo	Tipo	Descripción
`data`	`object`	Payload principal de la respuesta. La forma varía según el endpoint (objeto, array, o envelope JSON:API con `type`, `id`, `attributes`).
`type`	`string`	Tipo del recurso JSON:API (siempre `finance_summary`). p. ej. `finance_summary`
`attributes`	`object`	KPIs financieros del usuario para un mes calendario. Incluye conteos por veredicto Banxico, agregados monetarios, desglose diario, top contrapartes y bancos, distribución de veredicto, y comparativa con el mes anterior.
`period`	`object`	Rango temporal del resumen (mes calendario completo).
`month`	`string`	Mes en formato YYYY-MM. p. ej. `2026-04`
`from_utc`	`string (date-time)`	Inicio del mes en UTC (ISO 8601). p. ej. `2026-04-01T06:00:00Z`
`to_utc`	`string (date-time)`	Fin del mes en UTC (ISO 8601, exclusivo). p. ej. `2026-05-01T06:00:00Z`
`counts`	`object`	Conteos de validaciones por veredicto Banxico más soft-deletes del periodo (informativo).
`total`	`integer`	Total de validaciones completadas en el periodo (excluye `pending`). p. ej. `287`
`valid`	`integer`	Validaciones con veredicto Banxico `valid` en el periodo. p. ej. `228`
`invalid`	`integer`	Validaciones con veredicto Banxico `invalid` en el periodo. p. ej. `4`
`not_found`	`integer`	Validaciones con veredicto Banxico `not_found` en el periodo. p. ej. `32`
`cep_unavailable`	`integer`	Validaciones con veredicto Banxico `cep_unavailable` en el periodo. p. ej. `18`
`error`	`integer`	Validaciones que terminaron en error técnico (Banxico no respondió, timeout, etc.) en el periodo. p. ej. `3`
`pending`	`integer`	Validaciones aún en proceso (asíncronas que no han recibido respuesta de Banxico) al cierre del periodo. p. ej. `2`
`deleted`	`integer`	Validaciones eliminadas (soft-delete) en el periodo. p. ej. `6`
`amounts`	`object`	Agregados monetarios del periodo. `verified_volume` suma únicamente validaciones con resultado `valid`.
`total_volume`	`number`	Volumen total en MXN. p. ej. `1234567.89`
`verified_volume`	`number`	Volumen en MXN de validaciones con resultado `valid`. p. ej. `980123.45`
`unverified_volume`	`number`	Diferencia entre volumen total y verificado. p. ej. `254444.44`
`avg_ticket`	`number`	Monto promedio por validación en MXN. p. ej. `4302.32`
`median_ticket`	`number`	Monto mediano por validación en MXN. p. ej. `3100`
`max_ticket`	`number`	Mayor monto individual del mes en MXN. p. ej. `250000`
`min_ticket`	`number`	Menor monto individual del mes en MXN. p. ej. `50`
`verified_share_pct`	`number`	Porcentaje del volumen total correspondiente a validaciones verificadas, expresado de 0 a 100. p. ej. `79.4`
`success_rate`	`number`	Tasa de éxito: porcentaje de validaciones con resultado `valid` sobre el total completado, expresado de 0 a 100. p. ej. `79.4`
`avg_processing_ms`	`integer`	Tiempo promedio de procesamiento en milisegundos del periodo. p. ej. `412`
`daily_breakdown`	`array`	Desglose diario con actividad. Los días sin validaciones se omiten.
`top_counterparties`	`array`	Top 5 cuentas beneficiarias del usuario por volumen verificado en el mes.
`top_banks_receptor`	`array`	Top 5 bancos receptores por volumen verificado.
`top_banks_emisor`	`array`	Top 5 bancos emisores por volumen verificado.
`verdict_distribution`	`object`	Conteo de validaciones por valor de veredicto Banxico. Los valores ausentes implican cero. p. ej. `{"valid":228,"not_found":32,"cep_unavailable":18,"invalid":4,"error":3}`
`comparison_prev_month`	`object`	Comparativa contra el mes anterior. Los deltas son `null` cuando el mes anterior tuvo base cero (crecimiento no definido).
`prev_month`	`string`	Mes anterior en formato YYYY-MM. p. ej. `2026-03`
`total`	`integer`	Total de validaciones del mes anterior. p. ej. `251`
`verified_volume`	`number`	Volumen verificado del mes anterior en MXN. p. ej. `880000`
`total_delta_pct`	`number \| null`anulable	Cambio porcentual del conteo total respecto al mes anterior. `null` cuando el mes anterior tuvo cero validaciones. p. ej. `14.3`
`volume_delta_pct`	`number \| null`anulable	Cambio porcentual del volumen verificado respecto al mes anterior. `null` cuando el mes anterior tuvo cero volumen verificado. p. ej. `11.4`
`folio`	`string`	Folio determinístico del estado de cuenta del mes, idéntico al devuelto en la cabecera `X-Finance-Folio` del endpoint de exportación. p. ej. `A3F12B9C0D4E`
`meta`	`object`	Metadatos de la respuesta, incluyendo versión de la API, prefijo de ruta, identificador único de la petición y marca temporal del servidor en UTC.
`version`	`string`	Versión de la API que procesó la petición. p. ej. `1.47.0`
`api_version`	`string`	Versión del prefijo de ruta de la API (ej. `v1`). p. ej. `v1`
`request_id`	`string`	Identificador único de la petición (hex). p. ej. `a1b2c3d4e5f6`
`datetime`	`object`	Descriptor compañero presente en el bloque `meta` de cada respuesta (y en el `meta` del cuerpo de los webhooks salientes). Permite a los clientes afirmar el contrato de zona horaria sin releer el spec. p. ej. `{"timezone":"UTC","format":"ISO 8601"}`
`timezone`*	`string`	Siempre `UTC` — la zona canónica para cada campo datetime del cuerpo. p. ej. `UTC`
`format`*	`string`	Siempre `ISO 8601` — sufijo `Z` explícito en cada datetime. p. ej. `ISO 8601`
`links`	`object`	Enlaces de paginación o relacionados, presentes solo cuando el endpoint devuelve una colección paginada.

**Códigos de respuesta**`GET /v1/finance/summary`
Código	Clase	Descripción	Cuerpo
200	`2xx`	KPIs mensuales del usuario con comparativa al mes anterior.	`FinanceSummaryResponse`
400	`4xx`	Parámetro `month` inválido o ausente	`ErrorResponse`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`

**Cabeceras de respuesta**`200`
Cabecera	Tipo	Descripción
`Cache-Control`	`string`	Directiva de caché privada con stale-while-revalidate.

**Errores de `GET /v1/finance/summary`**
Código	Clave	Ejemplo
400	`invalid_month`	'month' es obligatorio y debe tener el formato YYYY-MM. Envelope meta.request_id `d5e6f7a8b9c1`
401	`unauthorized`	Credenciales de autenticación ausentes o inválidas. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	No tienes permiso para acceder a este recurso. Envelope meta.request_id `d5e6f7a8b9c0`