Introducción

Bienvenido a la documentación oficial de ShortLink

¿Qué es ShortLink?

ShortLink es un servicio de acortamiento de URLs rápido, seguro y completamente gratuito. Permite crear enlaces cortos que nunca expiran y proporciona estadísticas detalladas de cada enlace.

A diferencia de otros servicios, ShortLink no requiere registro para uso básico, no muestra anuncios y respeta la privacidad de los usuarios. Incluye un sistema completo de administración con roles y permisos.

Rápido

Genera enlaces en milisegundos con verificación en tiempo real

Seguro

Autenticación JWT y protección contra abusos

Analytics

Estadísticas detalladas públicas sin necesidad de cuenta

Administración

Sistema de roles (admin/mod) con gestión completa de usuarios y URLs

Inicio Rápido

Aprende a usar ShortLink en minutos

Uso Básico

Hay dos formas de acortar URLs con ShortLink:

1. Interfaz Web: Visita la página principal y pega tu URL en el formulario.

2. API REST: Envía una petición POST al endpoint /api/shorten

curl
curl -X POST https://shorter.qzz.io/api/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://ejemplo.com/pagina-muy-larga"}'
Respuesta JSON
{
    "success": true,
    "shortUrl": "https://shorter.qzz.io/abc123",
    "shortId": "abc123",
    "originalUrl": "https://ejemplo.com/pagina-muy-larga",
    "clicks": 0,
    "uniqueVisitors": 0,
    "verified": true,
    "verification": {
        "statusCode": 200,
        "statusMessage": "OK"
    }
}

Características

Todo lo que ShortLink ofrece

IDs Únicos

Los IDs cortos se generan de forma segura garantizando unicidad. Para URLs personalizadas, puedes especificar tu propio ID (requiere autenticación y rol de administrador/moderador).

Privacidad

Las IPs de los visitantes se almacenan de forma segura, permitiendo contar visitantes únicos sin almacenar información personal identificable.

Rate Limiting

Para prevenir abuso, el sistema implementa límites de tasa diferenciados por tipo de ruta. Exceder estos límites resulta en un bloqueo temporal.

Base de Datos PostgreSQL

ShortLink utiliza PostgreSQL como sistema de almacenamiento, ofreciendo mejor rendimiento, escalabilidad y confiabilidad.

Sistema de Autenticación JWT

Sistema de autenticación moderno basado en JWT (JSON Web Tokens) con roles de administrador (admin) y moderador (mod).

Gestión Avanzada de IDs

Los administradores y moderadores pueden:

  • Pausar/reanudar IDs (impidiendo el acceso temporal)
  • Transferir todos los datos de un ID a otro nuevo (sin perder estadísticas)
  • Intercambiar datos entre dos IDs existentes
  • Listar IDs personalizados

Referencia API

Documentación completa de los endpoints

POST/api/shorten

Acorta una URL y devuelve el enlace corto junto con información adicional. Admite autenticación JWT y IDs personalizados (requiere rol mod/admin).

Parámetros del Body

Nombre Tipo Descripción
url * string URL a acortar. Puede incluir o no el protocolo https://
id string ID personalizado (máximo 20 caracteres alfanuméricos, requiere autenticación)

Headers Requeridos para IDs Personalizados

Authorization: Bearer <tu_token_jwt>

GET/api/redirect/:shortId

Obtiene la URL original asociada a un shortId. Registra la visita (clics, visitantes únicos) y actualiza estadísticas. Si el ID está en pausa, devuelve error 403.

Nota: Para obtener la URL original sin registrar visita, usa GET /api/link/:shortId.

POST/api/delete

Elimina un enlace corto y todos sus datos asociados. Requiere autenticación JWT con rol de moderador (mod) o administrador (admin).

Headers Requeridos

Authorization: Bearer <tu_token_jwt>

Parámetros del Body

Nombre Tipo Descripción
id * string ID corto del enlace a eliminar
GET/api/stats/:shortId

Obtiene estadísticas detalladas de un enlace específico, incluyendo clics por día/hora, visitantes únicos y datos de verificación.

GET/api/analytics

Obtiene estadísticas globales del servicio ShortLink: total de URLs, clics, visitantes únicos, IDs en pausa, etc.

Códigos de Error

Respuestas de error que puedes encontrar al usar la API

Códigos de Estado HTTP

Código Descripción Solución
200 Solicitud exitosa Todo funciona correctamente
400 Solicitud incorrecta Verifica los parámetros enviados (URL inválida, formato incorrecto)
401 No autorizado Token JWT faltante o inválido. Inicia sesión en /api/auth/login
403 Prohibido No tienes permisos para esta acción o el ID está en pausa
404 No encontrado El enlace corto solicitado no existe
405 Método no permitido El método HTTP usado no está soportado para este endpoint
414 URL demasiado larga La URL excede el límite máximo de 2048 caracteres
429 Demasiadas solicitudes Has excedido el límite de tasa. Espera unos minutos antes de reintentar
500 Error interno del servidor Problema temporal en el servidor. Intenta nuevamente más tarde

Errores Comunes en Respuestas JSON

Mensaje de Error Descripción
"ID personalizado ya existe" El ID personalizado que intentas usar ya está en uso
"ID personalizado debe contener solo caracteres alfanuméricos" El ID solo puede contener letras, números y guion bajo
"URL no disponible" La URL destino no responde o devolvió un error
"No se permiten IPs privadas o de red interna" La URL apunta a una dirección IP privada (protección SSRF)
"Token expirado" Tu token JWT ha expirado. Inicia sesión nuevamente
"El ID está en pausa" El enlace ha sido deshabilitado temporalmente por un administrador

Autenticación JWT

Sistema de autenticación basado en tokens JWT

Login y Obtención de Token

