Skip to content

API pública ​

La API de linkable.id permite que tus propios sistemas, como un CRM, una herramienta de campañas o un script, creen enlaces cortos, descarguen sus códigos QR y lean sus estadísticas de clics. Es una API REST en JSON sobre HTTPS.

Disponibilidad: los planes Business, Agency y Enterprise. Pídenos activarla para tu cuenta.

El documento OpenAPI, para importarlo en Postman, Insomnia o un generador de clientes, está en el propio linkable.id: inicia sesión, abre Configuración → Tokens de API y haz clic en Descargar documento OpenAPI en Referencia de la API. La misma sección muestra la URL base de tu API con un botón para copiarla.

Inicio rápido ​

  1. En Configuración → Tokens de API, crea un token con los permisos que necesitas. Consulta Tokens de API.
  2. Copia la URL base desde Referencia de la API en la misma página. Es https://{dominio-de-administración}/api/v1, donde el dominio de administración es la dirección donde inicias sesión en linkable.id.
  3. Guarda el token en una variable de entorno (así no queda escrito en tus scripts) y envíalo como token Bearer:
bash
export LINKABLE_API_TOKEN="pega-aquí-tu-token"
curl https://tu-dominio-de-administracion/api/v1/me \
  -H "Authorization: Bearer $LINKABLE_API_TOKEN"

/me responde con el espacio de trabajo, los permisos y el vencimiento del token, una buena primera comprobación.

Un token funciona en un espacio de trabajo. Todo lo que crea o lee pertenece a ese espacio de trabajo.

Permisos ​

PermisoPermite al token
links:readListar y leer enlaces, y descargar sus códigos QR
links:writeCrear y actualizar enlaces
stats:readLeer las estadísticas de clics de los enlaces

Un token nunca puede hacer más de lo que permite el rol de su propietario. Si un administrador quita un permiso de tu rol, tus tokens lo pierden de inmediato.

Enlaces ​

Listar enlaces. Del más reciente al más antiguo, 25 por página (hasta 100 con limit). Filtra con search (nombre), tag y domain (nombre de dominio).

bash
curl "https://tu-dominio-de-administracion/api/v1/links?tag=primavera&limit=50" \
  -H "Authorization: Bearer $LINKABLE_API_TOKEN"

Crear un enlace. name, target y domain (uno de tus dominios, por su nombre) son obligatorios. Opcionales: description, tags (nombres; los nuevos se crean) y los parámetros UTM utm_id, utm_source, utm_medium, utm_campaign, utm_term, utm_content. La dirección corta se genera, y el enlace usa el tema QR predeterminado de tu espacio de trabajo.

bash
curl https://tu-dominio-de-administracion/api/v1/links \
  -H "Authorization: Bearer $LINKABLE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"name": "Volante de primavera", "target": "https://tienda.example.com/primavera", "domain": "go.example.com", "tags": ["primavera"], "utm_source": "volante"}'

Leer o actualizar un enlace. GET /links/{id} y PATCH /links/{id}. Un PATCH cambia solo los campos que envías. Un valor UTM vacío quita ese parámetro, y tags reemplaza toda la lista. La dirección corta nunca cambia. El enlace corto de una página de marca, un sitio o una Página personalizada siempre lleva a su página, así que su target no se puede cambiar.

Código QR. GET /links/{id}/qr.svg devuelve el código QR del enlace en SVG, con su tema QR.

Estadísticas ​

Clics de un enlace en el tiempo:

bash
curl "https://tu-dominio-de-administracion/api/v1/links/42/stats?from=2026-09-01&to=2026-09-30&interval=week" \
  -H "Authorization: Bearer $LINKABLE_API_TOKEN"

Clics por enlace en un periodo: GET /stats/links, en páginas como la lista de enlaces.

Ambos aceptan from y to (fechas AAAA-MM-DD, por defecto los últimos 30 días) e interval (auto, day, week, month, quarter o year). El periodo termina hoy como máximo y no empieza antes de lo que permite el historial de analítica de tu plan. Un periodo largo pedido por day se agrupa con un intervalo más amplio. Cada respuesta indica el from, el to y el interval que usó realmente.

Páginas ​

Las listas devuelven data y next_cursor. Envía next_cursor como cursor para obtener la página siguiente; es null en la última página.

Reintentar con seguridad ​

Agrega un encabezado Idempotency-Key (cualquier texto único de hasta 255 caracteres) a un POST. Si una solicitud exitosa se reintenta con la misma clave y el mismo cuerpo dentro de 24 horas, recibes de nuevo la primera respuesta, marcada con Idempotent-Replayed: true, en lugar de un segundo enlace. La misma clave con otro cuerpo se rechaza con 409, igual que un reintento mientras la primera solicitud sigue en curso. Una solicitud rechazada (por ejemplo, un 422) no se guarda, así que puedes corregir el cuerpo y reintentar con la misma clave.

Errores ​

Los errores siguen RFC 9457 (application/problem+json):

json
{
  "type": "urn:linkable:problem:validation_failed",
  "title": "Validación fallida",
  "status": 422,
  "detail": "Algunos campos no son válidos. Revisa errors.",
  "errors": { "domain": ["El campo domain seleccionado no es válido."] }
}
EstadoCuándo
401El token falta, venció o fue revocado, o su propietario salió del espacio de trabajo
403El token no tiene el permiso, o tu plan no incluye la API
404No existe nada con ese id en el espacio de trabajo del token
409Una Idempotency-Key usada con otro cuerpo, o su primera solicitud aún está en curso
422Campos no válidos (ver errors)
429Demasiadas solicitudes (ver abajo)

type es estable, así que basa el manejo de errores en él y no en el texto. detail está en el idioma del propietario del token.

Límites ​

  • Frecuencia: 120 solicitudes por minuto por token, indicadas en los encabezados X-RateLimit-Limit y X-RateLimit-Remaining. Por encima, recibes 429 con Retry-After (segundos). Las solicitudes con un token faltante o no válido se limitan aparte, por IP.
  • Llamadas mensuales: tu plan incluye una cantidad de llamadas a la API por mes, que ves en Plan y uso. Superarla envía un aviso a tus administradores y nunca detiene la API.

Versiones ​

Esta es la versión 1 (/api/v1). Dentro de v1 solo agregamos: endpoints nuevos, campos opcionales nuevos, campos nuevos en las respuestas. Haz que tu integración ignore los campos que no conoce. Un cambio incompatible llegaría como /api/v2, anunciado en Novedades al menos seis meses antes de que v1 deje de funcionar.

Con Claude ​

Claude no usa la API pública: trabaja con el conector de Claude, que cubre mucho más que los enlaces y actúa como la persona que lo conectó. Usa la API para tus propias integraciones, con un token; usa el conector para trabajar con Claude.