Nodos
Nodos del organigrama — los departamentos, equipos y roles que conforman el árbol organizacional.
GET/api/v1/nodes
Devuelve una lista plana paginada de todos los nodos del organigrama en tu organización.
Parámetros de consulta
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| limit | integer | opcional | Número de resultados (por defecto 100, máximo 500). |
| cursor | ISO 8601 | opcional | Cursor de paginación del nextCursor de la página anterior. |
| parentId | uuid | opcional | Filtrar a hijos directos de este nodo. |
Ejemplo de respuesta
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"parentId": null,
"title": "Engineering",
"description": "All software teams",
"nodeType": "department",
"sortOrder": 0,
"color": "#6366f1",
"metadata": {},
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-15T09:30:00.000Z"
},
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"parentId": "550e8400-e29b-41d4-a716-446655440000",
"title": "Platform Team",
"description": "Infrastructure and DevOps",
"nodeType": "team",
"sortOrder": 1,
"color": null,
"metadata": {},
"createdAt": "2025-03-02T08:00:00.000Z",
"updatedAt": "2025-03-02T08:00:00.000Z"
}
],
"nextCursor": null
}GET/api/v1/nodes/:id
Devuelve un nodo individual por ID. 404 si no se encuentra o está fuera de tu organización.
Parámetros de ruta
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| id | uuid | obligatorio | ID del nodo. |
Ejemplo de respuesta
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"parentId": null,
"title": "Engineering",
"description": "All software teams",
"nodeType": "department",
"sortOrder": 0,
"color": "#6366f1",
"metadata": {},
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-15T09:30:00.000Z"
}
}Objeto nodo
Campos
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| id | uuid | opcional | ID único del nodo. |
| parentId | uuid | null | opcional | ID del nodo padre. null para nodos raíz. |
| title | string | opcional | Nombre para mostrar del nodo. |
| description | string | null | opcional | Descripción opcional. |
| nodeType | string | opcional | Etiqueta de tipo: department, team, role, o personalizada. |
| sortOrder | integer | opcional | Orden entre hermanos (ascendente). |
| color | string | null | opcional | Código de color hexadecimal, ej. "#6366f1". |
| metadata | object | opcional | Metadatos JSON de forma libre asociados a este nodo. |
| createdAt | ISO 8601 | opcional | Marca de tiempo de creación. |
| updatedAt | ISO 8601 | opcional | Marca de tiempo de última modificación. |
Construir un árbol a partir de la lista plana
La API devuelve un array plano. Usa parentId para reconstruir la jerarquía:
function buildTree(nodes) {
const map = {};
for (const n of nodes) map[n.id] = { ...n, children: [] };
const roots = [];
for (const n of Object.values(map)) {
if (n.parentId && map[n.parentId]) {
map[n.parentId].children.push(n);
} else {
roots.push(n);
}
}
return roots;
}Ejemplos de código
# Listar todos los nodos
curl "https://sopflow.io/api/v1/nodes?limit=100" \
-H "Authorization: Bearer sk_live_YOUR_KEY"
# Listar hijos de un nodo específico
curl "https://sopflow.io/api/v1/nodes?parentId=PARENT_NODE_ID" \
-H "Authorization: Bearer sk_live_YOUR_KEY"Mutaciones de nodos
Las mutaciones requieren el permiso write en la clave de API. Incluye un encabezado Idempotency-Key en POSTs para hacer la llamada resistente a reintentos (ver Errores y Límites).
POST/api/v1/nodes
Crear un nodo. Establece parentId=null para un nodo raíz, u otro ID de nodo para adjuntarlo como hijo.
Campos del cuerpo
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| parentId | uuid | null | obligatorio | Nodo padre, o null para raíz. |
| title | string | obligatorio | 1–200 caracteres. |
| nodeType | string | obligatorio | department, team, role, o una etiqueta personalizada. |
| description | string | null | opcional | Hasta 2000 caracteres. |
| color | string | null | opcional | Código hexadecimal como #6366f1. |
| sortOrder | integer | opcional | Posición entre hermanos; por defecto es el último. |
| metadata | object | opcional | JSON arbitrario. |
Ejemplo de respuesta
{
"data": {
"id": "af803555-3a41-4fd2-a8da-79537b8781b0",
"parentId": null,
"title": "New Department",
"nodeType": "department",
"color": "#6366f1",
"createdAt": "2026-05-03T04:00:00.000Z"
}
}PATCH/api/v1/nodes/:id
Actualizar campos en un nodo existente. Solo se modifican los campos que proporcionas.
Campos del cuerpo (todos opcionales)
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| title | string | opcional | 1–200 caracteres. |
| description | string | null | opcional | — |
| nodeType | string | opcional | — |
| color | string | null | opcional | Código hexadecimal o null para limpiar. |
| metadata | object | opcional | — |
Ejemplo de respuesta
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"parentId": null,
"title": "Engineering",
"description": "All software teams",
"nodeType": "department",
"sortOrder": 0,
"color": "#6366f1",
"metadata": {},
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-15T09:30:00.000Z"
}
}POST/api/v1/nodes/:id/move
Reasignar padre y/o reordenar un nodo. Los hijos se mueven con él.
Campos del cuerpo
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| newParentId | uuid | null | obligatorio | Padre destino, o null para convertir en nueva raíz. |
| newSortOrder | integer | obligatorio | Posición entre nuevos hermanos (basado en 0). |
Ejemplo de respuesta
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"parentId": null,
"title": "Engineering",
"description": "All software teams",
"nodeType": "department",
"sortOrder": 0,
"color": "#6366f1",
"metadata": {},
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-15T09:30:00.000Z"
}
}DELETE/api/v1/nodes/:id
Eliminar permanentemente un nodo y todos sus descendientes. Devuelve 204 en caso de éxito. Los SOP asignados a nodos eliminados quedan sin asignar pero no se eliminan.
Ejemplo de respuesta
HTTP/1.1 204 No Content