REST API v1 Reference

call2.tw 來電驗證 API 文件

提供標準 RESTful 介面。只需 2 個 API 即可發起Call to verify驗證。

1 運作流程與架構 (Overview)

Call to verify 來電驗證模式為使用者發起驗證請求後，使用手機撥打由 call2.tw 提供的專屬專線（例如 02-8192-0116）。系統在中華電信門號秒級收到來電廣播後，自動比對來電號碼並於 1 秒內發送指令自動掛斷，完成極速驗證。

STEP 1: 發起驗證

客戶端 POST 呼叫 API 建立 60 秒 Session，取得專線號碼。

STEP 2: 手機撥打

使用者點擊撥號專線，系統收發通訊號令並於 1 秒內自動掛斷。

STEP 3: 狀態更新

狀態即時變更為 SUCCESS，App 輪詢或收到通知即驗證通過。

2 POST

/v1/start

功能：發起來電驗證請求 (Start Verification Session)

向伺服器發起一筆手機號碼驗證請求。系統將鎖定該號碼 60 秒獨佔 Session，回傳供使用者撥打的驗證專線號碼 dial_number，並可在帶入 callback_url 時於驗證成功當下進行非同步 Webhook 推送通知。

Request Body (JSON)

欄位	型態	必填	說明
api_key	string	必填	您的專屬 API Key。
phone	string	必填	台灣 10 位手機號碼 (格式: `09xxxxxxxx`)。
callback_url	string	選填	驗證成功時接收即時 Webhook POST 通知之 Callback URL。
sign	string	必填	MD5 防偽簽名 (詳見 MD5 簽名計算規則說明)。

請求範例 (Request Example Body)

{
  "api_key": "your_api_key_here",
  "phone": "0912345678",
  "callback_url": "https://your-domain.com/webhook/verify",
  "sign": "3b2a1c0d4e5f..."
}

回應範例 (Response 200 OK - 發起成功)

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "phone": "0912345678",
    "dial_number": "02-8192-0116",
    "expires_at": 1788452460,
    "callback_url": "https://your-domain.com/webhook/verify",
    "sign": "a1b2c3d4e5f6..."
  }
}

3 POST

/v1/verify

功能：查詢驗證狀態 (Check Verification Status)

後端伺服器可輪詢此 API (建議週期 1.5 秒)，查詢該門號號碼是否已有匹配通話紀錄並核對通過。

Request Body (JSON)

欄位	型態	必填	說明
api_key	string	必填	您的專屬 API Key。
phone	string	必填	欲查詢的手機號碼 (例如: `0912345678`)。
sign	string	必填	MD5 防偽簽名 (詳見 MD5 簽名計算規則說明)。

請求範例 (Request Example Body)

{
  "api_key": "your_api_key_here",
  "phone": "0912345678",
  "sign": "3b2a1c0d4e5f..."
}

回應範例 (驗證成功 SUCCESS)

{
  "code": 200,
  "data": {
    "phone": "0912345678",
    "status": "SUCCESS",
    "verified_at": 1788452405,
    "call_id": "call_20260910_164201",
    "sign": "3b2a1c0d4e5f..."
  }
}

回應範例 (待撥打中 PENDING)

{
  "code": 200,
  "data": {
    "phone": "0912345678",
    "status": "PENDING",
    "expires_at": 1788452460,
    "sign": "3b2a1c0d4e5f..."
  }
}

回應範例 (逾時作廢 EXPIRED)

{
  "code": 200,
  "data": {
    "phone": "0912345678",
    "status": "EXPIRED",
    "msg": "無驗證紀錄或已逾時作廢"
  }
}

status 狀態值定義

status 值	代表含意與處理建議
PENDING	待驗證中（60 秒內等待使用者拿手機撥打專線，請繼續輪詢）。
SUCCESS	驗證成功！（來電已秒級核對匹配，通話已自動掛斷，停止輪詢完成登入）。
EXPIRED	已逾時作廢（超過 60 秒使用者未撥打，需引導使用者點擊重試）。

4 POST

Webhook 回傳通知 (Callback)

功能：驗證成功非同步 Webhook 主動通知

若發起驗證時有帶入選填參數 callback_url，當使用者撥打專線完成驗證（狀態變更為 SUCCESS）時，系統背景 Worker 將自動以 HTTP POST 方式主動將驗證結果推送到貴站指定的 URL。

