Descripción general de la API

Cómo realizar llamadas a la API de ProcessMind

Esta guía incluye ejemplos y prácticas recomendadas para llamar a la API de ProcessMind y recuperar datos, enviar información o automatizar flujos de trabajo.

Consulte la referencia de la API para ver la documentación completa de los endpoints y los formatos de solicitud y respuesta.

Encontrará más ejemplos y bibliotecas de cliente en la documentación de la API en GitHub.

URL base de la API

Todas las solicitudes a la API deben dirigirse a:

https://api.processmind.com

Todas las rutas están versionadas bajo /v1. La especificación completa de la API en formato legible por máquina (OpenAPI 3.1) está disponible en:

GET https://api.processmind.com/v1/openapi.json

Autenticación

Todas las solicitudes a la API requieren su clave de API en el encabezado x-api-key, excepto el documento público de OpenAPI (/v1/openapi.json) y los endpoints de OAuth de MCP:

x-api-key: your-api-key-here

Puede obtener la clave de API en la configuración de su cuenta de ProcessMind. Consulte Obtener su clave de API para ver las instrucciones.

Códigos de estado

La API de ProcessMind utiliza los códigos de estado HTTP estándar:

Conceptos clave

• apiKey: token de autenticación para todas las solicitudes a la API.
• tenantId: identifica el contexto de su espacio de trabajo u organización. Puede encontrarlo en la configuración de su cuenta.
• datatableId: identifica una tabla de datos específica para las operaciones con datos. Está disponible en la opción Obtener ID de la tabla de datos, en el menú de configuración del conjunto de datos de ProcessMind.

Qué puede hacer

La API de ProcessMind le permite:

• Administrar inquilinos: consultar información de los inquilinos, actualizar la configuración y ver estadísticas
• Administrar usuarios: añadir, actualizar o quitar usuarios de inquilinos y organizaciones
• Administrar procesos: crear procesos, cargar modelos BPMN y organizarlos en carpetas
• Conectar datos: asignar tablas de datos a procesos para analizarlos
• Cargar datos: cargar archivos CSV/XLSX directamente en tablas de datos
• Administrar conjuntos de datos: consultar, inspeccionar y eliminar conjuntos de datos y tablas de datos

Ejemplos habituales

A continuación encontrará ejemplos prácticos de operaciones habituales con la API de ProcessMind.

Obtener una URL de carga prefirmada

Para cargar un archivo en una tabla de datos, primero obtenga una URL prefirmada:

const presignedUrl = await getPresignedUploadUrl({
	apiKey,
	tenantId: "tenant-123",
	datatableId: "table-456"
});
console.log(presignedUrl); // https://s3.amazonaws.com/…?X-Amz-Signature=…

Consultar los conjuntos de datos

Recupere todos los conjuntos de datos de su inquilino:

const datasets = await getDatasets({
	apiKey,
	tenantId: "tenant-123"
});
console.log(datasets);

Obtener información del inquilino

Recupere los detalles de su inquilino:

const tenantInfo = await getTenant({
	apiKey,
	tenantId: "tenant-123"
});
console.log(tenantInfo);

Crear un proceso

Cree un proceso en su inquilino:

const process = await createProcess({
	apiKey,
	tenantId: "tenant-123",
	displayName: "Order to Cash"
});
console.log(process.id); // Use this ID for subsequent operations

Cargar un modelo BPMN

Cargue un archivo BPMN para definir el modelo de proceso:

const fs = require("fs");
const bpmnXml = fs.readFileSync("./my-process.bpmn", "utf8");

await uploadBpmn({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	bpmnXml
});

Asignar datos a un proceso

Conecte una tabla de datos a un proceso para analizarla:

const mapping = await createProcessMapping({
	apiKey,
	tenantId: "tenant-123",
	processId: "process-456",
	dataTableId: "datatable-789",
	displayName: "Sales Data 2024",
	showByDefault: true
});

Añadir un usuario a un inquilino

Añada un usuario a su inquilino:

const result = await addTenantUser({
	apiKey,
	tenantId: "tenant-123",
	id: "user-456",
	email: "colleague@example.com",
	isAdminInTenant: false,
	isActiveInTenant: true,
	sendInvitationEmail: true
});

