Descripción general de la API

Cómo realizar llamadas a la API de ProcessMind

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

Para consultar la documentación completa de los endpoints, incluidos los formatos de solicitud y respuesta, consulte la Referencia de la API.

Para obtener más ejemplos y bibliotecas de cliente, visite 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 utilizan el versionado /v1. La especificación completa de la API en un formato legible por máquinas, 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:

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

Puede obtener la clave de API en la configuración de su cuenta de ProcessMind. Consulte Cómo obtener su clave de API para conocer las instrucciones.

Códigos de estado

La API de ProcessMind utiliza 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. Se encuentra en la configuración de su cuenta.
• datatableId: identifica una tabla de datos concreta para las operaciones con datos. Está disponible en la opción Obtener ID de tabla de datos del menú de configuración del conjunto de datos en ProcessMind.

Qué puede hacer

La API de ProcessMind le permite:

• Gestionar inquilinos: recuperar información del inquilino, actualizar la configuración y consultar estadísticas
• Gestionar usuarios: añadir, actualizar o eliminar usuarios de inquilinos y organizaciones
• Gestionar procesos: crear procesos, cargar modelos BPMN y organizarlos en carpetas
• Conectar datos: asignar tablas de datos a procesos para su análisis
• Cargar datos: cargar archivos CSV/XLSX directamente en tablas de datos
• Gestionar conjuntos de datos: enumerar, inspeccionar y eliminar conjuntos de datos y tablas de datos

Ejemplos habituales

A continuación se muestran 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, obtenga primero una URL prefirmada:

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

Enumerar 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 nuevo 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 su 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 analizarlo:

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 literalmente. Los endpoints de gestión de usuarios ofrecen una superficie completa de administración del inquilino, por lo que solo debe emitir claves de API con permisos de escritura a personas en quienes confíe para ejercer el control administrativo. La System API no envía ningún correo electrónico de invitación; usted es responsable de incorporar al usuario.

Cargar archivos

El flujo 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 se incluyen 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 del disco.
3. Cargue el archivo en la URL prefirmada mediante HTTP PUT.

Configuración:

• Proporcione su clave de API, tenantId, datatableId y filePath al llamar a uploadFile().
• La URL base de la API está establecida en 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 del 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 una matriz JSON sin envoltorio, sin envoltorio ni recuento total:

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

Para recorrer todos los resultados por páginas, siga realizando solicitudes con offset += limit hasta que la matriz de respuesta sea más corta que el limit solicitado o esté vacía. Los valores superiores al máximo se rechazan con 400. Los endpoints de datos versionados, como conjuntos de datos, tablas de datos, versiones y webhooks, siguen la misma convención.

Versionado y obsolescencia

• Todas las rutas utilizan el versionado /v1; los cambios incompatibles se publican en una versión nueva en lugar de modificar silenciosamente /v1.
• Las obsolescencias se anuncian en el registro de cambios y en esta página al menos 6 meses antes de retirar una ruta, y las rutas obsoletas siguen funcionando durante ese periodo.
• Las respuestas de las rutas obsoletas incluyen un encabezado Sunset con la fecha de retirada, y Deprecation: true.
• Los cambios importantes visibles para el cliente siempre aparecen en el registro de cambios; suscríbase o vuelva a consultar la página antes de actualizar clientes de API con versiones fijadas.

Próximos pasos

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