🔗 API de Acortador de Enlaces - SimpleData Corp

Servicio corporativo de acortador de enlaces reutilizable para todos los proyectos de la empresa.

📋 Características

• ✅ Generación de enlaces cortos - Crea URLs cortas corporativas a partir de URLs largas
• ✅ Reserva de enlaces - Reserva enlaces sin destino para QR impresos
• ✅ Gestión centralizada - Administra enlaces por proyecto con trazabilidad completa
• ✅ Estados configurables - ACTIVO, RESERVADO, DESHABILITADO, EXPIRADO
• ✅ Métricas básicas - Registro de clics y última visita
• ✅ API REST completa - Endpoints para crear, actualizar, listar y redirigir
• ✅ Autenticación segura - API Keys y Bearer Tokens
• ✅ Auditoría completa - Historial de cambios de estado y URL
• ✅ Documentación Swagger/OpenAPI 3.0 - Interfaz interactiva en /api-docs
• ✅ Base de datos con TypeORM - Persistencia con MySQL/MariaDB

🚀 Inicio Rápido

1. Instalación

npm install

2. Configuración Base de Datos

# Ejecutar migraciones
npm run migration:run

# Verificar estado
npm run migration:show

3. Configuración

Copia .env.example a .env y configura:

PORT=4300
SHORT_DOMAIN=http://localhost:4300/r
API_KEYS=tu-api-key-aqui

# Base de Datos
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=sdc
DB_PASSWORD=tu-password
DB_DATABASE=SDC_SHORT_LINK

4. Desarrollo

npm run dev

5. Producción

npm run build
npm start

6. Acceder a la Documentación

Abre tu navegador en: http://localhost:4300/api-docs

📚 Documentación

🌟 Documentación Interactiva

• Swagger UI - Documentación interactiva completa con pruebas en vivo
• OpenAPI 3.0 Spec - Especificación exportable

📖 Guías de Referencia

• API Reference - Resumen de endpoints y ejemplos rápidos
• Swagger Guide - Cómo usar la documentación interactiva
• API Testing - Colección de pruebas con curl/Postman

🗄️ Base de Datos

• TypeORM Guide - Entidades, repositorios, migraciones y queries

🚀 Despliegue

• Production Deployment - Guía completa para Ubuntu/Debian y CentOS/AlmaLinux

👨‍💻 Desarrollo

• Developer Guide (AGENTS.md) - Arquitectura, estándares y convenciones para desarrolladores/IA

🔑 Endpoints Principales

Crear Enlace

POST /v1/short-links
X-API-Key: tu-api-key

{
  "proyecto": "marketing-2025",
  "creado_por": "admin@empresa.com",
  "url_destino": "https://www.ejemplo.com"
}

Listar Enlaces

GET /v1/short-links?proyecto=marketing-2025&estado=ACTIVO
X-API-Key: tu-api-key

Actualizar Enlace

PATCH /v1/short-links/{id}
X-API-Key: tu-api-key

{
  "actualizado_por": "admin@empresa.com",
  "url_destino": "https://www.ejemplo.com/nuevo",
  "estado": "ACTIVO"
}

Redirección (Público)

GET /r/{codigo}

🎯 Casos de Uso

1. Enlace Estándar

Crear un enlace corto que redirige a una URL específica:

• Marketing puede generar enlaces cortos para campañas
• URLs amigables para redes sociales

2. Enlace Reservado para QR

Reservar un enlace antes de imprimirlo en material físico:

1. Crear enlace sin URL de destino
2. Imprimir QR con el enlace corto
3. Configurar URL de destino más tarde
4. El QR sigue funcionando sin necesidad de reimprimir

3. Gestión de Campañas

Organizar enlaces por proyecto, módulo y etiquetas:

• Filtrar por campaña
• Ver métricas de uso
• Deshabilitar campañas vencidas

📊 Estados de Enlaces

Estado	Descripción	Comportamiento
RESERVADO_SIN_DESTINO	Enlace reservado sin URL	Redirige a página genérica
ACTIVO	Enlace activo	Redirige a URL configurada
DESHABILITADO	Enlace deshabilitado	Muestra mensaje de error
EXPIRADO	Enlace vencido	Muestra mensaje de expiración

🛡️ Seguridad

• Autenticación mediante API Key o Bearer Token
• Endpoints administrativos protegidos
• Endpoint de redirección público
• Auditoría completa de cambios

📦 Stack Tecnológico

• Node.js + Express - Framework web
• TypeScript - Tipado estático
• Gemini AI - Integración opcional
• JWT - Autenticación (futuro)

🔧 Scripts Disponibles

npm run dev      # Desarrollo con hot-reload
npm run build    # Compilar TypeScript
npm start        # Ejecutar en producción
npm test         # Ejecutar tests

📁 Estructura del Proyecto

src/
├── config/           # Configuración
├── controllers/      # Lógica de negocio
│   └── shortlink.controller.ts
├── entity/          # Modelos de datos
│   └── ShortLink.entity.ts
├── middlewares/     # Middleware de autenticación
│   └── auth.middleware.ts
├── routes/          # Definición de rutas
│   ├── shortlink.route.ts
│   └── redirect.route.ts
├── utils/           # Utilidades
│   └── shortlink.utils.ts
└── index.ts         # Punto de entrada

🧪 Testing

Ver Swagger UI para documentación interactiva completa.

📋 Estructura de Documentación

docs/
├── 📖 API_SHORTLINK.md     → Resumen rápido de la API
├── 🧪 API_TESTING.md       → Guía de testing con ejemplos
├── 📚 SWAGGER.md           → Cómo usar Swagger UI
├── 🗄️ DATABASE.md          → TypeORM: entidades y repositorios
└── 🚀 DEPLOYMENT.md        → Despliegue en producción

AGENTS.md                   → Guía para desarrolladores/IA

💡 Recomendación: Comienza por Swagger UI para explorar la API interactivamente.

---

🤝 Contribución

Proyecto corporativo interno de SimpleData Corp.

Proceso:

1. Crear branch desde 1-feature-base-acortador
2. Hacer cambios siguiendo AGENTS.md
3. Crear Merge Request
4. Revisión del equipo técnico

---

👥 Equipo

• Autor: Dey Gordillo
• Email: dey.gordillo@simpledatacorp.com
• Organización: SimpleData Corp

📄 Licencia

UNLICENSED - Uso corporativo interno exclusivo