API de analítica de enlaces: obtén estadísticas de clics con una clave API

La API de analítica de enlaces de Elido es un único endpoint, GET /v1/workspaces/{workspace_id}/analytics/{report} en https://api.elido.app, autenticado con una clave API de espacio de trabajo. Ofrece 15 informes: series temporales de clics, un resumen de interacción, enlaces principales, un feed paginado con cursor de clics recientes y desgloses por país, referente, dispositivo, navegador, host y destino. Las fechas abarcan por defecto los últimos 30 días, link_id limita cualquier informe a un enlace corto, y la exportación CSV, los embudos, las cohortes y LTV se mantienen en el panel.

Esa es toda la respuesta si solo necesitaba la URL. El resto de esta guía es lo que me gustaría que cada página de API de analítica de clics explicara desde el principio: los parámetros exactos, el JSON que recibe, dónde el intervalo de fechas funciona, sin avisar, de forma distinta a lo que supondría y un script de 30 líneas que publica cada mañana en Slack las cifras de ayer.

La mayoría de quienes extraen datos de clics están cerrando un ciclo que comienza con el etiquetado de campañas, así que si sus enlaces aún no incluyen UTM coherentes, resuelva eso primero con el seguimiento UTM integral. Unos datos de entrada limpios hacen que las estadísticas merezcan la pena.

Qué devuelve la API de analítica de enlaces

Todos los informes están en la misma ruta, y el nombre del informe es el último segmento. Los nombres con una barra (links/top, clicks/recent, breakdown/country) se envían sin codificar. Si solicita algo fuera de la lista permitida, obtiene un 404 con unknown analytics report.

Observe la última fila. Los informes de región y ciudad envuelven sus filas en points, no en items, porque cada fila contiene un país más una región o ciudad en lugar de una sola clave. He visto un analizador genérico fallar con eso exactamente una vez. Una vez basta.

La misma interfaz respalda las API y SDK, la herramienta de analítica del servidor MCP y la operación Get Analytics del nodo n8n, así que lo que aprenda aquí se traslada.

Autenticación con una clave API de espacio de trabajo

Las claves API comienzan por elido_ y pertenecen exactamente a un espacio de trabajo. Envíe la clave como token bearer:

curl -s "https://api.elido.app/v1/workspaces/4821/analytics/summary" \
  -H "Authorization: Bearer $ELIDO_API_KEY"

El enrutador comprueba dos cosas antes de ejecutar cualquier consulta: que la clave pertenece al espacio de trabajo 4821 y que tiene analytics.view. Todos los roles integrados tienen ese permiso, incluido Viewer. Por tanto, cree una clave Viewer para las tareas de informes. Un cron de informes no debería poder eliminar enlaces, y una clave Viewer no puede. Una clave sin acceso recibe un 403.

link_id tampoco amplía el acceso. El ID de espacio de trabajo de la ruta es el que se comprueba, de modo que un ID de enlace tomado de un espacio de trabajo ajeno coincide con cero filas y devuelve una lista vacía. Es el fallo correcto: aburrido y sin filtraciones.

Parámetros de consulta para estadísticas de clics: fechas, zona horaria y filtros

Seis parámetros cubren casi todas las llamadas a la API de estadísticas de enlaces cortos que hará:

• from y to, como YYYY-MM-DD. Omita ambos y recibirá los 30 días hasta ahora. Establezca solo to y from se fija por defecto en 30 días antes.
• link_id para limitar cualquier informe a un enlace, y host para limitarlo a un dominio de redirección, útil cuando un espacio de trabajo gestiona varios dominios de marca.
• interval para timeseries, hour o day (el valor predeterminado). Cualquier otro valor hace que falle la solicitud.
• limit para desgloses y listas principales, de 1 a 200, 50 por defecto. links/top es el caso atípico: devuelve 10 salvo que pida más.

Aquí está el detalle que puede causar problemas. Ambas fechas se interpretan como medianoche UTC, y el intervalo incluye from pero termina antes de to. Para todo el 21 de septiembre, envíe from=2026-09-21&to=2026-09-22. Envíe to=2026-09-21 y no obtendrá nada de ese día.

