Tài liệu tham khảo API: tổ chức

Tổ chức nhóm nhiều tenant dưới cùng một đơn vị.

Lấy thông tin tổ chức của tenant

Có thể đọc bằng API key giới hạn theo tenant; API key giới hạn theo tổ chức cũng được chấp nhận.

Điểm cuối: GET /v1/tenant/{tenantId}/organization

Xác thực: API key giới hạn theo tenant hoặc tổ chức · phạm vi read

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Thông tin tổ chức

{
	"id": "00000000-0000-0000-0000-000000000000",
	"displayName": "string",
	"createdAt": "2024-03-15T16:30:00Z",
	"contactEmail": "string",
	"isActive": true,
	"allowedLogins": {
		"Microsoft": true,
		"Google": true,
		"LinkedIn": true
	},
	"createdBy": "00000000-0000-0000-0000-000000000000"
}

Trường	Kiểu	Bắt buộc	Mô tả
id	string	Có	Định dạng: uuid
displayName	string	Có	Mặc định: "" Độ dài tối đa: 128
createdAt	string	Có	Định dạng: date-time
contactEmail	string	Có	Định dạng: email
isActive	boolean	Có	Mặc định: true
allowedLogins	object	Có
createdBy	string	Có	Định dạng: uuid

Lỗi:

• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key
• 404 Không tìm thấy tài nguyên

Lấy hạn mức chỗ ngồi và chính sách tự đồng bộ của tổ chức

Trả về số chỗ ngồi đã mua và đang sử dụng trên toàn tổ chức theo từng cấp (Process Foundation, Process Architecture, Process Intelligence), hạn mức Viewer miễn phí, mục tiêu tự đồng bộ, giải thích về chênh lệch chỗ ngồi (hệ thống sẽ làm gì và khi nào), chu kỳ thanh toán và externalApiSeatPolicy. Có thể đọc bằng API key giới hạn theo tenant. Tham số đường dẫn {tenantId} là tenant ngữ cảnh (tổ chức gắn với API key giới hạn theo tổ chức), không phải đối tượng của thao tác.

Điểm cuối: GET /v1/tenant/{tenantId}/organization/billing/seats

Xác thực: API key giới hạn theo tenant hoặc tổ chức · phạm vi read

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Hạn mức chỗ ngồi

{
	"contractType": "free",
	"isTrial": true,
	"purchased": {
		"foundation": 0,
		"architecture": 0,
		"intelligence": 0
	},
	"inUseBillable": {
		"foundation": 0,
		"architecture": 0,
		"intelligence": 0
	},
	"inUseFree": 0,
	"inUseDashboardViewers": 0,
	"totalBillable": 0,
	"freeViewerAllowance": 0,
	"freeViewerOverAllowance": 0,
	"dashboardViewerAllowance": 0,
	"dashboardViewerOverAllowance": 0,
	"fixedOverage": 0,
	"target": {
		"foundation": 0,
		"architecture": 0,
		"intelligence": 0
	},
	"drift": [
		{
			"rung": "foundation",
			"paid": 0,
			"actual": 0,
			"state": "equal",
			"buffer": 0
		}
	],
	"interval": "month",
	"nextBilledAt": "string",
	"externalApiSeatPolicy": "autoBill"
}

Trường	Kiểu	Bắt buộc	Mô tả
contractType	free | selfServe | fixed | unlimited	Có	Giá trị được phép: free, selfServe, fixed, unlimited
isTrial	boolean	Có
purchased	object	Có
inUseBillable	object	Có
inUseFree	number	Có
inUseDashboardViewers	number	Có
totalBillable	number	Có
freeViewerAllowance	number	Có
freeViewerOverAllowance	number	Có
dashboardViewerAllowance	number	Có
dashboardViewerOverAllowance	number	Có
fixedOverage	number	Có
target	object	Có
drift	object[]	Có
interval	month | year	Có	Giá trị được phép: month, year
nextBilledAt	string	Có
externalApiSeatPolicy	autoBill | requireCapacity	Có	Giá trị được phép: autoBill, requireCapacity

Lỗi:

• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key
• 404 Không tìm thấy tài nguyên

Lấy số liệu thống kê toàn tổ chức

Tham số đường dẫn {tenantId} là tenant ngữ cảnh (tổ chức gắn với API key giới hạn theo tổ chức), không phải đối tượng của thao tác.

Điểm cuối: GET /v1/tenant/{tenantId}/organization/statistics

Xác thực: API key giới hạn theo tổ chức · phạm vi read

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Số liệu thống kê tổ chức

{
	"userCount": 0,
	"tenantCount": 0,
	"tenantStatistics": [
		{
			"tenantId": "00000000-0000-0000-0000-000000000000",
			"uploadedDataSize": 0,
			"uploadedDataCount": 0,
			"modelCount": 0,
			"simulationCount": 0,
			"userCount": 0
		}
	]
}

Trường	Kiểu	Bắt buộc	Mô tả
userCount	number	Có
tenantCount	number	Có
tenantStatistics	object[]	Có