Nota: Los campos de rol del cuerpo (isAdminInTenant, access, isDashboardViewer) se respetan tal cual. Los endpoints de administración de usuarios ofrecen acceso completo de administración del inquilino, por lo que solo debe entregar claves de API con permisos de escritura a quienes tengan autorización para administrarlo. La API del sistema no envía correos de invitación; usted es responsable de incorporar al usuario.

Cargar archivos

El proceso general para cargar un archivo en ProcessMind es el siguiente:

1. Obtenga una URL prefirmada mediante la llamada getPresignedUploadUrl.
2. Realice una solicitud PUT a esa URL con el contenido del archivo.
3. La URL prefirmada autoriza la carga directamente en el almacenamiento en la nube; no se necesitan credenciales adicionales.

Este es un ejemplo simplificado con fetch:

async function uploadFile({ apiKey, tenantId, datatableId, file }) {
	// Step 1: Obtain a presigned URL
	const uploadUrl = await getPresignedUploadUrl({ apiKey, tenantId, datatableId });
	
	// Step 2: Upload the file via PUT
	await fetch(uploadUrl, {
		method: "PUT",
		headers: {
			"Content-Type": file.type
		},
		body: file
	});
}

Ejemplos completos

A continuación encontrará ejemplos completos, listos para copiar y pegar, en distintos lenguajes.

Ejemplo de Bash: cargar un archivo

Script mínimo de Bash para cargar un archivo en ProcessMind mediante dos llamadas curl, con marcadores de posición para todos los valores

#!/bin/bash
# Minimal Bash script to upload a file to ProcessMind using two curl calls, with placeholders for all values

# Replace the following placeholders with your actual values:
# <API_KEY>, <TENANT_ID>, <DATATABLE_ID>, <FILE_PATH>

curl -s -H "x-api-key: <API_KEY>" \
	"https://api.processmind.com/v1/tenant/<TENANT_ID>/datatables/<DATATABLE_ID>/uploads/presigned-url" \
	| grep -oP '"PreSignedUploadUrl"\s*:\s*"\K[^"]+' \
	| xargs -I {} curl -s -X PUT --upload-file "<FILE_PATH>" "{}"

Ejemplo de Node.js: cargar un archivo CSV local

Carga un archivo CSV local en ProcessMind mediante una URL prefirmada.

Pasos:

1. Obtenga una URL de carga prefirmada de la API.
2. Lea el archivo local desde el disco.
3. Cargue el archivo en la URL prefirmada mediante HTTP PUT.

Configuración:

• Al llamar a uploadFile(), proporcione su clave de API, tenantId, datatableId y filePath.
• La URL base de la API está configurada como https://api.processmind.com

/**
 * Uploads a local CSV file to ProcessMind using a presigned URL.
 *
 * Steps:
 * 1. Fetch a presigned upload URL from the API.
 * 2. Read the local file from disk.
 * 3. Upload the file to the presigned URL using HTTP PUT.
 *
 * Configuration:
 * - Provide your API key, tenantId, datatableId, and filePath when calling uploadFile().
 * - The API base URL is set to https://api.processmind.com
 */

const fs = require("node:fs");

/**
 * Uploads a file to ProcessMind datatable using a presigned URL.
 * @param {string} apiKey - Your API key for authentication.
 * @param {string} tenantId - Your tenant identifier.
 * @param {string} datatableId - Your datatable identifier.
 * @param {string} filePath - Path to the file to upload.
 */

async function getApi({path, apiKey, apiUrl = "https://api.processmind.com"}) {
	try {
        const response = await fetch(`${apiUrl}${path}`, {
            method: "GET",
            headers: {
                "x-api-key": apiKey
            }
        });
        const body = await response.json();
        if (!response.ok) {
            console.error(`Error loading from API: ${response.status}, ${response.statusText}: ${body.message}`);
            return;
        }
        return body;
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

async function getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl = "https://api.processmind.com"}) {
	return (await getApi({apiKey, path: `/v1/tenant/${tenantId}/datatables/${datatableId}/uploads/presigned-url`, apiUrl})).PreSignedUploadUrl;
}

async function getDatasets({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/datasets`, apiUrl});
}

async function getTenant({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}`, apiUrl});
}

