Tra cứu API FactoryFlow

GET/wms/v1/tasks#

Danh sách tác vụ kho

listWmsTasks · WMS · task:read

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
limit	query	Không	{"type": "integer", "minimum": 1, "maximum": 100, "default": 20}
cursor	query	Không	{"type": "string", "minLength": 1}
status	query	Không	{"type": "string", "minLength": 1, "enum": ["CREATED", "VALIDATED", "ALLOCATED", "RELEASED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "EXCEPTION"]}

TaskPage · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
items	array	Có	Các phần tử trong trang kết quả hiện tại.	{"items": {"$ref": "#/components/schemas/Task"}}
nextCursor	string	Không	Con trỏ cho trang sau; không có nghĩa đã duyệt mọi kết quả.	{"minLength": 1}

cURL

curl --request GET \
  "https://factoryflow-api.example.invalid/wms/v1/tasks" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001"

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001'}
data = None
request = urllib.request.Request(base + "/wms/v1/tasks", data=data, headers=headers, method="GET")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wms/v1/tasks"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .GET();
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 200

Dữ liệu tĩnh, không request nào được gửi.

{
  "items": [
    {
      "id": "DEMO-TASK",
      "status": "CREATED",
      "version": 1
    }
  ],
  "nextCursor": "DEMO-NEXT"
}

400 · 401 · 403 · 429 · 503 → application/problem+json

Giới hạn trang và cursor theo contract; cursor không hợp lệ cần bắt đầu lại truy vấn, không diễn giải là hết task.

Điều kiện lỗi và xử lý

Với listWmsTasks: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Đối tượng không tìm thấy cần kiểm ID và phạm vi; không suy là nhiệm vụ thất bại.

POST/wms/v1/tasks#

Tạo tác vụ kho

createWmsTask · WMS · task:create

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Có	{"type": "string", "minLength": 1}

Nội dung yêu cầu mẫu

{
  "taskType": "TRANSFER",
  "siteId": "DEMO-SITE",
  "warehouseId": "DEMO-WH",
  "sourceLocationId": "DEMO-A",
  "targetLocationId": "DEMO-B",
  "lines": [
    {
      "skuId": "DEMO-SKU",
      "quantity": 1,
      "uom": "EA"
    }
  ],
  "executionMode": "AMR"
}

TaskRequest · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
taskType	string	Có	Loại công việc kho; quyết định điều kiện vị trí nguồn/đích.	{"minLength": 1, "enum": ["RECEIVE", "PUTAWAY", "TRANSFER", "REPLENISH", "PICK", "PACK", "CYCLE_COUNT"]}
siteId	string	Có	Mã nhà máy, phải khớp ngữ cảnh được cấp quyền.	{"minLength": 1}
warehouseId	string	Có	Kho thuộc site được phép.	{"minLength": 1}
sourceLocationId	string	Có điều kiện	Vị trí nguồn; bắt buộc khi TRANSFER hoặc PICK.	{"minLength": 1}
targetLocationId	string	Có điều kiện	Vị trí đích; bắt buộc khi PUTAWAY, TRANSFER hoặc REPLENISH.	{"minLength": 1}
lines	array	Có	Các dòng mã hàng, lượng và đơn vị cần xử lý.	{"minItems": 1, "items": {"type": "object", "properties": {"skuId": {"type": "string", "minLength": 1, "description": "Mã hàng trong dữ liệu nền được chọn."}, "quantity": {"type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Lượng dương, tính theo uom của dòng; không tự suy đơn vị."}, "uom": {"type": "string", "minLength": 1, "description": "Mã đơn vị tính, phải được ánh xạ trong dữ liệu nền."}}, "required": ["skuId", "quantity", "uom"], "additionalProperties": false}}
executionMode	string	Có	Phương thức dự kiến; chỉ dùng khi profile và năng lực dự án hỗ trợ.	{"minLength": 1, "enum": ["MANUAL", "AMR", "COBOT", "CONVEYOR", "HYBRID"]}

Task · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "VALIDATED", "ALLOCATED", "RELEASED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "EXCEPTION"]}
version	integer	Có	Phiên bản đối tượng để phát hiện cập nhật đồng thời.	{"minimum": 1}
siteId	string	Không	Mã nhà máy, phải khớp ngữ cảnh được cấp quyền.	{}
warehouseId	string	Không	Kho thuộc site được phép.	{}
sourceLocationId	string	Không	Vị trí nguồn; bắt buộc khi TRANSFER hoặc PICK.	{}
targetLocationId	string	Không	Vị trí đích; bắt buộc khi PUTAWAY, TRANSFER hoặc REPLENISH.	{}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/wms/v1/tasks" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'taskType': 'TRANSFER', 'siteId': 'DEMO-SITE', 'warehouseId': 'DEMO-WH', 'sourceLocationId': 'DEMO-A', 'targetLocationId': 'DEMO-B', 'lines': [{'skuId': 'DEMO-SKU', 'quantity': 1, 'uom': 'EA'}], 'executionMode': 'AMR'}).encode("utf-8")
request = urllib.request.Request(base + "/wms/v1/tasks", data=data, headers=headers, method="POST")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wms/v1/tasks"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 201

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-TASK",
  "status": "CREATED",
  "version": 1
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

TRANSFER thiếu nguồn hoặc đích bị chặn; SKU/UOM sai cần sửa mapping trước tạo.

Điều kiện lỗi và xử lý

Với createWmsTask: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Request ghi phải giữ key/body khi retry; khác body cần ý định mới sau khi đối soát.

GET/wms/v1/tasks/{taskId}#

Tra cứu tác vụ kho

getWmsTask · WMS · task:read

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
taskId	path	Có	{"type": "string", "minLength": 1}

Task · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "VALIDATED", "ALLOCATED", "RELEASED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "EXCEPTION"]}
version	integer	Có	Phiên bản đối tượng để phát hiện cập nhật đồng thời.	{"minimum": 1}
siteId	string	Không	Mã nhà máy, phải khớp ngữ cảnh được cấp quyền.	{}
warehouseId	string	Không	Kho thuộc site được phép.	{}
sourceLocationId	string	Không	Vị trí nguồn; bắt buộc khi TRANSFER hoặc PICK.	{}
targetLocationId	string	Không	Vị trí đích; bắt buộc khi PUTAWAY, TRANSFER hoặc REPLENISH.	{}

cURL

curl --request GET \
  "https://factoryflow-api.example.invalid/wms/v1/tasks/DEMO-ID" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001"

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001'}
data = None
request = urllib.request.Request(base + "/wms/v1/tasks/DEMO-ID", data=data, headers=headers, method="GET")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wms/v1/tasks/DEMO-ID"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .GET();
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 200

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-TASK",
  "status": "IN_PROGRESS",
  "version": 3
}

400 · 401 · 403 · 429 · 503 · 404 → application/problem+json

Kiểm task thuộc site được phép; status COMPLETED phải được hiểu trong miền WMS.

Điều kiện lỗi và xử lý

Với getWmsTask: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Đối tượng không tìm thấy cần kiểm ID và phạm vi; không suy là nhiệm vụ thất bại.

POST/wms/v1/tasks/{taskId}/confirm#

Xác nhận nghiệp vụ

confirmWmsTask · WMS · task:execute

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Có	{"type": "string", "minLength": 1}
taskId	path	Có	{"type": "string", "minLength": 1}

Nội dung yêu cầu mẫu

{
  "confirmationType": "SCAN",
  "expectedVersion": 3,
  "evidenceRef": "DEMO-SCAN"
}

Confirmation · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
confirmationType	string	Có	Loại bằng chứng xác nhận tác vụ.	{"minLength": 1, "enum": ["SCAN", "DEVICE_EVENT", "MANUAL_OVERRIDE"]}
expectedVersion	integer	Có	Bản mà người gọi đã xem; bản cũ phải được đối soát.	{"minimum": 1}
evidenceRef	string	Có	Tham chiếu bằng chứng đã kiểm quyền và tính phù hợp.	{"minLength": 1}

Task · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "VALIDATED", "ALLOCATED", "RELEASED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "EXCEPTION"]}
version	integer	Có	Phiên bản đối tượng để phát hiện cập nhật đồng thời.	{"minimum": 1}
siteId	string	Không	Mã nhà máy, phải khớp ngữ cảnh được cấp quyền.	{}
warehouseId	string	Không	Kho thuộc site được phép.	{}
sourceLocationId	string	Không	Vị trí nguồn; bắt buộc khi TRANSFER hoặc PICK.	{}
targetLocationId	string	Không	Vị trí đích; bắt buộc khi PUTAWAY, TRANSFER hoặc REPLENISH.	{}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/wms/v1/tasks/DEMO-ID/confirm" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'confirmationType': 'SCAN', 'expectedVersion': 3, 'evidenceRef': 'DEMO-SCAN'}).encode("utf-8")
request = urllib.request.Request(base + "/wms/v1/tasks/DEMO-ID/confirm", data=data, headers=headers, method="POST")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wms/v1/tasks/DEMO-ID/confirm"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 200

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-TASK",
  "status": "COMPLETED",
  "version": 4
}

