Ringkasan API

Cara melakukan panggilan API ke ProcessMind

Panduan ini berisi contoh dan praktik terbaik untuk memanggil API ProcessMind guna mengambil data, mengirimkan informasi, atau mengotomatiskan workflow.

Untuk dokumentasi endpoint lengkap beserta format permintaan dan respons, lihat Referensi API.

Untuk contoh tambahan dan pustaka klien, kunjungi Dokumentasi API di GitHub.

URL dasar API

Kirim semua permintaan API ke:

https://api.processmind.com

Semua rute menggunakan versi di bawah /v1. Spesifikasi API lengkap yang dapat dibaca mesin (OpenAPI 3.1) tersedia di:

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

Autentikasi

Semua permintaan API harus menyertakan kunci API di header x-api-key, kecuali dokumen OpenAPI publik (/v1/openapi.json) dan endpoint OAuth MCP:

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

Kunci API dapat diperoleh dari pengaturan akun ProcessMind Anda. Lihat Mendapatkan kunci API untuk petunjuknya.

Kode status

API ProcessMind menggunakan kode status HTTP standar:

Konsep utama

• apiKey: Token autentikasi untuk semua permintaan API.
• tenantId: Menentukan konteks ruang kerja atau organisasi Anda. Nilai ini tersedia di pengaturan akun.
• datatableId: Menentukan datatable tertentu untuk operasi data. Nilai ini tersedia melalui opsi Dapatkan ID Tabel Data di menu pengaturan dataset dalam ProcessMind.

Hal yang dapat Anda lakukan

API ProcessMind memungkinkan Anda untuk:

• Mengelola tenant: Mengambil informasi tenant, memperbarui pengaturan, dan melihat statistik
• Mengelola pengguna: Menambahkan, memperbarui, atau menghapus pengguna dari tenant dan organisasi
• Mengelola proses: Membuat proses, mengunggah model BPMN, dan mengaturnya dalam folder
• Menghubungkan data: Memetakan datatable ke proses untuk dianalisis
• Mengunggah data: Mengunggah file CSV/XLSX langsung ke datatable
• Mengelola dataset: Melihat daftar, memeriksa, dan menghapus dataset serta datatable

Contoh umum

Berikut beberapa contoh praktis untuk menjalankan operasi umum dengan API ProcessMind.

Mendapatkan URL unggah bertanda tangan

Untuk mengunggah file ke datatable, dapatkan URL bertanda tangan terlebih dahulu:

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

Melihat daftar dataset

Ambil semua dataset di tenant Anda:

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

Mendapatkan informasi tenant

Ambil detail tenant Anda:

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

Membuat proses

Buat proses baru di tenant Anda:

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

Mengunggah model BPMN

Unggah file BPMN untuk menentukan model proses Anda:

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

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

Memetakan data ke proses

Hubungkan datatable ke proses untuk dianalisis:

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

Menambahkan pengguna ke tenant

Tambahkan pengguna ke tenant Anda:

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

Catatan: Kolom peran dalam isi permintaan (isAdminInTenant, access, isDashboardViewer) digunakan persis seperti yang diberikan. Endpoint manajemen pengguna menyediakan akses penuh sebagai admin tenant. Karena itu, berikan kunci API dengan cakupan tulis hanya kepada pemanggil yang Anda percayai untuk mengelola administrasi. System API tidak mengirim email undangan. Anda bertanggung jawab untuk menyiapkan pengguna tersebut.

Mengunggah file

Berikut alur umum untuk mengunggah file ke ProcessMind:

1. Dapatkan URL bertanda tangan menggunakan panggilan getPresignedUploadUrl.
2. Kirim permintaan PUT ke URL tersebut dengan isi file.
3. URL bertanda tangan memberi izin untuk mengunggah langsung ke penyimpanan cloud. Kredensial tambahan tidak diperlukan.

Berikut contoh sederhana menggunakan 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
	});
}

Contoh lengkap

Berikut contoh lengkap dalam berbagai bahasa pemrograman yang siap disalin dan dijalankan.

Contoh Bash: mengunggah file

Skrip Bash sederhana untuk mengunggah file ke ProcessMind menggunakan dua panggilan curl, dengan placeholder untuk semua nilai

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

Contoh Node.js: mengunggah file CSV lokal

Mengunggah file CSV lokal ke ProcessMind menggunakan URL bertanda tangan.

Langkah-langkah:

1. Ambil URL unggah bertanda tangan dari API.
2. Baca file lokal dari disk.
3. Unggah file ke URL bertanda tangan menggunakan HTTP PUT.

Konfigurasi:

• Saat memanggil uploadFile(), berikan kunci API, tenantId, datatableId, dan filePath Anda.
• URL dasar API ditetapkan ke 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 
};

Contoh Python: mengunggah file CSV lokal

Mengunggah file CSV lokal ke API jarak jauh menggunakan URL bertanda tangan.

Langkah-langkah:

1. Ambil URL unggah bertanda tangan dari API.
2. Baca file lokal dari disk.
3. Unggah file ke URL bertanda tangan menggunakan HTTP PUT.

Konfigurasi:

• Perbarui api_key, tenant_id, datatable_id, dan file_path sesuai kebutuhan.

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

Paginasi

Endpoint daftar menerima parameter kueri limit dan offset, lalu mengembalikan array JSON langsung (tanpa pembungkus dan tanpa jumlah total):

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

Untuk menelusuri semua halaman, terus kirim permintaan dengan offset += limit sampai array respons lebih pendek daripada nilai limit yang diminta (atau kosong). Nilai yang melebihi batas maksimum akan ditolak dengan 400. Endpoint data berversi (dataset, versi, webhook) menggunakan aturan yang sama. Batas untuk kedua daftar datatable adalah limit250.

Pembuatan versi dan penghentian dukungan

• Semua rute menggunakan versi di bawah /v1. Perubahan yang tidak kompatibel dirilis dalam versi baru, bukan mengubah /v1 tanpa pemberitahuan.
• Perubahan dan penghapusan rute diumumkan dalam catatan rilis.
• Perubahan besar yang terlihat oleh klien selalu dicantumkan di changelog. Berlangganan pembaruan atau periksa kembali sebelum memperbarui klien API yang versinya dikunci.

Langkah berikutnya

• Referensi API: Dokumentasi lengkap semua endpoint, termasuk format permintaan dan respons
• Contoh di GitHub: Contoh yang dapat diunduh dan pustaka klien
• Mendapatkan API key: Cara mendapatkan dan mengelola API key Anda