SIM Swap

SIM Swap（換卡）是指用戶的手機號碼與一張新的 SIM 卡綁定的過程，通常發生在以下場景：掛失補卡、升級 SIM 卡、攜號轉網、開通多卡服務，或新用戶繼承了曾被他人使用的號碼等。

攻擊者會利用 SIM Swap 劫持他人手機號，攔截簡訊驗證碼，進而重置密碼、接管帳戶。SIM Swap API 可即時檢測指定手機號是否發生過換卡，幫助業務方在簡訊 OTP 驗證等關鍵環節識別潛在的 SIM 劫持風險，降低帳戶被接管的機率。

注意： 當前僅支援以下國家/地區的號碼查詢 SIM Swap：巴西、印尼。

本 API 提供兩個獨立介面：

Retrieve Date：查詢指定手機號最近一次 SIM Swap 發生的時間
Check：檢測指定手機號在過去 N 小時內是否發生過 SIM Swap

呼叫驗證

這兩個介面均採用 HTTP Basic Auth 的驗證方式，在 HTTP Header 中添加 Authorization：

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

此代碼塊在浮窗中顯示

${base64_auth_string} 的生成演算法為：base64(dev_key:dev_secret)。

更多詳情可參考呼叫驗證了解如何進行 API 鑑權。

Retrieve Date

查詢指定手機號最近一次 SIM Swap 發生的時間。

呼叫地址

POST https://otp.api.engagelab.cc/v1/sim-swap/retrieve-date

請求範例

一個請求物件以 JSON 格式表達，因此請求頭需要帶 Content-Type: application/json。

請求頭

POST /v1/sim-swap/retrieve-date HTTP/1.1 Content-Type: application/json Authorization: Basic ${base64_auth_string}

              
              POST /v1/sim-swap/retrieve-date HTTP/1.1
Content-Type: application/json
Authorization: Basic ${base64_auth_string}

此代碼塊在浮窗中顯示

請求體

{ "phone_number": "+381692223535" }

              
              {
  "phone_number": "+381692223535"
}

此代碼塊在浮窗中顯示

請求參數

參數	類型	選項	說明
`phone_number`	String	必填	查詢目標手機號，建議使用 E.164 格式

返回參數

成功返回

欄位	類型	選項	描述
`request_id`	String	必填	本次查詢記錄 ID
`latest_sim_change`	String / null	必填	最近一次 SIM Swap 時間，RFC3339 格式；從未換卡時返回首次啟動時間；因隱私法規限制無法返回資料時為 `null`

成功返回範例：

{ "request_id": "2055136570436075520", "latest_sim_change": "2026-05-01T15:00:00Z" }

              
              {
  "request_id": "2055136570436075520",
  "latest_sim_change": "2026-05-01T15:00:00Z"
}

此代碼塊在浮窗中顯示

失敗返回

HTTP 狀態碼為 4xx 或 5xx，回應體包含欄位如下：

欄位	類型	選項	描述
`code`	int	必填	錯誤碼，詳見錯誤碼說明
`message`	String	必填	錯誤詳情

常見失敗返回範例：

參數錯誤範例：

{ "code": 3002, "message": "invalid phone_number" }

              
              {
  "code": 3002,
  "message": "invalid phone_number"
}

此代碼塊在浮窗中顯示

餘額不足範例：

{ "code": 3005, "message": "balance not enough" }

              
              {
  "code": 3005,
  "message": "balance not enough"
}

此代碼塊在浮窗中顯示

號碼不在服務覆蓋範圍範例：

{ "code": 5101, "message": "phone number is not in sim swap service coverage" }

              
              {
  "code": 5101,
  "message": "phone number is not in sim swap service coverage"
}

此代碼塊在浮窗中顯示

通用失敗範例：

{ "code": 5100, "message": "failed to retrieve sim swap date" }

              
              {
  "code": 5100,
  "message": "failed to retrieve sim swap date"
}

此代碼塊在浮窗中顯示

Check

檢測指定手機號在過去 N 小時內是否發生過 SIM Swap。

呼叫地址

POST https://otp.api.engagelab.cc/v1/sim-swap/check

請求範例

一個請求物件以 JSON 格式表達，請求頭同樣需要帶 Content-Type: application/json。

請求頭

POST /v1/sim-swap/check HTTP/1.1 Content-Type: application/json Authorization: Basic ${base64_auth_string}

              
              POST /v1/sim-swap/check HTTP/1.1
Content-Type: application/json
Authorization: Basic ${base64_auth_string}

此代碼塊在浮窗中顯示

請求體

{ "phone_number": "+381692223535", "max_age": 400 }

              
              {
  "phone_number": "+381692223535",
  "max_age": 400
}

此代碼塊在浮窗中顯示

請求參數

參數	類型	選項	說明
`phone_number`	String	必填	查詢目標手機號，建議使用 E.164 格式
`max_age`	Integer	必填	查詢窗口，單位小時，取值範圍 `1 ~ 2400`

返回參數

成功返回

欄位	類型	選項	描述
`request_id`	String	必填	本次查詢記錄 ID
`swapped`	Boolean	必填	在指定時間窗口內是否發生過 SIM Swap

成功返回範例：

{ "request_id": "2055136570293469184", "swapped": true }

              
              {
  "request_id": "2055136570293469184",
  "swapped": true
}

此代碼塊在浮窗中顯示

失敗返回

結構與 Retrieve Date 介面一致。特有的失敗返回範例：

參數錯誤（max_age 超出範圍）：

{ "code": 3002, "message": "max_age must be between 1 and 2400" }

              
              {
  "code": 3002,
  "message": "max_age must be between 1 and 2400"
}

此代碼塊在浮窗中顯示

錯誤碼

錯誤碼	HTTP Code	說明
`1000`	500	內部錯誤
`2001`	401	鑑權失敗，未攜帶正確的 token
`2002`	401	鑑權失敗，token 已過期或已被禁用
`2004`	403	無呼叫此 API 的權限
`3001`	400	請求參數格式無效，請檢查是否符合參數格式的 JSON 內容
`3002`	400	請求參數有誤，請檢查請求參數是否符合要求
`3005`	400	餘額不足
`5100`	400	SIM Swap 通用失敗
`5101`	400	該號碼不在 SIM Swap 服務覆蓋範圍內，包括國家、營運商、號段暫不支援或號碼無法識別