https://api.veriko.mx/v1/finance/summary Resumen financiero mensual (KPIs)
Guía de uso →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ámetro | Ubicación | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
month * | query | string | obligatorio | Mes a consultar en formato `YYYY-MM`. |
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`. |
curl -X GET 'https://api.veriko.mx/v1/finance/summary' \
-H 'Authorization: Bearer mxcep_••••'
Ejemplo en Python — próximamente.
Ejemplo en JavaScript — próximamente.
Ejemplo en PHP — próximamente.
| Campo | Tipo | Descripción |
|---|---|---|
type | string | Tipo del recurso JSON:API (siempre `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. |
from_utc | string (date-time) | Inicio del mes en UTC (ISO 8601). |
to_utc | string (date-time) | Fin del mes en UTC (ISO 8601, exclusivo). |
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`). |
valid | integer | Validaciones con veredicto Banxico `valid` en el periodo. |
invalid | integer | Validaciones con veredicto Banxico `invalid` en el periodo. |
not_found | integer | Validaciones con veredicto Banxico `not_found` en el periodo. |
cep_unavailable | integer | Validaciones con veredicto Banxico `cep_unavailable` en el periodo. |
error | integer | Validaciones que terminaron en error técnico (Banxico no respondió, timeout, etc.) en el periodo. |
pending | integer | Validaciones aún en proceso (asíncronas que no han recibido respuesta de Banxico) al cierre del periodo. |
deleted | integer | Validaciones eliminadas (soft-delete) en el periodo. |
amounts | object | Agregados monetarios del periodo. `verified_volume` suma únicamente validaciones con resultado `valid`. |
total_volume | number | Volumen total en MXN. |
verified_volume | number | Volumen en MXN de validaciones con resultado `valid`. |
unverified_volume | number | Diferencia entre volumen total y verificado. |
avg_ticket | number | Monto promedio por validación en MXN. |
median_ticket | number | Monto mediano por validación en MXN. |
max_ticket | number | Mayor monto individual del mes en MXN. |
min_ticket | number | Menor monto individual del mes en MXN. |
verified_share_pct | number | Porcentaje del volumen total correspondiente a validaciones verificadas, expresado de 0 a 100. |
success_rate | number | Tasa de éxito: porcentaje de validaciones con resultado `valid` sobre el total completado, expresado de 0 a 100. |
avg_processing_ms | integer | Tiempo promedio de procesamiento en milisegundos del periodo. |
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. |
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. |
total | integer | Total de validaciones del mes anterior. |
verified_volume | number | Volumen verificado del mes anterior en MXN. |
total_delta_pct | number | null anulable | Cambio porcentual del conteo total respecto al mes anterior. `null` cuando el mes anterior tuvo cero validaciones. |
volume_delta_pct | number | null anulable | Cambio porcentual del volumen verificado respecto al mes anterior. `null` cuando el mes anterior tuvo cero volumen verificado. |
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. |
| 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 |
| Cabecera | Tipo | Descripción |
|---|---|---|
Cache-Control | string | Directiva de caché privada con stale-while-revalidate. |
| Código | Clave | Detalle |
|---|---|---|
| 400 | invalid_month | 'month' is required and must be YYYY-MM. Envelope
|
| 401 | unauthorized | Invalid or missing authentication credentials. Envelope
|
| 403 | forbidden | You do not have permission to access this resource. Envelope
|