{
    "openapi": "3.0.3",
    "info": {
        "title": "MiTravel URL Shortener API",
        "description": "API RESTful corporativa para acortamiento de enlaces, analítica en tiempo real, gestión de vigencias y generación de códigos QR para el dominio mitravel.com.mx.",
        "version": "1.0.0",
        "contact": {
            "name": "Soporte Técnico MiTravel",
            "email": "dev@mitravel.com.mx",
            "url": "https://mitravel.com.mx"
        }
    },
    "servers": [
        {
            "url": "https://short.mitravel.com.mx/api/v1",
            "description": "Servidor de Producción / Base API v1"
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-KEY",
                "description": "Clave de acceso a la API (o como Bearer Token)"
            },
            "BearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Token Bearer en cabecera Authorization"
            }
        }
    },
    "paths": {
        "/shorten": {
            "post": {
                "summary": "Acortar una URL",
                "description": "Crea un nuevo enlace corto con soporte para slug personalizado, título y fecha de expiración.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "url"
                                ],
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "example": "https://mitravel.com.mx/tours/cancun-2026?promo=1"
                                    },
                                    "custom_slug": {
                                        "type": "string",
                                        "example": "cancun-promo"
                                    },
                                    "title": {
                                        "type": "string",
                                        "example": "Campaña Verano"
                                    },
                                    "expires_at": {
                                        "type": "string",
                                        "example": "2026-12-31 23:59:59"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Enlace creado exitosamente."
                    },
                    "422": {
                        "description": "Error de validación en URL o slug."
                    },
                    "429": {
                        "description": "Límite de tasa excedido."
                    }
                }
            }
        },
        "/bulk-shorten": {
            "post": {
                "summary": "Acortar múltiples URLs en lote",
                "description": "Procesa hasta 50 enlaces en una sola llamada.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "links"
                                ],
                                "properties": {
                                    "links": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "url"
                                            ],
                                            "properties": {
                                                "url": {
                                                    "type": "string"
                                                },
                                                "custom_slug": {
                                                    "type": "string"
                                                },
                                                "title": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Lote procesado."
                    }
                }
            }
        },
        "/urls": {
            "get": {
                "summary": "Listar enlaces",
                "description": "Obtiene lista paginada de URLs cortas con filtros de búsqueda y estado.",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 20
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "active",
                                "expired",
                                "inactive"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Listado de enlaces."
                    }
                }
            }
        },
        "/urls/{code}": {
            "get": {
                "summary": "Obtener detalle de un enlace",
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Detalle del enlace."
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            },
            "put": {
                "summary": "Actualizar un enlace",
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "original_url": {
                                        "type": "string"
                                    },
                                    "title": {
                                        "type": "string"
                                    },
                                    "expires_at": {
                                        "type": "string"
                                    },
                                    "is_active": {
                                        "type": "integer",
                                        "enum": [
                                            0,
                                            1
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Actualizado con éxito."
                    }
                }
            },
            "delete": {
                "summary": "Eliminar un enlace",
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Eliminado con éxito."
                    }
                }
            }
        },
        "/stats/{code}": {
            "get": {
                "summary": "Obtener analíticas y clics",
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Métricas completas."
                    }
                }
            }
        },
        "/qr/{code}": {
            "get": {
                "summary": "Obtener información de código QR",
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "size",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 250
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Información de código QR."
                    }
                }
            }
        },
        "/health": {
            "get": {
                "summary": "Chequeo de salud del servicio",
                "responses": {
                    "200": {
                        "description": "Servicio operativo."
                    }
                }
            }
        }
    }
}