TRUSTED FACTORYFLOW
Quickstart. Một task, một execution, một mission.
Theo dữ liệu DEMO từ tạo tác vụ tới callback và xác nhận WMS, với các khoảng chuyển trạng thái được giải thích rõ.
Chuẩn bị trước khi gọi API
Client đã đăng ký, scope/site hợp lệ và dữ liệu SKU/UOM/vị trí đã được kiểm. Dùng cùng correlation cho hành trình, nhưng mỗi ý định ghi có idempotency key riêng. Không dán token vào website.
| Header | Ý nghĩa |
|---|---|
| X-Correlation-Id | 00000000-0000-4000-8000-000000000001 |
| X-Tenant-Id / X-Site-Id | DEMO-TENANT / DEMO-SITE |
| X-Idempotency-Key | DEMO-create-task, DEMO-create-execution…; retry cùng ý định dùng lại key và body. |
01 / POST /wms/v1/tasks
Tạo task ở CREATED/version 1. WMS kiểm dữ liệu, giữ chỗ và phát hành theo quy trình miền; ví dụ tạo execution tiếp theo giả định task đã tới version 2.
Request body
{
"taskType": "TRANSFER",
"siteId": "DEMO-SITE",
"warehouseId": "DEMO-WH",
"sourceLocationId": "DEMO-A",
"targetLocationId": "DEMO-B",
"lines": [
{
"skuId": "DEMO-SKU",
"quantity": 1,
"uom": "EA"
}
],
"executionMode": "AMR"
}Phản hồi minh họa
{
"id": "DEMO-TASK",
"status": "CREATED",
"version": 1
}02 / POST /wcs/v1/execution-orders
Liên kết DEMO-TASK; response là DEMO-EXE/CREATED/version 1. Bước lập kế hoạch miền đưa execution tới PLANNED/version 2 trước dispatch.
Request body
{
"taskId": "DEMO-TASK",
"expectedTaskVersion": 2,
"routeRef": "DEMO-ROUTE"
}Phản hồi minh họa
{
"id": "DEMO-EXE",
"taskId": "DEMO-TASK",
"status": "CREATED",
"version": 1
}03 / POST /wcs/v1/execution-orders/{orderId}/dispatch
Gửi expectedVersion 2; response 202 là DISPATCHING/version 3. Đây là tiếp nhận điều phối, chưa là giao xong.
Request body
{
"expectedVersion": 2,
"executorRef": "DEMO-EXECUTOR",
"policyRef": "DEMO-POLICY"
}Phản hồi minh họa
{
"id": "DEMO-EXE",
"taskId": "DEMO-TASK",
"status": "DISPATCHING",
"version": 3
}04 / POST /fleet/v1/missions
Bước của bên thực thi/adapter: tạo DEMO-MISSION cho DEMO-EXE nếu chưa có mission. Không để cả client ERP và WCS cùng tạo nhiệm vụ.
Request body
{
"executionId": "DEMO-EXE",
"pickupPoint": "DEMO-A",
"dropoffPoint": "DEMO-B",
"fleetProfile": "DEMO-FLEET"
}Phản hồi minh họa
{
"id": "DEMO-MISSION",
"status": "CREATED"
}05 / POST /device-callback/v1/fleet-events
Callback báo DEMO-MISSION COMPLETED, entityVersion 9. Receipt RECEIVED chỉ nhận sự kiện; cần khử trùng và kiểm thứ tự trước cập nhật miền.
Request body
{
"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"
}
}Phản hồi minh họa
{
"id": "DEMO-RECEIPT",
"status": "RECEIVED"
}06 / GET /fleet/v1/missions/{missionId}
Ảnh chụp trạng thái sau callback: COMPLETED. Đây là ví dụ theo thời điểm khác với response CREATED ở bước tạo.
Phản hồi minh họa
{
"id": "DEMO-MISSION",
"status": "COMPLETED"
}07 / POST /wms/v1/tasks/{taskId}/confirm
Sau xác minh scan DEMO-SCAN, task đang IN_PROGRESS/version 3 được xác nhận với expectedVersion 3; kết quả COMPLETED/version 4. Thiếu scan thì không xác nhận.
Request body
{
"confirmationType": "SCAN",
"expectedVersion": 3,
"evidenceRef": "DEMO-SCAN"
}Phản hồi minh họa
{
"id": "DEMO-TASK",
"status": "COMPLETED",
"version": 4
}Retry, lỗi và đối soát
| Tình huống | Xử lý tham chiếu |
|---|---|
| 409 | Version cũ: đọc lại đối tượng và xem thay đổi; không tự tăng expectedVersion để bỏ qua quyết định. |
| 422 | Dữ liệu hoặc điều kiện miền sai: sửa nguyên nhân, không retry mù. |
| 429 / 503 | Tôn trọng Retry-After khi có; kiểm idempotency và kết quả trước gửi lại ý định ghi. |
| UNKNOWN | Tra external ID và hiện trường; chưa rõ hiệu ứng thì giữ chờ. Phạm vi key và TTL phải được contract triển khai quy định. |