Asignaciones
REST requiere Starter o Pro activo. Listar/leer requiere assignments:read; crear, actualizar y borrar, assignments:write (incluye lectura). La planificación permite comprobar disponibilidad sin guardar con solo lectura.
Endpoints y consultas
| Método y ruta | Parámetros | Éxito |
|---|---|---|
GET /api/v1/assignments |
Query opcional project_id, resource_id (IDs positivos), limit (entero 1–100, defecto 50), offset (entero ≥0, defecto 0) |
200, array data y meta |
GET /api/v1/assignments/:id |
ID positivo obligatorio | 200 {"data": asignación} |
POST /api/v1/assignments |
JSON de creación | 201 {"data": resultado} |
PATCH /api/v1/assignments/:id |
ID obligatorio, JSON parcial | 200 {"data": resultado} |
PUT /api/v1/assignments/:id |
Igual que PATCH, conserva valores omitidos | 200 {"data": resultado} |
DELETE /api/v1/assignments/:id |
ID obligatorio, sin cuerpo | 200 {"data":{"deleted":true,"id":42}} |
Lista por ID ascendente, sin filtros de nombre, etiquetas ni fechas. meta contiene limit, offset, total. Los filtros de proyecto/recurso deben pertenecer a la organización. GET individual admite include=monthly_hours y from/to (ISO, juntos, ordenados, máximo 3660 días), pero no añade una matriz a una asignación.
Cuerpo de creación y actualización
| Campo | Tipo | Crear | Actualizar |
|---|---|---|---|
project_id |
ID entero positivo | Obligatorio | Opcional, conserva el actual |
resource_id |
ID entero positivo | Obligatorio | Opcional, conserva el actual |
start_date, end_date |
string date YYYY-MM-DD |
Ambos obligatorios | Opcionales, conserva los actuales |
daily_hours |
número decimal 0.01–8, máximo 2 decimales | Este o total_hours |
Opcional; si no envías ninguno conserva jornada actual |
total_hours |
entero 1–14616 | Este o daily_hours |
Opcional, recalcula distribución |
cost_source |
contract_default o manual_override |
Opcional | Opcional |
cost_per_hour |
decimal string finito no negativo | Obligatorio con manual_override |
Obligatorio al elegir override salvo conservación del existente |
Envía exactamente uno de los modos de horas al crear. REST también acepta cadenas numéricas para horas; MCP exige números para daily_hours y enteros para total_hours. No se admite hours, attrs, query, tag_ids, limit, after_id ni campos de organización en mutaciones.
El periodo debe estar ordenado, no superar 1826 días y quedar dentro del proyecto. El proyecto original y el destino deben estar activos. Se revalidan contratos, capacidad y coste al guardar. Sin cost_source, enviar coste selecciona manual_override; sin ambos se usa contract_default. En actualización, un override existente se conserva si omites ambos campos. Para volver al contrato envía {"cost_source":"contract_default"}; un coste suministrado con esa fuente no se usa como override.
Ejemplos de consulta y escritura
Todas las peticiones llevan Authorization: Bearer <API_KEY>.
GET /api/v1/assignments?project_id=10&resource_id=7&limit=50&offset=0
GET /api/v1/assignments/42
POST /api/v1/assignments
Content-Type: application/json
{"project_id":10,"resource_id":7,"start_date":"2026-06-01","end_date":"2026-06-30","total_hours":80}
PATCH /api/v1/assignments/42
Content-Type: application/json
{"daily_hours":4,"cost_source":"manual_override","cost_per_hour":"52.50"}
DELETE /api/v1/assignments/42
Respuestas
La representación individual tiene id, project_id, project_title, resource_id, resource_name, start_date, end_date, daily_hours, cost_per_hour (decimal string), cost_source, inserted_at, updated_at. Los nombres relacionados pueden ser null en resultados de escritura; consulta GET para obtener los datos relacionados. Fechas ISO y timestamps ISO 8601.
Crear/actualizar devuelve data.assignments (array, no un objeto único), total_hours, requested_total_hours, planned_total_hours, deviation_hours, tolerance_hours, exact. El modo total puede generar varios segmentos: la actualización reutiliza el ID original para el primero y crea los restantes. No presupongas que todos comparten el ID de la ruta.
En modo diario requested_total_hours y deviation_hours son null, tolerance_hours es 0 y exact true. En modo total, total_hours es el total planificado; inspecciona desviación y tolerancia (0.01 horas, sin superar lo solicitado). exact: false puede ser un éxito. {} en PATCH revalida y recalcula la asignación actual, no es una operación de lectura ni garantiza ausencia de efectos sobre costes.
Errores y MCP
400 invalid_params: parámetros desconocidos, modos simultáneos, fechas/horas inválidas. 404 not_found: entidad inexistente/ajena. 422 allocation_unavailable, cost_unavailable, archived_project, validation_error u otro rechazo de dominio; 409 conflict cuando corresponda. Formato {"errors":{"code":"allocation_unavailable","detail":"Insufficient resource availability"}}. También 401/403 comunes.
MCP Pro: kordia_search (entity: "assignments"), kordia_get (entity: "assignment", id) y kordia_manage_assignment (action: "create", "update", "delete"). Atributos planos; id para update/delete. Consulta contratos para disponer de capacidad.