400 · 401 · 403 · 429 · 503 · 404 · 409 · 422 → application/problem+json

Scan thiếu hoặc expectedVersion cũ chặn xác nhận; đọc lại task và xác minh bằng chứng.

Điều kiện lỗi và xử lý

Với confirmWmsTask: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Request ghi phải giữ key/body khi retry; khác body cần ý định mới sau khi đối soát.

POST/wcs/v1/execution-orders#

Tạo lệnh thực thi

createExecutionOrder · WCS · wcs:dispatch

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Có	{"type": "string", "minLength": 1}

Nội dung yêu cầu mẫu

{
  "taskId": "DEMO-TASK",
  "expectedTaskVersion": 2,
  "routeRef": "DEMO-ROUTE"
}

ExecutionRequest · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
taskId	string	Có	Tham chiếu tác vụ kho nguồn.	{"minLength": 1}
expectedTaskVersion	integer	Có	Phiên bản task dùng khi lập execution.	{"minimum": 1}
routeRef	string	Có	Tham chiếu tuyến/bản đồ được phép.	{"minLength": 1}

Execution · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
taskId	string	Có	Tham chiếu tác vụ kho nguồn.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "PLANNED", "DISPATCHING", "DISPATCHED", "EXECUTING", "PAUSED", "COMPLETED", "FAILED", "UNKNOWN"]}
version	integer	Có	Phiên bản đối tượng để phát hiện cập nhật đồng thời.	{"minimum": 1}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/wcs/v1/execution-orders" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'taskId': 'DEMO-TASK', 'expectedTaskVersion': 2, 'routeRef': 'DEMO-ROUTE'}).encode("utf-8")
request = urllib.request.Request(base + "/wcs/v1/execution-orders", data=data, headers=headers, method="POST")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wcs/v1/execution-orders"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 201

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-EXE",
  "taskId": "DEMO-TASK",
  "status": "CREATED",
  "version": 1
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