async function getOrganization({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/v1/tenant/${tenantId}/organization`, apiUrl});
}

async function uploadFile({apiKey, tenantId, datatableId, filePath, apiUrl = "https://api.processmind.com"}) {
    try {
        const uploadUrl = await getPresignedUploadUrl({apiKey, tenantId, datatableId, apiUrl});

		console.log("Uploading file...");
        fs.readFile(filePath, async (err, data) => {
            if (err) {
                console.error("Error reading file:", err);
                return;
            }
            try {
                const uploadRes = await fetch(uploadUrl, {
                    method: "PUT",
                    body: data
                });
                if (!uploadRes.ok) {
                    console.error("Upload failed:", uploadRes.status, uploadRes.statusText);
                } else {
                    console.log("File uploaded successfully.");
                }
            } catch (uploadErr) {
                console.error("Error uploading file:", uploadErr);
            }
        });
    } catch (err) {
        console.error("Unexpected error:", err);
    }
}

// Export the function for use in other modules
module.exports = { 
	getPresignedUploadUrl,
	getDatasets,
	getTenant,
	getOrganization,
	uploadFile 
};

Ejemplo de Python: cargar un archivo CSV local

Carga un archivo CSV local en una API remota mediante una URL prefirmada.

Pasos:

1. Obtenga una URL de carga prefirmada de la API.
2. Lea el archivo local desde el disco.
3. Cargue el archivo en la URL prefirmada mediante HTTP PUT.

Configuración:

• Actualice api_key, tenant_id, datatable_id y file_path según sea necesario.

"""
Uploads a local CSV file to a remote API using a presigned URL.

Steps:
1. Fetch a presigned upload URL from the API.
2. Read the local file from disk.
3. Upload the file to the presigned URL using HTTP PUT.

Configuration:
- Update api_key, tenant_id, datatable_id, file_path as needed.
"""

import requests

# === Configuration ===
api_key = ""  # API key for authentication
tenant_id = ""  # Tenant identifier
datatable_id = ""  # Datatable identifier
file_path = ""  # Path to the file to upload


print("Fetching upload URL...")
api_url = "https://api.processmind.com"  # Base API URL
presign_url = f"{api_url}/v1/tenant/{tenant_id}/datatables/{datatable_id}/uploads/presigned-url"
presign_res = requests.get(presign_url, headers={"x-api-key": api_key})
if not presign_res.ok:
	print(f"Error fetching upload URL: {presign_res.status_code}, {presign_res.reason}: {presign_res.text}")
	exit(1)

presign_body = presign_res.json()
upload_url = presign_body.get("PreSignedUploadUrl")
if not upload_url:
	print("No presigned upload URL returned.")
	exit(1)

print("Uploading file...")
with open(file_path, "rb") as f:
	upload_res = requests.put(upload_url, data=f)
if not upload_res.ok:
	print(f"Upload failed: {upload_res.status_code}, {upload_res.reason}")
else:
	print("File uploaded successfully.")

Paginación

Los endpoints de lista aceptan los parámetros de consulta limit y offset y devuelven un array JSON sin envoltorio (sin envoltorio ni recuento total):

GET /v1/tenant/{tenantId}/processes?limit=50&offset=100

Para recorrer todas las páginas, siga realizando solicitudes con offset += limit hasta que el array de respuesta tenga menos elementos que el valor solicitado en limit (o esté vacío). Los valores superiores al máximo se rechazan con 400. Los endpoints de datos versionados (conjuntos de datos, versiones y webhooks) siguen la misma convención, y las dos listas de tablas de datos limitan limit a 250.

Versionado y obsolescencia

• Todas las rutas están versionadas bajo /v1; los cambios incompatibles se publican en una nueva versión, en lugar de modificar /v1 sin aviso.
• Los cambios y las eliminaciones de rutas se anuncian en las notas de la versión.
• Los cambios importantes que afectan a los clientes siempre se incluyen en el registro de cambios. Suscríbase o consúltelo antes de actualizar los clientes de API fijados a una versión.

Próximos pasos

• Referencia de la API: documentación completa de todos los endpoints y sus formatos de solicitud y respuesta
• Ejemplos en GitHub: ejemplos descargables y bibliotecas de cliente
• Obtener su clave de API: cómo obtener y administrar su clave de API