Visão geral da API

Como fazer chamadas de API para a ProcessMind

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

Para consultar a documentação completa dos endpoints, com formatos de requisição e resposta, veja 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 requisiçõ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 requisições à API exigem sua chave de API no cabeçalho x-api-key:

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

A chave de API pode ser obtida 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 da ProcessMind segue os códigos de status HTTP padrão:

Conceitos principais

• apiKey: seu token de autenticação para todas as requisições à API.
• tenantId: identifica o contexto do seu espaço de trabalho ou organização. Está disponível nas configurações da sua conta.
• datatableId: identifica uma tabela de dados específica para operações com dados. Está disponível na opção Obter ID da tabela de dados, no menu de configurações do conjunto de dados dentro da ProcessMind.

O que você pode fazer

A API da ProcessMind permite que você:

• Gerencie ambientes: recupere 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, inspecione e exclua conjuntos de dados e tabelas de dados

Exemplos comuns

A seguir, veja exemplos práticos de como executar operações comuns com a API da ProcessMind.

Obtendo 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=…

Listando conjuntos de dados

Recupere todos os conjuntos de dados do seu ambiente:

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

Obtendo informações do ambiente

Recupere os detalhes do seu ambiente:

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

Criando um processo

Crie um novo 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

Carregando um modelo BPMN

Carregue um arquivo BPMN para definir seu modelo de processo:

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

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

Mapeando 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
});

Adicionando 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 considerados exatamente como enviados. Os endpoints de gerenciamento de usuários oferecem uma superfície completa de administração do ambiente, portanto emita chaves de API com escopo de gravação somente para pessoas em quem você confia para exercer controle administrativo. A System API não envia e-mail de convite; você é responsável por integrar o usuário.

Carregando arquivos

O fluxo geral para carregar um arquivo na ProcessMind é:

1. Obtenha uma URL pré-assinada usando a chamada getPresignedUploadUrl.
2. Faça uma requisição PUT para essa URL com o conteúdo do arquivo.
3. A URL pré-assinada autoriza o carregamento diretamente no armazenamento em nuvem; não são necessárias 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, veja exemplos completos, prontos para copiar e colar, em diferentes linguagens.

Exemplo em Bash: carregando um arquivo

Script Bash mínimo para carregar um arquivo na ProcessMind usando duas chamadas curl, com placeholders 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: carregando um arquivo CSV local

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

Etapas:

1. Obtenha uma URL de carregamento pré-assinada da 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: carregando 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 da 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 e sem contagem total:

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

Para paginar todos os resultados, continue fazendo requisições com offset += limit até que o array de resposta seja menor que o limit solicitado ou esteja vazio. Valores acima do máximo são rejeitados com 400. Os endpoints de dados versionados, conjuntos de dados, tabelas de dados, versões e webhooks, seguem a mesma convenção.

Versionamento e descontinuação

• Todas as rotas são versionadas em /v1; mudanças incompatíveis são lançadas em uma nova versão em vez de alterar silenciosamente /v1.
• As descontinuações são anunciadas no changelog e nesta página pelo menos 6 meses antes da remoção de uma rota, e as rotas descontinuadas continuam funcionando durante esse período.
• As respostas das rotas descontinuadas incluem um cabeçalho Sunset com a data de remoção, e Deprecation: true.
• As principais mudanças visíveis para o cliente são sempre listadas no changelog; assine as atualizações ou consulte a página novamente antes de atualizar clientes da API com versões fixadas.

Próximos passos

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