Task chưa phát hành hoặc version không khớp: giữ yêu cầu, trả về bên WMS xử lý.

Điều kiện lỗi và xử lý

Với createExecutionOrder: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Request ghi phải giữ key/body khi retry; khác body cần ý định mới sau khi đối soát.

POST/wcs/v1/execution-orders/{orderId}/dispatch#

Điều phối lệnh thực thi

dispatchExecutionOrder · WCS · wcs:dispatch

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Có	{"type": "string", "minLength": 1}
orderId	path	Có	{"type": "string", "minLength": 1}

Nội dung yêu cầu mẫu

{
  "expectedVersion": 2,
  "executorRef": "DEMO-EXECUTOR",
  "policyRef": "DEMO-POLICY"
}

DispatchRequest · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
expectedVersion	integer	Có	Bản mà người gọi đã xem; bản cũ phải được đối soát.	{"minimum": 1}
executorRef	string	Có	Bên thực thi đáp ứng profile của lệnh.	{"minLength": 1}
policyRef	string	Có	Policy áp dụng cho quyết định dispatch.	{"minLength": 1}

Execution · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
taskId	string	Có	Tham chiếu tác vụ kho nguồn.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "PLANNED", "DISPATCHING", "DISPATCHED", "EXECUTING", "PAUSED", "COMPLETED", "FAILED", "UNKNOWN"]}
version	integer	Có	Phiên bản đối tượng để phát hiện cập nhật đồng thời.	{"minimum": 1}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/wcs/v1/execution-orders/DEMO-ID/dispatch" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'expectedVersion': 2, 'executorRef': 'DEMO-EXECUTOR', 'policyRef': 'DEMO-POLICY'}).encode("utf-8")
request = urllib.request.Request(base + "/wcs/v1/execution-orders/DEMO-ID/dispatch", data=data, headers=headers, method="POST")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wcs/v1/execution-orders/DEMO-ID/dispatch"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 202

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-EXE",
  "taskId": "DEMO-TASK",
  "status": "DISPATCHING",
  "version": 3
}