Callback 推送 Body 參數說明

參數名稱	型態	說明
api_key	string	貴站專屬 API Key (供貴站辨識帳戶歸屬)。
phone	string	驗證成功的手機門號 (例如: `0912345678`)。
status	string	驗證狀態，固定為 `SUCCESS`。
call_id	string	系統撥號驗證紀錄單號。
verified_at	integer	完成驗證時間戳 (10 位 Unix Timestamp)。
sign	string	MD5 防偽簽名 (供貴站比對防竄改，詳見 MD5 簽名計算規則說明)。

POST Payload 範例

{
  "api_key": "your_api_key_here",
  "phone": "0912345678",
  "status": "SUCCESS",
  "call_id": "call_20260910_164201",
  "verified_at": 1788452405,
  "sign": "3b2a1c0d4e5f..."
}

重試機制與停止條件說明

重試次數：若 Callback 發送失敗或未收回應，系統背景 Task 最多自動重試 3 次。
時間戳記錄：每次嘗試推送皆會即時更新最後發送時間戳記錄。
停止條件：貴站 Webhook 接收端於 HTTP Response Header/Body 回傳內容包含 OK（不區分大小寫，例如回傳字串 "OK" 或 "{"status":"OK"}"）時，系統即視為通知成功並停止重試。

5 HTTP 狀態碼與錯誤訊息對照表

HTTP Code	訊息 (`msg`)	原因說明與排除建議
200 OK	SUCCESS	請求執行成功。
400 Bad Request	手機號碼格式不正確 / 已有進行中的驗證	手機門號需為 10 位數字 `09xxxxxxxx`；或該號碼在 60 秒內已有一筆待撥打 Session。
401 Unauthorized	無效的 API Key	傳入的 `api_key` 無法在系統中對應戶號，請登入後台確認 API Key。
403 Forbidden	MD5 簽名驗證不符合	帶入的 `sign` 與伺服器以 `secret_key` 算出的簽名不符，請核對計算公式。
500 Server Error	伺服器內部錯誤	系統異常，請稍後重試或聯繫客服團隊。

6 認證機制與 MD5 簽章演算法說明

為確保 API 傳輸防竄改與安全性，發起驗證請求 (/v1/start)、狀態查詢 (/v1/verify) 及收到的 Webhook Callback 通知中皆包含 sign 簽章。

MD5 簽名計算步驟 (ksort ➔ http_build_query ➔ 拼接 secret ➔ md5)

簽名計算分為 4 個清晰步驟，確保客戶端與伺服器端計算結果完全一致：

1 步驟 1：Key 字典序排序 (ksort) ➔ 顯示排序後 JSON

排除 sign 欄位後，將其餘請求 Body 欄位按 Key 的 ASCII 字典序進行升冪排序：

原始 Request Body (未排序 JSON):

{
  "phone": "0912345678",
  "api_key": "YOUR_API_KEY"
}

排序後 (ksort Key 升冪排序 JSON):

{
  "api_key": "YOUR_API_KEY",
  "phone": "0912345678"
}

2 步驟 2：URL-encoded 串接 (http_build_query) ➔ 顯示串接後字串

將步驟 1 排序後的鍵值對組合轉為標準 URL-encoded 查詢字串：

串接後字串 (http_build_query 輸出):

api_key=YOUR_API_KEY&phone=0912345678

3 步驟 3：末端拼接 Secret Key 專屬金鑰 (&secret_key=...)

在串接後的字串末端加上專屬金鑰 &secret_key=YOUR_SECRET_KEY：

拼接 Secret Key 後的完整待簽字串:

api_key=YOUR_API_KEY&phone=0912345678&secret_key=YOUR_SECRET_KEY

4 步驟 4：計算 MD5 雜湊值 (md5) ➔ 產生 32 位小寫簽名

對步驟 3 的完整字串計算小寫 MD5 雜湊值，即獲得帶入請求或驗證 Callback 的 sign：

最終簽名計算公式與輸出:

sign = md5("api_key=YOUR_API_KEY&phone=0912345678&secret_key=YOUR_SECRET_KEY")
// 輸出 sign: "3b2a1c0d4e5f6a7b8c9d0e1f2a3b4c5d"