Visão geral da API

Como fazer chamadas à API do ProcessMind

Este guia apresenta exemplos e práticas recomendadas para chamar a API do ProcessMind e recuperar dados, enviar informações ou automatizar fluxos de trabalho.

Para consultar a documentação completa dos endpoints, com os formatos de solicitação e resposta, acesse a Referência da API.

Para ver mais exemplos e bibliotecas de cliente, acesse a documentação da API no GitHub.

URL base da API

Todas as solicitações à API devem ser feitas para:

https://api.processmind.com

Todas as rotas são versionadas em /v1. A especificação completa da API em formato legível por máquina (OpenAPI 3.1) está disponível em:

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

Autenticação

Todas as solicitações à API exigem sua chave de API no cabeçalho x-api-key, exceto o documento público OpenAPI (/v1/openapi.json) e os endpoints MCP OAuth:

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

Você encontra a chave de API nas configurações da sua conta ProcessMind. Consulte Como obter sua chave de API para ver as instruções.

Códigos de status

A API do ProcessMind segue os códigos de status HTTP padrão:

Conceitos principais

• apiKey: token de autenticação para todas as solicitações à API.
• tenantId: identifica o contexto do seu espaço de trabalho ou organização. Você encontra esse valor nas configurações da conta.
• datatableId: identifica uma tabela de dados específica para operações com dados. Você encontra esse valor na opção Obter ID da tabela de dados, no menu de configurações do conjunto de dados do ProcessMind.

O que você pode fazer

A API do ProcessMind permite que você:

• Gerencie ambientes: consulte informações do ambiente, atualize configurações e veja estatísticas
• Gerencie usuários: adicione, atualize ou remova usuários de ambientes e organizações
• Gerencie processos: crie processos, carregue modelos BPMN e organize-os em pastas
• Conecte dados: mapeie tabelas de dados para processos para análise
• Carregue dados: carregue arquivos CSV/XLSX diretamente nas tabelas de dados
• Gerencie conjuntos de dados: liste, consulte e exclua conjuntos de dados e tabelas de dados

Exemplos comuns

A seguir, você encontra exemplos práticos de operações comuns com a API do ProcessMind.

Como obter uma URL de carregamento pré-assinada

Para carregar um arquivo em uma tabela de dados, primeiro obtenha uma URL pré-assinada:

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

Listar conjuntos de dados

Recupere todos os conjuntos de dados do seu ambiente:

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

Obter informações do ambiente

Recupere os detalhes do seu ambiente:

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

Criar um processo

Crie um processo no seu ambiente:

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

Carregar um modelo BPMN

Carregue um arquivo BPMN para definir o modelo do processo:

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

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

Mapear dados para um processo

Conecte uma tabela de dados a um processo para análise:

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

Adicionar um usuário a um ambiente

Adicione um usuário ao seu ambiente:

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

Observação: os campos de função no corpo (isAdminInTenant, access, isDashboardViewer) são respeitados exatamente como enviados. Os endpoints de gerenciamento de usuários oferecem controle administrativo completo do ambiente. Por isso, emita chaves de API com permissão de gravação apenas para quem você confia para administrar o ambiente. A API do sistema não envia e-mails de convite. Você é responsável por integrar o usuário.

Carregar arquivos

O processo geral para carregar um arquivo no ProcessMind é:

1. Obtenha uma URL pré-assinada usando a chamada getPresignedUploadUrl.
2. Faça uma solicitação PUT para essa URL com o conteúdo do arquivo.
3. A URL pré-assinada autoriza o carregamento diretamente no armazenamento em nuvem, sem precisar de credenciais adicionais.

Veja um exemplo simplificado usando 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
	});
}

Exemplos completos

A seguir, você encontra exemplos completos, prontos para copiar e colar, em diferentes linguagens.

Exemplo em Bash: carregar um arquivo

Script Bash mínimo para carregar um arquivo no ProcessMind usando duas chamadas curl, com espaços reservados para todos os 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>" "{}"

Exemplo em Node.js: carregar um arquivo CSV local

Carrega um arquivo CSV local no ProcessMind usando uma URL pré-assinada.

Etapas:

1. Obtenha uma URL de carregamento pré-assinada pela API.
2. Leia o arquivo local do disco.
3. Carregue o arquivo na URL pré-assinada usando HTTP PUT.

Configuração:

• Informe sua chave de API, tenantId, datatableId e filePath ao chamar uploadFile().
• A URL base da API está definida 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 
};

Exemplo em Python: carregar um arquivo CSV local

Carrega um arquivo CSV local em uma API remota usando uma URL pré-assinada.

Etapas:

1. Obtenha uma URL de carregamento pré-assinada pela API.
2. Leia o arquivo local do disco.
3. Carregue o arquivo na URL pré-assinada usando HTTP PUT.

Configuração:

• Atualize api_key, tenant_id, datatable_id e file_path conforme necessário.

"""
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.")

Paginação

Os endpoints de listagem aceitam os parâmetros de consulta limit e offset e retornam um **array JSON simples **, sem envelope nem contagem total:

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

Para percorrer todos os resultados, continue fazendo solicitações com offset += limit até que o array da resposta tenha menos itens do que o valor solicitado em limit (ou esteja vazio). Valores acima do máximo são rejeitados com 400. Os endpoints de dados versionados (conjuntos de dados, versões e webhooks) seguem a mesma convenção, e as duas listas de tabelas de dados limitam limit a 250.

Versionamento e descontinuação

• Todas as rotas são versionadas em /v1. Alterações incompatíveis são lançadas em uma nova versão, em vez de modificar /v1 sem aviso.
• As alterações e remoções de rotas são anunciadas nas notas da versão.
• As principais alterações visíveis para clientes são sempre listadas no changelog. Inscreva-se para receber atualizações ou consulte-o antes de atualizar clientes da API com versão fixada.

Próximas etapas

• Referência da API: documentação completa de todos os endpoints, com formatos de solicitação e resposta
• Exemplos no GitHub: exemplos para baixar e bibliotecas de cliente
• Como obter sua chave de API: como obter e gerenciar sua chave de API