400 · 401 · 403 · 429 · 503 · 404 · 409 · 422 → application/problem+json

Sai route, executor không sẵn sàng hoặc safety không đạt: giữ chưa dispatch; 202 không là hoàn thành.

Điều kiện lỗi và xử lý

Với dispatchExecutionOrder: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Request ghi phải giữ key/body khi retry; khác body cần ý định mới sau khi đối soát.

GET/wcs/v1/execution-orders/{orderId}#

Đối soát thực thi

getExecutionOrder · WCS · wcs:read

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
orderId	path	Có	{"type": "string", "minLength": 1}

Execution · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
taskId	string	Có	Tham chiếu tác vụ kho nguồn.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "PLANNED", "DISPATCHING", "DISPATCHED", "EXECUTING", "PAUSED", "COMPLETED", "FAILED", "UNKNOWN"]}
version	integer	Có	Phiên bản đối tượng để phát hiện cập nhật đồng thời.	{"minimum": 1}

cURL

curl --request GET \
  "https://factoryflow-api.example.invalid/wcs/v1/execution-orders/DEMO-ID" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001"

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001'}
data = None
request = urllib.request.Request(base + "/wcs/v1/execution-orders/DEMO-ID", data=data, headers=headers, method="GET")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wcs/v1/execution-orders/DEMO-ID"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .GET();
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 200

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-EXE",
  "taskId": "DEMO-TASK",
  "status": "EXECUTING",
  "version": 4
}

400 · 401 · 403 · 429 · 503 · 404 → application/problem+json

Nếu UNKNOWN, tra mission/controller và callback; không tự đổi sang FAILED.

Điều kiện lỗi và xử lý

Với getExecutionOrder: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Đối tượng không tìm thấy cần kiểm ID và phạm vi; không suy là nhiệm vụ thất bại.

POST/fleet/v1/missions#

Tạo nhiệm vụ robot

createMission · Fleet · fleet:manage

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Có	{"type": "string", "minLength": 1}

Nội dung yêu cầu mẫu

{
  "executionId": "DEMO-EXE",
  "pickupPoint": "DEMO-A",
  "dropoffPoint": "DEMO-B",
  "fleetProfile": "DEMO-FLEET"
}

MissionRequest · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
executionId	string	Có	Lệnh thực thi liên kết mission/cell job.	{"minLength": 1}
pickupPoint	string	Có	Điểm lấy theo map/profile Fleet.	{"minLength": 1}
dropoffPoint	string	Có	Điểm giao theo map/profile Fleet.	{"minLength": 1}
fleetProfile	string	Có	Profile Fleet được cấu hình cho site.	{"minLength": 1}

Mission · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "ACCEPTED", "GOING_TO_PICKUP", "ARRIVED_PICKUP", "LOADED", "GOING_TO_DROPOFF", "ARRIVED_DROPOFF", "UNLOADED", "COMPLETED", "FAILED", "UNKNOWN"]}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/fleet/v1/missions" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'executionId': 'DEMO-EXE', 'pickupPoint': 'DEMO-A', 'dropoffPoint': 'DEMO-B', 'fleetProfile': 'DEMO-FLEET'}).encode("utf-8")
request = urllib.request.Request(base + "/fleet/v1/missions", data=data, headers=headers, method="POST")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/fleet/v1/missions"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 201

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-MISSION",
  "status": "CREATED"
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

