Visão Geral da API

Como Fazer Chamadas de API para o ProcessMind

Este guia traz exemplos e boas práticas para realizar chamadas à API dos serviços do ProcessMind. Seja para acessar dados, enviar informações ou automatizar workflows, saber como integrar com nossa API é fundamental.

Para a documentação completa dos endpoints com formatos de request/response, acesse a Referência da API.

Para exemplos extra e bibliotecas cliente, consulte nossa Documentação da API no GitHub.

URL Base da API

Todas as requisições para a API devem ser feitas em:

https://api.processmind.com

Autenticação

Todas as requisições para a API exigem a sua API key no header x-api-key:

x-api-key: sua-api-key-aqui

A API key pode ser obtida nas configurações da sua conta ProcessMind. Veja como conseguir em Como obter sua API Key.

Conceitos-Chave

• apiKey – Seu token de autenticação para todas chamadas da API.
• tenantId – Identifica o workspace/contexto da sua organização. Você encontra nas configurações da conta.
• datatableId – Identifica uma datatable específica para operações de dados. Localize no menu de configurações do dataset em [Get Data Table ID] dentro do ProcessMind.

O que Você Pode Fazer

A API do ProcessMind permite:

• Gerenciar Tenants – Consultar informações, atualizar configurações e visualizar estatísticas
• Gerenciar Usuários – Adicionar, atualizar ou remover usuários de tenants e organizações
• Gerenciar Processos – Criar processos, enviar modelos BPMN e organizar em pastas
• Conectar Dados – Mapear datatables a processos para análises
• Fazer Upload de Dados – Enviar arquivos CSV/XLSX direto para datatables
• Gerenciar Datasets – Listar, inspecionar e excluir datasets e datatables

Exemplos Comuns

Veja abaixo exemplos práticos de como realizar operações comuns utilizando a API do ProcessMind.

Obtendo uma Presigned Upload URL

Para fazer upload de um arquivo em uma datatable, obtenha antes uma presigned URL:

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

Listando Datasets

Recupere todos os datasets do seu tenant:

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

Consultando Informações do Tenant

Recupere informações sobre seu tenant:

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

Criando um Processo

Crie um novo processo no seu tenant:

const process = await createProcess({
	apiKey,
	tenantId: "tenant-123",
	displayName: "Order to Cash"
});
console.log(process.id); // Utilize este ID para outras operações

Enviando um Modelo BPMN

Faça upload de um arquivo BPMN para definir o modelo do seu 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 em um Processo

Conecte uma datatable 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 Usuário no Tenant

Inclua um usuário em seu tenant:

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

Upload de Arquivos

O fluxo básico para fazer upload de um arquivo no ProcessMind é:

1. Obtenha uma URL presigned utilizando a função getPresignedUploadUrl.
2. Realize uma requisição PUT para essa URL com o conteúdo do arquivo.
3. A URL presigned autoriza o upload direto para o cloud storage – não é necessário informar outras credenciais.

Veja um exemplo simplificado utilizando fetch:

async function uploadFile({ apiKey, tenantId, datatableId, file }) {
	// Passo 1: Obter uma URL presigned
	const uploadUrl = await getPresignedUploadUrl({ apiKey, tenantId, datatableId });
	
	// Passo 2: Realizar o upload via PUT
	await fetch(uploadUrl, {
		method: "PUT",
		headers: {
			"Content-Type": file.type
		},
		body: file
	});
}

Exemplos Completos

Confira exemplos completos, prontos para copiar e colar, em diferentes linguagens.

Exemplo em Bash: Upload de Arquivo

Script Bash simples para subir um arquivo no ProcessMind usando dois comandos curl, com espaços para todos os valores.

#!/bin/bash
# Script Bash simples para enviar um arquivo ao ProcessMind usando dois comandos curl, com placeholders para todos os valores

# Substitua os placeholders abaixo pelos seus valores reais:
# <API_KEY>, <TENANT_ID>, <DATATABLE_ID>, <FILE_PATH>

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

Exemplo Node.js: Upload de CSV Local

Faz upload de arquivo CSV local no ProcessMind via presigned URL.

Passos:

