SOPs

Procedimientos operativos estándar — cada uno con historial de versiones, fases (columnas) y pasos (tarjetas).

GET/api/v1/sops

Lista paginada de SOPs con resumen de su versión activa.

Parámetros de consulta

Nombre	Tipo	Obligatorio	Descripción
limit	integer	opcional	Número de resultados (predeterminado 100, máximo 500).
cursor	ISO 8601	opcional	Cursor de paginación desde nextCursor.
nodeId	uuid	opcional	Filtrar a SOPs que pertenecen a este nodo de la organización.

Ejemplo de respuesta

Json

{
  "data": [
    {
      "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "sopNumber": "SOP-001",
      "orgNodeId": "550e8400-e29b-41d4-a716-446655440000",
      "category": "Onboarding",
      "reviewPeriodMonths": 12,
      "createdAt": "2025-03-05T09:00:00.000Z",
      "activeVersionId": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "activeVersionTitle": "New Employee Onboarding v2",
      "activeVersionStatus": "active",
      "activeVersionMajor": 2,
      "activeVersionMinor": 0,
      "activeVersionEffectiveDate": "2025-04-01"
    }
  ],
  "nextCursor": null
}

GET/api/v1/sops/:id

SOP completo con versión activa, fases y pasos.

Parámetros de ruta

Nombre	Tipo	Obligatorio	Descripción
id	uuid	obligatorio	ID del SOP.

Ejemplo de respuesta

Json

{
  "data": {
    "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "sopNumber": "SOP-001",
    "orgNodeId": "550e8400-e29b-41d4-a716-446655440000",
    "category": "Onboarding",
    "reviewPeriodMonths": 12,
    "createdAt": "2025-03-05T09:00:00.000Z",
    "activeVersion": {
      "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "versionMajor": 2,
      "versionMinor": 0,
      "status": "active",
      "title": "New Employee Onboarding v2",
      "purpose": "Ensure every new hire has a consistent first-week experience.",
      "scope": "Applies to all full-time employees.",
      "effectiveDate": "2025-04-01",
      "approvedAt": "2025-03-28T14:00:00.000Z",
      "createdAt": "2025-03-20T10:00:00.000Z",
      "phases": [
        {
          "id": "phase-1-id",
          "title": "Day 1",
          "sortOrder": 0,
          "color": "#6366f1",
          "createdAt": "2025-03-20T10:00:00.000Z",
          "steps": [
            {
              "id": "step-1-id",
              "title": "Set up laptop and accounts",
              "description": "IT hands off laptop with standard image. Employee activates SSO.",
              "stepType": "action",
              "assignedRole": "IT",
              "sortOrder": 0,
              "estimatedDuration": "2 hours",
              "createdAt": "2025-03-20T10:00:00.000Z"
            }
          ]
        }
      ]
    }
  }
}

Objeto SOP

Campos de nivel superior

Nombre	Tipo	Obligatorio	Descripción
id	uuid	opcional	ID único del SOP.
sopNumber	string	opcional	Identificador legible por humanos, p. ej. "SOP-001".
orgNodeId	uuid \| null	opcional	El nodo del organigrama que es dueño de este SOP.
category	string \| null	opcional	Etiqueta de categoría opcional.
reviewPeriodMonths	integer	opcional	Con qué frecuencia (en meses) se debe revisar este SOP.
createdAt	ISO 8601	opcional	Cuándo se creó el SOP.
activeVersion	SopVersion \| null	opcional	La versión activa actual (solo en el endpoint de detalle).

Campos de SopVersion

Nombre	Tipo	Obligatorio	Descripción
id	uuid	opcional	ID de la versión.
versionMajor	integer	opcional	Número de versión mayor.
versionMinor	integer	opcional	Número de versión menor.
status	string	opcional	draft \| review \| approved \| active \| retired
title	string	opcional	Título de esta versión.
purpose	string \| null	opcional	Declaración de propósito.
scope	string \| null	opcional	Declaración de alcance.
effectiveDate	date \| null	opcional	Cuándo entró en vigencia esta versión.
approvedAt	ISO 8601 \| null	opcional	Cuándo se aprobó esta versión.
phases	Phase[]	opcional	Lista ordenada de fases (solo en el endpoint de detalle).

Campos de Fase

Nombre	Tipo	Obligatorio	Descripción
id	uuid	opcional	ID de la fase.
title	string	opcional	Título de la fase (etiqueta de columna).
sortOrder	integer	opcional	Posición entre fases.
color	string \| null	opcional	Color hexadecimal para esta columna de fase.
steps	Step[]	opcional	Lista ordenada de pasos en esta fase.

Campos de Paso

Nombre	Tipo	Obligatorio	Descripción
id	uuid	opcional	ID del paso.
title	string	opcional	Título del paso.
description	string \| null	opcional	Descripción en Markdown.
stepType	string	opcional	action \| decision \| approval \| subprocess \| reference
assignedRole	string \| null	opcional	Rol responsable de este paso.
sortOrder	integer	opcional	Posición dentro de la fase.
estimatedDuration	string \| null	opcional	Estimación de duración legible por humanos.

