Actualizar, archivar y borrar proyectos
Todas estas operaciones requieren projects:write (incluye projects:read). REST requiere Starter o Pro activo; autenticación y errores comunes se aplican a todos los endpoints. La organización la determina la clave.
| Método y ruta | Parámetros | Éxito |
|---|---|---|
PATCH /api/v1/projects/:id |
ID positivo obligatorio en ruta; JSON de atributos opcionales | 200, {"data": proyecto} |
PUT /api/v1/projects/:id |
Igual que PATCH; no reemplaza los campos omitidos | 200, {"data": proyecto} |
POST /api/v1/projects/:id/archive |
ID obligatorio; sin atributos | 200, proyecto con status: "archived" |
POST /api/v1/projects/:id/unarchive |
ID obligatorio; sin atributos | 200, proyecto con status: "active" |
DELETE /api/v1/projects/:id |
ID obligatorio; sin atributos | 200, {"data": proyecto} eliminado, no 204 |
Atributos de actualización
| Campo | Tipo | Requerido | Efecto |
|---|---|---|---|
title |
string no vacío | No | Título único en la organización, sin distinguir mayúsculas ni espacios exteriores |
external_id |
string o null | No | Identificador externo único por organización; null o cadena vacía lo elimina |
start_date, end_date |
string date YYYY-MM-DD |
No | Fechas del proyecto |
budgeted_hours |
integer | No | Presupuesto de horas |
budgeted_cost |
decimal string o null | No | Coste presupuestado no negativo, por ejemplo "16000.00" |
tag_ids |
array de IDs positivos | No | Reemplaza etiquetas; [] las retira; deben admitir proyectos |
project_tag_ids |
array de IDs positivos | No | Alias REST de tag_ids; no enviar ambos |
tag_budgets |
array de objetos | No | Reemplaza partidas; [] las elimina; omitir conserva las existentes |
Cada partida tiene tag_id (ID obligatorio de etiqueta de recurso), hours (entero obligatorio) y id (opcional, obligatorio para editar una partida existente sin sustituirla). El ID debe pertenecer a ese proyecto. No repitas etiquetas ni superes budgeted_hours con la suma de partidas.
REST admite atributos planos o dentro de attrs (objeto); no dupliques un campo en ambos. {} conserva los datos. No se aceptan status, organization_id ni assignments en actualización: usa los endpoints específicos.
Ejemplos
Los ejemplos HTTP llevan Authorization: Bearer <API_KEY>; los cuerpos JSON, Content-Type: application/json. Sustituye los IDs por registros de tu organización.
PATCH /api/v1/projects/10
Content-Type: application/json
{"title":"Proyecto Atlas revisado","budgeted_hours":320,"budgeted_cost":"16000.00","tag_ids":[],"tag_budgets":[{"tag_id":3,"hours":120}]}
POST /api/v1/projects/10/archive
POST /api/v1/projects/10/unarchive
DELETE /api/v1/projects/10
El objeto data contiene id, external_id, title, fechas, presupuestos, status, tags, tag_budgets, inserted_at y updated_at, como en leer proyecto, pero sin assignments. Fechas ISO, timestamps ISO 8601 y dinero en cadenas decimales (o null).
Archivo, borrado y errores
Archivar conserva el proyecto y sus asignaciones; las operaciones de planificación/escritura de asignaciones rechazan proyectos archivados. Archivar un proyecto ya archivado o reactivar uno ya activo no cambia su estado. Reactivar uno archivado comprueba el límite de proyectos activos. Borrar es destructivo: no equivale a archivar ni dispone de recuperación por API.
Errores: 400 invalid_params (atributos desconocidos, duplicados o etiquetas inválidas), 404 not_found (ID inexistente o ajeno), 422 validation_error (título/external_id duplicado, presupuesto inválido o límite al reactivar), 422 plan_limit_reached cuando el límite se comunica como tal, y 409 conflict para otros conflictos. El envelope es {"errors":{"code":"…","detail":"…"}}, con detalles de campos cuando existen. No asumas idempotencia de DELETE: repetirlo tras el borrado produce 404.
MCP: kordia_manage_project con action: "update", "archive", "unarchive" o "delete" e id; usa atributos planos y tag_ids, no los alias REST. MCP requiere Pro activo.
Continúa con crear, listar, asignaciones o informes.