Execution đã có mission: đối soát ID cũ; không tạo lại vì response bị mất.

Điều kiện lỗi và xử lý

Với createMission: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Request ghi phải giữ key/body khi retry; khác body cần ý định mới sau khi đối soát.

GET/fleet/v1/missions/{missionId}#

Tra cứu nhiệm vụ

getMission · Fleet · fleet:read

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
missionId	path	Có	{"type": "string", "minLength": 1}

Mission · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "ACCEPTED", "GOING_TO_PICKUP", "ARRIVED_PICKUP", "LOADED", "GOING_TO_DROPOFF", "ARRIVED_DROPOFF", "UNLOADED", "COMPLETED", "FAILED", "UNKNOWN"]}

cURL

curl --request GET \
  "https://factoryflow-api.example.invalid/fleet/v1/missions/DEMO-ID" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001"

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001'}
data = None
request = urllib.request.Request(base + "/fleet/v1/missions/DEMO-ID", data=data, headers=headers, method="GET")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/fleet/v1/missions/DEMO-ID"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .GET();
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 200

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-MISSION",
  "status": "CREATED"
}

400 · 401 · 403 · 429 · 503 · 404 → application/problem+json

ID không thấy có thể do profile hoặc mapping; kiểm Fleet nguồn trước phát nhiệm vụ khác.

Điều kiện lỗi và xử lý

Với getMission: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Đối tượng không tìm thấy cần kiểm ID và phạm vi; không suy là nhiệm vụ thất bại.

POST/robot-cell/v1/cell-jobs#

Tạo công việc trạm robot

createCellJob · Cell · robot-cell:operate

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Có	{"type": "string", "minLength": 1}

Nội dung yêu cầu mẫu

{
  "executionId": "DEMO-EXE",
  "cellId": "DEMO-CELL",
  "recipeId": "DEMO-RECIPE",
  "recipeVersion": "1"
}

CellRequest · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
executionId	string	Có	Lệnh thực thi liên kết mission/cell job.	{"minLength": 1}
cellId	string	Có	Trạm robot thuộc phạm vi được phép.	{"minLength": 1}
recipeId	string	Có	Mã recipe thuộc cell và phạm vi được phép.	{"minLength": 1}
recipeVersion	string	Có	Phiên bản recipe đã duyệt cho job.	{"minLength": 1}

CellJob · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "ACCEPTED", "RUNNING", "COMPLETED", "BLOCKED", "FAILED", "UNKNOWN"]}
recipeVersion	string	Có	Phiên bản recipe đã duyệt cho job.	{"minLength": 1}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/robot-cell/v1/cell-jobs" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'executionId': 'DEMO-EXE', 'cellId': 'DEMO-CELL', 'recipeId': 'DEMO-RECIPE', 'recipeVersion': '1'}).encode("utf-8")
request = urllib.request.Request(base + "/robot-cell/v1/cell-jobs", data=data, headers=headers, method="POST")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/robot-cell/v1/cell-jobs"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 201

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-JOB",
  "status": "CREATED",
  "recipeVersion": "1"
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

Recipe/program không khớp hoặc cell không ready: chặn job; kỹ sư cell kiểm bản và mode.

Điều kiện lỗi và xử lý

Với createCellJob: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Request ghi phải giữ key/body khi retry; khác body cần ý định mới sau khi đối soát.

POST/devices/v1/devices/{deviceId}/commands#

Gửi ý định lệnh thiết bị

createDeviceCommand · Device · device:command

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Có	{"type": "string", "minLength": 1}
deviceId	path	Có	{"type": "string", "minLength": 1}

Nội dung yêu cầu mẫu

{
  "commandType": "START_JOB",
  "expectedVersion": 1,
  "policyRef": "DEMO-POLICY"
}

