Analytics

Los endpoints de Analytics resumen la actividad de firma de tu tenant: indicadores clave, el embudo de firma, la tendencia mensual, quién frena los documentos, la actividad por miembro del equipo y los eventos más recientes. Son de solo lectura y agregan datos que ya viven en tus documentos.

Los seis endpoints exigen el scope analytics:read (o analytics:*). Una API key con solo document:* recibe 403 PERMISSION_DENIED con la extensión requiredScope: "analytics:read" — genera o edita una key con ese scope en el Dashboard antes de consultarlos.

Todas las respuestas usan camelCase en el wire e ids opacos con prefijo (usr_, evt_). Los errores siguen problem+json (RFC 9457) con un code en UPPER_SNAKE. Estas listas son colecciones acotadas (object: "list" con hasMore siempre false): NO paginan por cursor — su tamaño lo limita el propio endpoint (el embudo tiene 4 etapas, la tendencia 6 meses, etc.). Cada respuesta trae headers RateLimit-*.

KPIs

GET /analytics/kpis

Indicadores clave del periodo: total de documentos, completados, pendientes, expirados, tasa de finalización y tiempo promedio de firma. La respuesta es un objeto plano (no un sobre list).

Parámetros

period query Ventana de tiempo: 7d, 30d, 90d o 12m. Default 30d. Otro valor es un 422 VALIDATION_ERROR.

Ejemplo (cURL)

curl "https://api.allsign.io/v3/analytics/kpis?period=30d" \
  -H "Authorization: Bearer allsign_live_sk_..."

Respuestas

200 Objeto plano con los KPIs del periodo. — AnalyticsKPIs

{
  "totalDocs": 150,
  "completed": 42,
  "pending": 93,
  "expired": 15,
  "completionRate": 0.28,
  "avgSignTimeHours": 18.4
}

Errores posibles (problem+json): 401 403 422 429

Signing funnel

GET /analytics/funnel

El embudo de firma en cuatro etapas fijas: Enviados → En progreso → Completados → Expirados. La colección siempre trae exactamente 4 elementos.

Parámetros

period query Ventana de tiempo: 7d, 30d, 90d o 12m. Default 30d.

Ejemplo (cURL)

curl "https://api.allsign.io/v3/analytics/funnel?period=30d" \
  -H "Authorization: Bearer allsign_live_sk_..."

Respuestas

200 Colección acotada (object: "list") con las 4 etapas del embudo, en orden. — FunnelList

{
  "object": "list",
  "data": [
    {
      "label": "Enviados",
      "count": 150,
      "pct": 100
    },
    {
      "label": "En progreso",
      "count": 93,
      "pct": 62
    },
    {
      "label": "Completados",
      "count": 42,
      "pct": 28
    },
    {
      "label": "Expirados",
      "count": 15,
      "pct": 10
    }
  ],
  "hasMore": false
}

Errores posibles (problem+json): 401 403 422 429

Monthly trend

GET /analytics/trend

Documentos firmados y horas promedio de firma por mes, para los últimos 6 meses (fijo, sin parámetros).

Ejemplo (cURL)

curl "https://api.allsign.io/v3/analytics/trend" \
  -H "Authorization: Bearer allsign_live_sk_..."

Respuestas

200 Colección acotada (object: "list") con un punto por mes (hasta 6). — TrendList

{
  "object": "list",
  "data": [
    {
      "month": "2026-02",
      "signed": 28,
      "avgHours": 22.1
    },
    {
      "month": "2026-03",
      "signed": 35,
      "avgHours": 19.8
    },
    {
      "month": "2026-07",
      "signed": 42,
      "avgHours": 18.4
    }
  ],
  "hasMore": false
}

Errores posibles (problem+json): 401 403 422 429

Bottlenecks

GET /analytics/bottlenecks

Los firmantes que más documentos tienen pendientes — quién está frenando tus flujos de firma.

Parámetros

limit query Máximo de firmantes a devolver (1–20, default 5).

Ejemplo (cURL)

curl "https://api.allsign.io/v3/analytics/bottlenecks?limit=5" \
  -H "Authorization: Bearer allsign_live_sk_..."

Respuestas

200 Colección acotada (object: "list"), firmantes ordenados por firmas pendientes. — BottleneckList

{
  "object": "list",
  "data": [
    {
      "signerName": "María López",
      "signerEmail": "maria@empresa.com",
      "pendingCount": 7,
      "avgDays": 4.2
    },
    {
      "signerName": "Proveedor externo",
      "signerEmail": null,
      "pendingCount": 3,
      "avgDays": 9.5
    }
  ],
  "hasMore": false
}

Errores posibles (problem+json): 401 403 422 429

Team activity

GET /analytics/team

Actividad de envío y firma por cada miembro del tenant — una fila por miembro.

Parámetros

period query Ventana de tiempo: 7d, 30d, 90d o 12m. Default 30d.

Ejemplo (cURL)

curl "https://api.allsign.io/v3/analytics/team?period=30d" \
  -H "Authorization: Bearer allsign_live_sk_..."

Respuestas

200 Colección acotada (object: "list"), una fila por miembro del tenant. — TeamActivityList

{
  "object": "list",
  "data": [
    {
      "userId": "usr_1a2b3c4d5e6f7g8h",
      "name": "Ana Ramírez",
      "initials": "AR",
      "role": "admin",
      "sent": 34,
      "signed": 12,
      "rate": 0.71
    }
  ],
  "hasMore": false
}

Errores posibles (problem+json): 401 403 422 429

Recent events

GET /analytics/events

El feed de actividad reciente del tenant — los últimos eventos de documento (creado, enviado, firmado, etc.).

Parámetros

limit query Máximo de eventos a devolver (1–50, default 8).

Ejemplo (cURL)

curl "https://api.allsign.io/v3/analytics/events?limit=8" \
  -H "Authorization: Bearer allsign_live_sk_..."

Respuestas

200 Colección acotada (object: "list"), eventos recientes (más nuevos primero). — RecentEventList

{
  "object": "list",
  "data": [
    {
      "id": "evt_7c9e6679742540de944be07fc1f90ae7",
      "documentName": "Contrato de arrendamiento 2026.pdf",
      "eventType": "document.completed",
      "actorName": "Ana Ramírez",
      "actorInitials": "AR",
      "createdAt": "2026-07-11T20:15:00Z"
    }
  ],
  "hasMore": false
}

Errores posibles (problem+json): 401 403 422 429