AuroBox Dispatch API�單筆派工流程說明

2026.06

任務說明

物業端

輸入派工資料

AuroBox

建立任務 / 狀態機

Pudu API

custom_call / doors

閃電俠

移動 / QR / 艙門

核心任務：建立單筆派工，讓 AuroBox 串接 Pudu 控制閃電俠到點、顯示 QR、開艙、關艙並完成任務。

• 已通過真機驗證

• QR 驗證目前尚未實作，現階段重點是 QR 顯示與後續開/關艙 API 流程驗證。

• 保留 tasks 陣列格式，方便未來擴充多筆派工或多艙位配送。

AuroBox Dispatch API｜單筆派工流程

1

設計目標與 MVP 範圍

已確認功能

• 單筆派工任務
• 閃電俠可顯示QR Code
• 四個艙位皆可使用1–4
• 開艙關艙皆正常

尚未實機確認

• 多筆派工任務

​

​

​

資料邊界

• 一次派送任務建立一個派工陣列。

• 派工陣列目前放一筆任務(多筆任務驗證中)。

• 同一台機器同時間只允許一個 active batch。

• 確認關艙狀態回傳後才會正常結束任務。

對華康APP端:

• 只需呼叫建立派工、開艙、確認取件等高階 API。

• Pudu本身API由 AuroBox 內部處理。

• APP可以看到的機器狀態以queued、on_the_way、arrived、picking_up、completed 等狀態為主。

AuroBox Dispatch API｜單筆派工流程

2

系統角色與責任分工

APP負責

• 產生 QR_payload

• 提供目標點與艙門

• 觸發開關艙

AuroBox 負責

• 建立派工任務

• 保存任務狀態

• 串接 Pudu API 與 callback

• 控管開關艙流程

Pudu / 機器人負責

• 移動到 Pudu 地圖點位

• 顯示 QR 內容

• 執行艙門控制

• 回傳抵達與艙門 callback

AuroBox Dispatch API｜單筆派工流程

3

建立派工資料格式

{� "tasks": [� {� "unit_no": "12F-A",� "compartment": 1,� "qr_payload": "https://property-app.example/pickup/TOKEN-001",� "package_name": "測試包裹"� }� ]�}

重要限制

unit_no 必須與 Pudu 地圖點位名稱一致

AuroBox Dispatch API｜單筆派工流程

4

完整派送流程圖：單筆 Happy Path

1. 建立派工

POST /dispatches

2. 派送到點

custom_call

3. 抵達顯示 QR

ARRIVE + QR

4. 開艙

POST /unlock

5. 取件完成

POST /confirm

6. 關艙完成

CLOSED callback

7. 完成任務

complete_call

狀態切換

queued → moving / on_the_way → arrived / awaiting_scan → unlocking → door_opened → closing → completing → completed

物業端主動呼叫

• 建立派工 POST /dispatches

• 驗證通過後開艙 POST /unlock(還未完成驗證流程)

• 取件後關艙 POST /confirm-pickup

AuroBox / Pudu 事件驅動

• Pudu callback 驅動 moving、arrived、door_opened、completed

• CLOSED 是 complete_call 前的必要安全閘點

AuroBox Dispatch API｜單筆派工流程

5

步驟一：建立派工並發送 custom_call

物業端建立任務，AuroBox 檢查機器狀態並呼叫 Pudu 出發

入口 API

POST /api/v1/dispatches

AuroBox 建檔

dispatch_batch + dispatch_task

Pudu 動作

custom_call 到 unit_no 對應點位

處理順序

1. 驗證 tasks、compartment、unit_no、qr_payload。

2. 選擇 robot_sn 並查詢 Pudu 狀態。

3. 阻擋低電量、offline、busy、已有 active batch。

4. 建立 batch/task，初始狀態 queued。

5. 呼叫 scheduler 發送 custom_call。

關鍵設計

• unit_no 會直接作為 Pudu point。

• call_mode = QR_CODE，抵達後等待外部流程繼續。

• do_not_queue = true，避免 Pudu 端自行排隊造成狀態不可控。

• Pudu 回傳 task_id 後寫入 pudu_call_task_id。

輸出狀態

batch: dispatching / in_progress；task: queued → moving / on_the_way → arrived / awaiting_scan

AuroBox Dispatch API｜單筆派工流程

7

步驟二：抵達後顯示 QR，驗證後開艙

現階段 QR 只顯示；驗證通過後由物業端呼叫 AuroBox 開艙 API

抵達訊號

Pudu callback�notifyCustomCall(ARRIVE)

QR 顯示

AuroBox 補推 custom_content�閃電俠螢幕顯示 QR

開艙

POST /unlock�control_doors(open)

開艙 API

POST /api/v1/dispatches/{batch_id}/tasks/{task_id}/unlock��{� "compartment": 1,� "resident_token": "JWT_FROM_RESIDENT_APP"�}

前置條件

• task 必須已抵達並進入 awaiting_scan。

• compartment 必須與該 task 原始艙位一致。

• resident_token 目前只記錄事件，不由 AuroBox 解析。

• 開門成功需等待 notifyDoorsState(OPENED)。

狀態變化

arrived / awaiting_scan → unlocking / picking_up → door_opened / picking_up

AuroBox Dispatch API｜單筆派工流程

8

步驟三：確認取件、關艙並完成 Pudu 任務

confirm-pickup 只發送關門命令；真正完成需等 CLOSED callback

確認取件 API

POST /api/v1/dispatches/{batch_id}/tasks/{task_id}/confirm-pickup��{� "compartment": 1�}

處理邏輯

1. 確認 task internal_status = door_opened。

2. 呼叫 Pudu control_doors(operation=false)。

3. 本地狀態先更新為 closing / picking_up。

4. 等待 notifyDoorsState(CLOSED)。

完成任務的安全閘點

1. door_opened

艙門已開

2. confirm-pickup

通知關艙

3. closing

等待關門

4. CLOSED callback

確認已關

5. complete_call

結束 Pudu 任務

6. completed

任務完成

注意：不能在 confirm-pickup 的 HTTP response 直接視為完成；必須等艙門 CLOSED callback 後，AuroBox 才呼叫 complete_call。

AuroBox Dispatch API｜單筆派工流程

9

API 與狀態總覽

物業端需要理解的 API 介面與主要狀態

主要狀態

• queued：已建立，等待派送

• on_the_way：機器人移動中

• arrived：抵達，等待掃 QR

• picking_up：開艙 / 取件 / 關艙中

• completed：該筆任務完成

整合注意事項

• QR_payload 顯示與 QR 驗證需明確切分：現階段 AuroBox 未處理驗證，只負責顯示與後續開艙控制。

• unit_no 與 Pudu 地圖點位必須一致，否則 custom_call 會失敗。

• CLOSED callback 是關艙與完成任務之間的必要事件，避免艙門未關就結束 Pudu 任務。

• 若未來擴充多筆 tasks，需補齊跨 task 排程、失敗恢復與完整真機驗證策略。

AuroBox Dispatch API｜單筆派工流程

10