有車喇合作方接入

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。

接入原則

  1. 建立測試合作方
  2. 在隔離測試環境驗證
  3. 排定受控試行
  4. 啟用及提交事件
  5. 持續監察及核對
  • 營運管理員使用 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.arrivedassignedarrived;可帶非必要資料。
trip.startedarrivedin_trip。
trip.completedin_tripcompleted;data.fare 必須是 HKD 明細,總額等於底價加附加費。
driver.location_updatedassigned、arrived、in_trip狀態不變;data.latitude 及 data.longitude 必須在港區範圍。
order.cancelledcancel_pendingcancelled;cancel_request_id 必須符合訂單,並帶 reason_code。
order.cancel_rejectedcancel_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-TimestampUnix 秒,接收方應拒絕過舊或未來請求。
X-Youchela-Delivery-Id本次投遞 ID;用於接收方冪等去重。
X-Youchela-Signaturev1=<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 最新訂單,再決定是否可用原事件內容重送。不要在未知結果下建立第二個接單或派單流程。

聯合驗收

  1. 在隔離測試環境確認 transportApi 已部署,並由有權限的 Firebase 管理員建立 testing 合作方;完成簽章、接單、事件及取消測試後,才按受控試行程序啟用 production。
  2. 以一次性憑證完成 GET 訂單權限測試,證明不會返回 passenger_id。
  3. 驗證 HMAC 原始 body、時間容忍、重播、錯 secret、錯 delivery ID 及 64 位 hex 格式。
  4. 接受一筆測試邀請,檢查 assignment、版本及首個事件序號;重送相同 key 不得重複接單。
  5. 依序提交抵達、開始及完成事件,檢查總車費加總、錯誤版本及 event sequence gap。
  6. 測試取消待確認、合作方確認取消及拒絕取消,且不把未確認狀態當成終止。
  7. 測試 Webhook 2xx、408、429、5xx、4xx 及網絡逾時的重試路徑。
  8. 營運人員只在 uncertain 狀態以當時的訂單版本、關聯編號、證據來源及參考編號核實;版本衝突時必須重讀並重新確認,已撤銷合作方不能繼續用舊權杖接單。
驗收結論只適用於實際測試過的環境。
源碼中的接口或測試文件不等同 production 已開放。合作方啟用前,仍需確認部署版本、CORS、Secret Manager、Firebase admin claim、Firestore 索引及實際通知網絡。