Referencia de API

Referencia de API

Esta sección está orientada a integradores y usuarios semi-técnicos que consumen la API de Kairo directamente. Si solo usas el portal web o el bot de Telegram, puedes omitir esta página.

---

Información general

Propiedad	Valor
Base URL	https://{host}/api/v1
Formato de datos	JSON
Autenticación	Bearer JWT en el header Authorization
Paginación	Offset-based (?page=0&size=20)

Header de autenticación

Todos los endpoints excepto /auth/register y /auth/login requieren:

Authorization: Bearer {tu_jwt_token}

Códigos de respuesta HTTP

Código	Significado
200	Éxito (GET, PUT)
201	Recurso creado (POST)
204	Éxito sin contenido (DELETE)
400	Error de validación o datos inválidos
401	No autenticado (JWT inválido o ausente)
403	Sin permiso (no eres manager, miembro, o asignado)
404	Recurso no encontrado
409	Conflicto (ej. activar sprint cuando ya hay uno activo)

Formato de error

{
  "error": "SPRINT_ALREADY_ACTIVE",
  "message": "El proyecto ya tiene un sprint activo",
  "status": 409
}

Respuesta paginada

{
  "content": [...],
  "page": 0,
  "size": 20,
  "totalElements": 57,
  "totalPages": 3
}

---

Autenticación

Registrar usuario

POST /api/v1/auth/register

Body:

{
  "full_name": "Ana García",
  "email": "ana@example.com",
  "password": "miContraseña123"
}

Respuesta 201: devuelve el objeto de usuario + JWT.

---

Login

POST /api/v1/auth/login

Body:

{
  "email": "ana@example.com",
  "password": "miContraseña123"
}

Respuesta 200: devuelve el JWT. Guárdalo para usarlo en el header de las siguientes peticiones. Expira en 24 horas.

---

Proyectos

Método	Endpoint	Permiso	Descripción
GET	/api/v1/projects	ANY	Mis proyectos (manager o miembro)
POST	/api/v1/projects	ANY	Crear proyecto
GET	/api/v1/projects/{id}	PARTICIPANT	Detalle del proyecto
PUT	/api/v1/projects/{id}	MANAGER	Editar proyecto
DELETE	/api/v1/projects/{id}	MANAGER	Eliminar proyecto
POST	/api/v1/projects/{id}/close	MANAGER	Cerrar proyecto
POST	/api/v1/projects/{id}/transfer	MANAGER	Transferir ownership

Body para crear/editar:

{
  "project_name": "Nombre del proyecto",
  "description": "Descripción opcional"
}

---

Miembros del proyecto

Método	Endpoint	Permiso	Descripción
GET	/api/v1/projects/{id}/members	PARTICIPANT	Listar miembros
POST	/api/v1/projects/{id}/members	MANAGER	Agregar miembro
DELETE	/api/v1/projects/{id}/members/{userId}	MANAGER	Remover miembro

Body para agregar:

{ "user_id": 42 }

---

Sprints

Método	Endpoint	Permiso	Descripción
GET	/api/v1/projects/{id}/sprints	PARTICIPANT	Listar sprints
POST	/api/v1/projects/{id}/sprints	MANAGER	Crear sprint
GET	/api/v1/projects/{id}/sprints/{sprintId}	PARTICIPANT	Detalle de sprint
PUT	/api/v1/projects/{id}/sprints/{sprintId}	MANAGER	Editar sprint
POST	/api/v1/projects/{id}/sprints/{sprintId}/activate	MANAGER	Activar sprint
POST	/api/v1/projects/{id}/sprints/{sprintId}/close	MANAGER	Cerrar sprint

Body para crear/editar:

{
  "sprint_name": "Sprint 1",
  "goal": "Implementar autenticación",
  "start_date": "2026-06-01",
  "end_date": "2026-06-14"
}

⚠️ Activar un sprint cuando ya hay otro ACTIVE devuelve 409 SPRINT_ALREADY_ACTIVE.

---

Tareas

Método	Endpoint	Permiso	Descripción
GET	/api/v1/projects/{id}/tasks	PARTICIPANT	Listar tareas (con filtros)
POST	/api/v1/projects/{id}/tasks	MANAGER	Crear tarea
GET	/api/v1/projects/{id}/tasks/{taskId}	PARTICIPANT	Detalle de tarea
PUT	/api/v1/projects/{id}/tasks/{taskId}	MANAGER	Editar tarea completa
DELETE	/api/v1/projects/{id}/tasks/{taskId}	MANAGER	Eliminar tarea
PATCH	/api/v1/projects/{id}/tasks/{taskId}/status	MANAGER o ASSIGNED	Cambiar estado
PATCH	/api/v1/projects/{id}/tasks/{taskId}/sprint	MANAGER	Mover a sprint / backlog

Filtros disponibles en el listado:

?status=TODO&sprint=5&assigned_to=3&priority=HIGH

Body para crear tarea:

{
  "task_name": "Implementar login",
  "description": "Formulario de autenticación con JWT",
  "story_points": 3,
  "priority": "HIGH",
  "assigned_to": 42,
  "sprint": 7
}

Body para cambiar estado:

{
  "status": "DONE",
  "actual_hours": 4.5
}

⚠️ actual_hours es obligatorio cuando status = DONE. Omitirlo devuelve 400.

Body para mover a sprint (o backlog):

{ "sprint_id": 7 }

Para mover al backlog, usar { "sprint_id": null }.

---

Actividad de tareas

Método	Endpoint	Permiso	Descripción
POST	/api/v1/projects/{id}/tasks/{taskId}/comments	PARTICIPANT	Agregar comentario
GET	/api/v1/projects/{id}/tasks/{taskId}/activity	PARTICIPANT	Historial de actividad

Body para comentar:

{ "content": "Revisé el código, listo para PR" }

---

Dashboard y KPIs

Todos los endpoints de dashboard requieren permiso PARTICIPANT.

Endpoint	Descripción
GET /api/v1/projects/{id}/dashboard/sprint-summary	Resumen del sprint activo
GET /api/v1/projects/{id}/dashboard/velocity?sprints=5	Velocidad histórica
GET /api/v1/projects/{id}/dashboard/burndown	Burn-down del sprint activo
GET /api/v1/projects/{id}/dashboard/workload	Carga de trabajo por miembro
GET /api/v1/projects/{id}/dashboard/efficiency	Eficiencia SP vs horas por miembro
GET /api/v1/projects/{id}/dashboard/backlog	Resumen del backlog

💡 El endpoint efficiency devuelve 404 si el proyecto no tiene sprint activo.

---

Perfil de usuario

Método	Endpoint	Permiso	Descripción
GET	/api/v1/users/me	ANY	Ver mi perfil
PUT	/api/v1/users/me	ANY	Editar mi perfil

Body para editar:

{
  "full_name": "Ana García",
  "email": "ana.nueva@example.com"
}