API de acortamiento de enlaces de Linkly
Crea, actualiza y gestiona enlaces mediante programación usando la API de acortamiento de enlaces de Linkly.
Relacionado: Analytics API | Webhooks
Antes de empezar
Linkly genera solicitudes de API en la interfaz para que las copies y pegues en tus aplicaciones.
Esto funciona para la creación de enlaces y la actualización de enlaces.
Ahorra tiempo y deja que hagamos el trabajo duro:
- 1Ve a continuación para ver las solicitudes de API de creación de enlaces.
- 2Copia las solicitudes en su totalidad. Puedes verificar que funcionen para ti.
- 3Pide a ChatGPT o equivalente que adapte estas solicitudes a código fuente para tu aplicación. No es necesario pasar tiempo en una integración compleja. Nuestra API es completamente consumible por máquinas.
Especificación OpenAPI 3.0
Puedes generar solicitudes de API directamente desde la interfaz de usuario de Linkly.
Constructor de API de acortamiento de enlaces de Linkly
La API de acortamiento de enlaces de Linkly construye automáticamente solicitudes de API basadas en el contenido del formulario. Puedes pegar el texto que se proporciona aquí en cualquier LLM para generar automáticamente código para tu aplicación.
La API de Linkly está documentada utilizando el estándar OpenAPI, que va más allá de lo que se proporciona a continuación. Los mismos endpoints también están disponibles como una colección de Postman de un clic.
Autorización
Necesitarás:
- Tu clave de API
- ID del espacio de trabajo
Puedes obtener estos detalles dentro de Linkly.
- 1Inicia sesión en Linkly.
- 2Haz clic en Configuración.
- 3Haz clic en Claves de API.
Crear o actualizar un enlace
Para crear un enlace, todo lo que necesitas hacer es enviar una solicitud POST a:
https://app.linklyhq.com/api/v1/link
con los siguientes campos en el cuerpo.
El tipo de codificación es x-www-form-urlencoded o application/json.
Si estás presentando el campo Rules, debes usar application/json.
Te recomendamos que uses JSON con la especificación Open API.
| Etiqueta | Clave | Tipo | Notas |
|---|---|---|---|
| Clave de API de cuenta | api_key | Cadena | Requerido |
| ID del espacio de trabajo | workspace_id | Entero | Requerido |
| ID de enlace | id | Entero | Requerido si se actualiza un enlace existente |
| Destino | url | Cadena | Requerido |
| Apodo | name | Cadena | |
| Notas | note | Cadena | |
| Metadatos | metadata | Objeto | Tus propios datos de clave-valor, como IDs de tu sistema. Ver metadatos |
| Etiquetas de retargeting (región head) | head_tags | Cadena | Para píxeles de retargeting |
| Etiquetas de retargeting (región body) | body_tags | Cadena | Para píxeles de retargeting |
| Parámetros de envío | forward_params | Booleano | |
| Ocultar referidor | hide_referrer | Booleano | Envía referrer-policy: no-referrer para que el destino no vea Linkly en el encabezado referer |
| Enmascaramiento | cloaking | Booleano | Enmasca la URL de destino detrás de un marco |
| Bloquear bots | block_bots | Booleano | Bloquea bots/rastreadores conocidos |
| Omitir rastreo de rastreador social | skip_social_crawler_tracking | Booleano | Cuando block_bots está activado, aún permite que los rastreadores sociales pasen para que funcionen las previsualizaciones de OG |
| Análisis público | public_analytics | Booleano | Habilita la página /abc123.stats pública para este enlace |
| Contraseña | password | Cadena | Los visitantes deben ingresar esta contraseña antes de redirigir |
| Estado de publicación | enabled | Booleano | |
| Fuente de UTM | utm_source | Cadena | Para rastreo de UTM |
| Medio de UTM | utm_medium | Cadena | Para rastreo de UTM |
| Campaña de UTM | utm_campaign | Cadena | Para rastreo de UTM |
| Término de UTM | utm_term | Cadena | Para rastreo de UTM |
| Contenido de UTM | utm_content | Cadena | Para rastreo de UTM |
| Dominio personalizado | domain | Cadena | Requerido si se proporciona slug. Ver dominios personalizados |
| Sufijo de dominio personalizado | slug | Cadena | Si se proporciona dominio y slug es nulo, se generará automáticamente |
| Título de Open Graph | og_title | Cadena | Para vistas previas de redes sociales |
| Descripción de Open Graph | og_description | Cadena | Para vistas previas de redes sociales |
| URL de imagen de Open Graph | og_image | Cadena | Para vistas previas de redes sociales |
| ID de píxel Meta | fb_pixel_id | Cadena | Para píxel Meta |
| ID de píxel TikTok | tiktok_pixel_id | Cadena | |
| ID de Google Analytics 4 | ga4_tag_id | Cadena | |
| Contenedor de Google Tag Manager | gtm_id | Cadena | |
| Linkify Words | linkify_words | Cadena | Frases separadas por saltos de línea que deben acortarse automáticamente en páginas de destino |
| Reemplazos | replacements | Cadena | Reglas de reemplazo de texto aplicadas a la página de destino |
| Fecha y hora de vencimiento | expiry_datetime | Cadena de fecha ISO8601 | Para enlaces que expiran |
| Destino de vencimiento | expiry_destination | Cadena (URL) | Para enlaces que expiran. Debe comenzar con http. |
| Clics de vencimiento | expiry_clicks | Entero | Vencer el enlace después de este número de clics |
| Webhooks | webhooks | Array de cadenas | URLs de webhook por enlace. Ver webhooks. |
| IDs de usuario a notificar | notify_user_ids | Array de enteros | IDs de usuarios del espacio de trabajo a notificar en cada clic |
| Estilos de código QR | qr_styles | Objeto JSON | Para estilos de código QR. Claves: fgColor, bgColor, qrStyle, eyeStyle, eyeColorInner, eyeColorOuter, logoImage, logoWidth, logoHeight, logoPadding, logoStyle, quietZone |
| Reglas | rules | Array JSON | Para rotadores, redirecciones geo, y redirecciones de dispositivo |
Solicitud de ejemplo usando curl
El código a continuación ilustra cómo hacer una solicitud de API para crear un enlace.
curl -X POST https://app.linklyhq.com/api/v1/link
-H 'cache-control: no-cache'
-d 'api_key=your_secret_key&workspace_id=1&url=http%3A%2F%2Fwww.wikijob.co.uk&name=Test%20Link'
Una respuesta exitosa devolverá un objeto JSON que representa el enlace, junto con un id de enlace.
{
"id": 9512,
"url": "https://www.wikijob.co.uk",
"name": "Test Link",
"note": null,
"metadata": {},
"head_tags": null,
"body_tags": null,
"linkify_words": null,
"replacements": null,
"enabled": true,
"cloaking": false,
"forward_params": false,
"hide_referrer": false,
"block_bots": false,
"skip_social_crawler_tracking": false,
"public_analytics": false,
"password": null,
"domain": null,
"slug": null,
"utm_source": null,
"utm_medium": null,
"utm_campaign": null,
"utm_term": null,
"utm_content": null,
"og_title": null,
"og_description": null,
"og_image": null,
"fb_pixel_id": null,
"tiktok_pixel_id": null,
"ga4_tag_id": null,
"gtm_id": null,
"full_url": "https://l.linklyhq.com/l/2TQ",
"rules": [],
"expiry_datetime": null,
"expiry_destination": null,
"expiry_clicks": null,
"qr_styles": null,
"webhooks": [],
"notify_user_ids": [],
"workspace_id": 1448,
"deleted": false
}
Actualizar un enlace
Para actualizar un enlace, envía la misma solicitud que usarías para crear el enlace, pero incluye el campo id para el enlace que deseas actualizar, junto con los cambios.
Adjuntar tus propios datos a un enlace (metadatos)
Usa metadata para almacenar tus propios identificadores en un enlace, como un ID de pedido, un ID de contacto de CRM o una referencia de campaña de tu propio sistema. Es un conjunto de pares clave-valor, y se devuelve siempre que obtengas el enlace y en cada carga útil de webhook (eventos de clic y enlace), para que puedas vincular un clic al registro al que pertenece.
Envíalo en un cuerpo de solicitud JSON, como un objeto:
curl -X POST https://app.linklyhq.com/api/v1/link
-H 'Content-Type: application/json'
-d '{"api_key": "your_secret_key", "workspace_id": 1, "url": "https://example.com", "metadata": {"order_id": "A-10293", "crm_contact_id": "3f2b8c1e-9a47-4d0e-b6a5-1c2d3e4f5a6b"}}'
El enlace en la respuesta incluye "metadata": {"order_id": "A-10293", "crm_contact_id": "3f2b8c1e-9a47-4d0e-b6a5-1c2d3e4f5a6b"}.
Cómo funciona:
- Las actualizaciones se fusionan. Cuando actualizas un enlace, las claves que envías se agregan a los metadatos existentes del enlace, y las claves que no mencionas se dejan sin cambios. Para eliminar una clave, establécela en
null(por ejemplo{"metadata": {"order_id": null}}). - Los valores son cadenas. Los números y booleanos se almacenan como texto, por lo que
42vuelve como"42". Los objetos anidados y las matrices no están permitidos. - Límites. Hasta 20 claves por enlace, claves de hasta 40 caracteres y valores de hasta 500 caracteres, suficiente para un UUID.
- Privado para ti. Los metadatos nunca se muestran a las personas que hacen clic en el enlace, no se utilizan para construir la redirección y no se agregan a la URL de destino.
- En la aplicación. También puedes ver y editar metadatos en la configuración de Automatización de un enlace, en Metadatos.
Metadatos, notas y parámetros de UTM
Los metadatos, el campo note y los parámetros de UTM todos describen un enlace, pero hacen trabajos diferentes:
- Metadatos son datos estructurados de clave-valor para tus propios sistemas. Se devuelven por la API y se envían en webhooks, para que el software pueda leerlos.
- Nota es un único campo de texto libre para que una persona lo lea en la aplicación.
- Parámetros de UTM se agregan a la URL de destino, por lo que la página a la que envías visitantes y su análisis pueden verlos. Los metadatos nunca lo hacen. Para pasar un valor a la página de destino, usa un parámetro de UTM, o activa Reenviar parámetros para que los parámetros de consulta en el enlace corto se pasen.
Metadatos y análisis
Los metadatos no se incluyen en el análisis de clics o exportaciones de clics, y no puedes agrupar ni filtrar clics, ni buscar enlaces, por metadatos. Para vincular clics a tus propios registros, usa el id del enlace. Aparece en cargas útiles de webhooks, en análisis desglosado por enlace, y en respuestas de enlaces. Ya sea que busques tu registro desde el id del enlace de tu lado, o recuperes el enlace para leer sus metadatos.
Creación de rotadores a través de la API
Para crear un rotador, presenta un campo llamado rules como un array JSON, junto con la carga útil del enlace anterior. Debes usar application/json para enviar arrays JSON.
Por ejemplo:
[
{"what": "rotator", "url": "https://www.microsoft.com", "percentage": "50"},
{"what": "rotator", "url": "https://www.apple.com", "percentage": "50"}
]
Creación de redirecciones geo a través de la API
Para redirigir por país, presenta un campo llamado rules como un array JSON, junto con la carga útil del enlace anterior. Debes usar la codificación application/json para enviar arrays JSON.
Por ejemplo:
[
{"what": "country", "url": "https://www.microsoft.com", "matches": "UK"},
{"what": "country", "url": "https://www.apple.com", "matches": "US"}
]
El país es el código de país ISO 3166 alfa-2.
Creación de redirecciones de dispositivo a través de la API
Para redirigir por dispositivo, presenta un campo llamado rules como un array JSON, junto con la carga útil del enlace anterior.
Por ejemplo:
[
{"what": "platform", "url": "https://www.google.com", "matches": "windows"},
{"what": "platform", "url": "https://www.apple.com", "matches": "ios"}
]
Donde el campo matches es uno de:
- ios
- android
- windows
- linux
- mac
Crear o actualizar múltiples enlaces en una solicitud
Linkly admite la creación/enmienda de hasta 1000 enlaces por solicitud.
Para hacerlo, presenta tu clave de API como parte de la solicitud de la siguiente manera:
https://app.linklyhq.com/api/v1/links?api_key=XXXXXXXXXXX
Luego, usa el mismo esquema que arriba para los casos de enlace individual, pero envuelve las solicitudes de enlace en un array, de la forma:
[{link}, {link}]
Aquí hay una solicitud completa que actualizará dos enlaces:
wget --no-check-certificate \
--method POST \
--timeout=0 \
--header 'Content-Type: application/json' \
--body-data '[
{
"workspace_id": "WORKSPACE_ID",
"url": "https://nature.com",
"name": "Test",
"id": LINK_ID
},
{
"workspace_id": "WORKSPACE_ID",
"url": "https://science.com",
"id": LINK_ID
}
]' \
'https://app.linklyhq.com/api/v1/links?api_key=API_KEY'
Esto funciona tanto para acciones de creación como de actualización.
Tenga en cuenta que puede tomar hasta 60 segundos para una solicitud grande. Si las solicitudes toman más tiempo que esto, fallarán y debe considerar dividir su carga de trabajo en fragmentos más pequeños.
Límites de velocidad
La API de acortamiento de enlaces está limitada a 20 solicitudes/segundo. Hasta 200/solicitudes por segundo están disponibles bajo solicitud. Puedes cargar hasta 1000 enlaces en una sola solicitud.
Relacionado
- Analytics API - Exporta datos de clics e informes de tráfico
- Webhooks - Notificaciones de clics en tiempo real
- Integración de Zapier - Integraciones sin código
Disponibilidad del plan
Incluido en todos los planes
Rastrea 500 clics mensuales con todas las funciones incluidas.