La zona horaria es el otro punto. Pase tz como un nombre de zona horaria IANA, o establezca una cabecera X-User-TZ, y timeseries calcula sus bloques horarios o diarios según la hora local. Solo se mueven los bloques. El intervalo from/to sigue siendo UTC, así que un "ayer" de Berlín necesita un intervalo algo más amplio, que el script siguiente gestiona. Una errata como Europe/Berln devuelve un 400 con unknown IANA timezone, mejor que un gráfico silenciosamente incorrecto.

curl -s -G "https://api.elido.app/v1/workspaces/4821/analytics/timeseries" \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "to=2026-09-22" \
  --data-urlencode "interval=day" \
  --data-urlencode "tz=Europe/Berlin" \
  --data-urlencode "link_id=918273"

Estructuras de respuesta que puede usar en código

Un punto de serie temporal contiene ts, una marca de tiempo RFC 3339 que indica el inicio del bloque, y count. Los bloques con cero clics simplemente no aparecen, así que complete usted mismo los huecos antes de crear el gráfico o un domingo tranquilo desaparecerá del eje x.

{
  "items": [
    { "ts": "2026-09-19T00:00:00Z", "count": 412 },
    { "ts": "2026-09-21T00:00:00Z", "count": 388 }
  ]
}

Los desgloses devuelven {"items": [{"key": "DE", "count": 1204}, ...]}, ordenados por recuento. El resumen es un objeto plano:

{
  "total_clicks": 5310,
  "unique_visitors": 3987,
  "returning_visitors": 611,
  "avg_clicks_per_visitor": 1.33,
  "bounce_rate": 0.85
}

Importan dos definiciones. Los visitantes únicos se cuentan por dirección IP distinta dentro del intervalo, por lo que una oficina tras una misma conexión cuenta una sola vez. Y bounce_rate es una fracción, no un porcentaje: la proporción de visitantes únicos que hicieron clic solo una vez en el intervalo. No dice nada de lo que ocurrió en su página de destino, por eso estas cifras nunca coinciden con las sesiones de GA4 (la publicación clics frente a sesiones de GA4 explica la diferencia). Todas las cifras se filtran de bots antes de llegarle, los mismos recuentos que ve en la analítica de enlaces de Elido.

Paginación de clics recientes con un cursor

clicks/recent es el informe de la API de seguimiento de enlaces que devuelve clics individuales, del más reciente al más antiguo. Cada fila tiene ts, link_id, slug, host, referer, country_code, device, browser, destination, user_agent e ip. El tamaño de página va de 1 a 500; el valor predeterminado es 100.

Cuando una página vuelve llena, la respuesta contiene un next_cursor. Páselo como ?cursor= para obtener la siguiente página, más antigua; null significa que ha llegado al final del intervalo.

El cursor apunta a la marca de tiempo y al ID de enlace de la última fila. Dos clics en el mismo enlace en el mismo milisegundo pueden empatar en un límite de página, y el peor caso es una fila duplicada, nunca una omitida. Elimine duplicados usando la fila completa al almacenarlas. Es raro, pero una inserción de diez líneas evita tener que explicarle a finanzas un error por uno (off-by-one).

Esas filas incluyen direcciones IP y agentes de usuario, por lo que son datos personales. Si las copia a un almacén de datos, manténgalo en la UE y establezca un período de retención; la guía de residencia de datos de la UE para equipos de marketing explica el motivo. Para la mayoría de informes no necesita filas sin procesar, y un agregado diario es más considerado con todos.

Un script de informe diario de clics para Slack o una hoja de cálculo

Este es el trabajo que la mayoría de personas realmente quiere: cada mañana, publicar en un canal los clics de ayer y los cinco enlaces principales. Usa solo la biblioteca estándar de Python y un webhook entrante de Slack.

import datetime as dt, json, os, urllib.parse, urllib.request
from zoneinfo import ZoneInfo

BASE = "https://api.elido.app/v1/workspaces/{ws}/analytics/{report}"
WS, KEY = os.environ["ELIDO_WORKSPACE_ID"], os.environ["ELIDO_API_KEY"]
TZ = ZoneInfo("Europe/Berlin")

def report(name, **params):
    url = BASE.format(ws=WS, report=name) + "?" + urllib.parse.urlencode(params)
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {KEY}"})
    with urllib.request.urlopen(req, timeout=20) as r:
        return json.load(r)

