順風耳電話號碼驗證平台 - API說明文件

提出電話號碼驗證請求－全自動模式

驗證流程

此模式開發較簡易，使用者不需要每隔一段時間就和平台伺服器確認電話驗證狀態，只要將會員導向平台的驗證網址，驗證有效後自動導向使用者設定的網址，而且也能設定驗證過期後的導向網址。

備註：電話驗證有效時，會自動導向使用者設定為驗證有效之網址。

• check_mode_type(Integer)

  必要
  在全自動模式下，此參數設定值為2

• pn(String) / 可用字元[0-9][+] / 字元最大長度14

  必要
  要驗證的電話號碼
  範例：
  市話　0423456789
  手機　0912345678
  國外電話／手機　+1234567890
  註：以上電話號碼僅作為敘述，非本平台所專用的電話號碼

• time(Integer)

  可選
  要驗證的時間，單位為分鐘，未設定時，預設值為2分鐘
  最少1分鐘，最長5分鐘

• token(String)

  必要
  使用者的通行權杖，需申請本平台會員

• auto_mode_phone_valid_url(String) / 字元最大長度512

  可選
  當電話驗證有效時，會自動導向此網址，可以加入自訂的參數當做驗證依據
  範例：
  https://example.com/user.php?token=xxxxxxxx

• auto_mode_phone_invalid_url(String) / 字元最大長度512

  可選
  當電話驗證過期，會自動導向此網址，可以加入自訂的參數當做驗證依據
  範例：
  https://example.com/user.php?token=xxxxxxxx

• status(String)

  ok，代表請求成功
  error，代表請求失敗

• phone_number(String)

  本次請求要驗證的電話號碼

• call_number(String)

  本次請求要撥打的平台專線號碼

• effective_time(String)

  本次請求的生效時間

• expiration_time(String)

  本次請求的過期時間

• query_token(String)

  查詢驗證狀態的權杖
  權杖的有效時間為10分鐘

• guest_url(String)

  將會員導向本平台的驗證網址，後續驗證有效／過期時，本平台自動將會員導向使用者設定的網址路徑

• message(String)

  請求失敗時，可以參考message字段訊息

提出電話號碼驗證請求－主動模式

驗證流程

此模式特色為使用者每隔一段時間需主動向本平台查詢電話驗證狀態，與全自動模式不同，本平台不參與網址導向動作，僅供作為查詢服務，因此使用者能自行設計驗證網頁，與使用者網頁的美術風格相同。

• check_mode_type(Integer)

  必要
  在主動模式下，此參數設定值為0

• pn(String) / 可用字元[0-9][+] / 字元最大長度14

  必要
  要驗證的電話號碼
  範例：
  市話　0423456789
  手機　0912345678
  國外電話／手機　+1234567890
  註：以上電話號碼僅作為敘述，非本平台所專用的電話號碼

• time(Integer)

  可選
  要驗證的時間，單位為分鐘，未設定時，預設值為2分鐘
  最少1分鐘，最長5分鐘

• token(String)

  必要
  使用者的通行權杖，需申請本平台會員

• status(String)

  ok，代表請求成功
  error，代表請求失敗

• phone_number(String)

  本次請求要驗證的電話號碼

• call_number(String)

  本次請求要撥打的平台專線號碼

• effective_time(String)

  本次請求的生效時間

• expiration_time(String)

  本次請求的過期時間

• query_token(String)

  查詢驗證狀態的權杖
  權杖的有效時間為10分鐘

• message(String)

  請求失敗時，可以參考message字段訊息

提出電話號碼驗證請求－被動模式

驗證流程

此模式特色為使用者無需向本平台查詢電話驗證狀態，當電話驗證有效時，本平台會將驗證結果傳回使用者指定的網址路徑，也能應用在物聯網設備上。

在此模式下，使用者也能自行設計驗證網頁，與使用者網頁的美術風格相同。

備註：在被動模式下，本平台無法保證一定會傳回驗證結果，傳回的影響因素在於雙方的網路是否順暢。

• check_mode_type(Integer)

  必要
  在被動模式下，此參數設定值為1

• pn(String) / 可用字元[0-9][+] / 字元最大長度14

  必要
  要驗證的電話號碼
  範例：
  市話　0423456789
  手機　0912345678
  國外電話／手機　+1234567890
  註：以上電話號碼僅作為敘述，非本平台所專用的電話號碼

• time(Integer)

  可選
  要驗證的時間，單位為分鐘，未設定時，預設值為2分鐘
  最少1分鐘，最長5分鐘

• token(String)

  必要
  使用者的通行權杖，需申請本平台會員

• passive_mode_protocol(Integer)

  必要
  當電話驗證有效時，本平台會將驗證結果傳回使用者指定的網址路徑的通訊協定
  設定值為0時，傳回時使用HTTP協定，通訊埠為80
  設定值為1時，傳回時使用HTTPS協定，不支援自簽章憑證，通訊埠為443

• passive_mode_host(String) / 可用字元[0-9][a-z][.][-] / 字元最大長度128

  必要
  當電話驗證有效時，本平台會將驗證結果傳回使用者指定的網址路徑的主機名稱
  註：假如要傳回的網址為「https://example.com/user.php」，「example.com」就是主機名稱

• passive_mode_path(String) / 可用字元[0-9][a-z][.][-][/] / 字元最大長度128

  必要
  當電話驗證有效時，本平台會將驗證結果傳回使用者指定的網址路徑的路徑名稱
  註：假如要傳回的網址為「https://example.com/user.php」，「/user.php」就是路徑名稱

• status(String)

  ok，代表請求成功
  error，代表請求失敗

• phone_number(String)

  本次請求要驗證的電話號碼

• call_number(String)

  本次請求要撥打的平台專線號碼

• effective_time(String)

  本次請求的生效時間

• expiration_time(String)

  本次請求的過期時間

• query_token(String)

  查詢驗證狀態的權杖
  權杖的有效時間為10分鐘

• message(String)

  請求失敗時，可以參考message字段訊息

提出電話號碼驗證請求－被動模式傳回格式

• phone_number_check_status(Integer)

  1，代表驗證有效

• phone_number(String)

  驗證有效的電話號碼

• phone_number_check_create_time(String)

  本次驗證的建立時間

• phone_number_check_done_time(String)

  本次驗證的完成時間

• token(String)

  本次驗證的識別權杖

查詢電話號碼驗證狀態

• token(String)

  必要
  查詢驗證狀態的權杖

• status(String)

  ok，代表查詢成功
  error，代表查詢失敗

• phone_number_check_status(Integer)

  0，代表未通過驗證
  1，代表通過驗證

• phone_number(String)

  本次驗證的電話號碼

• phone_number_check_create_time(String)

  本次驗證的建立時間

• phone_number_check_done_time(String)

  本次驗證的完成時間
  註：當電話號碼未通過驗證時，此欄位為空白

• message(String)

  請求失敗時，可以參考message字段訊息

查詢使用者每日剩餘電話驗證請求次數

• token(String)

  必要
  使用者的通行權杖，需申請本平台會員

• status(String)

  ok，代表查詢成功
  error，代表查詢失敗

• free_point(Integer)

  今日剩餘的驗證請求次數

• free_point_daily(Integer)

  每日的驗證請求次數上限

• message(String)

  請求失敗時，可以參考message字段訊息