Informes

Informes de solo lectura, con Starter o Pro activo por REST. No hay scope reports: se comprueba el área del informe. :write incluye :read en esa misma área.

Todos responden 200 {"data": informe}, sin paginación. IDs enteros positivos de la organización. La ruta genérica /reports/:kind solo tiene sentido sin ID para availability; los demás tipos requieren ID. No hay parámetros limit, offset, query, project_id ni resource_id: usa el ID de ruta (o id opcional en query para filtrar availability sin ID en ruta).

Periodos

Sin periodo, project_hours/tag_breakdown usan el periodo del proyecto; resource_hours usa el intervalo de sus asignaciones (vacío si no existen); availability usa el año UTC actual. Con rango se recortan los días de los extremos, no se cuentan meses completos fuera de él. Fechas se serializan ISO, claves mensuales YYYY-MM, dinero decimal string y horas numéricas.

Ejemplos

Todas las peticiones requieren Authorization: Bearer <API_KEY>.

GET /api/v1/reports/project_hours/10?year=2026
GET /api/v1/reports/resource_hours/7?from=2026-06-01&to=2026-06-30
GET /api/v1/reports/tag_breakdown/10?year=2026
GET /api/v1/reports/availability/7?year=2026
GET /api/v1/reports/availability?from=2026-06-15&to=2026-07-15

Horas mensuales

project_hours devuelve resources (array), months (array de meses), totals (objeto mes→horas) y grand_total (número). Cada recurso tiene resource_id, resource_name, months (objeto mes→horas) y total_hours.

resource_hours devuelve projects en lugar de resources; cada fila tiene project_id, project_title, months y total_hours. No confundir el array data.months con el mapa months de cada fila.

Ejemplo de proyecto sin asignaciones en junio:

{"data":{"resources":[],"months":["2026-06"],"totals":{"2026-06":0},"grand_total":0}}

Disponibilidad

data.resources_data es un array de objetos con resource (representación del recurso con etiquetas/contratos), monthly_hours (mapa mes→horas libres), total_hours. monthly_totals suma las filas y grand_total suma todo el periodo. Se calcula capacidad contractual menos horas asignadas, con mínimo cero; no es una reserva ni garantiza que cualquier asignación concreta sea viable.

Ejemplo sin recursos para un rango de un mes:

{"data":{"resources_data":[],"monthly_totals":{"2026-06":0},"grand_total":0}}

Desglose por etiquetas

data contiene budget_groups (array), untagged (objeto), other_groups (array), has_budgets? (boolean), exceeded_count (entero), assigned_hours (número), people_count (entero), multi_tagged? (boolean). Los signos ? forman parte de las claves JSON.

Cada grupo tiene key, kind (budget, untagged, other), name, color nullable, budget (entero o null), hours y resources (array de {"resource": recurso, "hours": número}). Un recurso cuenta en todos sus grupos con cupo; no sumes grupos esperando un total sin duplicados. untagged reúne recursos sin etiqueta con cupo; other_groups es informativo. Los presupuestos no se prorratean al seleccionar un rango y superarlos se señala, no bloquea una asignación.

Errores y MCP

400 invalid_params por tipo/rango inválido, solo una fecha, mezcla year/rango o ID mal formado; 404 not_found por entidad inexistente o ajena. También 401/403 comunes. Envelope {"errors":{"code":"invalid_params","detail":"from and to are required together"}}.

MCP Pro: kordia_report con kind: "project_hours", "resource_hours", "availability" o "tag_breakdown", id según tabla, y year o from/to. Para disponibilidad de organización omite id.

Continúa con planificar, contratos y proyectos.