Tổng quan về API

Cách gọi API ProcessMind

Hướng dẫn này cung cấp ví dụ và cách làm nên áp dụng khi gọi API ProcessMind để lấy dữ liệu, gửi thông tin hoặc tự động hóa quy trình làm việc.

Xem Tài liệu tham khảo API để biết đầy đủ các endpoint cùng định dạng yêu cầu và phản hồi.

Xem thêm ví dụ và thư viện client tại Tài liệu API trên GitHub.

URL cơ sở của API

Gửi tất cả yêu cầu API đến địa chỉ sau:

https://api.processmind.com

Tất cả route đều được đánh phiên bản dưới /v1. Bản đặc tả API đầy đủ, có thể đọc bằng máy (OpenAPI 3.1), có tại:

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

Xác thực

Mọi yêu cầu API đều cần API key trong x-api-key, ngoại trừ tài liệu OpenAPI công khai (/v1/openapi.json) và các endpoint MCP OAuth:

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

Bạn có thể lấy API key trong phần cài đặt tài khoản ProcessMind. Xem hướng dẫn tại Lấy API key.

Mã trạng thái

API của ProcessMind sử dụng các mã trạng thái HTTP tiêu chuẩn:

Các khái niệm chính

• apiKey: Mã xác thực dùng cho mọi yêu cầu API.
• tenantId: Xác định không gian làm việc hoặc tổ chức của bạn. Bạn có thể tìm thấy mã này trong phần cài đặt tài khoản.
• datatableId: Xác định một bảng dữ liệu cụ thể để thao tác với dữ liệu. Bạn có thể lấy mã này từ tùy chọn Lấy mã bảng dữ liệu trong menu cài đặt tập dữ liệu của ProcessMind.

Bạn có thể làm gì

API ProcessMind cho phép bạn:

• Quản lý tenant: Lấy thông tin tenant, cập nhật cài đặt và xem số liệu thống kê
• Quản lý người dùng: Thêm, cập nhật hoặc xóa người dùng khỏi tenant và tổ chức
• Quản lý quy trình: Tạo quy trình, tải mô hình BPMN lên và sắp xếp vào thư mục
• Kết nối dữ liệu: Ánh xạ bảng dữ liệu vào quy trình để phân tích
• Tải dữ liệu lên: Tải trực tiếp tệp CSV/XLSX vào bảng dữ liệu
• Quản lý tập dữ liệu: Liệt kê, kiểm tra và xóa tập dữ liệu cùng bảng dữ liệu

Ví dụ thường gặp

Dưới đây là các ví dụ thiết thực về cách thực hiện những thao tác thường gặp bằng API ProcessMind.

Lấy URL tải lên có chữ ký

Để tải tệp lên bảng dữ liệu, trước tiên hãy lấy URL có chữ ký:

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

Liệt kê tập dữ liệu

Lấy tất cả tập dữ liệu trong tenant của bạn:

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

Lấy thông tin tenant

Lấy thông tin chi tiết về tenant của bạn:

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

Tạo quy trình

Tạo quy trình mới trong tenant của bạn:

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

Tải mô hình BPMN lên

Tải tệp BPMN lên để xác định mô hình quy trình:

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

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

Ánh xạ dữ liệu vào quy trình

Kết nối bảng dữ liệu với quy trình để phân tích:

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

Thêm người dùng vào tenant

Thêm người dùng vào tenant của bạn:

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

Lưu ý: Các trường vai trò trong nội dung yêu cầu (isAdminInTenant, access, isDashboardViewer) được giữ nguyên như đã gửi. Các endpoint quản lý người dùng cung cấp đầy đủ quyền quản trị tenant, vì vậy chỉ cấp API key có quyền ghi cho những bên bạn tin tưởng giao quyền quản trị. System API không gửi email mời người dùng; bạn cần tự thực hiện quy trình tiếp nhận người dùng.

Tải tệp lên

Quy trình chung để tải tệp lên ProcessMind như sau:

1. Lấy URL có chữ ký bằng lệnh gọi getPresignedUploadUrl.
2. Gửi yêu cầu PUT đến URL đó cùng nội dung tệp.
3. URL có chữ ký cho phép tải tệp trực tiếp lên bộ nhớ đám mây, không cần thông tin xác thực bổ sung.

Dưới đây là ví dụ đơn giản dùng 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
	});
}

Ví dụ đầy đủ

Dưới đây là các ví dụ hoàn chỉnh, có thể sao chép và chạy ngay, bằng nhiều ngôn ngữ khác nhau.

Ví dụ Bash: tải tệp lên

Tập lệnh Bash tối giản để tải tệp lên ProcessMind bằng hai lệnh curl, với chỗ giữ chỗ cho mọi giá trị

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

Ví dụ Node.js: tải tệp CSV trên máy lên

Tải tệp CSV trên máy lên ProcessMind bằng URL có chữ ký.

Các bước:

1. Lấy URL tải lên có chữ ký từ API.
2. Đọc tệp trên máy từ ổ đĩa.
3. Tải tệp lên URL có chữ ký bằng HTTP PUT.

Cấu hình:

• Khi gọi uploadFile(), hãy cung cấp API key, tenantId, datatableId và filePath.
• URL cơ sở của API được đặt thành 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 
};

Ví dụ Python: tải tệp CSV trên máy lên

Tải tệp CSV trên máy lên API từ xa bằng URL có chữ ký.

Các bước:

1. Lấy URL tải lên có chữ ký từ API.
2. Đọc tệp trên máy từ ổ đĩa.
3. Tải tệp lên URL có chữ ký bằng HTTP PUT.

Cấu hình:

• Cập nhật api_key, tenant_id, datatable_id và file_path nếu cần.

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

Phân trang

Các endpoint liệt kê chấp nhận tham số truy vấn limit và offset, đồng thời trả về mảng JSON thuần (không có lớp bao ngoài hay tổng số mục):

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

Để lấy hết dữ liệu qua nhiều trang, tiếp tục gửi yêu cầu với offset += limit cho đến khi mảng phản hồi ngắn hơn limit đã yêu cầu (hoặc mảng rỗng). Giá trị vượt quá mức tối đa sẽ bị từ chối với 400. Các endpoint dữ liệu có phiên bản (tập dữ liệu, phiên bản, webhook) cũng dùng quy ước tương tự. Hai danh sách bảng dữ liệu giới hạn limit ở mức 250.

Quản lý phiên bản và ngừng hỗ trợ

• Tất cả route đều có phiên bản theo /v1. Thay đổi không tương thích sẽ được phát hành trong phiên bản mới, thay vì âm thầm thay đổi /v1.
• Các thay đổi và route bị gỡ sẽ được thông báo trong ghi chú phát hành.
• Mọi thay đổi lớn mà ứng dụng phía người dùng có thể nhận biết đều được ghi trong nhật ký thay đổi. Hãy đăng ký nhận thông báo hoặc kiểm tra trước khi nâng cấp các API client đang ghim phiên bản.

Các bước tiếp theo

• Tài liệu API: Tài liệu đầy đủ về các endpoint và định dạng request/response
• Ví dụ trên GitHub: Tải ví dụ và thư viện client
• Lấy API key: Cách lấy và quản lý API key