CommandRequest · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
commandType	string	Có	Loại ý định lệnh trong allowlist; không là raw motion.	{"minLength": 1, "enum": ["CREATE_MISSION", "PRINT_LABEL", "READ_WEIGHT", "START_JOB", "PLC_WRITE_SIGNAL"]}
expectedVersion	integer	Có	Bản mà người gọi đã xem; bản cũ phải được đối soát.	{"minimum": 1}
policyRef	string	Có	Policy áp dụng cho quyết định dispatch.	{"minLength": 1}

Command · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "SENT", "ACKED", "COMPLETED", "TIMEOUT", "FAILED", "UNKNOWN"]}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/devices/v1/devices/DEMO-ID/commands" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'commandType': 'START_JOB', 'expectedVersion': 1, 'policyRef': 'DEMO-POLICY'}).encode("utf-8")
request = urllib.request.Request(base + "/devices/v1/devices/DEMO-ID/commands", data=data, headers=headers, method="POST")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/devices/v1/devices/DEMO-ID/commands"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 202

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-COMMAND",
  "status": "CREATED"
}

400 · 401 · 403 · 429 · 503 · 404 · 409 · 422 → application/problem+json

Lệnh ngoài allowlist hoặc interlock không đạt: từ chối; không gửi raw command thay thế.

Điều kiện lỗi và xử lý

Với createDeviceCommand: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Request ghi phải giữ key/body khi retry; khác body cần ý định mới sau khi đối soát.

POST/device-callback/v1/fleet-events#

Tiếp nhận phản hồi đội robot

receiveFleetEvent · Callback · fleet:event

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Có	{"type": "string", "minLength": 1}
X-Request-Timestamp	header	Không	{"type": "string", "minLength": 1}
X-Request-Signature	header	Không	{"type": "string", "minLength": 1}

Nội dung yêu cầu mẫu

{
  "eventId": "DEMO-EVENT",
  "correlationId": "00000000-0000-4000-8000-000000000001",
  "entityId": "DEMO-MISSION",
  "entityVersion": 9,
  "eventType": "mission.status.changed",
  "occurredAt": "2026-10-26T00:00:00Z",
  "schemaVersion": "1.0",
  "source": "DEMO-FLEET-ADAPTER",
  "payload": {
    "status": "COMPLETED",
    "executionId": "DEMO-EXE"
  }
}

Callback · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
eventId	string	Có	Định danh sự kiện để khử trùng.	{"minLength": 1}
correlationId	string	Có	Định danh truy vết xuyên các bước.	{"minLength": 1, "format": "uuid"}
entityId	string	Có	Đối tượng được sự kiện mô tả.	{"minLength": 1}
entityVersion	integer	Có	Phiên bản đối tượng tại nguồn, dùng kiểm thứ tự.	{"minimum": 1}
eventType	string	Có	Tên sự kiện chuẩn theo catalogue tham chiếu.	{"minLength": 1}
occurredAt	string	Có	Thời điểm nguồn phát sinh theo RFC 3339; giữ múi giờ.	{"minLength": 1, "format": "date-time"}
schemaVersion	string	Có	Phiên bản envelope/schema mà consumer phải hiểu.	{"minLength": 1, "enum": ["1.0"]}
source	string	Có	Dịch vụ hoặc adapter phát sự kiện.	{"minLength": 1}
payload	#/components/schemas/EventPayload	Có	Dữ liệu sự kiện; nhận callback không tự xác nhận tồn.	{"$ref": "#/components/schemas/EventPayload"}

Receipt · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["RECEIVED", "DUPLICATE", "QUARANTINED"]}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/device-callback/v1/fleet-events" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'eventId': 'DEMO-EVENT', 'correlationId': '00000000-0000-4000-8000-000000000001', 'entityId': 'DEMO-MISSION', 'entityVersion': 9, 'eventType': 'mission.status.changed', 'occurredAt': '2026-10-26T00:00:00Z', 'schemaVersion': '1.0', 'source': 'DEMO-FLEET-ADAPTER', 'payload': {'status': 'COMPLETED', 'executionId': 'DEMO-EXE'}}).encode("utf-8")
request = urllib.request.Request(base + "/device-callback/v1/fleet-events", data=data, headers=headers, method="POST")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/device-callback/v1/fleet-events"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 202

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-RECEIPT",
  "status": "RECEIVED"
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