Para obtener un token JWT, usa el endpoint /api/auth/login.

POST /api/auth/login 
curl -X POST https://shorter.qzz.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "tu_contraseña"}'
Respuesta Exitosa
{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {"id": 1, "username": "admin", "role": "admin"},
    "expiresIn": "10m"
}

Uso del Token

Para usar endpoints que requieren autenticación, incluye el token en el header Authorization: Bearer <tu_token_jwt>

Roles:

  • admin: Acceso completo a todas las funcionalidades
  • mod: Acceso a gestión básica (pausar IDs, eliminar URLs, ver listas de IDs personalizados)

Gestión de Usuarios

Endpoints para administrar usuarios (solo administradores)

GET/api/admin/users

Obtiene la lista de todos los usuarios registrados en el sistema. Requiere rol de administrador.

POST/api/admin/user

Crea, edita, desactiva o reactiva usuarios. Requiere rol de administrador.

Gestión de IDs

Funcionalidades avanzadas para gestión de enlaces

POST/api/admin/pause-id

Pone un ID en pausa, bloqueando su acceso. Requiere rol de moderador o administrador.

Parámetros: { "shortId": "abc123", "reason": "opcional" }

POST/api/admin/resume-id

Reanuda un ID previamente pausado. Requiere rol de moderador o administrador.

Parámetros: { "shortId": "abc123" }

GET/api/admin/paused-ids

Obtiene la lista de todos los IDs actualmente en pausa. Requiere rol de moderador o administrador.

GET/api/admin/custom-ids

Obtiene la lista de todos los IDs personalizados. Requiere rol de moderador o administrador.

Transferencia e Intercambio de IDs

Funcionalidades avanzadas para reorganización de enlaces

POST/api/admin/transfer-id

Transfiere todos los datos de un ID origen a un ID destino (el destino no debe existir).

Parámetros: { "sourceId": "viejo", "targetId": "nuevo" }

POST/api/admin/swap-ids

Intercambia los datos entre dos IDs existentes. Ambos IDs deben existir.

Parámetros: { "firstId": "id1", "secondId": "id2" }

Ejemplos de Código

Integra ShortLink en tus proyectos

JavaScript / Node.js 
async function login(username, password) {
    const response = await fetch('https://shorter.qzz.io/api/auth/login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ username, password })
    });
    const data = await response.json();
    if (data.success) return data.token;
    throw new Error(data.error);
}

async function shortenUrl(url, customId, token) {
    const headers = { 'Content-Type': 'application/json' };
    if (customId) headers['Authorization'] = `Bearer ${token}`;
    const response = await fetch('https://shorter.qzz.io/api/shorten', {
        method: 'POST',
        headers,
        body: JSON.stringify({ url, id: customId })
    });
    return response.json();
}
Python
import requests

class ShortLinkClient:
    def __init__(self, base_url="https://shorter.qzz.io"):
        self.base_url = base_url
        self.token = None

    def login(self, username, password):
        resp = requests.post(f'{self.base_url}/api/auth/login',
                             json={'username': username, 'password': password})
        data = resp.json()
        if data['success']:
            self.token = data['token']
            return self.token
        raise Exception(data.get('error'))

    def shorten_url(self, url, custom_id=None):
        headers = {'Content-Type': 'application/json'}
        payload = {'url': url}
        if custom_id:
            if not self.token:
                raise Exception("Se requiere token")
            headers['Authorization'] = f'Bearer {self.token}'
            payload['id'] = custom_id
        resp = requests.post(f'{self.base_url}/api/shorten', headers=headers, json=payload)
        return resp.json()

Casos de Uso

Cómo otros usan ShortLink

Redes Sociales

Comparte enlaces más limpios en Twitter, Instagram y otras plataformas.

Email Marketing

Rastrea clics en tus campañas de email con estadísticas detalladas.

Códigos QR

URLs más cortas generan códigos QR más simples y fáciles de escanear.

Material Impreso

Enlaces memorables para tarjetas de presentación, folletos y posters.

Enlaces Privados

Los administradores pueden crear y gestionar enlaces con IDs personalizados.

Migración de Contenido

Usa transferencia e intercambio de IDs para reorganizar contenido sin perder estadísticas.

Tecnología

Cómo funciona ShortLink internamente

Stack Tecnológico

Backend: Node.js con Express.js, Helmet para seguridad, JWT para autenticación.

Base de Datos: PostgreSQL con sistema de almacenamiento optimizado.

Seguridad: Protección contra abusos, rate limiting, headers de seguridad HTTP, protección SSRF.

Frontend: HTML5, CSS3, JavaScript vanilla, diseño responsive y modo oscuro/claro.

Preguntas Frecuentes

Respuestas a las dudas más comunes

¿Los enlaces expiran?
No, los enlaces de ShortLink nunca expiran. Una vez creado, tu enlace permanecerá activo indefinidamente.
¿Hay límites de uso?
Sí, existen límites de tasa para prevenir abuso. Si excedes los límites, recibirás una respuesta 429. No hay límite en la cantidad total de enlaces.
¿Cómo funciona la autenticación?
ShortLink usa JWT (JSON Web Tokens). Los tokens se obtienen mediante /api/auth/login y se envían en el header Authorization: Bearer <token>.
¿Puedo usar IDs personalizados?
Sí, los usuarios autenticados con rol mod/admin pueden especificar IDs personalizados de hasta 20 caracteres alfanuméricos.
¿Qué son los IDs en pausa?
Son enlaces temporalmente deshabilitados por administradores. No se puede acceder a ellos ni crear nuevos enlaces con esos IDs.
¿Las estadísticas son públicas?
Sí, cualquier persona puede ver las estadísticas de un enlace visitando /stats/{shortId} o usando la API /api/stats/{shortId}.