Planificar asignaciones
POST /api/v1/planning/assignments requiere assignments:read (también concedido por assignments:write) y Starter o Pro activo. Es solo lectura: no reserva capacidad ni guarda asignaciones. MCP Pro ofrece kordia_plan_assignment.
Parámetros JSON
| Campo | Tipo | Requerido | Uso |
|---|---|---|---|
project_id |
ID positivo | Sí para plan nuevo | Proyecto activo; con id, REST puede conservar el original |
start_date, end_date |
date string ISO | Sí para plan nuevo | Periodo ordenado ≤1826 días dentro del proyecto |
daily_hours |
número 0.01–8, hasta 2 decimales | Este o total_hours |
Jornada diaria |
total_hours |
entero 1–14616 | Este o daily_hours |
Total que se desea repartir |
resource_id |
ID positivo | No | Si se envía, calcula preview concreto; si se omite, busca candidatos |
id |
ID positivo | No | Simula editar una asignación y la excluye del consumo previo |
cost_source |
contract_default o manual_override |
No | Coste del preview concreto |
cost_per_hour |
decimal string no negativo finito | Con override | Por ejemplo "50.00" |
query |
string, máximo 200 bytes | No | Solo candidatos, busca nombre; defecto "" |
tag_ids |
array, máximo 100 IDs positivos | No | Solo candidatos; todas las etiquetas deben ser de recursos y de la organización |
limit |
entero 1–100 | No | Solo candidatos; defecto 100 |
after_id |
ID positivo | No | Solo candidatos; cursor de la página anterior, omitir en la primera |
Los filtros de candidatos no se admiten junto con resource_id, ni en creación/actualización real. tag_ids requiere todas las etiquetas, a diferencia de los filtros de catálogo. REST acepta cadenas numéricas de horas; MCP exige tipos numéricos. Con id se heredan recurso, proyecto, fechas y jornada si se omiten; por ello es normalmente preview concreto. MCP exige siempre project_id, start_date y end_date, incluso con id.
Las reglas de coste y conservación de override son las de asignaciones. Buscar candidatos solo estima disponibilidad: no valida que el coste o el reparto exacto final puedan guardarse.
Buscar candidatos
POST /api/v1/planning/assignments
Authorization: Bearer <API_KEY>
Content-Type: application/json
{"project_id":10,"start_date":"2026-06-01","end_date":"2026-06-30","total_hours":80,"query":"Ana","tag_ids":[3],"limit":20}
Respuesta 200 posible:
{"data":{"candidates":[],"exact":false,"candidate_limit":20,"next_after_id":27}}
candidates es un array de recursos (id, external_id, name, tags, contracts, timestamps); no presupongas que contracts esté cargado en esta búsqueda. La página limita recursos examinados antes de filtrar disponibilidad. Continúa con after_id: 27 mientras next_after_id no sea null, incluso con candidatos vacíos. No hay meta.total ni paginación por offset. exact: false expresa que esta búsqueda no es un plan concreto.
Preview concreto
POST /api/v1/planning/assignments
Authorization: Bearer <API_KEY>
Content-Type: application/json
{"project_id":10,"resource_id":7,"start_date":"2026-06-01","end_date":"2026-06-30","total_hours":80}
200 devuelve data.resource_id, segments y los campos de resumen total_hours, requested_total_hours, planned_total_hours, deviation_hours, tolerance_hours, exact. Cada segmento contiene start_date, end_date, daily_hours, cost_per_hour (cadena decimal), cost_source; no tiene un ID persistido.
En modo total puede haber varios segmentos y una desviación de hasta 0.01 horas sin superar la solicitud; inspecciona exact y el total planificado. En modo diario la desviación y lo solicitado son null, tolerancia 0 y exact true. Para guardar, envía los parámetros de negocio a POST /assignments, no el objeto de respuesta ni filtros de candidatos. La disponibilidad puede cambiar entre preview y guardado.
Errores
400 invalid_params por filtros mezclados, fechas fuera de proyecto, horas o parámetros inválidos; 404 not_found; 422 archived_project, allocation_unavailable o cost_unavailable. El envelope es errors con code y detail; autenticación y errores 401/403. Una lista de candidatos vacía es 200, no un error.