Llega un momento en que un equipo deja de crear enlaces a mano. El producto necesita un enlace para compartir por usuario, el CMS debería generar una URL corta al publicar un artículo y la herramienta de campañas quiere un enlace con seguimiento por cada creatividad. Una integración para desarrolladores que crea enlaces con dominio propio y seguimiento convierte el acortador en una función a la que llaman tus sistemas.
Esta guía recorre la integración de principio a fin: qué decidir antes de escribir código, cómo funcionan la autenticación y la llamada de creación, cómo hacer que los enlaces tengan seguimiento sin romper la atribución, los casos límite de las redirecciones que dan problemas, cómo encajan los webhooks y cómo probarlo todo. El ejemplo práctico es la API de LinkPilot; la estructura vale para la mayoría de las plataformas.
Decide primero la arquitectura
Cuatro decisiones, tomadas una vez, ahorran la mayor parte del trabajo rehecho.
- Qué sistemas crean enlaces y con qué disparador: un evento de publicación, una acción del usuario, el guardado de un registro de campaña.
- Qué campos controla quien llama. Normalmente el destino y las etiquetas; a veces el slug. Rara vez el dominio, que debería ser una configuración por espacio de trabajo o por cliente.
- Cómo se traducen los datos de campaña al seguimiento. La campaña, el canal y la ubicación de tu sistema se convierten en etiquetas del enlace y en parámetros UTM del destino. Decide la correspondencia y ponla en una sola función.
- Enlace directo, enlace profundo o alternativa. Un enlace que abre una app móvil necesita una alternativa web para quien no tiene la app. Decide si eso lo resuelve el acortador o el destino.
Ponlo por escrito. La integración es sobre todo código de unión, y ese código debería ser aburrido.
Autentícate con claves de alcance limitado
La API de LinkPilot se autentica con claves de tipo Bearer que empiezan por
lp_live_, se crean en el panel y están disponibles en todos los planes,
también en el Free. Cada clave pertenece a un espacio de trabajo, así que
una integración de agencia usa una clave por cada espacio de trabajo de
cliente y los enlaces acaban en el sitio correcto por diseño.
curl https://uselinkpilot.com/api/v1/me \
-H "Authorization: Bearer lp_live_..."
GET /me devuelve el espacio de trabajo, el plan, los límites, el uso
actual y el margen de peticiones de la clave. Llámalo al arrancar y muestra
los límites en tus propios registros, para enterarte de un tope antes de que
lo descubra una campaña.
Trata la clave como una credencial de producción: guárdala en un gestor de secretos, nunca en un repositorio ni en el código del front-end y, cuando tengas que dársela a quien construye la integración, envíala con un enlace secreto de un solo uso. La guía sobre claves de API explica la entrega y la rotación.
Crea el enlace
La llamada de creación recibe el destino y algunos campos opcionales.
curl -X POST https://uselinkpilot.com/api/v1/links \
-H "Authorization: Bearer lp_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/launch?utm_source=newsletter&utm_medium=email&utm_campaign=oct-launch",
"slug": "oct-launch-email",
"domain": "go.example.com",
"title": "October launch, newsletter",
"tags": ["oct-launch", "email"]
}'
La respuesta incluye el ID del enlace, la URL corta y los metadatos que
enviaste. Guarda el ID junto a tu propio registro: es lo que usarás después
para leer, actualizar o eliminar el enlace. GET /links lista los enlaces
del más reciente al más antiguo con paginación por cursor
({ data, next_cursor }), y GET /links/{id} y DELETE /links/{id}
actúan sobre uno.
Algunas reglas que mantienen la integración en orden:
- Construye la URL de destino en el código, con las etiquetas UTM, a partir de los campos de la campaña. Las etiquetas escritas a mano acaban divergiendo. La guía de UTM fija las convenciones.
- Deja que la plataforma genere los slugs, salvo que vaya a leerlos una persona. Cuando los definas tú, derívalos de la campaña, el canal y la ubicación, en minúsculas y con guiones, y resuelve un conflicto añadiendo un sufijo corto y reintentando una vez.
- Haz que la creación sea idempotente. Asocia cada creación al ID de tu
propio registro, para que un reintento tras un tiempo de espera agotado
encuentre el enlace existente en lugar de crear otro. Si la plataforma no
ofrece una clave de idempotencia, busca tu etiqueta o tu slug con
GET /linksantes de crear. - En bloque, un bucle con espera progresiva. Respeta el margen de
peticiones que indica
/me, espera ante un 429 y registra cada error con el registro al que correspondía.
Para scripts y herramientas locales, la CLI linkpilot de npm envuelve las
mismas llamadas, y el servidor @uselinkpilot/mcp las pone a disposición de
agentes de IA. Ambos son de código abierto y están en GitHub, bajo
TetraCoreHQ.
Haz que los enlaces tengan seguimiento sin romper la atribución
Cada clic en un enlace creado por API se registra igual que en uno creado desde el panel: hora, referente, dispositivo, navegador, país, región, marca de bot y un hash con sal en lugar de la IP. Eso te da el recuento del enlace. La atribución en el destino sigue dependiendo de que la URL llegue intacta.
- Conserva los parámetros de consulta a través de la redirección. Prueba un enlace con el comprobador de redirecciones y confirma que las etiquetas UTM están en la URL final.
- Evita las cadenas. Un enlace corto que redirige a otra redirección pierde parámetros y velocidad. Apunta a la página final.
- Decide qué recopilas. El país y el dispositivo son estadísticas agregadas. Un enlace por usuario vinculado a la ficha de un cliente es un dato personal. La guía actual del seguimiento de enlaces enumera lo que se registra y lo que se deja fuera a propósito.
- Fija las expectativas en el producto. Un recuento de clics no es un recuento de conversiones. Muestra los dos, cada uno con su nombre.
Resuelve los casos límite de la redirección
- Validación del destino. Antes de crear el enlace, rechaza los destinos sin HTTPS, los que apunten a tu propio dominio de acortador y cualquiera que esté en una lista de bloqueo. Una redirección abierta con tu marca es una herramienta de phishing.
- Enlaces caducados, desactivados o inexistentes. Decide la página alternativa al crear el enlace y configúrala, para que un enlace de una campaña terminada lleve a la página de inicio y no a un error. En los enlaces impresos, mejor editar el destino que dejar que expiren.
- Enlaces profundos. Usa un destino que detecte la app y, si no está, pase a la web, o una función de la plataforma que lo haga. Prueba en los dos sistemas operativos, con la app instalada y sin ella.
- Codificación. Codifica la URL de destino antes de ponerla en el JSON, sobre todo si lleva su propia cadena de consulta. La doble codificación es el error habitual.
- Idiomas. Si un mismo enlace corto sirve varios idiomas, detecta el idioma en el destino, no en el slug.
Añade webhooks para los eventos que importan
Los webhooks permiten que el resto de tus sistemas reaccionen a la actividad
de los enlaces sin consultar una y otra vez. LinkPilot firma cada envío con
una cabecera de firma HMAC y los dispara en el ciclo de vida de los enlaces
(link.created, link.updated, link.deleted) y en el de los secretos
(secret.created, secret.viewed, secret.burned). Verifica la firma
antes de procesar el contenido, responde rápido, procesa desde una cola y
guarda los ID de evento para que los reintentos no hagan daño. Los datos de
clics son un flujo de informes, no un webhook: léelos en las estadísticas y
las exportaciones. La guía de integraciones con
webhooks
explica cómo construir el receptor.
Prueba de principio a fin y sigue vigilando
Antes de que la integración toque una campaña real:
- Crea un enlace con tus etiquetas de prueba en un espacio de trabajo de pruebas.
- Confirma que la respuesta trae el ID y la URL corta que esperas.
- Haz clic desde un teléfono y desde un portátil. Confirma la redirección, las etiquetas UTM al llegar y los dos clics en las estadísticas con los tipos de dispositivo correctos.
- Crea otra vez el mismo registro y confirma que obtienes el mismo enlace, no un duplicado.
- Elimínalo y confirma que
link.deletedllega a tu endpoint de webhooks, si usas uno.
En producción, vigila tres cosas: la tasa de errores de la API por código de
estado, la latencia de la redirección medida con una comprobación sintética
y una conciliación semanal del número de enlaces entre tus registros y
GET /links. Rota la clave de API de forma periódica y cada vez que alguien
deje el equipo que la tiene.
Documenta la integración como un producto interno: los campos que acepta,
la regla de los slugs, el comportamiento de la página alternativa, los
límites que indica /me y a quién llamar cuando una campaña marque cero
clics. La próxima persona que la toque lo agradecerá, y muchas veces serás
tú.