{"openapi":"3.1.0","info":{"title":"Scrum Nodriza · API v1","version":"1.0.0","description":"API de la empresa en Scrum Nodriza: leer y gestionar fichas, sprints y tablero desde otras herramientas.\n\nAutenticación: `Authorization: Bearer nsk_…`. La llave la crea el administrador en Mi empresa → API y MCP y define la empresa y el alcance (lectura o escritura).\n\nLlaves de grupo: una llave puede ser de un grupo empresarial y servir para todas sus empresas activas. Con ella, cada operación acepta `empresa` (id, nombre o comienzo del nombre, como «magna»): sin ella, las lecturas juntan todas las empresas y cada elemento trae `empresa: {id, nombre}`; las escrituras sobre una ficha toman la empresa de la ficha (si el código, como F-001, se repite entre empresas, responde 409 y pide `empresa` o el id); crear fichas o sprints exige `empresa` (422 con la lista de empresas). `GET /empresas` dice cuáles abre la llave.\n\nLímite: 120 peticiones por minuto por llave (ventana fija de un minuto); al pasarlo responde 429 con Retry-After: 60.\n\nToda respuesta es `{ok: true, data}` o `{ok: false, error: {codigo, mensaje}}`.\n\nLas escrituras quedan en la bitácora de la empresa a nombre de quien creó la llave, con origen «api».","contact":{"name":"Scrum Nodriza","url":"https://www.nodrizascrum.com/desarrolladores"}},"servers":[{"url":"https://www.nodrizascrum.com/api/v1"}],"security":[{"llave":[]}],"tags":[{"name":"Lectura"},{"name":"Escritura (alcance «escritura»)"}],"paths":{"/empresas":{"get":{"tags":["Lectura"],"operationId":"listarEmpresas","summary":"Empresas que abre la llave (una, o todas las activas del grupo)","responses":{"200":{"description":"Empresas","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/EmpresaBreve"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}}},"/empresa":{"get":{"tags":["Lectura"],"operationId":"verEmpresa","summary":"Empresa, equipos y la llave usada","responses":{"200":{"description":"Empresa","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/Empresa"}}}}}},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}},"parameters":[{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}]}},"/equipos":{"get":{"tags":["Lectura"],"operationId":"listarEquipos","summary":"Equipos con su sprint en curso","responses":{"200":{"description":"Equipos","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Equipo"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}},"parameters":[{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}]}},"/sprints":{"get":{"tags":["Lectura"],"operationId":"listarSprints","summary":"Sprints, del más reciente al más antiguo (máximo 100)","parameters":[{"name":"estado","in":"query","required":false,"schema":{"type":"string","enum":["planeado","en_curso","cerrado"]},"description":"Filtra por estado."},{"name":"equipo","in":"query","required":false,"schema":{"type":"string"},"description":"Id o nombre del equipo."},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"responses":{"200":{"description":"Sprints","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Sprint"}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"tags":["Escritura (alcance «escritura»)"],"operationId":"crearSprint","summary":"Crea un sprint planeado","description":"La capacidad se calcula con el equipo de hoy (60 puntos por persona por semana × disponibilidad). Sin número, toma el siguiente.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inicio","fin","meta"],"properties":{"inicio":{"type":"string","format":"date"},"fin":{"type":"string","format":"date"},"meta":{"type":"string"},"numero":{"type":"integer","minimum":1},"equipo":{"type":"string"},"empresa":{"type":"string","description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}}},"example":{"inicio":"2026-11-03","fin":"2026-11-16","meta":"Lanzar la convocatoria de noviembre"}}}},"responses":{"201":{"description":"Sprint creado","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/Sprint"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}},"parameters":[{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}]}},"/sprints/{id}":{"get":{"tags":["Lectura"],"operationId":"verSprint","summary":"Un sprint con su avance y sus fichas","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Id, número, «actual» o «siguiente»."},{"name":"equipo","in":"query","required":false,"schema":{"type":"string"},"description":"Desempata cuando varios equipos tienen ese número."},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"responses":{"200":{"description":"Sprint","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/SprintConFichas"}}}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/fichas":{"get":{"tags":["Lectura"],"operationId":"listarFichas","summary":"Fichas no archivadas, las más recientes primero","parameters":[{"name":"sprint","in":"query","required":false,"schema":{"type":"string"},"description":"Id, número, «actual», «siguiente» o «ninguno»."},{"name":"etapa","in":"query","required":false,"schema":{"type":"string","enum":["idea","priorizado"]},"description":""},{"name":"estado","in":"query","required":false,"schema":{"type":"string","enum":["por_hacer","haciendo","en_revision","hecho","aceptada"]},"description":""},{"name":"responsable","in":"query","required":false,"schema":{"type":"string"},"description":"Id, correo o nombre."},{"name":"texto","in":"query","required":false,"schema":{"type":"string"},"description":"Busca en el título."},{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":""},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"responses":{"200":{"description":"Fichas","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Ficha"}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"tags":["Escritura (alcance «escritura»)"],"operationId":"crearFicha","summary":"Crea una ficha","description":"Sin sprint nace como idea en el backlog general. Con sprint entra priorizada y, si tiene puntos, se revisa que el sprint no pase del 80 % de su capacidad.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["titulo"],"properties":{"titulo":{"type":"string","maxLength":300},"historia":{"type":"string","description":"Historia de usuario. «descripcion» es un alias; si llegan ambas se unen."},"descripcion":{"type":"string"},"criterios":{"type":"array","items":{"type":"string","maxLength":500},"maxItems":20},"puntos":{"type":["integer","null"],"enum":[1,2,3,5,8,13,21,null]},"prioridad":{"type":"string","enum":["alta","media","baja"],"default":"media"},"responsable":{"type":["string","null"],"description":"Id, correo o nombre exacto de una persona activa."},"sprint":{"type":["string","integer","null"],"description":"Id, número, «actual» o «siguiente». Con sprint, la ficha queda priorizada."},"etapa":{"type":"string","enum":["idea","priorizado"],"default":"idea"},"etiquetas":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"empresa":{"type":"string","description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}}},"example":{"titulo":"Publicar resultados de la convocatoria","historia":"Como coordinador quiero publicar los resultados para que los postulantes los consulten","criterios":["Publicado en la web","Correo enviado a postulantes"],"puntos":3,"prioridad":"alta"}}}},"responses":{"201":{"description":"Ficha creada","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/FichaDetalle"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}},"parameters":[{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}]}},"/fichas/lote":{"post":{"tags":["Escritura (alcance «escritura»)"],"operationId":"crearFichasEnLote","summary":"Crea hasta 30 fichas","description":"Cada ficha se crea por separado: las que fallan aparecen en «errores» y las demás quedan creadas.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fichas"],"properties":{"fichas":{"type":"array","maxItems":30,"items":{"type":"object","required":["titulo"],"properties":{"titulo":{"type":"string","maxLength":300},"historia":{"type":"string","description":"Historia de usuario. «descripcion» es un alias; si llegan ambas se unen."},"descripcion":{"type":"string"},"criterios":{"type":"array","items":{"type":"string","maxLength":500},"maxItems":20},"puntos":{"type":["integer","null"],"enum":[1,2,3,5,8,13,21,null]},"prioridad":{"type":"string","enum":["alta","media","baja"],"default":"media"},"responsable":{"type":["string","null"],"description":"Id, correo o nombre exacto de una persona activa."},"sprint":{"type":["string","integer","null"],"description":"Id, número, «actual» o «siguiente». Con sprint, la ficha queda priorizada."},"etapa":{"type":"string","enum":["idea","priorizado"],"default":"idea"},"etiquetas":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20}}}},"empresa":{"type":"string","description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}}}}}},"responses":{"201":{"description":"Resultado del lote","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"object","properties":{"creadas":{"type":"array","items":{"$ref":"#/components/schemas/FichaDetalle"}},"errores":{"type":"array","items":{"type":"object","properties":{"indice":{"type":"integer"},"titulo":{"type":"string"},"mensaje":{"type":"string"}}}}}}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}},"parameters":[{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}]}},"/fichas/priorizar":{"post":{"tags":["Escritura (alcance «escritura»)"],"operationId":"priorizarFichas","summary":"Prioriza hasta 50 fichas para el siguiente sprint planeado","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"},"maxItems":50},"empresa":{"type":"string","description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}}},"example":{"ids":["F-012","F-013"]}}}},"responses":{"200":{"description":"Priorización","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/Priorizacion"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}},"parameters":[{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}]}},"/fichas/{id}":{"get":{"tags":["Lectura"],"operationId":"verFicha","summary":"Una ficha con historia y criterios","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Código (F-012) o id de la ficha."},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"responses":{"200":{"description":"Ficha","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/FichaDetalle"}}}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}},"patch":{"tags":["Escritura (alcance «escritura»)"],"operationId":"actualizarFicha","summary":"Cambia campos de una ficha","description":"Solo cambia lo que se envía. null quita puntos, responsable, sprint o límite. «criterios» reemplaza la lista y conserva cumplidos los que repiten texto. Pasar a etapa idea la saca del sprint.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Código (F-012) o id de la ficha."},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"titulo":{"type":"string","maxLength":300},"historia":{"type":"string","description":"Historia de usuario. «descripcion» es un alias; si llegan ambas se unen."},"descripcion":{"type":"string"},"criterios":{"type":"array","items":{"type":"string","maxLength":500},"maxItems":20},"puntos":{"type":["integer","null"],"enum":[1,2,3,5,8,13,21,null]},"prioridad":{"type":"string","enum":["alta","media","baja"],"default":"media"},"responsable":{"type":["string","null"],"description":"Id, correo o nombre exacto de una persona activa."},"sprint":{"type":["string","integer","null"],"description":"Id, número, «actual» o «siguiente». Con sprint, la ficha queda priorizada."},"etapa":{"type":"string","enum":["idea","priorizado"],"default":"idea"},"etiquetas":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"limite":{"type":["string","null"],"format":"date"},"empresa":{"type":"string","description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}}},"example":{"puntos":5,"responsable":"ana@empresa.com","sprint":"actual"}}}},"responses":{"200":{"description":"Ficha actualizada","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/FichaDetalle"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}},"delete":{"tags":["Escritura (alcance «escritura»)"],"operationId":"eliminarFicha","summary":"Borra una ficha del backlog","description":"Solo si no está en un sprint, como en la plataforma. Para las comprometidas, sácalas del sprint primero o archívalas en la plataforma.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Código (F-012) o id de la ficha."},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"responses":{"200":{"description":"Ficha eliminada","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"object","properties":{"id":{"type":"string"},"codigo":{"type":"string"},"eliminada":{"const":true}}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/fichas/{id}/mover":{"post":{"tags":["Escritura (alcance «escritura»)"],"operationId":"moverFicha","summary":"Cambia el estado de una ficha en el tablero","description":"La ficha debe estar en un sprint. La aceptación no se hace por API: es de la review.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Código (F-012) o id de la ficha."},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["estado"],"properties":{"estado":{"type":"string","enum":["por_hacer","haciendo","en_revision","hecho"]},"empresa":{"type":"string","description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}}},"example":{"estado":"haciendo"}}}},"responses":{"200":{"description":"Ficha movida","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/Ficha"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/fichas/{id}/priorizar":{"post":{"tags":["Escritura (alcance «escritura»)"],"operationId":"priorizarFicha","summary":"Prioriza una ficha para el siguiente sprint planeado","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Código (F-012) o id de la ficha."},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"responses":{"200":{"description":"Priorización","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/Priorizacion"}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/fichas/{id}/criterios":{"post":{"tags":["Escritura (alcance «escritura»)"],"operationId":"agregarCriterio","summary":"Agrega un criterio de aceptación","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Código (F-012) o id de la ficha."},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["texto"],"properties":{"texto":{"type":"string","maxLength":500},"empresa":{"type":"string","description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}}},"example":{"texto":"El informe queda en la carpeta compartida"}}}},"responses":{"201":{"description":"Ficha con el criterio","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/FichaDetalle"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/backlog":{"get":{"tags":["Lectura"],"operationId":"verBacklog","summary":"Fichas sin sprint, de mayor a menor prioridad","responses":{"200":{"description":"Backlog","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Ficha"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}},"parameters":[{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}]}},"/personas":{"get":{"tags":["Lectura"],"operationId":"listarPersonas","summary":"Personas activas de la empresa","responses":{"200":{"description":"Personas","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}},"parameters":[{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}]}},"/desempeno":{"get":{"tags":["Lectura"],"operationId":"verDesempeno","summary":"Desempeño por sprint cerrado","parameters":[{"name":"equipo","in":"query","required":false,"schema":{"type":"string"},"description":""},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"responses":{"200":{"description":"Desempeño","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}}},"/tablero":{"get":{"tags":["Lectura"],"operationId":"verTablero","summary":"Tablero del sprint en curso, por columnas (un elemento por equipo)","parameters":[{"name":"equipo","in":"query","required":false,"schema":{"type":"string"},"description":""},{"name":"empresa","in":"query","required":false,"schema":{"type":"string"},"description":"Solo para llaves de grupo empresarial: la empresa, por id, nombre exacto o comienzo del nombre (por ejemplo «magna»), sin importar mayúsculas ni tildes. Sin ella, las lecturas juntan todas las empresas del grupo y cada elemento trae «empresa»; al escribir sobre una ficha, la empresa sale de la ficha; al crear fichas o sprints es obligatoria. Con una llave de empresa se omite; si llega, debe ser la de la llave (si no, 403)."}],"responses":{"200":{"description":"Tableros","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Tablero"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/llave":{"get":{"tags":["Lectura"],"operationId":"verLlave","summary":"Nombre, alcance y ámbito (empresa o grupo) de la llave usada, y las empresas que abre","responses":{"200":{"description":"Llave","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/Llave"}}}}}},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}}}},"components":{"securitySchemes":{"llave":{"type":"http","scheme":"bearer","bearerFormat":"nsk_…","description":"Llave creada en Mi empresa → API y MCP."}},"responses":{"E400":{"description":"Petición inválida (dato faltante o con formato equivocado).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"Falta la llave, no es válida o fue revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"La llave es de solo lectura, o «empresa» no es la de una llave de empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"No existe en la empresa (o empresas) de la llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"Choca con el estado actual (por ejemplo, borrar una ficha que está en un sprint, o un código de ficha que se repite entre empresas del grupo).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E422":{"description":"Rompe una regla de la plataforma (Fibonacci, tope del 80 %, cupo de mantenimiento…).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"Más de 120 peticiones por minuto con esta llave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false},"error":{"type":"object","required":["codigo","mensaje"],"properties":{"codigo":{"type":"string"},"mensaje":{"type":"string"}}}}},"Referencia":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nombre":{"type":"string"}}},"EmpresaBreve":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nombre":{"type":"string"},"sector":{"type":["string","null"]},"ciudad":{"type":["string","null"]},"personas_activas":{"type":"integer"},"fichas_abiertas":{"type":"integer"}}},"Llave":{"type":"object","properties":{"llave":{"type":"object","properties":{"nombre":{"type":"string"},"alcance":{"type":"string","enum":["lectura","escritura"]},"ambito":{"type":"string","enum":["empresa","grupo"]}}},"empresa":{"$ref":"#/components/schemas/Referencia","description":"Solo en llaves de empresa."},"grupo":{"$ref":"#/components/schemas/Referencia","description":"Solo en llaves de grupo."},"empresas":{"type":"array","items":{"$ref":"#/components/schemas/Referencia"}}}},"Ficha":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"codigo":{"type":"string","examples":["F-012"]},"titulo":{"type":"string"},"estado":{"type":"string","enum":["por_hacer","haciendo","en_revision","hecho","aceptada"]},"etapa":{"type":"string","enum":["idea","priorizado"]},"puntos":{"type":["integer","null"]},"prioridad":{"type":"string","enum":["alta","media","baja"]},"responsable":{"oneOf":[{"$ref":"#/components/schemas/Referencia"},{"type":"null"}]},"sprint":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"numero":{"type":"integer"},"estado":{"type":"string"}}},{"type":"null"}]},"bloqueada":{"type":"boolean"},"mantenimiento":{"type":"boolean"},"etiquetas":{"type":"array","items":{"type":"string"}},"limite":{"type":["string","null"],"format":"date"},"archivada":{"type":"boolean"},"creada":{"type":"string","format":"date-time"},"empresa":{"$ref":"#/components/schemas/Referencia","description":"Solo con llaves de grupo: la empresa de la ficha."}}},"FichaDetalle":{"allOf":[{"$ref":"#/components/schemas/Ficha"},{"type":"object","properties":{"historia":{"type":"string"},"epica":{"type":["string","null"]},"motivo_bloqueo":{"type":["string","null"]},"criterios":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orden":{"type":"integer"},"texto":{"type":"string"},"cumplido":{"type":"boolean"},"obligatorio":{"type":"boolean"}}}}}}]},"Sprint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"numero":{"type":"integer"},"estado":{"type":"string","enum":["planeado","en_curso","cerrado"]},"meta":{"type":"string"},"inicio":{"type":"string","format":"date"},"fin":{"type":"string","format":"date"},"semanas":{"type":"integer"},"equipo":{"$ref":"#/components/schemas/Referencia"},"capacidad_puntos":{"type":"integer"},"comprometido":{"type":"integer"},"progreso":{"type":"object","properties":{"fichas":{"type":"integer"},"hechas":{"type":"integer"},"puntos":{"type":"integer"},"puntos_hechos":{"type":"integer"},"porcentaje":{"type":"integer"},"bloqueadas":{"type":"integer"},"dias_restantes":{"type":"integer"}}}}},"SprintConFichas":{"allOf":[{"$ref":"#/components/schemas/Sprint"},{"type":"object","properties":{"fichas":{"type":"array","items":{"$ref":"#/components/schemas/Ficha"}}}}]},"Equipo":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"tipo":{"type":"string"},"proposito":{"type":["string","null"]},"limite_wip":{"type":"integer"},"personas":{"type":"integer"},"sprint_en_curso":{"type":["object","null"]}}},"Empresa":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"personas_activas":{"type":"integer"},"fichas_abiertas":{"type":"integer"},"ideas_en_backlog":{"type":"integer"},"equipos":{"type":"array","items":{"$ref":"#/components/schemas/Equipo"}},"llave":{"type":"object","properties":{"nombre":{"type":"string"},"alcance":{"type":"string","enum":["lectura","escritura"]}}}}},"Persona":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"correo":{"type":["string","null"]},"cargo":{"type":["string","null"]},"nivel":{"type":"string"},"disponibilidad":{"type":"string"},"equipos":{"type":"array","items":{"type":"string"}}}},"Tablero":{"type":"object","properties":{"equipo":{"$ref":"#/components/schemas/Referencia"},"sprint":{"$ref":"#/components/schemas/Sprint"},"columnas":{"type":"object","properties":{"por_hacer":{"type":"array","items":{"$ref":"#/components/schemas/Ficha"}},"haciendo":{"type":"array","items":{"$ref":"#/components/schemas/Ficha"}},"en_revision":{"type":"array","items":{"$ref":"#/components/schemas/Ficha"}},"hecho":{"type":"array","items":{"$ref":"#/components/schemas/Ficha"}}}}}},"Priorizacion":{"type":"object","properties":{"priorizadas":{"type":"array","items":{"type":"string"}},"no_priorizadas":{"type":"array","items":{"type":"string"}},"sprint":{"type":["object","null"]},"por_empresa":{"type":"array","description":"Solo con llave de grupo sin «empresa»: lo priorizado en cada empresa y su sprint.","items":{"type":"object","properties":{"empresa":{"$ref":"#/components/schemas/Referencia"},"priorizadas":{"type":"array","items":{"type":"string"}},"sprint":{"type":["object","null"]}}}}}}}}}