{"openapi":"3.0.3","info":{"title":"Portal de Libros Royal","version":"1.0.0","description":"API de la fábrica de libros del Colegio Royal. Autenticación con `Authorization: Bearer <token>` (agentes) o cookie de sesión (personas). Errores: `{error:{codigo,mensaje}}` en español. Los POST admiten `Idempotency-Key`."},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"},"sesion":{"type":"apiKey","in":"cookie","name":"lr_sesion"},"firma":{"type":"apiKey","in":"query","name":"firma"}}},"paths":{"/libros":{"get":{"tags":["Libros"],"summary":"Lista de libros con etapa y estado.","description":"Cualquier persona o agente autenticado.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"post":{"tags":["Libros"],"summary":"Crea un libro con sus siete etapas.","description":"Roles: agente, administrador.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":60},"titulo":{"type":"string","minLength":1,"maxLength":200},"materia":{"type":"string","maxLength":100},"grado":{"type":"string","maxLength":100},"ciclo":{"type":"string","maxLength":50},"tipo_libro":{"type":"string","maxLength":100},"fecha_objetivo":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"diseno":{"nullable":true,"type":"string"}},"required":["id","titulo"],"additionalProperties":false}}}}}},"/libros/{id}":{"get":{"tags":["Libros"],"summary":"Estado completo: etapas, últimos entregables y comentarios abiertos.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"patch":{"tags":["Libros"],"summary":"Actualiza datos del libro o declara su diseño (debe estar aprobado).","description":"Roles: agente, administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"titulo":{"type":"string","minLength":1,"maxLength":200},"materia":{"type":"string","maxLength":100},"grado":{"type":"string","maxLength":100},"ciclo":{"type":"string","maxLength":50},"tipo_libro":{"type":"string","maxLength":100},"fecha_objetivo":{"nullable":true,"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"diseno":{"nullable":true,"type":"string"},"responsables":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}}}}},"delete":{"tags":["Libros"],"summary":"Borra un libro vacío. Sólo administrador.","description":"Roles: administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/libros/{id}/etapas/{etapa}":{"patch":{"tags":["Libros"],"summary":"Cambia el estado de una etapa. El agente no puede poner `aprobada` en una parada.","description":"Roles: agente, administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"etapa","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"estado":{"type":"string","enum":["pendiente","en_trabajo","en_revision","con_cambios","aprobada"]}},"required":["estado"],"additionalProperties":false}}}}}},"/libros/{id}/direccion":{"get":{"tags":["Dirección y fuentes"],"summary":"Dirección del libro en JSON y en Markdown.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"put":{"tags":["Dirección y fuentes"],"summary":"Guardado parcial de la dirección del libro.","description":"Roles: administrador, aprobador, revisor, diseno.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"datos":{"type":"object","additionalProperties":{"type":"string","maxLength":5000}}},"required":["datos"],"additionalProperties":false}}}}}},"/libros/{id}/direccion/enviar":{"post":{"tags":["Dirección y fuentes"],"summary":"\"Enviar a la fábrica\".","description":"Roles: administrador, aprobador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/libros/{id}/fuentes":{"get":{"tags":["Dirección y fuentes"],"summary":"Libros base con enlace de descarga.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"post":{"tags":["Dirección y fuentes"],"summary":"Registra un libro base y devuelve su URL de subida.","description":"Roles: administrador, aprobador, revisor, diseno.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"papel":{"type":"string","enum":["principal","apoyo","ejercicios"]},"nota":{"type":"string","maxLength":1000},"archivo":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":200},"tamano":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["nombre","tamano"],"additionalProperties":false}},"required":["archivo"],"additionalProperties":false}}}}}},"/fuentes/{id}":{"delete":{"tags":["Dirección y fuentes"],"summary":"Quita un libro base que no terminó de subir.","description":"Roles: administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/libros/{id}/entregables":{"get":{"tags":["Libros"],"summary":"Entregables del libro con su versión vigente.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"post":{"tags":["Libros"],"summary":"Crea el entregable o una versión nueva. Devuelve una URL firmada de subida por cada archivo declarado.","description":"Roles: agente, administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"etapa":{"type":"string","enum":["direccion","ingesta","matriz","unidad_modelo","unidades","libro_armado","editable"]},"tipo":{"type":"string","enum":["matriz_xlsx","libro_alumno_pdf","libro_maestro_pdf","unidad_alumno_pdf","unidad_maestro_pdf","editable_zip","dictamen","paquete_diseno","comparacion_diseno","otro"]},"unidad":{"type":"string","maxLength":4},"nota":{"type":"string","maxLength":5000},"archivos":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":200},"tamano":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["nombre","tamano"],"additionalProperties":false}}},"required":["tipo"],"additionalProperties":false}}}}}},"/libros/{id}/comentarios":{"get":{"tags":["Libros"],"summary":"Comentarios con ancla, autor, entregable y versión. Filtros: estado, entregable, desde.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/libros/{id}/correcciones":{"get":{"tags":["Libros"],"summary":"Archivos de corrección subidos por personas, con enlace de descarga. Filtro: desde.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/libros/{id}/revisiones":{"get":{"tags":["Libros"],"summary":"Decisiones de aprobación.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/libros/{id}/eventos":{"get":{"tags":["Libros"],"summary":"Bitácora: \"qué pasó desde la última vez\". Filtro: desde.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/libros/{id}/novedades":{"get":{"tags":["Libros"],"summary":"Comentarios, correcciones, decisiones y eventos nuevos en una sola llamada. Filtro: desde.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/disenos":{"get":{"tags":["Diseños"],"summary":"Sistemas de diseño con su estado y los libros que los usan.","description":"Cualquier persona o agente autenticado.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"post":{"tags":["Diseños"],"summary":"Crea un sistema de diseño.","description":"Roles: agente, administrador, diseno.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":60},"nombre":{"type":"string","minLength":1,"maxLength":200},"nivel":{"type":"string","maxLength":100},"descripcion":{"type":"string","maxLength":2000}},"required":["id","nombre"],"additionalProperties":false}}}}}},"/disenos/{id}":{"get":{"tags":["Diseños"],"summary":"Estado del diseño, entregables vigentes y libros que lo usan.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"patch":{"tags":["Diseños"],"summary":"La fábrica marca `en_adopcion` (o regresa a `recibido`).","description":"Roles: agente, administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"estado":{"type":"string","enum":["recibido","en_adopcion","en_revision","aprobado"]}},"required":["estado"],"additionalProperties":false}}}}}},"/disenos/{id}/entregables":{"get":{"tags":["Diseños"],"summary":"Entregables del diseño con su versión vigente.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"post":{"tags":["Diseños"],"summary":"Crea el entregable o una versión nueva. Devuelve una URL firmada de subida por cada archivo declarado.","description":"Roles: agente, administrador, diseno.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"etapa":{"type":"string","enum":["direccion","ingesta","matriz","unidad_modelo","unidades","libro_armado","editable"]},"tipo":{"type":"string","enum":["matriz_xlsx","libro_alumno_pdf","libro_maestro_pdf","unidad_alumno_pdf","unidad_maestro_pdf","editable_zip","dictamen","paquete_diseno","comparacion_diseno","otro"]},"unidad":{"type":"string","maxLength":4},"nota":{"type":"string","maxLength":5000},"archivos":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":200},"tamano":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["nombre","tamano"],"additionalProperties":false}}},"required":["tipo"],"additionalProperties":false}}}}}},"/disenos/{id}/comentarios":{"get":{"tags":["Diseños"],"summary":"Comentarios con ancla, autor, entregable y versión. Filtros: estado, entregable, desde.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/disenos/{id}/correcciones":{"get":{"tags":["Diseños"],"summary":"Archivos de corrección subidos por personas, con enlace de descarga. Filtro: desde.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/disenos/{id}/revisiones":{"get":{"tags":["Diseños"],"summary":"Decisiones de aprobación.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/disenos/{id}/eventos":{"get":{"tags":["Diseños"],"summary":"Bitácora: \"qué pasó desde la última vez\". Filtro: desde.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/disenos/{id}/novedades":{"get":{"tags":["Diseños"],"summary":"Comentarios, correcciones, decisiones y eventos nuevos en una sola llamada. Filtro: desde.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/entregables/{id}":{"get":{"tags":["Entregables"],"summary":"Todas las versiones, sus archivos, decisiones y qué comentarios atiende cada una.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/entregables/{id}/versiones/{n}/archivos":{"post":{"tags":["Entregables"],"summary":"Agrega un archivo a una versión sin enviar. Devuelve la URL firmada de subida. Admite Idempotency-Key.","description":"Roles: agente, administrador, diseno.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"n","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":200},"tamano":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["nombre","tamano"],"additionalProperties":false}}}}}},"/entregables/{id}/versiones/{n}/enviar":{"post":{"tags":["Entregables"],"summary":"Pone la versión en revisión y avisa a los revisores.","description":"Roles: agente, administrador, diseno.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"n","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/entregables/{id}/versiones/{n}/revision":{"post":{"tags":["Entregables"],"summary":"Aprobar o pedir cambios. Sólo personas: aprobador en libros, diseño en diseños. Un agente recibe 403.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"n","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["aprobado","requiere_cambios"]},"nota":{"type":"string","maxLength":5000}},"required":["decision"],"additionalProperties":false}}}}}},"/entregables/{id}/versiones/{n}/comentarios":{"post":{"tags":["Comentarios"],"summary":"Comentario anclado a página, celda o texto libre; o respuesta en un hilo (padre_id).","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"n","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"texto":{"type":"string","minLength":1,"maxLength":5000},"ancla":{"anyOf":[{"type":"object","properties":{"tipo":{"type":"string","enum":["pagina"]},"pagina":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991}},"required":["tipo","pagina"],"additionalProperties":false},{"type":"object","properties":{"tipo":{"type":"string","enum":["celda"]},"hoja":{"type":"string","minLength":1,"maxLength":100},"celda":{"type":"string","pattern":"^[A-Z]{1,3}\\d{1,6}$"},"fila":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991}},"required":["tipo","hoja"],"additionalProperties":false},{"type":"object","properties":{"tipo":{"type":"string","enum":["texto"]},"texto":{"type":"string","minLength":1,"maxLength":300}},"required":["tipo","texto"],"additionalProperties":false}]},"tipo":{"type":"string","enum":["correccion","duda","decision","elogio"]},"padre_id":{"type":"string"},"adjuntos":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":200},"tamano":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["nombre","tamano"],"additionalProperties":false}}},"required":["texto"],"additionalProperties":false}}}}}},"/entregables/{id}/versiones/{n}/correcciones":{"post":{"tags":["Comentarios"],"summary":"Archivo de corrección de una persona (PDF anotado, Excel con cambios…). Devuelve URL de subida.","description":"Roles: administrador, aprobador, revisor, diseno.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"n","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nota":{"type":"string","maxLength":2000},"archivos":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":200},"tamano":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"required":["nombre","tamano"],"additionalProperties":false}}},"required":["archivos"],"additionalProperties":false}}}}}},"/comentarios/{id}/respuesta":{"post":{"tags":["Comentarios"],"summary":"Respuesta de la fábrica; puede marcar `atendido` o `descartado`, con versión y caso_id.","description":"Roles: agente, administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"texto":{"type":"string","minLength":1,"maxLength":5000},"estado":{"type":"string","enum":["abierto","atendido","descartado"]},"version":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"caso_id":{"type":"string"}},"required":["texto"],"additionalProperties":false}}}}}},"/comentarios/{id}":{"delete":{"tags":["Comentarios"],"summary":"Borra un comentario. Sólo administrador.","description":"Roles: administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/archivos/{id}":{"get":{"tags":["Archivos"],"summary":"Descarga por flujo, con Range. Requiere sesión, token o URL firmada. `?ver=1` lo muestra en el navegador.","description":"URL firmada (o sesión/token en descargas).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"firma":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"head":{"tags":["Archivos"],"summary":"Tamaño y suma SHA-256 sin descargar.","description":"URL firmada (o sesión/token en descargas).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"firma":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/archivos/{id}/enlace":{"get":{"tags":["Archivos"],"summary":"URL firmada de descarga, de vida corta.","description":"Cualquier persona o agente autenticado.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/subidas/{id}":{"put":{"tags":["Archivos"],"summary":"Recibe los bytes de un archivo reservado. Entero, o por partes con Content-Range. Se escribe a disco por flujo.","description":"URL firmada (o sesión/token en descargas).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"firma":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}}},"head":{"tags":["Archivos"],"summary":"Bytes ya recibidos (cabecera Upload-Offset), para reanudar.","description":"URL firmada (o sesión/token en descargas).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"firma":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/sesion":{"post":{"tags":["Sesión"],"summary":"Entrar con correo y contraseña. Deja la cookie de sesión.","description":"Pública.","parameters":[],"security":[],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"correo":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"contrasena":{"type":"string","minLength":1,"maxLength":200}},"required":["correo","contrasena"],"additionalProperties":false}}}}},"get":{"tags":["Sesión"],"summary":"Quién soy.","description":"Cualquier persona o agente autenticado.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"delete":{"tags":["Sesión"],"summary":"Salir.","description":"Pública.","parameters":[],"security":[],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/sesion/recuperar":{"post":{"tags":["Sesión"],"summary":"Pide el correo para cambiar la contraseña.","description":"Pública.","parameters":[],"security":[],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"correo":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["correo"],"additionalProperties":false}}}}}},"/sesion/contrasena":{"post":{"tags":["Sesión"],"summary":"Fija la contraseña con el token de una invitación o de una recuperación.","description":"Pública.","parameters":[],"security":[],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":20},"contrasena":{"type":"string","minLength":10,"maxLength":200}},"required":["token","contrasena"],"additionalProperties":false}}}}}},"/admin/tokens":{"get":{"tags":["Administración"],"summary":"Tokens de agente con fecha de último uso.","description":"Roles: administrador.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"post":{"tags":["Administración"],"summary":"Crea un token de agente. El valor se muestra una sola vez.","description":"Roles: administrador.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":100}},"required":["nombre"],"additionalProperties":false}}}}}},"/admin/tokens/{id}":{"delete":{"tags":["Administración"],"summary":"Revoca un token: deja de funcionar de inmediato.","description":"Roles: administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/admin/usuarios":{"get":{"tags":["Administración"],"summary":"Personas con acceso.","description":"Roles: administrador.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}},"post":{"tags":["Administración"],"summary":"Invita a una persona. Le llega un correo para crear su contraseña.","description":"Roles: administrador.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":120},"correo":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"rol":{"type":"string","enum":["administrador","aprobador","revisor","diseno"]}},"required":["nombre","correo","rol"],"additionalProperties":false}}}}}},"/admin/usuarios/{id}":{"patch":{"tags":["Administración"],"summary":"Cambia nombre o rol, o desactiva a una persona.","description":"Roles: administrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","minLength":1,"maxLength":120},"rol":{"type":"string","enum":["administrador","aprobador","revisor","diseno"]},"activo":{"type":"boolean"}},"additionalProperties":false}}}}}},"/admin/eventos":{"get":{"tags":["Administración"],"summary":"Bitácora general.","description":"Roles: administrador.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}},"/admin/disco":{"get":{"tags":["Administración"],"summary":"Uso de disco del volumen de archivos.","description":"Roles: administrador.","parameters":[],"security":[{"bearer":[]},{"sesion":[]}],"responses":{"200":{"description":"Correcto."},"401":{"description":"Sin token o sesión válidos."},"403":{"description":"El rol no lo permite."},"404":{"description":"No existe."},"409":{"description":"El estado actual no lo permite."},"422":{"description":"Datos inválidos."}}}}}}