1. Busque a presigned upload URL na API.
2. Leia o arquivo do disco.
3. Envie o arquivo via HTTP PUT para a URL.

Configuração:

• Informe API key, tenantId, datatableId e filePath ao rodar uploadFileToProcessMind().
• A URL base da API é https://api.processmind.com

/**
 * Faz upload de um arquivo CSV local para o ProcessMind usando uma URL pré-assinada.
 *
 * Passos:
 * 1. Busque uma URL pré-assinada de upload na API.
 * 2. Leia o arquivo local do disco.
 * 3. Faça o upload pela URL pré-assinada usando HTTP PUT.
 *
 * Configuração:
 * - Informe sua API key, tenantId, datatableId e filePath ao usar uploadFileToProcessMind().
 * - A URL base da API é https://api.processmind.com
 */

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

/**
 * Faz upload de um arquivo para a datatable do ProcessMind via URL pré-assinada.
 * @param {string} apiKey - Sua API key para autenticação.
 * @param {string} tenantId - Id. do tenant.
 * @param {string} datatableId - Id. da datatable.
 * @param {string} filePath - Caminho do arquivo para 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(`Erro ao acessar a API: ${response.status}, ${response.statusText}: ${body.message}`);
            return;
        }
        return body;
    } catch (err) {
        console.error("Erro inesperado:", err);
    }
}

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

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

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

async function getOrganization({apiKey, tenantId, apiUrl = "https://api.processmind.com"}) {
	return await getApi({apiKey, path: `/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("Enviando arquivo...");
        fs.readFile(filePath, async (err, data) => {
            if (err) {
                console.error("Erro ao ler o arquivo:", err);
                return;
            }
            try {
                const uploadRes = await fetch(uploadUrl, {
                    method: "PUT",
                    body: data
                });
                if (!uploadRes.ok) {
                    console.error("Falha no upload:", uploadRes.status, uploadRes.statusText);
                } else {
                    console.log("Arquivo enviado com sucesso.");
                }
            } catch (uploadErr) {
                console.error("Erro ao enviar arquivo:", uploadErr);
            }
        });
    } catch (err) {
        console.error("Erro inesperado:", err);
    }
}

// Exporta as funções para uso em outros módulos
module.exports = { 
	getPresignedUploadUrl,
	getDatasets,
	getTenant,
	getOrganization,
	uploadFile 
};

Exemplo Python: Upload de CSV Local

Faz upload de um arquivo CSV local para a API usando uma presigned URL.

Passos:

1. Obtenha a presigned upload URL pela API.
2. Leia o arquivo local no disco.
3. Faça upload para a URL usando HTTP PUT.

Configuração:

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

"""
Envia um arquivo CSV local para uma API remota usando uma URL pré-assinada.

Passos:
1. Busque uma URL pré-assinada de upload na API.
2. Leia o arquivo local do disco.
3. Faça upload pela URL pré-assinada usando HTTP PUT.

Configuração:
- Atualize api_key, tenant_id, datatable_id e file_path conforme necessário.
"""

import requests

# === Configuração ===
api_key = ""  # API key para autenticação
tenant_id = ""  # Identificador do tenant
datatable_id = ""  # Identificador da datatable
file_path = ""  # Caminho do arquivo para upload


print("Buscando URL de upload...")
api_url = "https://api.processmind.com"  # URL base da API
presign_url = f"{api_url}/tenant/{tenant_id}/datatable/{datatable_id}/uploads/presignedurl"
presign_res = requests.get(presign_url, headers={"x-api-key": api_key})
if not presign_res.ok:
	print(f"Erro ao buscar URL de upload: {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("Nenhuma Presigned Upload URL retornada.")
	exit(1)

print("Fazendo upload do arquivo...")
with open(file_path, "rb") as f:
	upload_res = requests.put(upload_url, data=f)
if not upload_res.ok:
	print(f"Falha no upload: {upload_res.status_code}, {upload_res.reason}")
else:
	print("Upload realizado com sucesso.")

Próximos Passos

• Referência da API – Documentação completa dos endpoints com exemplos de request/response
• Exemplos no GitHub – Exemplos práticos para download e bibliotecas cliente
• Como obter sua API Key – Veja como obter e gerenciar sua API key