Lỗi:

• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key

Liệt kê tất cả tenant trong tổ chức

Tham số đường dẫn {tenantId} là tenant ngữ cảnh (tổ chức gắn với API key giới hạn theo tổ chức), không phải đối tượng của thao tác.

Điểm cuối: GET /v1/tenant/{tenantId}/organization/tenants

Xác thực: API key giới hạn theo tổ chức · phạm vi read

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
limit	integer	query	Không	Số mục tối đa cần trả về
offset	integer	query	Không	Số mục cần bỏ qua

Phản hồi (200):

Danh sách tenant

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"createdBy": "00000000-0000-0000-0000-000000000000",
		"createdAt": "2024-03-15T16:30:00Z",
		"displayName": "string",
		"contactEmail": "string",
		"isActive": true,
		"shortName": "string",
		"useOrganizationTheme": true,
		"description": "string",
		"organizationId": "00000000-0000-0000-0000-000000000000",
		"allowedLogins": {
			"Microsoft": true,
			"Google": true,
			"LinkedIn": true
		},
		"tenantType": "normal",
		"url": "string"
	}
]

Lỗi:

• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key

Tạo tenant mới trong tổ chức (cần API key giới hạn theo tổ chức)

Tham số đường dẫn {tenantId} là tenant ngữ cảnh (tổ chức gắn với API key giới hạn theo tổ chức), không phải đối tượng của thao tác.

Điểm cuối: POST /v1/tenant/{tenantId}/organization/tenants

Xác thực: API key giới hạn theo tổ chức · phạm vi write

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid

Nội dung yêu cầu:

{
	"displayName": "string",
	"shortName": "string",
	"description": "string",
	"timezone": "string",
	"tenantType": "normal"
}

Trường	Kiểu	Bắt buộc	Mô tả
displayName	string	Không	Độ dài tối đa: 128
shortName	string	Có
description	string	Không	Độ dài tối đa: 200
timezone	string	Không	Độ dài tối đa: 64
tenantType	normal | sandbox | demo	Không	Giá trị được phép: normal, sandbox, demo

Phản hồi (201):

Đã tạo tenant

{
	"id": "00000000-0000-0000-0000-000000000000",
	"createdBy": "00000000-0000-0000-0000-000000000000",
	"createdAt": "2024-03-15T16:30:00Z",
	"displayName": "string",
	"contactEmail": "string",
	"isActive": true,
	"shortName": "string",
	"useOrganizationTheme": true,
	"description": "string",
	"organizationId": "00000000-0000-0000-0000-000000000000",
	"allowedLogins": {
		"Microsoft": true,
		"Google": true,
		"LinkedIn": true
	},
	"tenantType": "normal",
	"url": "string"
}

Trường	Kiểu	Bắt buộc	Mô tả
id	string	Có	Định dạng: uuid
createdBy	string	Có	Định dạng: uuid
createdAt	string	Có	Định dạng: date-time
displayName	string	Có	Mặc định: "" Độ dài tối đa: 128
contactEmail	string	Có	Định dạng: email
isActive	boolean	Có	Mặc định: true
shortName	string	Có
useOrganizationTheme	boolean	Có	Mặc định: true
description	string	Có	Độ dài tối đa: 200
organizationId	string	Có	Định dạng: uuid
allowedLogins	object	Có
tenantType	normal | sandbox | demo	Có	Giá trị được phép: normal, sandbox, demo Mặc định: normal
url	string	Có	Định dạng: uri

Lỗi:

• 400 Yêu cầu không hợp lệ, chẳng hạn biểu thức bộ lọc không hợp lệ, quy trình chưa có mô hình, loại tệp tải lên không được hỗ trợ hoặc thiếu trường bắt buộc
• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key
• 403 API key không có phạm vi cần thiết hoặc quyền truy cập tổ chức; tenant không hoạt động hoặc gói dịch vụ không hỗ trợ loại tệp này
• 406 Không thể chấp nhận giá trị này, chẳng hạn tên ngắn bị dành riêng hoặc bị trùng

Xóa mềm tenant trong tổ chức (cần API key giới hạn theo tổ chức)

Quyền truy cập API của tenant sẽ dừng ngay lập tức. Tenant và dữ liệu được giữ lại trong thời gian an toàn trước khi xóa, sau đó hệ thống tự động xóa hoàn toàn. Không thể xóa tenant bạn đang sử dụng (tenant ngữ cảnh).

Điểm cuối: DELETE /v1/tenant/{tenantId}/organization/tenants/{targetId}

Xác thực: API key giới hạn theo tổ chức · phạm vi write

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
targetId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Đã xóa tenant

{
	"success": true,
	"message": "string"
}

Trường	Kiểu	Bắt buộc	Mô tả
success	boolean	Có
message	string	Có

Lỗi:

