{"openapi":"3.0.3","info":{"title":"CampusPlanner REST API (v1)","version":"1.0.0","description":"API oficial de CampusPlanner para conectar aplicaciones externas (Apps móviles, portales universitarios, bots de WhatsApp/Telegram) con nuestra Inteligencia Artificial RAG y base documental del campus.","contact":{"name":"Soporte de Desarrolladores CampusPlanner","email":"soporte@campusplanner.app"}},"servers":[{"url":"http://localhost:3000","description":"Servidor de Desarrollo Local"},{"url":"https://campusplanner.app","description":"Servidor de Producción Cloud"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"paths":{"/api/v1/chat":{"post":{"summary":"Generar respuesta conversacional RAG","description":"Envía una pregunta o conversación y recibe una respuesta inteligente generada por nuestra Inteligencia Artificial fundamentada exclusivamente en los documentos oficiales del campus.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","example":"¿Cuáles son las fechas límite para la entrega del proyecto final?","description":"Pregunta o consulta enviada por el usuario."},"history":{"type":"array","description":"Historial previo de mensajes de la sesión conversacional (opcional).","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"],"example":"user"},"content":{"type":"string","example":"Hola, ¿dónde puedo consultar las becas?"}}}}}}}}},"responses":{"200":{"description":"Respuesta generada exitosamente con citas documentales.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"query":{"type":"string","example":"¿Cuáles son las fechas límite?"},"response":{"type":"string","example":"Las fechas límite según el reglamento son..."},"citations":{"type":"array","items":{"type":"object","properties":{"documentId":{"type":"string","example":"doc_12345"},"documentTitle":{"type":"string","example":"CalendarioAcademico.pdf"},"similarity":{"type":"number","example":0.89},"snippet":{"type":"string","example":"Entrega final: 15 de Mayo..."}}}}}}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalError"}}}},"/api/v1/search":{"post":{"summary":"Búsqueda semántica vectorial","description":"Busca en la base de conocimientos de nuestra Inteligencia Artificial usando vectores embebidos.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","example":"requisitos de titulación profesional","description":"Frase o palabras clave a buscar semánticamente."},"topK":{"type":"integer","default":5,"example":5,"description":"Número máximo de fragmentos coincidentes a devolver (1-20)."}}}}}},"responses":{"200":{"description":"Fragmentos vectoriales encontrados.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"query":{"type":"string","example":"requisitos de titulación"},"results":{"type":"array","items":{"type":"object","properties":{"documentId":{"type":"string"},"documentTitle":{"type":"string"},"similarity":{"type":"number"},"chunkText":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalError"}}}},"/api/v1/documents":{"get":{"summary":"Listar catálogo de documentos institucionales","description":"Obtiene la lista de documentos publicados e indexados pertenecientes al campus.","responses":{"200":{"description":"Catálogo de documentos retornado exitosamente.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"visibility":{"type":"string","example":"public"},"fileName":{"type":"string"},"fileSize":{"type":"integer"},"category":{"type":"string","nullable":true},"vectorIndexed":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalError"}}},"post":{"summary":"Subir e indexar documento para RAG","description":"Sube un documento en formato PDF, DOCX o TXT (vía multipart/form-data o Base64 JSON) y procesa automáticamente su fragmentación e indexación de vectores para nuestra Inteligencia Artificial.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Archivo binario a subir (PDF, DOCX, TXT)"},"categoryId":{"type":"string","description":"ID de la categoría asignada (opcional)"},"visibility":{"type":"string","enum":["public","internal"],"default":"public","description":"Visibilidad del documento en el campus"}}}},"application/json":{"schema":{"type":"object","required":["fileBase64","fileName"],"properties":{"fileBase64":{"type":"string","description":"Contenido del archivo codificado en Base64"},"fileName":{"type":"string","example":"ReglamentoGeneral.pdf"},"mimeType":{"type":"string","example":"application/pdf"},"categoryId":{"type":"string"},"visibility":{"type":"string","enum":["public","internal"],"default":"public"}}}}}},"responses":{"201":{"description":"Documento subido e indexado exitosamente en la base vectorial de la IA."},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalError"}}}},"/api/v1/documents/{id}":{"get":{"summary":"Obtener detalle de un documento","description":"Obtiene los metadatos y estado de indexación de un documento por su ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"ID único del documento"}],"responses":{"200":{"description":"Detalle del documento retornado exitosamente."},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalError"}}},"delete":{"summary":"Eliminar un documento del campus","description":"Elimina un documento y purga sus fragmentos vectoriales asociados de la IA.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"ID único del documento"}],"responses":{"200":{"description":"Documento eliminado exitosamente."},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalError"}}}},"/api/v1/categories":{"get":{"summary":"Listar categorías temáticas","description":"Obtiene las categorías organizativas de información del campus.","responses":{"200":{"description":"Lista de categorías retornada exitosamente."},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalError"}}},"post":{"summary":"Crear una nueva categoría","description":"Crea una categoría programáticamente para organizar documentos del campus.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Trámites Académicos"},"description":{"type":"string","example":"Procesos de inscripción y baja de materias."}}}}}},"responses":{"201":{"description":"Categoría creada exitosamente."},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalError"}}}},"/api/v1/institution":{"get":{"summary":"Obtener metadatos de la institución","description":"Obtiene la información pública del campus (nombre, dominio, marca y total de archivos).","responses":{"200":{"description":"Información institucional retornada exitosamente."},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalError"}}}},"/api/v1/webhooks":{"get":{"summary":"Listar webhooks registrados","description":"Obtiene la lista de webhooks configurados para recibir eventos asíncronos del campus.","responses":{"200":{"description":"Lista de webhooks retornada exitosamente."},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalError"}}},"post":{"summary":"Registrar un nuevo webhook de eventos","description":"Registra una URL receptora y genera una clave secreta de firma HMAC (whsec_...) para recibir notificaciones (document.indexed, document.failed, document.deleted).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","example":"https://api.universidad.edu.mx/webhooks/campusplanner"},"events":{"type":"array","items":{"type":"string"},"example":["document.indexed","document.failed","document.deleted"]}}}}}},"responses":{"201":{"description":"Webhook registrado exitosamente."},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalError"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Clave de API proporcionada en la sección de Configuración (ej: cp_live_xxxx...)"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API-Key","description":"Token Bearer en el encabezado Authorization (ej: Bearer cp_live_xxxx...)"}},"responses":{"400BadRequest":{"description":"Solicitud incorrecta o parámetros requeridos faltantes.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"El parámetro \"name\" es requerido."}}}}}},"401Unauthorized":{"description":"API Key no proporcionada, inexistente o inactiva.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"API key no válida o inexistente."}}}}}},"403Forbidden":{"description":"Permisos insuficientes en la API Key o funcionalidad deshabilitada por el Administrador General.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Las integraciones por API Key han sido deshabilitadas para esta institución."}}}}}},"404NotFound":{"description":"El recurso o entidad solicitada no existe o no pertenece al campus.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Recurso no encontrado."}}}}}},"500InternalError":{"description":"Error interno en el servidor o motor de Inteligencia Artificial.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error interno en la API de Chat."}}}}}}}}}