Saltar al contenido

Referencia de API de SOPFlow

Acceso programático a tu organigrama, SOPs y datos del equipo.

URL base

https://sopflow.io/api/v1

Todos los endpoints utilizan HTTPS. Las solicitudes sobre HTTP se rechazan.

Versionado

La API está versionada por URL. La versión actual es v1. Cuando se requieran cambios de ruptura, se introducirá una nueva ruta de versión (/api/v2) con aviso previo. v1 seguirá siendo compatible durante al menos 12 meses después del lanzamiento de una nueva versión.

Autenticación

Cada solicitud debe incluir una clave de API en el encabezado Authorization :

Authorization: Bearer sk_live_YOUR_KEY

Las claves de API se crean en Configuración → Claves de API. Consulta la página de Autenticación para obtener detalles completos y ejemplos de código.

Convenciones HTTP

  • Todas las respuestas son JSON. El Content-Type es siempre application/json.
  • Formato de éxito: { data: ... } para objetos únicos; { data: [...], nextCursor: string | null } para listas.
  • Formato de error: { error, code, details?, requestId }. Consulta la página de Errores y límites.
  • Métodos: GET para lecturas, POST / PATCH / DELETE para escrituras (requieren scope write).
  • Especificación OpenAPI: definición legible por máquina en /api/v1/openapi.json (3.1, requiere una clave válida).
  • IDs de solicitud: toda respuesta lleva un encabezado X-Request-Id — úsalo cuando reportes problemas.
  • Idempotencia: Los POSTs aceptan un encabezado Idempotency-Key para hacer que los reintentos sean seguros para reproducción durante 24h.
  • Paginación: Los endpoints de lista aceptan ?limit= (predeterminado 100, máximo 500) y ?cursor= (marca de tiempo ISO 8601 del nextCursor de la página anterior).
  • Aislamiento de inquilino: Todas las consultas están limitadas a la organización que posee la clave de API. No puedes leer ni modificar datos de otros espacios de trabajo.

Recursos

Organización

Nombre de org, slug, plan y estado.

Nodos

Nodos del organigrama — listar, leer, crear, actualizar, mover, eliminar.

SOPs

SOPs, versiones, fases, pasos y transiciones de estado.

Usuarios

Miembros del equipo — listar y actualizar rol / estado / ancla.

Flujos de proceso

Diagramas interfuncionales con nodos y bordes.

Primera integración: consultar el espacio

Crea una clave de lectura en un espacio habilitado y guárdala en tu servidor. Consulta la organización, confirma el espacio y solicita una página de SOP. Sigue nextCursor para obtener la colección completa.

El ejemplo no crea ni modifica contenido. Resuelve los rechazos antes de consultar otro recurso; un error de acceso no equivale a un espacio vacío.

// Server-side JavaScript. Store the real key in your secret manager.
const key = process.env.SOPFLOW_API_KEY;
const expectedWorkspaceId = process.env.SOPFLOW_WORKSPACE_ID;
if (!key || !expectedWorkspaceId) throw new Error("Configure SOPFLOW_API_KEY and SOPFLOW_WORKSPACE_ID");
async function read(path) {
  const response = await fetch("https://sopflow.io/api/v1" + path, {
    headers: { Authorization: "Bearer " + key },
  });
  if (!response.ok) throw new Error("Request failed: " + response.status);
  return response.json();
}
const workspace = await read("/organization");
if (workspace.data.id !== expectedWorkspaceId) throw new Error("Unexpected workspace");
const page = await read("/sops");
const first = page.data[0];
if (first) {
  const procedure = await read("/sops/" + encodeURIComponent(first.id));
  console.log({ hasActiveVersion: !!procedure.data.activeVersion });
}
// Use page.nextCursor with the documented cursor parameter for more pages.