裝置註冊與綁定¶

PAYMENT 先建立短效 enrollment token；現場人員在 FarmAgent 輸入 token 完成綁定。 Token 明文只在 POST /v1/enrollments 回應出現一次；不得當 URL 熵值依賴。

新裝置註冊（device_create）¶

sequenceDiagram
  participant P as PAYMENT
  participant F as Farm
  participant A as FarmAgent/Field
  P->>F: POST /v1/enrollments（不帶 device_code）
  F-->>P: 201 enrollment_id + device_code + token（只一次）
  Note over P: 保存 device_code；token 交現場
  A->>F: POST /v1/enrollments/redeem（token 即憑證）
  F-->>A: 200 bound
  F-->>P: webhook device.bound（best-effort）
  P->>F: GET /v1/enrollments/{id}（callback 遺失時）
  F-->>P: state=bound, device_code
  Note over P: 權威保存 device_code

既有裝置加銀行（bank_add）¶

sequenceDiagram
  participant P as PAYMENT
  participant F as Farm
  participant A as FarmAgent/Field
  P->>F: POST /v1/enrollments（帶既有 device_code）
  F-->>P: 201 token + mode=bank_add
  A->>F: POST /v1/enrollments/redeem
  F-->>A: 200 bound（sealed PIN 寫入 bank binding）
  F-->>P: webhook bank.bound（best-effort）
  P->>F: GET enrollment + GET device
  F-->>P: bank + pin_configured 確認

POST /v1/enrollments¶

POST /v1/enrollments
Authorization: Bearer $FARM_API_KEY
Content-Type: application/json

完整 request 欄位（EnrollIn）¶

最小 request（新機）¶

curl -sS -X POST "$FARM_BASE/v1/enrollments" \
  -H "Authorization: Bearer $FARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "TH",
    "bank_code": "SCB",
    "bank_payload": {"pin": "000000"},
    "label": "desk-placeholder",
    "ttl_seconds": 1800
  }'

最小 request（既有機加銀行）¶

{
  "region": "TH",
  "bank_code": "KTB",
  "bank_payload": {"pin": "000000"},
  "device_code": "TH-XXXX"
}

成功 response（201）¶

{
  "enrollment_id": "enr_…",
  "device_code": "TH-XXXX",
  "device_id": "TH-XXXX",
  "token": "A3K9MP",
  "mode": "device_create",
  "region": "TH",
  "bank_code": "SCB",
  "status": "pending",
  "expires_at": 0
}

Token 規則： 恰 6 字元，字集 23456789ABCDEFGHJKMNPQRSTUVWXYZ（無 0/O/1/I/L）。 Redeem 會正規化為大寫。安全依賴短 TTL + 單次使用 + 現場實體配對，不是 URL 熵。

常見錯誤¶

GET /v1/enrollments/{enrollment_id}¶

Callback 遺失時的權威狀態。跨 tenant → 404。

{
  "enrollment_id": "enr_…",
  "tenant_id": "…",
  "device_id": "TH-XXXX",
  "device_code": "TH-XXXX",
  "mode": "device_create",
  "region": "TH",
  "bank_code": "SCB",
  "device_type": "ios",
  "state": "bound",
  "udid_bound": true,
  "label": "desk-placeholder",
  "allowed_apps": [],
  "created_at": 0,
  "expires_at": 0
}

POST /v1/enrollments/redeem（Field／FarmAgent）¶

請求形狀（供理解 FLOW）：

{ "token": "A3K9MP", "udid": null, "install_id": null }

成功 → status=bound，並觸發 device.bound 或 bank.bound。 無效／過期 token → 404；無可用裝置 → 409；猜測過頻 → 429。

Webhook：device.bound / bank.bound¶

{
  "event": "device.bound",
  "idempotency_key": "enr_…",
  "enrollment_id": "enr_…",
  "device_id": "TH-XXXX",
  "device_code": "TH-XXXX",
  "bank_code": "SCB",
  "region": "TH",
  "tenant_id": "…",
  "label": "desk-placeholder",
  "allowed_apps": []
}

• mode=bank_add 時 event 為 bank.bound。
• 永不帶 PIN。
• 投遞：best-effort，無持久化重送。失敗時以 GET /v1/enrollments/{id} 恢復。
• 接收端去重鍵：enrollment_id（同 idempotency_key）。

PAYMENT 必須保存¶

是否可重試¶