Analítica

GET /v1/analytics resume los análisis de un periodo: cuántos hubo, qué porcentaje salió válido, no válido o a revisar, cuánto tardaron, cuántos créditos gastaron y por qué se rechazan más. Es la misma información que la sección Analítica del panel, para llevarla a tu propio cuadro de mando o a una hoja de cálculo.

GET /v1/analytics?from=2026-09-01&to=2026-09-30&group_by=type
Authorization: Bearer ck_live_…

Usa una clave secreta y cubre solo el modo de la clave: con ck_live_… los análisis reales, con ck_test_… los de prueba.

ParámetrosCopy Anchor Link

Los análisis sin valor para la agrupación (sin tipo, sin plantilla o sin esa clave de metadata) se agrupan con key: null y una etiqueta como «Sin plantilla». Como mucho 500 grupos.

RespuestaCopy Anchor Link

{
  "object": "analytics",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "group_by": "type",
  "mode": "live",
  "totals": {
    "count": 1240, "completed": 1228, "failed": 12,
    "valid": 1015, "invalid": 131, "review": 82,
    "valid_rate": 0.8265, "invalid_rate": 0.1067, "review_rate": 0.0668,
    "avg_ms": 3120, "p50_ms": 2410, "p95_ms": 7800,
    "credits": 1412.4
  },
  "groups": [
    { "key": "es_dni", "label": "DNI (España)", "count": 802, "completed": 798, "failed": 4, "valid": 701, "invalid": 61, "review": 36, "valid_rate": 0.8784, "invalid_rate": 0.0764, "review_rate": 0.0451, "avg_ms": 2380, "p50_ms": 2100, "p95_ms": 4300, "credits": 802 }
  ],
  "top_reasons": [
    { "code": "not_expired", "severity": "error", "count": 58, "example": "El documento caducó el 03/02/2026." },
    { "code": "low_confidence", "severity": "warning", "count": 41, "example": "No se ha podido leer con seguridad el número de documento." }
  ]
}

Cuentan también los análisis cuyos resultados ya se borraron por retención: el registro mínimo (tipo, veredicto, créditos, metadatos) se conserva para la analítica.

CSVCopy Anchor Link

Con format=csv la respuesta es un fichero analytics-<modo>-<agrupación>-<desde>-<hasta>.csv preparado para Excel: separador ;, decimales con coma, BOM UTF-8, una fila por grupo (clave, grupo, totales, porcentajes, tiempo medio, p95 y créditos) y una fila final de total. Las cabeceras de columna van en el idioma de Accept-Language.

curl -G https://api.constaia.com/v1/analytics \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -H "Accept-Language: es" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "to=2026-09-30" \
  --data-urlencode "group_by=metadata.club_id" \
  --data-urlencode "format=csv" \
  -o analitica-septiembre.csv

EjemplosCopy Anchor Link

curl -G https://api.constaia.com/v1/analytics \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "to=2026-09-30" \
  --data-urlencode "group_by=template"

Ideas de usoCopy Anchor Link

• Comparar plantillas: group_by=template muestra qué configuración rechaza más o manda más a revisión.
• Por cliente o evento: guarda su id en metadata al analizar y agrupa con group_by=metadata.<clave>.
• Vigilar la calidad: si sube review_rate o aparece low_quality en top_reasons, revisa las instrucciones de captura o usa el widget, que avisa de fotos borrosas antes de subir.
• Coste: credits por grupo, junto con GET /v1/usage para el detalle diario.

ErroresCopy Anchor Link

Siguientes pasosCopy Anchor Link