Přehled API

Volání API ProcessMind

Tento průvodce obsahuje příklady a doporučené postupy pro volání API ProcessMind. Pomocí API můžete načítat data, odesílat informace nebo automatizovat workflow.

Úplný přehled endpointů včetně formátů požadavků a odpovědí najdete v referenci API.

Další příklady a klientské knihovny najdete v dokumentaci API na GitHubu.

Základní URL API

Všechny požadavky API odesílejte na:

https://api.processmind.com

Všechny cesty jsou verzované pod /v1. Úplná strojově čitelná specifikace API (OpenAPI 3.1) je k dispozici na adrese:

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

Ověřování

Všechny požadavky API musí obsahovat váš API klíč v hlavičce x-api-key. Výjimkou je veřejný dokument OpenAPI (/v1/openapi.json) a endpointy MCP OAuth:

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

API klíč najdete v nastavení účtu ProcessMind. Pokyny najdete v části Jak získat API klíč.

Stavové kódy

API ProcessMind používá standardní stavové kódy HTTP:

Základní pojmy

• apiKey: Ověřovací token pro všechny požadavky API.
• tenantId: Určuje kontext vašeho pracovního prostoru nebo organizace. Najdete ho v nastavení účtu.
• datatableId: Určuje konkrétní datovou tabulku pro práci s daty. Najdete ho v nastavení datové sady v ProcessMind pod možností Získat ID datové tabulky.

Co můžete dělat

Pomocí API ProcessMind můžete:

• Spravovat tenanty: Načítat informace o tenantech, měnit nastavení a zobrazovat statistiky
• Spravovat uživatele: Přidávat, upravovat a odebírat uživatele z tenantů a organizací
• Spravovat procesy: Vytvářet procesy, nahrávat modely BPMN a organizovat je do složek
• Propojovat data: Mapovat datové tabulky na procesy pro analýzu
• Nahrávat data: Nahrávat soubory CSV/XLSX přímo do datových tabulek
• Spravovat datové sady: Zobrazovat, kontrolovat a odstraňovat datové sady a datové tabulky

Běžné příklady

Níže najdete praktické příklady běžných operací s API ProcessMind.

Získání předem podepsané URL pro nahrání

Chcete-li nahrát soubor do datové tabulky, nejprve získejte předem podepsanou URL:

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

Výpis datových sad

Načtěte všechny datové sady ve svém tenantu:

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

Získání informací o tenantu

Načtěte podrobnosti o svém tenantu:

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

Vytvoření procesu

Vytvořte nový proces ve svém tenantu:

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

Nahrání modelu BPMN

Nahrajte soubor BPMN a definujte model procesu:

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

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

Mapování dat na proces

Propojte datovou tabulku s procesem pro analýzu:

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

Přidání uživatele do tenantu

Přidejte uživatele do svého tenantu:

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

Poznámka: Pole rolí v těle požadavku (isAdminInTenant, access, isDashboardViewer) se použijí přesně tak, jak jsou zadaná. Endpointy pro správu uživatelů poskytují úplný přístup správce tenantu. Proto vydávejte API klíče s oprávněním k zápisu pouze volajícím, kterým důvěřujete a chcete jim svěřit správu. Systémové API neodesílá pozvánky e-mailem. Za uvedení uživatele do systému odpovídáte vy.

Nahrávání souborů

Soubor nahrajete do ProcessMind takto:

1. Pomocí volání getPresignedUploadUrl získejte předem podepsanou URL.
2. Odešlete na tuto URL požadavek PUT s obsahem souboru.
3. Předem podepsaná URL umožňuje nahrát soubor přímo do cloudového úložiště. Další přihlašovací údaje nejsou potřeba.

Zjednodušený příklad s použitím 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
	});
}

Úplné příklady

Níže najdete úplné příklady v různých jazycích, které můžete rovnou zkopírovat a spustit.

Příklad v Bash: nahrání souboru

Jednoduchý skript Bash nahraje soubor do ProcessMind pomocí dvou volání curl. Všechny hodnoty jsou nahrazené zástupnými symboly.

#!/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>" "{}"

Příklad v Node.js: nahrání místního souboru CSV

Nahraje místní soubor CSV do ProcessMind pomocí předem podepsané URL.

Postup:

1. Získejte z API předem podepsanou URL pro nahrání.
2. Načtěte místní soubor z disku.
3. Nahrajte soubor na předem podepsanou URL pomocí HTTP PUT.

Nastavení:

• Při volání funkce uploadFile() zadejte svůj API klíč, tenantId, datatableId a filePath.
• Základní URL API je nastavena na 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 
};

Příklad v Pythonu: nahrání místního souboru CSV

Nahraje místní soubor CSV do vzdáleného API pomocí předem podepsané URL.

Postup:

1. Získejte z API předem podepsanou URL pro nahrání.
2. Načtěte místní soubor z disku.
3. Nahrajte soubor na předem podepsanou URL pomocí HTTP PUT.

Nastavení:

• Podle potřeby upravte api_key, tenant_id, datatable_id a file_path.

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

Stránkování

Endpointy pro výpis přijímají parametry dotazu limit a offset a vracejí prosté pole JSON (bez obálky a celkového počtu):

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

Chcete-li projít všechny výsledky po stránkách, opakujte požadavek s hodnotou offset += limit, dokud pole v odpovědi nebude kratší než požadovaná hodnota limit nebo prázdné. Hodnoty nad maximem jsou odmítnuty chybou 400. Verzované datové endpointy (datasets, versions, webhooks) používají stejný postup. U dvou seznamů datových tabulek je maximum limit 250.

Verzování a ukončení podpory

• Všechny trasy jsou verzované pod /v1. Změny, které nejsou zpětně kompatibilní, vydáváme v nové verzi, místo abychom potichu měnili /v1.
• Změny tras a jejich odstranění oznamujeme v poznámkách k vydání.
• Změny, které mají dopad na klienty, vždy uvádíme v changelogu. Před aktualizací klientů API s pevně nastavenou verzí se přihlaste k odběru novinek nebo si changelog zkontrolujte.

Další kroky

• Reference API: dokumentace všech endpointů včetně formátů požadavků a odpovědí
• Příklady na GitHubu: příklady ke stažení a klientské knihovny
• Jak získat API key: postup pro získání a správu API key