{
  "openapi": "3.1.0",
  "info": {
    "title": "LinkLider API — Tasks",
    "description": "Módulo de tareas de la API unificada de LinkLider (multi-tenant por API Key). Incluye listado/filtrado, vistas por rango de fechas y operaciones masivas (bulk).",
    "version": "v1"
  },
  "servers": [
    { "url": "https://api.linklider.com", "description": "Producción" }
  ],
  "security": [ { "ApiKeyAuth": [] } ],
  "paths": {
    "/v1/tasks": {
      "get": {
        "operationId": "ListTasks",
        "summary": "Lista tareas (paginado)",
        "parameters": [
          { "name": "project_id", "in": "query", "description": "ID del proyecto, o \"none\" para tareas sin proyecto.", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string", "enum": ["none"] } ] } },
          { "name": "due_from", "in": "query", "schema": { "type": "string", "format": "date-time" } },
            { "name": "due_to", "in": "query", "schema": { "type": "string", "format": "date-time" } },
            { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["open","doing","done","waiting","delegated"] } },
            { "name": "priority", "in": "query", "schema": { "type": "string", "enum": ["low","medium","high","urgent"] } },
            { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 255 } },
            { "name": "include_completed", "in": "query", "schema": { "type": "boolean" } },
            { "name": "sort", "in": "query", "schema": { "type": "string" }, "description": "Campos: due_at,priority,created_at,status,title. Comas. Prefijo - para DESC." }
        ],
        "responses": { "200": { "description": "OK" } }
      },
      "post": {
        "operationId": "CreateTask",
        "summary": "Crea tarea",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreate" } } } },
        "responses": { "201": { "description": "Creada" }, "422": { "description": "Validación" } }
      }
    },
    "/v1/tasks/today": {
      "get": {
        "operationId": "TodayTasks",
        "summary": "Tareas de hoy (y atrasadas opcional)",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["open","doing","done","waiting","delegated"] } },
          { "name": "priority", "in": "query", "schema": { "type": "string", "enum": ["low","medium","high","urgent"] } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "include_completed", "in": "query", "schema": { "type": "boolean" } },
          { "name": "include_overdue", "in": "query", "schema": { "type": "boolean" } },
          { "name": "sort", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/v1/tasks/month": {
      "get": {
        "operationId": "MonthTasks",
        "summary": "Tareas de un mes",
        "parameters": [
          { "name": "year", "in": "query", "schema": { "type": "integer" } },
          { "name": "month", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["open","doing","done","waiting","delegated"] } },
          { "name": "priority", "in": "query", "schema": { "type": "string", "enum": ["low","medium","high","urgent"] } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "include_completed", "in": "query", "schema": { "type": "boolean" } },
          { "name": "group", "in": "query", "schema": { "type": "boolean" } },
          { "name": "sort", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "OK" }, "422": { "description": "Parámetros inválidos" } }
      }
    },
    "/v1/tasks/week": {
      "get": {
        "operationId": "WeekTasks",
        "summary": "Tareas de una semana ISO",
        "parameters": [
          { "name": "year", "in": "query", "schema": { "type": "integer" } },
          { "name": "week", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 53 } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["open","doing","done","waiting","delegated"] } },
          { "name": "priority", "in": "query", "schema": { "type": "string", "enum": ["low","medium","high","urgent"] } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "include_completed", "in": "query", "schema": { "type": "boolean" } },
          { "name": "group", "in": "query", "schema": { "type": "boolean" } },
          { "name": "sort", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "OK" }, "422": { "description": "Parámetros inválidos" } }
      }
    },
    "/v1/tasks/range": {
      "get": {
        "operationId": "RangeTasks",
        "summary": "Tareas en rango arbitrario",
        "parameters": [
          { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["open","doing","done","waiting","delegated"] } },
          { "name": "priority", "in": "query", "schema": { "type": "string", "enum": ["low","medium","high","urgent"] } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "include_completed", "in": "query", "schema": { "type": "boolean" } },
          { "name": "group", "in": "query", "schema": { "type": "boolean" } },
          { "name": "sort", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "OK" }, "422": { "description": "Parámetros inválidos / rango grande" } }
      }
    },
    "/v1/tasks/{id}": {
      "patch": {
        "operationId": "UpdateTask",
        "summary": "Actualiza tarea",
        "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdate" } } } },
        "responses": { "200": { "description": "Actualizada" }, "404": { "description": "No encontrada" }, "422": { "description": "Validación" } }
      },
      "delete": {
        "operationId": "DeleteTask",
        "summary": "Elimina tarea",
        "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
        "responses": { "200": { "description": "Eliminada" }, "404": { "description": "No encontrada" } }
      }
    },
    "/v1/projects": {
      "get": { "operationId": "ListProjects", "summary": "Lista proyectos (grupos de tareas) con su avance", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["active","on_hold","done"] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } } } } } },
      "post": { "operationId": "CreateProject", "summary": "Crea proyecto", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectInput" } } } }, "responses": { "201": { "description": "Creado" }, "422": { "description": "Validación" } } }
    },
    "/v1/projects/{id}": {
      "patch": { "operationId": "UpdateProject", "summary": "Actualiza proyecto", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectInput" } } } }, "responses": { "200": { "description": "OK" }, "404": { "description": "No encontrado" } } },
      "delete": { "operationId": "DeleteProject", "summary": "Elimina proyecto (sus tareas se conservan sin proyecto)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Eliminado" }, "404": { "description": "No encontrado" } } }
    },
    "/v1/tasks/bulk": {
      "post": { "operationId": "BulkCreateTasks", "summary": "Crea varias tareas", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskBulkCreate" } } } }, "responses": { "201": { "description": "Creadas" }, "422": { "description": "Validación" } } },
      "patch": { "operationId": "BulkUpdateTasks", "summary": "Actualiza varias tareas", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskBulkUpdate" } } } }, "responses": { "200": { "description": "Actualizadas" }, "422": { "description": "Validación" } } },
      "delete": { "operationId": "BulkDeleteTasks", "summary": "Elimina varias tareas", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkIds" } } } }, "responses": { "200": { "description": "Eliminadas" }, "422": { "description": "Validación" } } }
    },
    "/v1/tasks/bulk-status": {
      "patch": { "operationId": "BulkStatusTasks", "summary": "Cambia estado masivo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkStatus" } } } }, "responses": { "200": { "description": "Estados actualizados" }, "422": { "description": "Validación" } } }
    },
    "/v1/tasks/bulk-duplicate": {
      "post": { "operationId": "BulkDuplicateTasks", "summary": "Duplica tareas", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDuplicate" } } } }, "responses": { "200": { "description": "Duplicadas" }, "422": { "description": "Error duplicación" } } }
    },
    "/v1/tasks/bulk-shift": {
      "patch": { "operationId": "BulkShiftTasks", "summary": "Desplaza fechas", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkShift" } } } }, "responses": { "200": { "description": "Fechas movidas" }, "422": { "description": "Validación" } } }
    }
  },
  "components": {
    "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } },
    "schemas": {
      "Project": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["active","on_hold","done"] }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "tasks_total": { "type": "integer" }, "tasks_done": { "type": "integer" }, "tasks_overdue": { "type": "integer" }, "progress": { "type": "integer", "description": "0-100" }, "can_manage": { "type": "boolean" } }, "required": ["id","name","status"] },
      "ProjectInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "nullable": true }, "notes": { "type": "string", "maxLength": 2000, "nullable": true }, "status": { "type": "string", "enum": ["active","on_hold","done"] }, "start_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true } }, "required": ["name"] },
      "Task": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "priority": { "type": "string", "enum": ["low","medium","high","urgent"] }, "status": { "type": "string", "enum": ["open","doing","done","waiting","delegated"] }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "page_id": { "type": "integer", "nullable": true }, "project_id": { "type": "integer", "nullable": true }, "project_name": { "type": "string", "nullable": true }, "project_color": { "type": "string", "nullable": true }, "assignees": { "type": "array", "items": { "type": "integer" } } }, "required": ["id","title","priority","status"] },
      "TaskCreate": { "type": "object", "properties": { "project_id": { "type": "integer", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string", "enum": ["low","medium","high","urgent"], "default": "medium" }, "due_at": { "type": "string", "format": "date-time" }, "assignees": { "type": "array", "items": { "type": "integer" } } }, "required": ["title"] },
      "TaskUpdate": { "type": "object", "properties": { "project_id": { "type": "integer", "nullable": true, "description": "Solo en la tarea principal; sus subtareas lo heredan." }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["open","doing","done","waiting","delegated"] }, "priority": { "type": "string", "enum": ["low","medium","high","urgent"] }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "assignees": { "type": "array", "items": { "type": "integer" } } } },
      "TaskBulkCreate": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "string", "enum": ["low","medium","high","urgent"] }, "due_at": { "type": "string", "format": "date-time" }, "assignees": { "type": "array", "items": { "type": "integer" } } }, "required": ["title"] } } }, "required": ["tasks"] },
      "TaskBulkUpdate": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": ["open","doing","done","waiting","delegated"] }, "priority": { "type": "string", "enum": ["low","medium","high","urgent"] }, "due_at": { "type": "string", "format": "date-time" }, "assignees": { "type": "array", "items": { "type": "integer" } } }, "required": ["id"] } } }, "required": ["tasks"] },
      "BulkIds": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" } } }, "required": ["ids"] },
      "BulkStatus": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" } }, "status": { "type": "string", "enum": ["open","doing","done","waiting","delegated"] } }, "required": ["ids","status"] },
      "BulkDuplicate": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" } }, "prefix": { "type": "string" }, "shift_days": { "type": "integer", "minimum": -365, "maximum": 365 } }, "required": ["ids"] },
      "BulkShift": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" } }, "days": { "type": "integer", "minimum": -365, "maximum": 365 } }, "required": ["ids","days"] },
      "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }
    }
  }
}