eventId trùng được khử trùng; entityVersion cũ được đối soát theo contract, không ghi lùi trạng thái.

Điều kiện lỗi và xử lý

Với receiveFleetEvent: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Request ghi phải giữ key/body khi retry; khác body cần ý định mới sau khi đối soát.

POST/exceptions/v1/exceptions#

Mở ngoại lệ vận hành

raiseException · Exception · exception:create

Tham số	Vị trí	Bắt buộc	Lược đồ
X-Correlation-Id	header	Có	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Có	{"type": "string", "minLength": 1}
X-Site-Id	header	Có	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Có	{"type": "string", "minLength": 1}

Nội dung yêu cầu mẫu

{
  "entityId": "DEMO-MISSION",
  "reasonCode": "DEMO_TIMEOUT",
  "evidenceRef": "DEMO-TRACE",
  "ownerRef": "DEMO-OWNER"
}

ExceptionRequest · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
entityId	string	Có	Đối tượng được sự kiện mô tả.	{"minLength": 1}
reasonCode	string	Có	Mã lý do ngoại lệ cần phân loại và xử lý.	{"minLength": 1}
evidenceRef	string	Có	Tham chiếu bằng chứng đã kiểm quyền và tính phù hợp.	{"minLength": 1}
ownerRef	string	Có	Tham chiếu người hoặc nhóm chịu trách nhiệm xử lý.	{"minLength": 1}

Exception · lược đồ

Trường	Kiểu	Bắt buộc	Ý nghĩa	Ràng buộc
id	string	Có	Định danh đối tượng do dịch vụ sở hữu cấp.	{"minLength": 1}
status	string	Có	Trạng thái trong vòng đời của loại đối tượng; không dùng thay trạng thái miền khác.	{"minLength": 1, "enum": ["CREATED", "ASSIGNED", "IN_PROGRESS", "RESOLVED", "CLOSED"]}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/exceptions/v1/exceptions" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'entityId': 'DEMO-MISSION', 'reasonCode': 'DEMO_TIMEOUT', 'evidenceRef': 'DEMO-TRACE', 'ownerRef': 'DEMO-OWNER'}).encode("utf-8")
request = urllib.request.Request(base + "/exceptions/v1/exceptions", data=data, headers=headers, method="POST")
# Không gửi request trong ví dụ offline.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/exceptions/v1/exceptions"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// Không gửi trong ví dụ offline.

Xem phản hồi mẫu · 201

Dữ liệu tĩnh, không request nào được gửi.

{
  "id": "DEMO-EXCEPTION",
  "status": "CREATED"
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

reasonCode và đối tượng phải đủ ngữ cảnh; chuyển người xử lý khi kết quả thực chưa rõ.

Điều kiện lỗi và xử lý

Với raiseException: 401/403 yêu cầu kiểm danh tính, scope và site; không retry để vượt quyền. Request ghi phải giữ key/body khi retry; khác body cần ý định mới sau khi đối soát.

Tra cứu API FactoryFlow

Danh sách tác vụ kho

Tạo tác vụ kho

Nội dung yêu cầu mẫu

Tra cứu tác vụ kho

Xác nhận nghiệp vụ

Nội dung yêu cầu mẫu

Tạo lệnh thực thi

Nội dung yêu cầu mẫu

Điều phối lệnh thực thi

Nội dung yêu cầu mẫu

Đối soát thực thi

Tạo nhiệm vụ robot

Nội dung yêu cầu mẫu

Tra cứu nhiệm vụ

Tạo công việc trạm robot

Nội dung yêu cầu mẫu

Gửi ý định lệnh thiết bị

Nội dung yêu cầu mẫu

Tiếp nhận phản hồi đội robot

Nội dung yêu cầu mẫu

Mở ngoại lệ vận hành

Nội dung yêu cầu mẫu

Phiên bản và thay đổi

Tìm trong website

Mở liên kết ngoài

GoPaperless SSO