PARTNER INTEGRATION CONTRACT
的士合作方接入規範(草案)
此文件描述目前後端原始碼中的派單接口、合作方接單流程、事件、簽章及冪等規則。它是一份待聯合驗收的技術草案。
派單 API 已部署至 transport-eta-895d6;2026-11-02 的未登入查詢回報 HTTP 401,顯示身份驗證已啟用。正式接入仍待營運方核實合作車隊、服務覆蓋範圍、Webhook、管理員及咪錶/現金結算安排。此文件為接入草案,並不表示已有合作車隊接受訂單。
正式 API 根網址是 https://asia-east1-transport-eta-895d6.cloudfunctions.net/transportApi。除本文件列出的路徑外,沒有可供合作方使用的派單端點。既有 TDAS 路線 API 不是派單 API。
接入原則
- 建立測試合作方
- 在隔離測試環境驗證
- 排定受控試行
- 啟用及提交事件
- 持續監察及核對
- 營運管理員使用 Firebase ID Token;後端只在 custom claim
admin === true時允許管理操作。 - 合作方使用建立時取得、以
ycpt.開頭的專用 bearer 權杖。它不是 Firebase ID Token。 - 合作方權杖及 Webhook 簽章秘密只在建立回應顯示一次;不得放入 URL、localStorage、原始碼、聊天群組或一般日誌。
- 合作方狀態為
testing、active、paused、revoked。接到新邀請只會派給active且支援該車種的合作方;目前testing不會收到 production 測試邀請。先在隔離測試環境完成驗證,再按受控試行程序切換為active,不可為了取得測試邀請而無條件啟用 production 派單。 - 撤銷會停用現有合作方權杖;目前沒有公開的權杖輪替或重新簽發端點。
營運管理接口
全部要求 Authorization: Bearer <Firebase ID Token>。後端驗證權杖及 admin claim;網站的登入介面只處理既有帳戶,不提供註冊、建立或提升帳戶權限。
| 方法及路徑 | 用途 | 回應/限制 |
|---|---|---|
GET /v2/admin/rides?limit=100 | 列出最近訂單 | { items: RidePublicOrder[] };limit 1–100,預設 100。 |
GET /v2/admin/rides/:orderId | 訂單詳情及事件 | { order, events };events 最多 500 筆,按序號遞增。 |
POST /v2/admin/rides/:orderId/reconcile | 人工核實 uncertain 訂單 | 要求 Idempotency-Key。完成狀態須附已核實 final_fare(currency: HKD、整數仙 meter_minor、surcharges_minor、total_minor,總數須等於兩項之和);恢復進行中狀態只可回到 previous_status。嚴格 body 須帶 expected_version、status、reason、evidence.source、evidence.reference,以及當時的 assignment_id/cancel_request_id(如有)。版本或關聯編號不符即拒絕,不得套用到另一張或已更新的訂單。 |
GET /v2/admin/ride-partners | 列出合作方 | { items: PartnerPublic[] },不含秘密。 |
POST /v2/admin/ride-partners | 建立合作方 | 回應 { partner, credential_id, partner_token, webhook_secret }。兩個秘密只在此刻提供。 |
POST /v2/admin/ride-partners/:partnerId/credentials/rotate | 輪換合作方憑證 | 要求 Idempotency-Key;body 可帶 grace_seconds(0–86400,預設 900)。回應提供新 credential ID、token 及 webhook secret。 |
PATCH /v2/admin/ride-partners/:partnerId | 更新合作方狀態 | 嚴格 body:{"status":"testing"|"active"|"paused"|"revoked"}。 |
建立合作方的 body 必須包含 name、area、webhook_url、services、coverage_areas 及可選的 status(預設 testing)。coverage_areas 為 1–20 個已核實範圍,每個包含唯一 area_id、name 和 3–100 點 polygon;每點包含數字 latitude、longitude。上落客點均須落在範圍內,營運方必須核實,不會預設全港覆蓋。services 至少一項,值為 standard、comfort 或 extra_large。Webhook 必須是沒有帳密、查詢字串或片段的 HTTPS URL。
合作方接口
以下端點使用合作方權杖,而不是 Firebase ID Token。路徑中的 :orderId 是 backend 的 ord_… 訂單編號。
| 方法及路徑 | 用途 | 必要條件 |
|---|---|---|
GET /v2/partner/orders/:orderId | 查詢獲邀訂單 | 合作方必須在訂單獲邀 partner_ids 內。已指派合作方可查詢行程;落選或過期合作方只收到自己的邀請結果,不能取得最新行程資料。 |
POST /v2/partner/orders/:orderId/accept | 接受邀請並指派司機及車輛 | 必須帶有效 Idempotency-Key。 |
POST /v2/partner/orders/:orderId/events | 提交抵達、開始、完成或取消結果 | 必須帶有效 Idempotency-Key,並使用最新版本及連續事件序號。 |
合作方接單請求包含邀請 ID、預期訂單版本、合作方訂單編號、司機、車輛及接載 ETA。司機 contact_token 是不透明欄位;不要把乘客資料寫入其中。
{
"offer_id": "offer_demo_01",
"expected_version": 1,
"partner_order_id": "PARTNER-DISPATCH-24001",
"driver": {
"id": "driver_demo_17",
"display_name": "陳師傅",
"contact_token": "driver_contact_opaque_456"
},
"vehicle": {
"plate": "DEMO-123",
"service": "standard",
"seats": 4
},
"pickup_eta_seconds": 420
}
成功接單回應會把訂單遞增至版本 2,建立 assignment_id,並把 event sequence 設為 1。下列欄位只保留流程所需內容。
{
"order_id": "ord_demo_01",
"status": "assigned",
"order_version": 2,
"assignment_id": "asn_demo_01",
"next_event_sequence": 1
}
接單邀請及 45 秒有效期
建立乘客訂單時,後端會為所有 active、支援該車種及上落客點均在已核實覆蓋範圍內的合作方建立邀請。每個合作方收到 order.offered Webhook;邀請有效期為 45 秒。首個成功接單會鎖定訂單及司機,其他邀請不能再搶單。
{
"event_id": "evt_offer_demo",
"type": "order.offered",
"occurred_at": "2026-11-02T06:30:00Z",
"partner_id": "partner_demo",
"order_id": "ord_demo_01",
"offer_id": "offer_demo_01",
"expires_at": "2026-11-02T06:30:45Z",
"order_version": 1,
"pickup": {"name": "中環碼頭", "latitude": 22.2877, "longitude": 114.1597},
"destination": {"name": "旺角站", "latitude": 22.3193, "longitude": 114.1694},
"service": "standard",
"passenger_count": 2,
"estimate": {"currency": "HKD", "amount_minor": null},
"fare_mode": "metered",
"metered_fare_consent_at": "2026-11-02T06:30:00Z",
"metered_fare_consent_version": "metered-v1"
}
- 過期、已指派、版本不符、單號不符或同一司機已有活動訂單都會被拒絕。
- 逾時或不確定回覆不等同沒有接單。先查詢原訂單,不能盲目重派;uncertain 只能經營運人工核實。
- ETag、重試或版本更新不能代替 assignment_id 及合作方權杖驗證。
行程事件
接受訂單後,合作方按 backend 的狀態機提交事件。每次請求的 expected_version 必須等於目前訂單版本,event_sequence 從 1 開始連續增加,assignment_id 必須與原接單一致。
| 事件 type | 允許的目前狀態 | 結果/data 要求 |
|---|---|---|
driver.arrived | assigned | arrived;可帶非必要資料。 |
trip.started | arrived | in_trip。 |
trip.completed | in_trip | completed;data.fare 必須是 HKD 明細,總額等於底價加附加費。 |
driver.location_updated | assigned、arrived、in_trip | 狀態不變;data.latitude 及 data.longitude 必須在港區範圍。 |
order.cancelled | cancel_pending | cancelled;cancel_request_id 必須符合訂單,並帶 reason_code。 |
order.cancel_rejected | cancel_pending | 回復至取消前狀態;cancel_request_id 及 reason_code 必須存在。 |
{
"event_id": "evt_arrived_demo",
"event_sequence": 1,
"expected_version": 2,
"assignment_id": "asn_demo_01",
"type": "driver.arrived",
"occurred_at": "2026-11-02T06:35:00Z",
"data": {}
}
完工事件使用 meter_minor、surcharges_minor、total_minor;金額以 HKD 最小單位計算。以下事件假設上一個 arrived 事件已被接受,因此使用版本 3 及序號 2。
{
"event_id": "evt_started_demo",
"event_sequence": 2,
"expected_version": 3,
"assignment_id": "asn_demo_01",
"type": "trip.started",
"occurred_at": "2026-11-02T06:40:00Z",
"data": {}
}
冪等規則
Idempotency-Key 必須符合 ^[A-Za-z0-9._:-]{8,128}$。接單及事件請求缺少此標頭會回 HTTP 400 IDEMPOTENCY_KEY_REQUIRED。
- 同一合作方、同一操作範圍及同一 key 重送至 24 小時內會返回首次成功回應。
- 以同一 key 送出不同內容會回 HTTP 409
IDEMPOTENCY_CONFLICT。 - 合作方訂單建立接口(由乘客行程使用)同樣要求冪等標頭;營運網站的管理接口目前不建立訂單。
- admin 建立合作方、更新狀態及人工核實接口均要求
Idempotency-Key。若網絡未能確認回應,請使用原有 key、相同路徑及完全相同的 JSON 重試,再查詢狀態;不可換 key 重複建立或核實。 - 網絡逾時後應先原樣重送相同 key、路徑及 JSON,再查詢訂單;不要換 key 建立第二次接單或事件。
Webhook 發送
後端目前發出兩個 outbound 事件類型:order.offered 及 order.cancel_requested。請求是 HTTPS POST,JSON 是實際簽章內容;Content-Type 及 User-Agent 分別為 application/json 與 Youchela-Dispatch/1.0。
| 標頭 | 內容 |
|---|---|
X-Youchela-Key-Id | 簽署憑證 ID;接收方依此選擇該版本的 webhook secret,與 Delivery ID 不同。 |
X-Youchela-Timestamp | Unix 秒,接收方應拒絕過舊或未來請求。 |
X-Youchela-Delivery-Id | 本次投遞 ID;用於接收方冪等去重。 |
X-Youchela-Signature | v1=<64 lowercase hex>。 |
任何 2xx 回應代表已收件。網絡錯誤、逾時及 HTTP 408、429、5xx 會重試;最多嘗試 8 次,初始約 2 秒並以指數增加至最多 30 分鐘。其他 4xx 會視為永久失敗。每次 HTTP 呼叫逾時為 8 秒。Webhook Worker 每分鐘執行。
接收方需要自行保存 delivery ID 去重結果,並在回 2xx 前完成必要持久化。合作方後續透過 partner events endpoint 提交行程狀態,這些事件不會以本節兩個 outbound Webhook 類型回送。
簽章驗證
以 X-Youchela-Key-Id 尋找對應憑證版本的 webhook_secret 作 HMAC-SHA256 key。輪換期間保留舊版本至寬限期結束;以 Delivery ID 持久去重,同一投遞重試使用相同 ID。簽章原文必須是下列三段以句點連接,並使用收到的原始 body bytes,不能先重新格式化 JSON。
{timestamp}.{delivery_id}.{raw_body}
比較時使用 constant-time comparison。建議拒絕相差超過 300 秒的時間戳,並拒絕不標準的數字或空欄位。
import hashlib
import hmac
import re
def valid_signature(secret, timestamp, delivery_id, body, signature, max_age=300):
if not isinstance(secret, str) or not secret:
return False
if not isinstance(body, bytes):
return False
if not isinstance(timestamp, str) or not re.fullmatch(r"[0-9]{1,12}", timestamp):
return False
if not isinstance(delivery_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]{1,128}", delivery_id):
return False
if not isinstance(signature, str) or not re.fullmatch(r"v1=[0-9a-f]{64}", signature):
return False
try:
sent_at = int(timestamp)
except ValueError:
return False
if abs(int(__import__("time").time()) - sent_at) > max_age:
return False
message = timestamp.encode() + b"." + delivery_id.encode() + b"." + body
expected = "v1=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
def valid_webhook(keys, key_id, timestamp, delivery_id, body, signature):
if not isinstance(key_id, str) or not isinstance(keys, dict):
return False
secret = keys.get(key_id)
return valid_signature(secret, timestamp, delivery_id, body, signature)
錯誤及版本衝突
API 錯誤使用 error.code、中英文訊息及 requestId 包裝。合作方應按 code 及 HTTP status 處理,不應解析中文訊息作程式判斷。
{
"error": {
"code": "VERSION_CONFLICT",
"message": "訂單狀態已改變,請先查詢狀態",
"messageEn": "Version conflict"
},
"requestId": "request_demo_01"
}
遇到 VERSION_CONFLICT、EVENT_SEQUENCE_GAP、CANCEL_REQUEST_MISMATCH 或 ASSIGNMENT_MISMATCH 時,先 GET 最新訂單,再決定是否可用原事件內容重送。不要在未知結果下建立第二個接單或派單流程。
聯合驗收
- 在隔離測試環境確認 transportApi 已部署,並由有權限的 Firebase 管理員建立
testing合作方;完成簽章、接單、事件及取消測試後,才按受控試行程序啟用 production。 - 以一次性憑證完成 GET 訂單權限測試,證明不會返回 passenger_id。
- 驗證 HMAC 原始 body、時間容忍、重播、錯 secret、錯 delivery ID 及 64 位 hex 格式。
- 接受一筆測試邀請,檢查 assignment、版本及首個事件序號;重送相同 key 不得重複接單。
- 依序提交抵達、開始及完成事件,檢查總車費加總、錯誤版本及 event sequence gap。
- 測試取消待確認、合作方確認取消及拒絕取消,且不把未確認狀態當成終止。
- 測試 Webhook 2xx、408、429、5xx、4xx 及網絡逾時的重試路徑。
- 營運人員只在 uncertain 狀態以當時的訂單版本、關聯編號、證據來源及參考編號核實;版本衝突時必須重讀並重新確認,已撤銷合作方不能繼續用舊權杖接單。
源碼中的接口或測試文件不等同 production 已開放。合作方啟用前,仍需確認部署版本、CORS、Secret Manager、Firebase admin claim、Firestore 索引及實際通知網絡。