Ejemplos de código

# Todos los SOPs en la organización
curl "https://sopflow.io/api/v1/sops" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# SOPs para un nodo específico de la organización
curl "https://sopflow.io/api/v1/sops?nodeId=NODE_ID" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Detalle completo del SOP (con fases + pasos)
curl "https://sopflow.io/api/v1/sops/SOP_ID" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Modificar SOPs

Las modificaciones requieren el alcance write. Crear un SOP también crea una versión de borrador inicial; las fases y pasos se encuentran en una versión, así que agrégalos después de la creación.

POST/api/v1/sops

Crear una estructura de SOP más una versión de borrador inicial propiedad de ownerNodeId.

Campos del cuerpo

Nombre	Tipo	Obligatorio	Descripción
sopNumber	string	obligatorio	1–50 caracteres; único por espacio de trabajo (p. ej. SOP-001).
ownerNodeId	uuid \| null	obligatorio	Nodo del organigrama propietario. Pasa null para un SOP de catálogo sin asignación inicial.
title	string	obligatorio	Título para la versión de borrador inicial.
purpose	string \| null	opcional	Por qué existe este SOP.
scope	string \| null	opcional	Qué cubre / qué no cubre.
category	string	opcional	Hasta 100 caracteres.
reviewPeriodMonths	integer	opcional	1–120, predeterminado 12.

Ejemplo de respuesta

Json

{
  "data": {
    "id": "...",
    "sopNumber": "SOP-005",
    "createdAt": "..."
  }
}

DELETE/api/v1/sops/:id

Descarta un SOP elegible. El contenido publicado o con evidencias tiene restricciones; la eliminación crea un registro recuperable en la papelera. Devuelve 204 al completarse.

Ejemplo de respuesta

Json

HTTP/1.1 204 No Content

POST/api/v1/sops/:id/versions/:versionId/transition

Mover una versión de SOP a través de la máquina de estados: draft → in_review → approved → active → retired (con under_revision disponible desde active). Las transiciones inválidas devuelven 422 invalid_transition.

Campos del cuerpo

Nombre	Tipo	Obligatorio	Descripción
toStatus	string	obligatorio	draft \| in_review \| approved \| active \| retired \| under_revision
comment	string	opcional	Comentario opcional del revisor, registrado en approval_records.

Ejemplo de respuesta

Json

{
  "data": {
    "id": "...",
    "status": "active",
    "effectiveDate": "2026-05-03"
  }
}

Fases

POST/api/v1/sops/:id/phases

Agregar una fase (columna Kanban) a la versión de borrador actual del SOP.

Campos del cuerpo

Nombre	Tipo	Obligatorio	Descripción
sopVersionId	uuid	obligatorio	Versión a la que pertenece esta fase.
title	string	obligatorio	—
color	string \| null	opcional	Código hexadecimal para el encabezado de la columna.
sortOrder	integer	opcional	Posición entre hermanos; predeterminado último.

Ejemplo de respuesta

Json

{
  "data": { "id": "...", "title": "Plan", "sortOrder": 0, "color": "#dbeafe" }
}

PATCH/api/v1/phases/:id

Actualizar el título, color u orden de clasificación de una fase.

Ejemplo de respuesta

Json

{ "data": { "id": "...", "title": "Renamed" } }

DELETE/api/v1/phases/:id

Eliminar una fase y todos sus pasos.

Ejemplo de respuesta

Json

HTTP/1.1 204 No Content

Pasos

POST/api/v1/phases/:id/steps

Agregar un paso (tarjeta) a una fase.

Campos del cuerpo

Nombre	Tipo	Obligatorio	Descripción
phaseId	uuid	obligatorio	Fase a la que pertenece este paso.
title	string	obligatorio	Título del paso.
description	string \| null	opcional	Markdown permitido.
stepType	string	opcional	action \| decision \| approval \| subprocess \| reference
assignedRole	string \| null	opcional	Rol responsable de este paso.
estimatedDuration	string \| null	opcional	Estimación legible por humanos.
sortOrder	integer	opcional	Posición dentro de la fase.

Ejemplo de respuesta

Json

{
  "data": { "id": "...", "title": "Run pre-deploy checks", "stepType": "action" }
}

PATCH/api/v1/steps/:id

Actualizar cualquier campo de paso. Solo se escriben las claves que proporciones.

Ejemplo de respuesta

Json

{ "data": { "id": "...", "title": "Updated step" } }

DELETE/api/v1/steps/:id

Eliminar un paso.

Ejemplo de respuesta

Json

HTTP/1.1 204 No Content

SOPs

Objeto SOP

Ejemplos de código

Modificar SOPs

Fases

Pasos

Consultar un procedimiento y su versión