---
title: "Analytics — Endpoints API v3 de AllSign"
type: reference
canonical_url: "https://allsign.io/developers/docs/endpoints/analytics"
api_version: "2026-07-11"
---

# 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-*`.

Los ejemplos usan `$ALLSIGN_API_KEY`. Defínela una vez con tu key de sandbox: `export ALLSIGN_API_KEY="allsign_test_sk_…"` (en PowerShell: `$env:ALLSIGN_API_KEY="allsign_test_sk_…"`).

[Descargar OpenAPI](https://allsign.io/developers/docs/openapi.public.json)[Colección de Postman](https://allsign.io/developers/docs/allsign-api-v3.postman_collection.json)

Endpoints

-   [GET`/analytics/kpis`](#kpis)
-   [GET`/analytics/funnel`](#signing-funnel)
-   [GET`/analytics/trend`](#monthly-trend)
-   [GET`/analytics/bottlenecks`](#bottlenecks)
-   [GET`/analytics/team`](#team-activity)
-   [GET`/analytics/events`](#recent-events)

## 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` string query
    
    Ventana de tiempo: `7d`, `30d`, `90d` o `12m`. Default `30d`. Otro valor es un `422 VALIDATION_ERROR`.
    
    default "30d"
    
-   `AllSign-Version` enum header
    
    Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 `UNSUPPORTED_API_VERSION`.
    
    Valores: `2026-07-11`
    

#### Devuelve

**200** Objeto plano con los KPIs del periodo.

Ver los 6 atributos de la respuesta

-   `totalDocs` integer requerido
    
    Documentos enviados en el periodo, sin contar borradores.
    
-   `completed` integer requerido
    
    Documentos con todas las firmas completas.
    
-   `pending` integer requerido
    
    Documentos aún esperando firmas.
    
-   `expired` integer requerido
    
    Documentos que vencieron sin completarse.
    
-   `completionRate` number requerido
    
    Porcentaje de completados sobre los enviados (0–100).
    
-   `avgSignTimeHours` number puede ser null
    
    Horas promedio entre la creación del documento y su última firma. `null` si aún no hay documentos completados en el periodo.
    

Errores posibles (problem+json): [401](https://allsign.io/developers/docs/errors) [403](https://allsign.io/developers/docs/errors) [422](https://allsign.io/developers/docs/errors) [429](https://allsign.io/developers/docs/errors)

**cURL**

```
curl 'https://api.allsign.io/v3/analytics/kpis?period=30d' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11"
```

**Node**

```
const respuesta = await fetch('https://api.allsign.io/v3/analytics/kpis?period=30d', {
    headers: {
        Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}`,
        'AllSign-Version': '2026-07-11',
    },
});
console.log(respuesta.status, await respuesta.json());
```

**Python**

```
import os

import requests

respuesta = requests.get(
    "https://api.allsign.io/v3/analytics/kpis?period=30d",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
    },
)
print(respuesta.status_code, respuesta.json())
```

**Respuesta · 200**

```
{
  "totalDocs": 114,
  "completed": 110,
  "pending": 2,
  "expired": 0,
  "completionRate": 96.5,
  "avgSignTimeHours": null
}
```

Grabado en el entorno interno de AllSign con una key de sandbox · backend `24c0469` · 8 oct 2026, 06:12 (hora CDMX) · test `docs-checks-v3/tests/ejemplos/analitica.ejemplos.spec.ts`

## 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` string query
    
    Ventana de tiempo: `7d`, `30d`, `90d` o `12m`. Default `30d`.
    
    default "30d"
    
-   `AllSign-Version` enum header
    
    Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 `UNSUPPORTED_API_VERSION`.
    
    Valores: `2026-07-11`
    

#### Devuelve

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

Ver los 6 atributos de la respuesta

-   `object` string, siempre "list"
    
    Siempre `"list"`.
    
-   `data` array de objetos requerido
    
    Las 4 etapas del embudo, en orden.
    
    Ver 3 atributos hijos
    
    -   `data[].label` string requerido
        
        Nombre de la etapa (ej. "Enviados").
        
    -   `data[].count` integer requerido
        
        Documentos en esa etapa.
        
    -   `data[].pct` number requerido
        
        Porcentaje de esa etapa respecto a la primera.
        
    
-   `hasMore` boolean
    
    Siempre `false` — colección acotada, sin cursor.
    
    default false
    
-   `nextCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `previousCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `limit` null
    
    Siempre `null` — sin parámetro `limit` en este endpoint.
    

Errores posibles (problem+json): [401](https://allsign.io/developers/docs/errors) [403](https://allsign.io/developers/docs/errors) [422](https://allsign.io/developers/docs/errors) [429](https://allsign.io/developers/docs/errors)

**cURL**

```
curl 'https://api.allsign.io/v3/analytics/funnel?period=30d' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11"
```

**Node**

```
const respuesta = await fetch('https://api.allsign.io/v3/analytics/funnel?period=30d', {
    headers: {
        Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}`,
        'AllSign-Version': '2026-07-11',
    },
});
console.log(respuesta.status, await respuesta.json());
```

**Python**

```
import os

import requests

respuesta = requests.get(
    "https://api.allsign.io/v3/analytics/funnel?period=30d",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
    },
)
print(respuesta.status_code, respuesta.json())
```

**Respuesta · 200**

```
{
  "object": "list",
  "data": [
    {
      "label": "Enviados",
      "count": 114,
      "pct": 100
    },
    {
      "label": "En progreso",
      "count": 2,
      "pct": 1.8
    },
    {
      "label": "Completados",
      "count": 110,
      "pct": 96.5
    },
    {
      "label": "Expirados",
      "count": 0,
      "pct": 0
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "previousCursor": null,
  "limit": null
}
```

Grabado en el entorno interno de AllSign con una key de sandbox · backend `24c0469` · 8 oct 2026, 06:12 (hora CDMX) · test `docs-checks-v3/tests/ejemplos/analitica.ejemplos.spec.ts`

## Monthly trend

GET `/analytics/trend`

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

#### Parámetros

-   `AllSign-Version` enum header
    
    Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 `UNSUPPORTED_API_VERSION`.
    
    Valores: `2026-07-11`
    

#### Devuelve

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

Ver los 6 atributos de la respuesta

-   `object` string, siempre "list"
    
    Siempre `"list"`.
    
-   `data` array de objetos requerido
    
    Un punto por mes (hasta 6).
    
    Ver 3 atributos hijos
    
    -   `data[].month` string requerido
        
        Abreviatura del mes en inglés, sin año (ej. "Jan"). No es formato ISO `YYYY-MM`: el mismo valor se repite para meses de distintos años. Mantiene el formato que ya expone `GET /v2/analytics/trend` (contrato público en vivo) por compatibilidad.
        
    -   `data[].signed` integer requerido
        
        Documentos firmados ese mes.
        
    -   `data[].avgHours` number requerido
        
        Horas promedio de firma ese mes.
        
    
-   `hasMore` boolean
    
    Siempre `false`.
    
    default false
    
-   `nextCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `previousCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `limit` null
    
    Siempre `null` — sin parámetro `limit` en este endpoint.
    

Errores posibles (problem+json): [401](https://allsign.io/developers/docs/errors) [403](https://allsign.io/developers/docs/errors) [422](https://allsign.io/developers/docs/errors) [429](https://allsign.io/developers/docs/errors)

**cURL**

```
curl 'https://api.allsign.io/v3/analytics/trend' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11"
```

**Node**

```
const respuesta = await fetch('https://api.allsign.io/v3/analytics/trend', {
    headers: {
        Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}`,
        'AllSign-Version': '2026-07-11',
    },
});
console.log(respuesta.status, await respuesta.json());
```

**Python**

```
import os

import requests

respuesta = requests.get(
    "https://api.allsign.io/v3/analytics/trend",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
    },
)
print(respuesta.status_code, respuesta.json())
```

**Respuesta · 200**

```
{
  "object": "list",
  "data": [
    {
      "month": "Oct",
      "signed": 110,
      "avgHours": 0
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "previousCursor": null,
  "limit": null
}
```

Grabado en el entorno interno de AllSign con una key de sandbox · backend `24c0469` · 8 oct 2026, 06:12 (hora CDMX) · test `docs-checks-v3/tests/ejemplos/analitica.ejemplos.spec.ts`

## Bottlenecks

GET `/analytics/bottlenecks`

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

#### Parámetros

-   `limit` integer query
    
    Máximo de firmantes a devolver (1–20, default `5`).
    
    default 5 · entre 1 y 20
    
-   `AllSign-Version` enum header
    
    Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 `UNSUPPORTED_API_VERSION`.
    
    Valores: `2026-07-11`
    

#### Devuelve

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

Ver los 6 atributos de la respuesta

-   `object` string, siempre "list"
    
    Siempre `"list"`.
    
-   `data` array de objetos requerido
    
    Firmantes ordenados por firmas pendientes.
    
    Ver 4 atributos hijos
    
    -   `data[].signerName` string requerido
        
        Nombre del firmante.
        
    -   `data[].signerEmail` string puede ser null
        
        Correo del firmante, si se conoce.
        
    -   `data[].pendingCount` integer requerido
        
        Firmas pendientes de esta persona.
        
    -   `data[].avgDays` number requerido
        
        Días promedio que llevan pendientes.
        
    
-   `hasMore` boolean
    
    Siempre `false` — la lista la acota `limit`, no un cursor.
    
    default false
    
-   `nextCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `previousCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `limit` integer requerido
    
    El límite aplicado a esta respuesta.
    

Errores posibles (problem+json): [401](https://allsign.io/developers/docs/errors) [403](https://allsign.io/developers/docs/errors) [422](https://allsign.io/developers/docs/errors) [429](https://allsign.io/developers/docs/errors)

**cURL**

```
curl 'https://api.allsign.io/v3/analytics/bottlenecks?limit=5' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11"
```

**Node**

```
const respuesta = await fetch('https://api.allsign.io/v3/analytics/bottlenecks?limit=5', {
    headers: {
        Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}`,
        'AllSign-Version': '2026-07-11',
    },
});
console.log(respuesta.status, await respuesta.json());
```

**Python**

```
import os

import requests

respuesta = requests.get(
    "https://api.allsign.io/v3/analytics/bottlenecks?limit=5",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
    },
)
print(respuesta.status_code, respuesta.json())
```

**Respuesta · 200**

```
{
  "object": "list",
  "data": [
    {
      "signerName": "signer-declined@sandbox.allsign.io",
      "signerEmail": "signer-declined@sandbox.allsign.io",
      "pendingCount": 2,
      "avgDays": 0.1
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "previousCursor": null,
  "limit": 5
}
```

Grabado en el entorno interno de AllSign con una key de sandbox · backend `24c0469` · 8 oct 2026, 06:12 (hora CDMX) · test `docs-checks-v3/tests/ejemplos/analitica.ejemplos.spec.ts`

## Team activity

GET `/analytics/team`

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

#### Parámetros

-   `period` string query
    
    Ventana de tiempo: `7d`, `30d`, `90d` o `12m`. Default `30d`.
    
    default "30d"
    
-   `AllSign-Version` enum header
    
    Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 `UNSUPPORTED_API_VERSION`.
    
    Valores: `2026-07-11`
    

#### Devuelve

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

Ver los 6 atributos de la respuesta

-   `object` string, siempre "list"
    
    Siempre `"list"`.
    
-   `data` array de objetos requerido
    
    Una fila por miembro del equipo.
    
    Ver 7 atributos hijos
    
    -   `data[].userId` string requerido
        
        ID opaco del miembro (`usr_…`) — el mismo prefijo que usa `GET /v3/users/me`, no un UUID crudo.
        
    -   `data[].name` string requerido
        
        Nombre del miembro.
        
    -   `data[].initials` string requerido
        
        Iniciales para avatar.
        
    -   `data[].role` string requerido
        
        Rol del miembro en el tenant.
        
    -   `data[].sent` integer requerido
        
        Documentos enviados por el miembro.
        
    -   `data[].signed` integer requerido
        
        Documentos enviados por el miembro que ya se completaron.
        
    -   `data[].rate` number requerido
        
        Tasa de finalización del miembro.
        
    
-   `hasMore` boolean
    
    Siempre `false` — acotada por el número de asientos del tenant.
    
    default false
    
-   `nextCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `previousCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `limit` null
    
    Siempre `null` — sin parámetro `limit` en este endpoint.
    

Errores posibles (problem+json): [401](https://allsign.io/developers/docs/errors) [403](https://allsign.io/developers/docs/errors) [422](https://allsign.io/developers/docs/errors) [429](https://allsign.io/developers/docs/errors)

**cURL**

```
curl 'https://api.allsign.io/v3/analytics/team?period=30d' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11"
```

**Node**

```
const respuesta = await fetch('https://api.allsign.io/v3/analytics/team?period=30d', {
    headers: {
        Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}`,
        'AllSign-Version': '2026-07-11',
    },
});
console.log(respuesta.status, await respuesta.json());
```

**Python**

```
import os

import requests

respuesta = requests.get(
    "https://api.allsign.io/v3/analytics/team?period=30d",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
    },
)
print(respuesta.status_code, respuesta.json())
```

**Respuesta · 200**

```
{
  "object": "list",
  "data": [
    {
      "userId": "usr_40f0ca57b4a34de68d2adce4c1f053f3",
      "name": "Ana Torres",
      "initials": "AT",
      "role": "owner",
      "sent": 114,
      "signed": 110,
      "rate": 96.5
    },
    {
      "userId": "usr_22697584acbb4cdfa129d218622459cf",
      "name": "Luis Ramírez",
      "initials": "LR",
      "role": "developer",
      "sent": 0,
      "signed": 0,
      "rate": 0
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "previousCursor": null,
  "limit": null
}
```

Grabado en el entorno interno de AllSign con una key de sandbox · backend `24c0469` · 8 oct 2026, 06:12 (hora CDMX) · test `docs-checks-v3/tests/ejemplos/analitica.ejemplos.spec.ts`

## Recent events

GET `/analytics/events`

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

#### Parámetros

-   `limit` integer query
    
    Máximo de eventos a devolver (1–50, default `8`).
    
    default 8 · entre 1 y 50
    
-   `AllSign-Version` enum header
    
    Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 `UNSUPPORTED_API_VERSION`.
    
    Valores: `2026-07-11`
    

#### Devuelve

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

Ver los 6 atributos de la respuesta

-   `object` string, siempre "list"
    
    Siempre `"list"`.
    
-   `data` array de objetos requerido
    
    Eventos recientes, más nuevos primero.
    
    Ver 6 atributos hijos
    
    -   `data[].id` string requerido
        
        ID del evento (`evt_…`).
        
    -   `data[].documentName` string requerido
        
        Nombre del documento del evento.
        
    -   `data[].eventType` string requerido
        
        Tipo de evento (token opaco, ej. `document.created`).
        
    -   `data[].actorName` string puede ser null
        
        Nombre de quien originó el evento, o `null` si fue el sistema.
        
    -   `data[].actorInitials` string requerido
        
        Iniciales del actor.
        
    -   `data[].createdAt` string (fecha-hora ISO 8601) requerido
        
        Cuándo ocurrió (ISO 8601).
        
    
-   `hasMore` boolean
    
    Siempre `false` — la lista la acota `limit`.
    
    default false
    
-   `nextCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `previousCursor` null
    
    Siempre `null` — esta colección no pagina.
    
-   `limit` integer requerido
    
    El límite aplicado a esta respuesta.
    

Errores posibles (problem+json): [401](https://allsign.io/developers/docs/errors) [403](https://allsign.io/developers/docs/errors) [422](https://allsign.io/developers/docs/errors) [429](https://allsign.io/developers/docs/errors)

**cURL**

```
curl 'https://api.allsign.io/v3/analytics/events?limit=5' \
  -H "Authorization: Bearer $ALLSIGN_API_KEY" \
  -H "AllSign-Version: 2026-07-11"
```

**Node**

```
const respuesta = await fetch('https://api.allsign.io/v3/analytics/events?limit=5', {
    headers: {
        Authorization: `Bearer ${process.env.ALLSIGN_API_KEY}`,
        'AllSign-Version': '2026-07-11',
    },
});
console.log(respuesta.status, await respuesta.json());
```

**Python**

```
import os

import requests

respuesta = requests.get(
    "https://api.allsign.io/v3/analytics/events?limit=5",
    headers={
        "Authorization": f"Bearer {os.environ['ALLSIGN_API_KEY']}",
        "AllSign-Version": "2026-07-11",
    },
)
print(respuesta.status_code, respuesta.json())
```

**Respuesta · 200**

```
{
  "object": "list",
  "data": [
    {
      "id": "evt_8ae1527a4958486a8ab7309659efb9dc",
      "documentName": "Contrato de compraventa — firma en orden",
      "eventType": "document.viewed",
      "actorName": "Ana Torres",
      "actorInitials": "AT",
      "createdAt": "2026-07-11T18:00:00.000000Z"
    },
    {
      "id": "evt_1b16458ac1454c7b9fa51bc71d9900f2",
      "documentName": "Mi primer contrato (sandbox)",
      "eventType": "document.viewed",
      "actorName": "Ana Torres",
      "actorInitials": "AT",
      "createdAt": "2026-07-11T17:59:57.296000Z"
    },
    {
      "id": "evt_f0700cbe6c184ef9ba5d0062a2796b50",
      "documentName": "Contrato de compraventa — firma en orden",
      "eventType": "signature.signed",
      "actorName": "signer-pending+2@sandbox.allsign.io",
      "actorInitials": "SH",
      "createdAt": "2026-07-11T17:59:57.140000Z"
    },
    {
      "id": "evt_58b3d46cc6e3455fa54e76084910f03b",
      "documentName": "Contrato de compraventa — firma en orden",
      "eventType": "signature.consent_given",
      "actorName": "signer-pending+2@sandbox.allsign.io",
      "actorInitials": "SH",
      "createdAt": "2026-07-11T17:59:57.140000Z"
    },
    {
      "id": "evt_a5b8b7014cdf42c5ab4ada3e583b3bb4",
      "documentName": "Mi primer contrato (sandbox)",
      "eventType": "document.viewed",
      "actorName": "Ana Torres",
      "actorInitials": "AT",
      "createdAt": "2026-07-11T17:59:40.522000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "previousCursor": null,
  "limit": 5
}
```

Grabado en el entorno interno de AllSign con una key de sandbox · backend `24c0469` · 8 oct 2026, 06:12 (hora CDMX) · test `docs-checks-v3/tests/ejemplos/analitica.ejemplos.spec.ts`