API de acortador de URL: automatiza enlaces cortos en tu app

Crear enlaces a mano está bien hasta que deja de estarlo. En cuanto cada pedido necesita un enlace de seguimiento, cada usuario un enlace de referido o cada anuncio un código QR, necesitas lo mismo pero por código. Para eso existe una API de acortador de URL, y su superficie es lo bastante pequeña como para dejarla conectada mientras te tomas un café.

Qué puedes automatizar

• Enlaces por pedido o por usuario, generados en el momento en que hacen falta.
• Enlaces de campaña en lote: uno por canal, creados desde una hoja de cálculo en un bucle en vez de a mano.
• Códigos QR al vuelo para entradas, facturas, etiquetas y albaranes.
• Datos de clics traídos de vuelta a tu propio panel, para que los números vivan donde tu equipo ya mira.

Si no tienes claro si ya necesitas la API, la prueba honesta es volumen y repetición: si haces lo mismo en un navegador más de unas cuantas veces por semana, automatízalo.

Autentícate

Coge tu clave en la página de tu cuenta y mándala como cabecera X-Api-Key en cada petición. Dos reglas no negociables: guarda la clave en el servidor —cualquier cosa que esté en el JavaScript del front es pública, y una clave filtrada permite que desconocidos creen enlaces en tu nombre— y rótala de inmediato si alguna vez acaba en un repositorio o en un log.

Crear un enlace

Un POST a /api/getLink.json con el destino. Puedes pasar un alias, un modo, una caducidad y una contraseña en la misma llamada:

curl -X POST https://urlik.xyz/api/getLink.json -H "X-Api-Key: YOUR_KEY" -d "url=https://example.com/very/long/path" -d "alias=spring-sale"

La respuesta es un JSON con la URL corta, la URL de su QR y la de sus estadísticas. Los enlaces creados con una clave quedan asociados a tu cuenta, así que aparecen en tu panel y puedes editarlos después.

Un detalle que conviene saber antes de construir nada: el alias es único en todo el servicio. Si spring-sale está pillado recibes un error, no una alternativa silenciosa, así que o gestionas ese caso o pones un espacio de nombres a tus alias (acme-spring-sale).

Generar un código QR

GET /api/qr.json recibe los datos más los opcionales format, fg, bg, ecc y size, y devuelve el QR. Apúntalo a un enlace corto y no a una URL larga en crudo: obtienes un código más limpio y más resistente, y el destino sigue siendo editable después. Ese es el patrón del código QR dinámico, hecho desde tu backend.

Leer las estadísticas

GET /api/stats.json devuelve totales, una serie temporal, referentes, dispositivos y países de un enlace: los mismos números que la página de estadísticas, en un formato que puedes meter en tu propio panel de administración.

Consúltala con una periodicidad fija, no en cada carga de página. Las estadísticas de clics no son un sistema de registro en tiempo real, y machacar el endpoint para redibujar una gráfica que nadie está mirando es la forma de toparte con el limitador de peticiones.

Constrúyelo para que no se rompa a las 3 de la mañana

Los endpoints son simples; las integraciones que fallan son las que dan por hecho que nunca se tuerce nada. Cuatro hábitos que se pagan solos:

• Comprueba la respuesta, siempre. Cada llamada devuelve un estado: léelo. El fallo clásico es asumir que fue bien y guardar el cuerpo de un error como si fuera un enlace corto, y descubrirlo en una factura impresa.
• Nunca bloquees al usuario por un enlace. Si el acortado ocurre dentro del proceso de compra, una API lenta se convierte en una compra lenta. Hazlo en una tarea en segundo plano, o recurre a la URL larga y reintenta después. La URL larga siempre funciona: esa es tu red de seguridad.
• Cachea lo que no cambia. El mismo destino no necesita acortarse dos veces: guarda la URL corta junto al registro de origen y reutilízala. Más barato, más rápido y tu panel se mantiene legible.
• Recula ante los errores. Reintenta con esperas crecientes en lugar de en un bucle cerrado. Un límite de peticiones respondido con una tormenta de reintentos sigue siendo un límite de peticiones.

Dónde termina la API

Dos límites honestos. Los límites de peticiones existen y generoso no es infinito: los trabajos en lote hay que dosificarlos, no dispararlos todos de golpe. Y la API crea enlaces; no decide qué debe ir dentro. Etiqueta tus enlaces con parámetros UTM al crearlos (mira la guía de UTM) o automatizarás la producción de miles de enlaces que luego no podrás distinguir en la analítica, que es peor situación que hacerlo a mano.

En resumen

Un endpoint para crear, uno para el QR, otro para las estadísticas y una cabecera para autenticar. Guarda la clave en el servidor, comprueba cada respuesta, saca el trabajo de la ruta crítica, cachea lo que se repite y etiqueta al crear. La lista completa de parámetros, los códigos de error y los ejemplos están en la documentación de la API; si prefieres el contexto conceptual primero, empieza por qué es un acortador de URL.