Docs
EN

Objetivo

Entiende el estado y la forma de tu tráfico de validaciones: tasa de éxito, latencia, tendencias de volumen y qué contrapartes aparecen con mayor frecuencia. Usa estos datos para identificar patrones de error, detectar tráfico inusual y optimizar políticas de reintentos.

Requisitos previos

  • Una API key activa (mxcep_…) con el permiso insights:read_self.

Pasos

1. Comenzar con el resumen de KPIs

GET /v1/insights/overview proporciona un snapshot de los indicadores clave para las últimas 24–48 horas: validaciones totales, conteos de hoy y ayer, tasa de éxito y latencia promedio.

curl 'https://api.example.com/v1/insights/overview' \
  -H 'Authorization: Bearer mxcep_••••'
{
  "data": {
    "type": "insights_overview",
    "attributes": {
      "total_validations": 4821,
      "today": 143,
      "yesterday": 118,
      "success_rate_pct": 91.4,
      "avg_latency_ms_24h": 1320,
      "verdict_distribution_7d": {
        "valid": 87.2,
        "not_found": 9.1,
        "cep_unavailable": 2.5,
        "error": 1.2
      }
    }
  }
}

2. Profundizar en tendencias de series temporales

GET /v1/insights/trends devuelve datos de series temporales agrupados. Elige el range de tiempo y la metric:

rangeTamaño del bucket
24hPor hora
7dPor día
30dPor día
90dPor semana (semanas inician el lunes)

Tendencia de volumen (últimos 30 días):

curl 'https://api.example.com/v1/insights/trends?range=30d&metric=volume' \
  -H 'Authorization: Bearer mxcep_••••'

Percentiles de latencia (últimos 7 días):

curl 'https://api.example.com/v1/insights/trends?range=7d&metric=latency' \
  -H 'Authorization: Bearer mxcep_••••'

La métrica de latencia devuelve p50, p95 y p99 por bucket. Un p99 creciente mientras el p50 se mantiene estable indica lentitud intermitente del upstream Banxico en lugar de un problema sistemático.

3. Identificar los principales bancos por volumen o errores

GET /v1/insights/top-banks lista los bancos más frecuentes en tus validaciones durante los últimos 30 días:

# Top 10 bancos por volumen
curl 'https://api.example.com/v1/insights/top-banks?metric=volume&limit=10' \
  -H 'Authorization: Bearer mxcep_••••'

# Top bancos por conteo de errores — útil para detectar rutas problemáticas
curl 'https://api.example.com/v1/insights/top-banks?metric=errors&limit=10' \
  -H 'Authorization: Bearer mxcep_••••'

4. Identificar los principales beneficiarios

GET /v1/insights/top-beneficiaries lista las cuentas que aparecen con más frecuencia como destinos en tus validaciones:

curl 'https://api.example.com/v1/insights/top-beneficiaries' \
  -H 'Authorization: Bearer mxcep_••••'

Siguientes pasos