• 400 Yêu cầu không hợp lệ, chẳng hạn biểu thức bộ lọc không hợp lệ, quy trình chưa có mô hình, loại tệp tải lên không được hỗ trợ hoặc thiếu trường bắt buộc
• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key
• 403 API key không có phạm vi cần thiết hoặc quyền truy cập tổ chức; tenant không hoạt động hoặc gói dịch vụ không hỗ trợ loại tệp này
• 404 Không tìm thấy tài nguyên

Khôi phục tenant đã xóa mềm trong tổ chức (cần API key giới hạn theo tổ chức)

Hoàn tác thao tác xóa mềm trong thời gian an toàn trước khi xóa: tenant và dữ liệu được khôi phục nguyên trạng, đồng thời quyền truy cập API hoạt động trở lại. Tham số đường dẫn {tenantId} là tenant ngữ cảnh (tổ chức gắn với API key giới hạn theo tổ chức), không phải đối tượng của thao tác.

Điểm cuối: POST /v1/tenant/{tenantId}/organization/tenants/{targetId}/restore

Xác thực: API key giới hạn theo tổ chức · phạm vi write

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
targetId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Đã khôi phục tenant

{
	"success": true,
	"message": "string"
}

Trường	Kiểu	Bắt buộc	Mô tả
success	boolean	Có
message	string	Có

Lỗi:

• 400 Yêu cầu không hợp lệ, chẳng hạn biểu thức bộ lọc không hợp lệ, quy trình chưa có mô hình, loại tệp tải lên không được hỗ trợ hoặc thiếu trường bắt buộc
• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key
• 403 API key không có phạm vi cần thiết hoặc quyền truy cập tổ chức; tenant không hoạt động hoặc gói dịch vụ không hỗ trợ loại tệp này
• 404 Không tìm thấy tài nguyên

Liệt kê tất cả người dùng trong tổ chức

Tham số đường dẫn {tenantId} là tenant ngữ cảnh (tổ chức gắn với API key giới hạn theo tổ chức), không phải đối tượng của thao tác.

Điểm cuối: GET /v1/tenant/{tenantId}/organization/users

Xác thực: API key giới hạn theo tổ chức · phạm vi read

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
limit	integer	query	Không	Số mục tối đa cần trả về
offset	integer	query	Không	Số mục cần bỏ qua

Phản hồi (200):

Danh sách người dùng trong tổ chức

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"email": "string",
		"firstName": "string",
		"lastName": "string",
		"createdAt": "2024-03-15T16:30:00Z",
		"lastLoginAt": "2024-03-15T16:30:00Z",
		"organizationId": "00000000-0000-0000-0000-000000000000",
		"isActiveInOrganization": true,
		"isAdminInOrganization": true
	}
]

Lỗi:

• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key

Cập nhật cài đặt người dùng trong tổ chức (cần API key giới hạn theo tổ chức)

Các cờ vai trò trong nội dung yêu cầu (isAdminInOrganization, isActiveInOrganization) được áp dụng đúng như đã gửi; chỉ cấp API key giới hạn theo tổ chức cho quản trị viên tổ chức. Tham số đường dẫn {tenantId} là tenant ngữ cảnh (tổ chức gắn với API key giới hạn theo tổ chức), không phải đối tượng của thao tác.

Điểm cuối: PUT /v1/tenant/{tenantId}/organization/users/{userId}

Xác thực: API key giới hạn theo tổ chức · phạm vi write

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
userId	string	path	Có	Định dạng: uuid

Nội dung yêu cầu:

{
	"isActiveInOrganization": true,
	"isAdminInOrganization": true
}

Trường	Kiểu	Bắt buộc	Mô tả
isActiveInOrganization	boolean	Không	Người dùng có đang hoạt động trong tổ chức hay không
isAdminInOrganization	boolean	Không	Quyền quản trị tổ chức (áp dụng đúng như đã gửi: chỉ cấp API key giới hạn theo tổ chức cho quản trị viên tổ chức)

Phản hồi (200):

Đã cập nhật

{
	"message": "string"
}

Trường	Kiểu	Bắt buộc	Mô tả
message	string	Có

Lỗi:

• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key
• 403 API key không có phạm vi cần thiết hoặc quyền truy cập tổ chức; tenant không hoạt động hoặc gói dịch vụ không hỗ trợ loại tệp này
• 404 Không tìm thấy tài nguyên

Xóa người dùng khỏi tổ chức (cần API key giới hạn theo tổ chức)

Tham số đường dẫn {tenantId} là tenant ngữ cảnh (tổ chức gắn với API key giới hạn theo tổ chức), không phải đối tượng của thao tác.

Điểm cuối: DELETE /v1/tenant/{tenantId}/organization/users/{userId}

Xác thực: API key giới hạn theo tổ chức · phạm vi write

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
userId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Đã xóa người dùng

{
	"message": "string"
}

Trường	Kiểu	Bắt buộc	Mô tả
message	string	Có

Lỗi:

• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key
• 403 API key không có phạm vi cần thiết hoặc quyền truy cập tổ chức; tenant không hoạt động hoặc gói dịch vụ không hỗ trợ loại tệp này
• 404 Không tìm thấy tài nguyên