day = dt.datetime.now(TZ).date() - dt.timedelta(days=1)
# UTC window one day wider on each side, then keep only local hours of `day`
window = {"from": day - dt.timedelta(days=1), "to": day + dt.timedelta(days=2)}
hours = report("timeseries", interval="hour", tz="Europe/Berlin", **window)["items"]
total = sum(p["count"] for p in hours
            if dt.datetime.fromisoformat(p["ts"]).astimezone(TZ).date() == day)

top = report("links/top", limit=5, **{"from": day, "to": day + dt.timedelta(days=1)})
lines = [f"• {l['slug']}: {l['count']}" for l in top["items"]]
text = f"Clicks on {day} (Berlin): {total}\nTop links (UTC day):\n" + "\n".join(lines)

body = json.dumps({"text": text}).encode()
urllib.request.urlopen(urllib.request.Request(
    os.environ["SLACK_WEBHOOK_URL"], data=body,
    headers={"Content-Type": "application/json"}))

Ejecútelo desde cron a las 07:00 hora local. El truco horario es lo que hace que el total sea un día real de Berlín en lugar de uno UTC; links/top no tiene tz, así que su clasificación se mantiene en el día UTC, y el mensaje lo indica.

¿Prefiere una hoja de cálculo? Las mismas dos llamadas funcionan desde Google Apps Script con UrlFetchApp y un activador diario, añadiendo una fila por día. También es el camino más económico hacia un panel de Looker Studio.

Si todavía pega cifras de capturas de pantalla cada lunes, dé una clave Viewer a un script y recupere sus mañanas.

Lo que sigue siendo exclusivo del panel

La interfaz de claves API es de solo lectura y deliberadamente más limitada que el panel. No puede acceder a lo siguiente con una clave:

• La exportación de clics CSV (clicks.csv). El botón Descargar CSV del panel es la vía para archivos masivos.
• Embudos, cohortes, el informe LTV, los mapas de calor de tiempo y geografía, y la vista de calidad del tráfico.

Si solo necesita que un archivo llegue a algún sitio de forma programada, los informes por correo electrónico programados del panel lo hacen sin código. Para una extracción completa, como la que haría al abandonar un proveedor, vea qué puede exportar de una cuenta de enlaces cortos y cómo comprobar que está completa. Y todavía no existe una llamada combinada de "todo para un enlace", así que un panel por enlace implica una solicitud por informe. La guía rápida de SDK explica cómo ejecutarlas en paralelo y reducir el ritmo al alcanzar los límites de tasa.

Consultar la API de analítica de clics frente a webhooks en tiempo real

La versión honesta: hoy, los datos de clics solo se obtienen mediante consulta. Los webhooks de Elido envían eventos de enlaces y dominios, firmados y reintentados, pero un evento click.created por clic está previsto en la hoja de ruta y aún no se emite. Cualquier dato de clics en tiempo real requiere consultar clicks/recent.

Es menos molesto de lo que parece. Consulte cada minuto o dos, deténgase en cuanto llegue a una fila que ya haya almacenado y la carga seguirá siendo mínima, porque un minuto tranquilo es una página pequeña. Cuando se publique click.created, al controlador que procesa una fila le dará igual si provino de una página consultada o de un envío push. Las ventajas y desventajas generales se explican en webhooks frente a consultas para el seguimiento de clics, y si está decidiendo cuáles de estas cifras merecen siquiera un informe, qué medir en la analítica de enlaces cortos es una lectura más breve.

Mi opinión: comience con el resumen diario. Casi todos los equipos que me piden clics en tiempo real quedan satisfechos con las cifras de ayer entregadas antes del café.

Lea el artículo fundamental → Cómo realizar el seguimiento integral de campañas UTM

Contenido relacionado en el blog

• Guía rápida de la API y los SDK de acortador de URL - claves, SDK, límites de tasa y la llamada de creación.
• Nodo n8n de acortador de URL - los mismos informes de analítica dentro de un flujo de trabajo de n8n.
• Webhooks frente a consultas para el seguimiento de clics - cómo elegir el patrón de integración.
• Analítica de enlaces en Looker Studio - convertir la extracción diaria en un panel.
• Conecte Elido a Claude y Cursor con MCP - solicitar estadísticas de clics en lenguaje natural.