快速入門

全球行動網路基礎設施運作於稱為 SS7 信令網路的系統上。此網路促進電信業者之間的用戶資料交換、通話路由、簡訊傳輸以及即時行動連線狀態更新。每個行動網路都維護一個歸屬位置暫存器 (HLR) - 這是一個儲存其用戶重要資訊的核心資料庫。

HLR 查詢技術讓企業能夠查詢這些暫存器,並擷取任何行動電話號碼的即時連線和網路詳細資訊。這包括手機是否開機、目前分配到哪個網路、是否已攜碼、號碼是否有效或已停用,以及是否處於漫遊狀態。

HLR Lookups API 提供無縫的即時資料存取,讓企業能夠驗證行動號碼、優化路由,並增強客戶通訊。本文件將引導您整合 HLR Lookups 至您的軟體,實現即時行動情報的自動化擷取。

使用 HLR Lookups API

執行 HLR 查詢既快速又安全,且操作簡單。註冊並取得您的 API 金鑰後,您可以透過 POST /hlr-lookup 進行身分驗證並使用簡單的 HTTP POST 請求啟動即時查詢。或者,您可以選擇快速非同步 API 請求來處理大型資料集,並透過 webhook 將結果回傳至您的伺服器,詳情請參閱概念章節。

請求範例

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -H "X-Digest-Key: YOUR_API_KEY" \
          -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
          -H "X-Digest-Timestamp: UNIX_TIMESTAMP" \
          -d "@payload.json"

身分驗證透過 HTTP 標頭提供,而 payload.json 至少應包含以下 JSON 物件:

酬載範例

{
   "msisdn": "+14156226819"
}

成功執行後,您將收到包含指定行動號碼即時連線詳細資訊的回應。

成功回應 application/json

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

有關請求和回應屬性以及連線狀態的完整說明,請參閱 POST /hlr-lookup。

其他查詢服務

行動號碼可攜性 (MNP) 查詢

使用 MNP 查詢來確定網路歸屬和可攜性詳細資訊,無需查詢即時連線狀態。如果您只需要號碼的 MCCMNC,請參閱 POST /mnp-lookup。

號碼類型偵測 (NT) 查詢

透過 POST /nt-lookup 判斷電話號碼是屬於市話、行動電話、付費電話、VoIP、呼叫器或其他編號計畫範圍。

軟體開發套件 (SDK)

HLR Lookups API 可與任何程式語言的 REST 用戶端搭配使用,我們已在 GitHub 上發布 PHP、Ruby 和 NodeJS 的 SDK,協助您快速上手。

工具

為確保無縫的開發體驗,我們提供完整的工具套件,包括瀏覽器內 API 請求和 webhook 監控、IP 位址白名單、強大的身分驗證選項,以及身分驗證測試端點。

非開發人員?

HLR 查詢和號碼可攜性查詢無需任何編碼即可執行。深入了解我們的企業網頁用戶端和基於瀏覽器的報表功能。

身份驗證

為確保安全性和適當的存取控制,大多數對 HLR Lookups API 的請求都需要進行身份驗證。端點分為公開端點和受保護端點兩類。存取受保護端點時,您必須使用 API 金鑰和密鑰,透過 Digest-Auth 或 Basic-Auth 方法進行身份驗證。 Digest-Auth 是更安全的選項,強烈建議使用。使用 GET /auth-test 端點來驗證您的身份驗證設定。

API 金鑰和 API 密鑰

從 API 設定頁面取得您的 API 金鑰和密鑰。您也可以設定偏好的身份驗證方法,並啟用 IP 位址白名單以增強安全性。如果您懷疑 API 密鑰已被洩露,您可以隨時產生新的密鑰。

基本驗證摘要驗證 IP 白名單

標準基本驗證易於實作且廣泛支援。您可以在 HTTP 請求中將 API 金鑰和密鑰作為 user:pass 配對傳遞來進行身份驗證。

HTTP 基本驗證

curl 'https://YOUR_API_KEY:YOUR_API_SECRET@www.hlr-lookups.com/api/v2/auth-test'

這會發送一個 Authorization 標頭:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

建議:使用 SHA256 的 X-Basic 標頭

為提升安全性,您可以發送憑證的 SHA256 雜湊值,而非直接以 base64 傳輸。要使用此方法,請計算 YOUR_API_KEY:YOUR_API_SECRET 配對的雜湊值,並透過 X-Basic 標頭發送:

基本驗證請求

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: BASIC_AUTH_HASH"

基本驗證標頭

金鑰	類型	說明
`X-Basic`	string	`YOUR_API_KEY:YOUR_API_SECRET` 的 SHA256 雜湊值。雜湊中需包含冒號符號 (:)。	必填

程式碼範例

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

Digest-Auth 是保護 HLR Lookup API 受保護端點存取的建議方法。每個請求必須包含以下標頭:X-Digest-Key、X-Digest-Signature 和 X-Digest-Timestamp,說明如下。

請求範例

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

請求標頭

金鑰	類型	說明
`X-Digest-Key`	string	您的專屬 HLR Lookups API 金鑰。	必填
`X-Digest-Signature`	string	唯一的身份驗證簽章(見下文)。	必填
`X-Digest-Timestamp`	integer	目前的 Unix 時間戳記(另請參閱 `GET /time`)。	必填

建立簽章

X-Digest-Signature 使用 SHA256 HMAC 雜湊建立,並以您的 API 密鑰作為共享金鑰。

要雜湊的字串結構如下:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

. 符號代表字串串接。

摘要簽章組成元素

元素	類型	說明
`ENDPOINT_PATH`	string	請求的 API 端點,例如小寫的 `/auth-test`。
`UNIX_TIMESTAMP`	integer	目前的 Unix 時間戳記(必須在 30 秒內)。請參閱 `GET /time`。
`REQUEST_METHOD`	string	使用的 HTTP 方法,例如 `POST` 或 `GET`。
`REQUEST_BODY`	string	請求主體資料。`GET` 請求設定為 `null`。

程式碼範例

PHP

NodeJS

Ruby

$path = '/auth-test'
    $timestamp = time();
    $method = 'GET';
    $body = $method == 'GET' ? null : json_encode($params);
    $secret = 'YOUR_API_SECRET';

    $signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

require('crypto');

    let path = '/auth-test'
    let timestamp = Date.now() / 1000 | 0;
    let method = 'GET'
    let body = method === 'GET' ? '' : JSON.stringify(params)
    let secret = 'YOUR_API_SECRET'

    let signature = crypto.createHmac('sha256', secret)
                    .update(path + timestamp + method + body)
                    .digest('hex');

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

向上捲動

概念說明

透過我們的 HTTP REST API 在任何程式語言或系統中實作 HLR 查詢既簡單又高效。透過簡單的整合流程,您即可開始即時查詢行動網路,立即獲得電話號碼有效性、連線狀態及路由詳情等資訊。

選擇適當的 API 取決於您的特定使用情境。如果您需要即時查詢結果,例如 VoIP 電話、詐欺偵測或 SMS 路由等應用,同步 API 是最佳選擇。然而,如果您的使用情境涉及大量處理、批次查詢或大規模資料驗證,非同步 API 可提供優化效能,具備頻寬效率及批次查詢能力。

設定 API 使用我們的自訂路由選項,以優化速度、準確度及成本效益。您也可以將查詢結果儲存至儲存空間,以便輕鬆下載 CSV 和 JSON 報表,並透過網頁介面進行進階分析。

同步 HLR 查詢 API

POST /hlr-lookup 端點每次請求處理一個行動電話號碼 (MSISDN),並在 HTTP 回應本體中立即回傳結果。結果以 JSON 格式呈現,非常適合即時應用,包括行動號碼驗證、通話路由及 SMS 訊息傳送。

同步 API 呼叫包含直接的 HTTP 請求與回應。您的系統每次請求提交單一 MSISDN (行動號碼),並立即收到包含即時 HLR 查詢結果的 JSON 格式回應。此 API 專為需要即時驗證及連線檢查的使用情境而優化,例如詐欺偵測、VoIP 通話路由及 SMS 閘道優化。

非同步 HLR 查詢 API

POST /hlr-lookups 端點專為批次及大量處理而設計,允許您每次請求提交最多 1,000 個 MSISDN。此 API 不會立即回傳結果,而是使用自動化 webhook 將結果逐步傳送至您的伺服器。查詢結果透過 HTTP POST 回呼以 JSON 物件形式回傳。

非同步 API 針對速度、效率及擴展性進行優化。它消除了同步呼叫相關的網路延遲問題,非常適合需要高吞吐量查詢的企業。您的系統每次請求提交最多 1,000 個 MSISDN,我們的平台會平行處理,並透過 HTTP webhook 將結果批次回傳至您的伺服器,每次回呼最多傳送 1,000 筆結果。

SDK（軟體開發套件）

我們提供的 PHP、NodeJS 和 Ruby 軟體開發套件（SDK）可簡化整合流程，讓您能夠高效且輕鬆地連接 HLR Lookups API。

這些 SDK 提供預建函式、身份驗證處理和結構化 API 請求範本，可縮短開發時間並確保遵循最佳實務。

請前往 GitHub 瀏覽我們完整的 SDK 清單，立即開始整合。

PHP

NodeJS

Ruby

1   include('HLRLookupClient.class.php');
2
3   $client = new HLRLookupClient(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   );
8
9   $params = array('msisdn' => '+14156226819');
10  $response = $client->post('/hlr-lookup', $params);

在 GitHub 上查看 README.md

1   require('node-hlr-client');
2
3   let response = await client.post('/hlr-lookup', {msisdn: '+491788735000'});
4
5   if (response.status === 200) {
6      // lookup was successful
7      let data = response.data;
8   }

在 GitHub 上查看 README.md

1   require 'ruby_hlr_client/client'
2
3   client = HlrLookupsSDK::Client.new(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   )
8
9   params = { :msisdn => '+14156226819' }
10  response = client.get('/hlr-lookup', params)

在 GitHub 上查看 README.md

向上捲動

POST/hlr-lookup受保護

執行同步 HLR 查詢，直接從網路營運商取得即時的行動電話連線狀態與號碼可攜性資料。此端點適用於即時流量場景，當時效性應用程式需要立即驗證電話號碼目前是否可達（已連線）或無法接通（已關機）時使用。此外，它有助於區分有效號碼與無效、未知或虛假號碼。

對於不需要即時結果的大型資料集批次處理，建議使用專為高速批次處理最佳化的非同步 POST /hlr-lookups。

如果您主要關注的是取得行動號碼可攜性資料 (MCCMNC),而不需要即時連線狀態,POST /mnp-lookup 提供了一個具成本效益的行動號碼可攜性查詢替代方案。

請求成功回應錯誤回應狀態參考

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

請求內容

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

請求參數

金鑰	類型	說明	預設值	必填
`msisdn`	string	要查詢的行動電話號碼（MSISDN），須以國際格式提供（例如：+14156226819 或 0014156226819）。必須包含國碼。	null	必填
`route`	string(3)	選填的三字元識別碼，用於指定此次查詢的路由。設為 `null` 或省略此參數以套用您的自訂路由對應，或讓系統自動決定此次查詢的最佳路由。	null	選填
`storage`	string	選填的儲存識別碼，用於指定儲存結果的報表，以供人工審查、分析和報告使用。系統會自動附加當前月份的時間戳記。若省略或設為 `null`，系統將自動依月份分組結果以供報告使用。	null	選填

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

成功回應屬性

姓名	類型	說明	可為空值
`id`	string(12)	分配給此查詢請求的唯一識別碼。	false
`msisdn`	string	正在查詢的行動電話號碼,以國際格式顯示(例如:+14156226819 或 0014156226819)。	false
`connectivity_status`	string	指示是否成功取得號碼的連線狀態。可能的值:`CONNECTED` 、`ABSENT` 、`INVALID_MSISDN` 或 `UNDETERMINED` 。	false
`mccmnc`	string(5\|6)	五位或六位數的行動國家代碼(MCC)和行動網路代碼(MNC),用於識別目前與該電話號碼關聯的網路。	true
`mcc`	string(3)	三位數的行動國家代碼(MCC),用於識別電話號碼註冊所在的國家。	true
`mnc`	string(2\|3)	兩位或三位數的行動網路代碼(MNC),用於識別電話號碼所屬的特定網路。	true
`imsi`	string	國際行動用戶識別碼(IMSI),與此號碼關聯的 SIM 卡的唯一識別碼。可用性取決於網路配置。	true
`msin`	string(10)	行動營運商資料庫中的行動用戶識別號碼(MSIN)。可用性取決於網路配置。	true
`msc`	string(12)	目前處理此用戶通訊的行動交換中心(MSC)。可用性取決於網路配置。	true
`original_network_name`	string	與此號碼關聯的原始(本地)網路營運商名稱。	true
`original_country_name`	string	行動電話號碼最初註冊所在國家的完整名稱,以英文提供。	true
`original_country_code`	string(2)	代表電話號碼首次分配所在國家的兩字元 ISO 國家代碼。	true
`original_country_prefix`	string	對應於行動電話號碼原始國家的國際撥號代碼(國家電話代碼)。	true
`is_ported`	boolean	指示行動號碼是否已從其原始網路攜碼至不同的營運商。	true
`ported_network_name`	string	行動號碼已攜碼至的網路營運商名稱(如適用)。	true
`ported_country_name`	string	行動號碼已攜碼至的國家名稱(如適用)。	true
`ported_country_code`	string(2)	代表行動號碼已攜碼至的國家的兩字元 ISO 國家代碼(如適用)。	true
`ported_country_prefix`	string	行動號碼已攜碼至的國家的國際撥號代碼(國家電話代碼)(如適用)。	true
`is_roaming`	boolean	指示行動號碼目前是否在國外網路漫遊。漫遊狀態的可用性取決於行動網路營運商。	true
`roaming_network_name`	string	行動號碼目前漫遊所在的網路名稱(如適用)。	true
`roaming_country_name`	string	行動號碼目前漫遊所在的國家名稱(如適用)。	true
`roaming_country_code`	string(2)	行動號碼目前漫遊所在國家的兩字元 ISO 國家代碼(如適用)。	true
`roaming_country_prefix`	string	行動號碼目前漫遊所在國家的國際撥號代碼(國家電話代碼)(如適用)。	true
`cost`	string	以字串表示的十進位值,指示以歐元計價的查詢費用。	true
`timestamp`	string	包含時區的 W3C 格式時間戳記,指定查詢完成的時間。	true
`storage`	string	儲存查詢結果的儲存空間名稱。這對應於網頁介面中可用的報告名稱和 CSV 下載。	true
`route`	string(3)	三字元識別碼,指示用於此查詢請求的路由方法。	true
`processing_status`	string	查詢的處理結果。可能的值:`COMPLETED`(成功)、`REJECTED`(網路無法連線,未收費)或 `FAILED`(處理期間發生錯誤)。	false
`error_code`	integer	選擇性的內部錯誤代碼,為客戶支援提供額外的診斷資訊。	true
`error_description`	string	以英文純文字簡要說明給定的錯誤代碼(如有)。	true
`data_source`	string	此請求使用的資料來源。可能的值:`LIVE_HLR`(即時 HLR 查詢)或 `MNP_DB`(靜態行動號碼攜碼資料庫)。詳情請參閱路由選項。	false
`routing_instruction`	string	以冒號分隔的字串,描述請求中使用的路由指令。第一個部分在您指定路由時為 `STATIC`,自動路由時為 `AUTO`;第二個部分為路由識別碼,對於自動路由請求,第三個部分顯示路由決策所依據的來源(即 `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`)。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

狀態	說明
CONNECTED	號碼有效,目標手機目前已連接至行動網路。通話、簡訊及其他服務應能成功送達收件人。
ABSENT	號碼有效,但目標手機目前處於關機狀態或暫時超出網路覆蓋範圍。訊息或通話可能無法送達,直到裝置重新連接至網路為止。
INVALID_MSISDN	號碼無效或目前未分配給行動網路上的任何用戶。撥打此號碼的通話和訊息將無法送達。
UNDETERMINED	無法確定號碼的連線狀態。這可能是由於號碼無效、SS7 錯誤回應或與目標網路業者缺乏連線所致。請檢查錯誤代碼及其描述欄位以獲取更多診斷資訊。

向上捲動

POST/hlr-lookups受保護

啟動批次非同步 HLR 查詢，從網路營運商取得即時行動電話連線狀態與攜碼資料。查詢結果將透過 webhook 傳送至您的伺服器。此方法最適合處理大量無需立即回應的號碼，例如資料庫清理與驗證作業。若需即時應用（如來電路由或簡訊傳送），建議改用 POST /hlr-lookup 端點。

此端點適用於批次處理，可識別目前可接通（已連線）或無法接通（手機已關機）的電話號碼，同時過濾無效、未分配或虛假號碼。此外，還提供即時攜碼狀態 (MCCMNC) 與連線詳細資訊。

使用此端點前，請確保已設定 webhook URL 以非同步接收查詢結果。您可在 API 設定中進行設定。

請求成功回應錯誤回應 Webhooks 狀態參考

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

請求內容

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

請求參數

金鑰	類型	說明	預設值	必填
`msisdns`	array	國際格式的行動電話號碼 (MSISDN) 陣列（例如 +14156226819 或 0014156226819）。每次請求最多可包含 1000 個號碼。	null	必填
`route`	string(3)	選填的三字元識別碼，用於指定此次查詢的路由。設為 `null` 或省略此參數以套用您的自訂路由對應，或讓系統自動決定此次查詢的最佳路由。	null	選填
`storage`	string	選填的儲存識別碼，用於指定儲存結果的報表，以供人工審查、分析和報告使用。系統會自動附加當前月份的時間戳記。若省略或設為 `null`，系統將自動依月份分組結果以供報告使用。	null	選填

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

成功回應屬性

姓名	類型	說明	可為空值
`accepted`	array	包含唯一識別碼與已接受處理之 MSISDN 的物件清單。	false
`accepted_count`	integer	成功接受處理的 MSISDN 總數。	false
`rejected`	array	包含唯一識別碼與已拒絕處理之 MSISDN 的物件清單，通常是因為號碼無效。拒絕項目不收取費用。	false
`rejected_count`	integer	因驗證錯誤而拒絕的 MSISDN 總數。	false
`total_count`	integer	提交處理的已接受與已拒絕 MSISDN 總計數。	false
`cost`	string	以字串表示的十進位值，表示已接受查詢的總費用（歐元）。	false
`storage`	string	儲存查詢結果的儲存空間名稱，用於透過網頁介面進行報表與 CSV 下載。	false
`route`	string(3\|4)	指定此查詢請求所使用路由的三或四字元識別碼。若請求基於號碼的自動路由，則顯示 AUTO。	false
`webhook_urls`	array	在 API 設定中配置的 webhook URL。查詢結果將回傳至此處。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

處理 Webhook

提交後,我們的平台會開始處理提供的電話號碼,並將結果發送到您伺服器上預先指定的 webhook URL。結果以 HTTP POST 請求的形式傳輸,請求主體中包含 JSON 物件。

身份驗證

透過檢查 X-Signatures HTTP 標頭來驗證 webhook。

X-Signatures 標頭包含以分號分隔的簽章清單。清單中的每個簽章都使用您帳戶中配置的其中一個 API 密鑰生成。若要驗證 webhook,請使用您的 API 金鑰、密鑰和原始 HTTP 主體生成 SHA-256 雜湊值,然後將其與清單中的簽章進行比對。

若匹配成功,即可確認請求為真實且使用您控制的密鑰簽署。

程式碼範例

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

如果標頭中給定的任何簽章等於透過串連您的 API 金鑰、密鑰和 HTTP 主體計算出的 SHA256 雜湊值,則該請求有效。

確認接收

您的伺服器應回應 HTTP 狀態碼 200 OK 以確認成功接收。如果返回任何其他回應碼、發生逾時(10 秒)或出現任何其他傳送問題,系統將在一分鐘後自動重試 webhook。如果請求持續失敗,重試將遵循指數退避策略,後續嘗試將在 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 分鐘後進行。

此重試機制可確保將查詢結果傳送到您的基礎設施時達到最高可靠性。它可將因臨時網路問題或伺服器停機而導致資料遺失的風險降至最低。

Webhook 負載

{
   "type":"HLR",
   "results":[
      {
         "id":"3b4ac4b6ed1b",
         "msisdn":"+905536939460",
         "connectivity_status":"CONNECTED",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "imsi":"28603XXXXXXXXXX",
         "msin":"XXXXXXXXXX",
         "msc":"XXXXXXXXXX",
         "original_network_name":"Turk Telekom (AVEA)",
         "original_country_name":"Turkey",
         "original_country_code":"TR",
         "original_country_prefix":"+90",
         "is_ported":false,
         "ported_network_name":null,
         "ported_country_name":null,
         "ported_country_code":null,
         "ported_country_prefix":null,
         "is_roaming":false,
         "roaming_network_name":null,
         "roaming_country_name":null,
         "roaming_country_code":null,
         "roaming_country_prefix":null,
         "cost":"0.0100",
         "timestamp":"2020-08-13 00:04:38.261+0300",
         "storage":"ASYNC-API-2020-08",
         "route":"IP1",
         "processing_status":"COMPLETED",
         "error_code":null,
         "error_description":null,
         "data_source":"LIVE_HLR",
         "routing_instruction":"STATIC:IP1"
      }
   ]
}

Webhook 承載屬性

JSON 物件包含 type => HLR 屬性以及 results 屬性，後者包含查詢物件清單，詳細說明如下。

姓名	類型	說明	可為空值
`id`	string(12)	分配給此查詢請求的唯一識別碼。	false
`msisdn`	string	正在查詢的行動電話號碼,以國際格式顯示(例如:+14156226819 或 0014156226819)。	false
`connectivity_status`	string	指示是否成功取得號碼的連線狀態。可能的值:`CONNECTED` 、`ABSENT` 、`INVALID_MSISDN` 或 `UNDETERMINED` 。	false
`mccmnc`	string(5\|6)	五位或六位數的行動國家代碼(MCC)和行動網路代碼(MNC),用於識別目前與該電話號碼關聯的網路。	true
`mcc`	string(3)	三位數的行動國家代碼(MCC),用於識別電話號碼註冊所在的國家。	true
`mnc`	string(2\|3)	兩位或三位數的行動網路代碼(MNC),用於識別電話號碼所屬的特定網路。	true
`imsi`	string	國際行動用戶識別碼(IMSI),與此號碼關聯的 SIM 卡的唯一識別碼。可用性取決於網路配置。	true
`msin`	string(10)	行動營運商資料庫中的行動用戶識別號碼(MSIN)。可用性取決於網路配置。	true
`msc`	string(12)	目前處理此用戶通訊的行動交換中心(MSC)。可用性取決於網路配置。	true
`original_network_name`	string	與此號碼關聯的原始(本地)網路營運商名稱。	true
`original_country_name`	string	行動電話號碼最初註冊所在國家的完整名稱,以英文提供。	true
`original_country_code`	string(2)	代表電話號碼首次分配所在國家的兩字元 ISO 國家代碼。	true
`original_country_prefix`	string	對應於行動電話號碼原始國家的國際撥號代碼(國家電話代碼)。	true
`is_ported`	boolean	指示行動號碼是否已從其原始網路攜碼至不同的營運商。	true
`ported_network_name`	string	行動號碼已攜碼至的網路營運商名稱(如適用)。	true
`ported_country_name`	string	行動號碼已攜碼至的國家名稱(如適用)。	true
`ported_country_code`	string(2)	代表行動號碼已攜碼至的國家的兩字元 ISO 國家代碼(如適用)。	true
`ported_country_prefix`	string	行動號碼已攜碼至的國家的國際撥號代碼(國家電話代碼)(如適用)。	true
`is_roaming`	boolean	指示行動號碼目前是否在國外網路漫遊。漫遊狀態的可用性取決於行動網路營運商。	true
`roaming_network_name`	string	行動號碼目前漫遊所在的網路名稱(如適用)。	true
`roaming_country_name`	string	行動號碼目前漫遊所在的國家名稱(如適用)。	true
`roaming_country_code`	string(2)	行動號碼目前漫遊所在國家的兩字元 ISO 國家代碼(如適用)。	true
`roaming_country_prefix`	string	行動號碼目前漫遊所在國家的國際撥號代碼(國家電話代碼)(如適用)。	true
`cost`	string	以字串表示的十進位值,指示以歐元計價的查詢費用。	true
`timestamp`	string	包含時區的 W3C 格式時間戳記,指定查詢完成的時間。	true
`storage`	string	儲存查詢結果的儲存空間名稱。這對應於網頁介面中可用的報告名稱和 CSV 下載。	true
`route`	string(3)	三字元識別碼,指示用於此查詢請求的路由方法。	true
`processing_status`	string	查詢的處理結果。可能的值:`COMPLETED`(成功)、`REJECTED`(網路無法連線,未收費)或 `FAILED`(處理期間發生錯誤)。	false
`error_code`	integer	選擇性的內部錯誤代碼,為客戶支援提供額外的診斷資訊。	true
`error_description`	string	以英文純文字簡要說明給定的錯誤代碼(如有)。	true
`data_source`	string	此請求使用的資料來源。可能的值:`LIVE_HLR`(即時 HLR 查詢)或 `MNP_DB`(靜態行動號碼攜碼資料庫)。詳情請參閱路由選項。	false
`routing_instruction`	string	以冒號分隔的字串,描述請求中使用的路由指令。第一個部分在您指定路由時為 `STATIC`,自動路由時為 `AUTO`;第二個部分為路由識別碼,對於自動路由請求,第三個部分顯示路由決策所依據的來源(即 `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`)。	false

狀態	說明
CONNECTED	號碼有效,目標手機目前已連接至行動網路。通話、簡訊及其他服務應能成功送達收件人。
ABSENT	號碼有效,但目標手機目前處於關機狀態或暫時超出網路覆蓋範圍。訊息或通話可能無法送達,直到裝置重新連接至網路為止。
INVALID_MSISDN	號碼無效或目前未分配給行動網路上的任何用戶。撥打此號碼的通話和訊息將無法送達。
UNDETERMINED	無法確定號碼的連線狀態。這可能是由於號碼無效、SS7 錯誤回應或與目標網路業者缺乏連線所致。請檢查錯誤代碼及其描述欄位以獲取更多診斷資訊。

向上捲動

POST/mnp-lookup受保護

執行同步 MNP 查詢，提供行動號碼可攜性與網路資訊。若您的主要目標是即時提取指定行動電話號碼的當前 MCCMNC，並精確定位原始網路與當前網路，此端點最為適合。

對於不需要即時結果的大型資料集批次處理，建議使用專為高速批次處理最佳化的非同步 POST /mnp-lookups。

MNP 查詢可可靠地判定可攜性與網路資訊，但無法指示目標行動電話當前是否已連線至網路並可聯繫。若需提取即時連線資訊，請改用 POST /hlr-lookup 端點。

請求成功回應錯誤回應

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

請求內容

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

請求參數

金鑰	類型	說明	預設值	必填
`msisdn`	string	要查詢的行動電話號碼（MSISDN），須以國際格式提供（例如：+14156226819 或 0014156226819）。必須包含國碼。	null	必填
`route`	string(3)	選填的三字元識別碼，用於指定此次查詢的路由。設為 `null` 或省略此參數以套用您的自訂路由對應，或讓系統自動決定此次查詢的最佳路由。	null	選填
`storage`	string	選填的儲存識別碼，用於指定儲存結果的報表，以供人工審查、分析和報告使用。系統會自動附加當前月份的時間戳記。若省略或設為 `null`，系統將自動依月份分組結果以供報告使用。	null	選填

{
   "id":"e428acb1c0ae",
   "msisdn":"+14156226819",
   "query_status":"OK",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "is_ported":true,
   "original_network_name":"Verizon Wireless:6006 - SVR/2",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1415",
   "ported_network_name":"T-Mobile US:6529 - SVR/2",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "extra":"LRN:4154250000",
   "cost":"0.0050",
   "timestamp":"2020-08-05 21:21:33.490+0300",
   "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
   "route":"PTX",
   "error_code":null
}

成功回應屬性

姓名	類型	說明	可為空值
`id`	string(12)	此次查詢的唯一12字元識別碼。	false
`msisdn`	string	此次查詢請求中所評估的行動電話號碼。	false
`query_status`	string	指示可攜性和網路資訊的檢索是否成功。可能的值為 `OK` 或 `FAILED`。	false
`mccmnc`	string(5\|6)	五或六字元的 MCCMNC(行動國家代碼和行動網路代碼組合),用於識別該行動電話號碼目前所屬的網路。	true
`mcc`	string(3)	三字元的 MCC(行動國家代碼),代表與該行動電話號碼目前網路相關聯的國家。	true
`mnc`	string(2\|3)	兩或三字元的 MNC(行動網路代碼),用於識別該行動電話號碼的目前網路業者。	true
`is_ported`	boolean	指示該電話號碼是否已從原始網路攜碼至新業者。	true
`original_network_name`	string	任意字串(英文),指定所檢查行動電話號碼的原始網路業者名稱。	true
`original_country_name`	string	任意字串(英文),指示所檢查行動電話號碼的原始國家。	true
`original_country_code`	string(2)	兩字元的 ISO 國家代碼,代表所檢查行動電話號碼的原始國家。	true
`original_country_prefix`	string	與所檢查行動電話號碼相關聯的原始國家撥號代碼。	true
`ported_network_name`	string	指定所檢查行動電話號碼已攜碼至的網路業者(如適用)。	true
`ported_country_name`	string	指定所檢查行動電話號碼已攜碼至的國家(如適用)。	true
`ported_country_code`	string(2)	兩字元的 ISO 國家代碼,代表所檢查行動電話號碼已攜碼至的國家(如適用)。	true
`ported_country_prefix`	string	所檢查行動電話號碼已攜碼至的國家撥號代碼(如適用)。	true
`extra`	string	任意字串,提供有關該電話號碼的選擇性額外詳細資訊。	true
`cost`	string	以字串表示的十進位值,指示此次查詢的費用(歐元)。	true
`timestamp`	string	W3C 格式的時間戳記(包含時區資訊),指示查詢完成的時間。	true
`storage`	string	查詢結果附加至的儲存名稱(或報告名稱)。此用於透過網頁介面進行 CSV 下載和報告。	true
`route`	string(3)	三字元識別碼,指定此次查詢請求所使用的路由。	true
`error_code`	integer	選擇性的內部錯誤代碼,為客戶支援診斷提供額外的背景資訊。	true

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

POST/mnp-lookups受保護

啟動批次非同步 MNP(行動號碼可攜)查詢,即時取得當前 MCCMNC 並精確定位原始網路與當前網路。查詢結果將透過 webhook 傳送至您的伺服器。此方法最適合處理大量無需立即回應的號碼，例如資料庫清理與驗證作業。若需即時應用（如來電路由或簡訊傳送），建議改用 POST /mnp-lookup 端點。

MNP 查詢可可靠地判定可攜性與網路資訊，但無法指示目標行動電話當前是否已連線至網路並可聯繫。若需提取即時連線資訊，請改用 POST /hlr-lookups 端點。

使用此端點前，請確保已設定 webhook URL 以非同步接收查詢結果。您可在 API 設定中進行設定。

請求成功回應錯誤回應 Webhooks

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

請求內容

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

請求參數

金鑰	類型	說明	預設值	必填
`msisdns`	array	國際格式的行動電話號碼 (MSISDN) 陣列（例如 +14156226819 或 0014156226819）。每次請求最多可包含 1000 個號碼。	null	必填
`route`	string(3)	可選的三字元識別碼,用於指定此次查詢的路由。設定為 `null` 或省略此參數以套用您的自訂路由對應,或讓系統自動判定此請求的最佳路由。	null	選填
`storage`	string	選填的儲存識別碼，用於指定儲存結果的報表，以供人工審查、分析和報告使用。系統會自動附加當前月份的時間戳記。若省略或設為 `null`，系統將自動依月份分組結果以供報告使用。	null	選填

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

成功回應屬性

姓名	類型	說明	可為空值
`accepted`	array	包含唯一識別碼與已接受處理之 MSISDN 的物件清單。	false
`accepted_count`	integer	成功接受處理的 MSISDN 總數。	false
`rejected`	array	包含唯一識別碼與已拒絕處理之 MSISDN 的物件清單，通常是因為號碼無效。拒絕項目不收取費用。	false
`rejected_count`	integer	因驗證錯誤而拒絕的 MSISDN 總數。	false
`total_count`	integer	提交處理的已接受與已拒絕 MSISDN 總計數。	false
`cost`	string	以字串表示的十進位值，表示已接受查詢的總費用（歐元）。	false
`storage`	string	儲存查詢結果的儲存空間名稱，用於透過網頁介面進行報表與 CSV 下載。	false
`route`	string(3)	三字元識別碼,指定此次查詢請求所使用的路由。	false
`webhook_urls`	array	在 API 設定中配置的 webhook URL。查詢結果將回傳至此處。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

處理 Webhook

提交後,我們的平台會開始處理提供的電話號碼,並將結果發送到您伺服器上預先指定的 webhook URL。結果以 HTTP POST 請求的形式傳輸,請求主體中包含 JSON 物件。

身份驗證

透過檢查 X-Signatures HTTP 標頭來驗證 webhook。

X-Signatures 標頭包含以分號分隔的簽章清單。清單中的每個簽章都使用您帳戶中配置的其中一個 API 密鑰生成。若要驗證 webhook,請使用您的 API 金鑰、密鑰和原始 HTTP 主體生成 SHA-256 雜湊值,然後將其與清單中的簽章進行比對。

若匹配成功,即可確認請求為真實且使用您控制的密鑰簽署。

程式碼範例

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

如果標頭中給定的任何簽章等於透過串連您的 API 金鑰、密鑰和 HTTP 主體計算出的 SHA256 雜湊值,則該請求有效。

確認接收

您的伺服器應回應 HTTP 狀態碼 200 OK 以確認成功接收。如果返回任何其他回應碼、發生逾時(10 秒)或出現任何其他傳送問題,系統將在一分鐘後自動重試 webhook。如果請求持續失敗,重試將遵循指數退避策略,後續嘗試將在 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 分鐘後進行。

此重試機制可確保將查詢結果傳送到您的基礎設施時達到最高可靠性。它可將因臨時網路問題或伺服器停機而導致資料遺失的風險降至最低。

Webhook 負載

{
    "type":"MNP",
    "results":[
        {
           "id":"e428acb1c0ae",
           "msisdn":"+14156226819",
           "query_status":"OK",
           "mccmnc":"310260",
           "mcc":"310",
           "mnc":"260",
           "is_ported":true,
           "original_network_name":"Verizon Wireless:6006 - SVR/2",
           "original_country_name":"United States",
           "original_country_code":"US",
           "original_country_prefix":"+1415",
           "ported_network_name":"T-Mobile US:6529 - SVR/2",
           "ported_country_name":"United States",
           "ported_country_code":"US",
           "ported_country_prefix":"+1",
           "extra":"LRN:4154250000",
           "cost":"0.0050",
           "timestamp":"2020-08-05 21:21:33.490+0300",
           "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
           "route":"PTX",
           "error_code":null
        }
    ]
}

Webhook 承載屬性

JSON 物件包含 type => MNP 屬性以及 results 屬性，後者包含查詢物件清單，詳細說明如下。

姓名	類型	說明	可為空值
`id`	string(12)	此次查詢的唯一12字元識別碼。	false
`msisdn`	string	此次查詢請求中所評估的行動電話號碼。	false
`query_status`	string	指示可攜性和網路資訊的檢索是否成功。可能的值為 `OK` 或 `FAILED`。	false
`mccmnc`	string(5\|6)	五或六字元的 MCCMNC(行動國家代碼和行動網路代碼組合),用於識別該行動電話號碼目前所屬的網路。	true
`mcc`	string(3)	三字元的 MCC(行動國家代碼),代表與該行動電話號碼目前網路相關聯的國家。	true
`mnc`	string(2\|3)	兩或三字元的 MNC(行動網路代碼),用於識別該行動電話號碼的目前網路業者。	true
`is_ported`	boolean	指示該電話號碼是否已從原始網路攜碼至新業者。	true
`original_network_name`	string	任意字串(英文),指定所檢查行動電話號碼的原始網路業者名稱。	true
`original_country_name`	string	任意字串(英文),指示所檢查行動電話號碼的原始國家。	true
`original_country_code`	string(2)	兩字元的 ISO 國家代碼,代表所檢查行動電話號碼的原始國家。	true
`original_country_prefix`	string	與所檢查行動電話號碼相關聯的原始國家撥號代碼。	true
`ported_network_name`	string	指定所檢查行動電話號碼已攜碼至的網路業者(如適用)。	true
`ported_country_name`	string	指定所檢查行動電話號碼已攜碼至的國家(如適用)。	true
`ported_country_code`	string(2)	兩字元的 ISO 國家代碼,代表所檢查行動電話號碼已攜碼至的國家(如適用)。	true
`ported_country_prefix`	string	所檢查行動電話號碼已攜碼至的國家撥號代碼(如適用)。	true
`extra`	string	任意字串,提供有關該電話號碼的選擇性額外詳細資訊。	true
`cost`	string	以字串表示的十進位值,指示此次查詢的費用(歐元)。	true
`timestamp`	string	W3C 格式的時間戳記(包含時區資訊),指示查詢完成的時間。	true
`storage`	string	查詢結果附加至的儲存名稱(或報告名稱)。此用於透過網頁介面進行 CSV 下載和報告。	true
`route`	string(3)	三字元識別碼,指定此次查詢請求所使用的路由。	true
`error_code`	integer	選擇性的內部錯誤代碼,為客戶支援診斷提供額外的背景資訊。	true

向上捲動

POST/nt-lookup受保護

執行同步號碼類型 (NT) 查詢。如果您的主要目標是即時判斷所提供的電話號碼是否屬於固網、行動網路、高費率、VoIP、呼叫器或其他編號計劃範圍，此端點是理想選擇。

NT 查詢能可靠地偵測電話號碼類型；但不會指示目標號碼目前是否已連接至網路且可接通。如需取得即時連線資訊，請使用 POST /hlr-lookup 端點。

如果您的使用情境需要準確的網路與可攜性資訊 (MCCMNC)，但不需要即時連線狀態，請使用 POST /mnp-lookup 端點進行行動號碼可攜性查詢。

請求成功回應錯誤回應類型參考

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

請求內容

{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

請求參數

金鑰	類型	說明	預設值	必填
`number`	string	國際格式的電話號碼（例如 +4989702626 或 004989702626）。	null	mandatory
`route`	string(3)	選填的三字元識別碼，用於指定此查詢的路由。設定為 `null` 或省略此參數，以套用您的自訂路由對應，或讓系統自動決定此請求的最佳路由。	null	選填
`storage`	string	選填的儲存識別碼，用於指定儲存結果的報表，以供人工審查、分析和報告使用。系統會自動附加當前月份的時間戳記。若省略或設為 `null`，系統將自動依月份分組結果以供報告使用。	null	選填

{
     "id":"2ed0788379c6",
     "number":"+4989702626",
     "number_type":"LANDLINE",
     "query_status":"OK",
     "is_valid":true,
     "invalid_reason":null,
     "is_possibly_ported":false,
     "is_vanity_number":false,
     "qualifies_for_hlr_lookup":false,
     "mccmnc":null,
     "mcc":null,
     "mnc":null,
     "original_network_name":null,
     "original_country_name":"Germany",
     "original_country_code":"DE",
     "regions":[
        "Munich"
     ],
     "timezones":[
        "Europe/Berlin"
     ],
     "info_text":"This is a landline number.",
     "cost":"0.0050",
     "timestamp":"2015-12-04 10:36:41.866283+00",
     "storage":"SYNC-API-NT-2015-12",
     "route":"LC1"
}

成功回應屬性

姓名	類型	說明	可為空值
`id`	string(12)	分配給此查詢請求的唯一識別碼。	false
`number`	string	此次查詢請求中所評估的電話號碼。	false
`number_type`	string	偵測到的號碼類型。可能的值包括:`LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` 。	false
`query_status`	string	指示是否成功取得號碼類型資訊。成功時返回 `OK`,查詢失敗時返回 `FAILED`。	false
`is_valid`	boolean	指示電話號碼在語法上是否有效。	true
`invalid_reason`	string	以英文純文字訊息說明電話號碼被視為無效的原因(例如 "too short" 或 "invalid prefix"),若號碼有效則為 `null`。	true
`is_possibly_ported`	boolean	指示電話號碼是否可能已從原始電信業者攜碼至其他業者。如需確切的攜碼資訊,請使用 MNP 查詢。	true
`is_vanity_number`	boolean	指示電話號碼是否為虛榮號碼,即包含字母字元。	true
`qualifies_for_hlr_lookup`	boolean	指示電話號碼是否符合透過 HLR 查詢進行額外查詢的資格。	true
`mccmnc`	string(5\|6)	代表 MCCMNC 組合(行動國家代碼和行動網路代碼)的五或六字元字串,用於識別行動電話號碼的原始網路。	true
`mcc`	string(3)	代表 MCC(行動國家代碼)的三字元字串,用於識別與電話號碼原始行動網路相關聯的國家。	true
`mnc`	string(2\|3)	代表 MNC(行動網路代碼)的兩或三字元字串,用於識別電話號碼的原始行動網路業者。	true
`original_network_name`	string	以英文純文字字串指定所檢查行動電話號碼的原始網路業者名稱。	true
`original_country_name`	string	以英文純文字字串指定與所檢查行動電話號碼相關聯的原始國家。	true
`original_country_code`	string(2)	表示所檢查行動電話號碼原始國家的兩字元 ISO 國家代碼。	true
`regions`	array	以英文可讀字串列表指定與此電話號碼相關聯的地理區域。	true
`timezones`	array	與此電話號碼相關聯的時區列表(Olson 格式)。	true
`info_text`	string	可能包含有關電話號碼額外資訊的任意字串。	true
`cost`	string	以字串表示的十進位值,指示此次查詢的費用(以歐元計)。	true
`timestamp`	string	W3C 格式的時間戳記(包含時區),指示查詢完成的時間。	true
`storage`	string	指定查詢結果已附加至的儲存名稱。此名稱對應於透過網頁介面進行 CSV 下載和分析時使用的報告名稱。	true
`route`	string(3)	三字元識別碼,指定此次查詢請求所使用的路由。	true

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

類型	說明
LANDLINE	市話號碼。
MOBILE	行動電話號碼。符合 HLR 查詢資格，可取得額外的連線狀態、網路、攜碼及漫遊資訊。
MOBILE_OR_LANDLINE	市話或行動電話號碼。可能符合 HLR 查詢資格。
TOLL_FREE	免付費電話號碼。
PREMIUM_RATE	付費電話號碼，需支付額外費用。
SHARED_COST	分攤付費電話號碼。通常比付費電話號碼便宜。
VOIP	網路電話號碼。包含 TSoIP 電話號碼（IP 語音服務）。
PAGER	呼叫器號碼。通常不具備語音功能。
UAN	統一接取號碼（公司代表號）。可轉接至特定辦公室，但允許公司使用單一號碼。
VOICEMAIL	語音信箱號碼。
UNKNOWN	無法判定號碼類型。

向上捲動

POST/nt-lookups 受保護

此端點會執行一系列非同步號碼類型查詢，並透過 webhook 將結果回傳至您的伺服器。適用於判斷指定電話號碼是否屬於市話、行動電話、付費電話、VoIP、呼叫器或其他編號計畫範圍。針對大量號碼的快速處理進行最佳化，此端點非常適合批次作業(例如資料庫清理)。若需處理即時流量和時效性要求較高的使用情境，請改用 POST /nt-lookup 端點。

您需要在 API 設定中指定 webhook URL，方可呼叫此端點。

請求成功回應錯誤回應 Webhooks 類型參考

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

請求內容

{
   "numbers":["+14156226819","+4989702626"],
   "route":null,
   "storage":null
}

請求參數

金鑰	類型	說明	預設值	必填
`numbers`	array	國際格式的電話號碼陣列(例如 +14156226819 或 004989702626)。每次請求最多可包含 1000 個號碼。	null	必填
`route`	string(3)	選填的三字元識別碼，用於指定此查詢的路由。設定為 `null` 或省略此參數，即可套用您的自訂路由對應，或讓系統自動決定此請求的最佳路由。	null	選填
`storage`	string	選填的儲存識別碼，用於指定儲存結果的報表，以供人工審查、分析和報告使用。系統會自動附加當前月份的時間戳記。若省略或設為 `null`，系統將自動依月份分組結果以供報告使用。	null	選填

{
   "accepted":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "number":"+31"
      }
   ],
   "rejected_count":2,
   "total_count":3,
   "cost":0.005,
   "storage":"ASYNC-API-NT-2020-08",
   "route":"LC1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

成功回應屬性

姓名	類型	說明	可為空值
`accepted`	array	物件陣列，每個物件包含唯一識別碼和已接受處理的電話號碼。	false
`accepted_count`	integer	已接受處理的電話號碼總數。	false
`rejected`	array	物件陣列，每個物件包含唯一識別碼和被拒絕處理的電話號碼。通常這些號碼無效，不會收取費用。	false
`rejected_count`	integer	被拒絕處理的電話號碼總數。	false
`total_count`	integer	已提交處理的已接受和被拒絕電話號碼總數。	false
`cost`	string	代表這些查詢費用的十進位值字串，單位為歐元。	false
`storage`	string	查詢結果所附加的儲存空間(報表)名稱。此名稱用於透過網頁介面下載 CSV 和進行分析。	false
`route`	string(3)	三字元識別碼，用於指定此查詢請求所使用的路由。	false
`webhook_urls`	array	在 API 設定中配置的 webhook URL。查詢結果將回傳至此處。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

處理 Webhook

提交後,我們的平台會開始處理提供的電話號碼,並將結果發送到您伺服器上預先指定的 webhook URL。結果以 HTTP POST 請求的形式傳輸,請求主體中包含 JSON 物件。

身份驗證

透過檢查 X-Signatures HTTP 標頭來驗證 webhook。

X-Signatures 標頭包含以分號分隔的簽章清單。清單中的每個簽章都使用您帳戶中配置的其中一個 API 密鑰生成。若要驗證 webhook,請使用您的 API 金鑰、密鑰和原始 HTTP 主體生成 SHA-256 雜湊值,然後將其與清單中的簽章進行比對。

若匹配成功,即可確認請求為真實且使用您控制的密鑰簽署。

程式碼範例

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

如果標頭中給定的任何簽章等於透過串連您的 API 金鑰、密鑰和 HTTP 主體計算出的 SHA256 雜湊值,則該請求有效。

確認接收

您的伺服器應回應 HTTP 狀態碼 200 OK 以確認成功接收。如果返回任何其他回應碼、發生逾時(10 秒)或出現任何其他傳送問題,系統將在一分鐘後自動重試 webhook。如果請求持續失敗,重試將遵循指數退避策略,後續嘗試將在 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 分鐘後進行。

此重試機制可確保將查詢結果傳送到您的基礎設施時達到最高可靠性。它可將因臨時網路問題或伺服器停機而導致資料遺失的風險降至最低。

Webhook 負載

{
   "type":"NT",
   "results":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460",
         "numbertype":"MOBILE",
         "state":"COMPLETED",
         "isvalid":"Yes",
         "invalidreason":null,
         "ispossiblyported":"Yes",
         "isvanitynumber":"No",
         "qualifiesforhlrlookup":"Yes",
         "originalcarrier":"Turk Telekom (AVEA)",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "countrycode":"TR",
         "regions":[
            "Turkey"
         ],
         "timezones":[
            "Europe\/Istanbul"
         ],
         "infotext":"This number qualifies for HLR lookups. Determine if this subscriber number is connected, absent or invalid by running an HLR lookup. This is a mobile number and might be in roaming state. Run an HLR lookup to obtain roaming information (if available). This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup.",
         "usercharge":"0.0050",
         "inserttime":"2020-08-13 01:57:15.897+0300",
         "storage":"ASYNC-API-NT-2020-08",
         "route":"LC1",
         "interface":"Async API"
      }
   ]
}

Webhook 承載屬性

JSON 物件包含 type => NT 屬性以及 results 屬性，後者包含查詢物件清單，詳細說明如下。

姓名	類型	說明	可為空值
`id`	string(12)	分配給此查詢請求的唯一識別碼。	false
`number`	string	此次查詢請求中所評估的電話號碼。	false
`number_type`	string	偵測到的號碼類型。可能的值包括:`LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` 。	false
`query_status`	string	指示是否成功取得號碼類型資訊。成功時返回 `OK`,查詢失敗時返回 `FAILED`。	false
`is_valid`	boolean	指示電話號碼在語法上是否有效。	true
`invalid_reason`	string	以英文純文字訊息說明電話號碼被視為無效的原因(例如 "too short" 或 "invalid prefix"),若號碼有效則為 `null`。	true
`is_possibly_ported`	boolean	指示電話號碼是否可能已從原始電信業者攜碼至其他業者。如需確切的攜碼資訊,請使用 MNP 查詢。	true
`is_vanity_number`	boolean	指示電話號碼是否為虛榮號碼,即包含字母字元。	true
`qualifies_for_hlr_lookup`	boolean	指示電話號碼是否符合透過 HLR 查詢進行額外查詢的資格。	true
`mccmnc`	string(5\|6)	代表 MCCMNC 組合(行動國家代碼和行動網路代碼)的五或六字元字串,用於識別行動電話號碼的原始網路。	true
`mcc`	string(3)	代表 MCC(行動國家代碼)的三字元字串,用於識別與電話號碼原始行動網路相關聯的國家。	true
`mnc`	string(2\|3)	代表 MNC(行動網路代碼)的兩或三字元字串,用於識別電話號碼的原始行動網路業者。	true
`original_network_name`	string	以英文純文字字串指定所檢查行動電話號碼的原始網路業者名稱。	true
`original_country_name`	string	以英文純文字字串指定與所檢查行動電話號碼相關聯的原始國家。	true
`original_country_code`	string(2)	表示所檢查行動電話號碼原始國家的兩字元 ISO 國家代碼。	true
`regions`	array	以英文可讀字串列表指定與此電話號碼相關聯的地理區域。	true
`timezones`	array	與此電話號碼相關聯的時區列表(Olson 格式)。	true
`info_text`	string	可能包含有關電話號碼額外資訊的任意字串。	true
`cost`	string	以字串表示的十進位值,指示此次查詢的費用(以歐元計)。	true
`timestamp`	string	W3C 格式的時間戳記(包含時區),指示查詢完成的時間。	true
`storage`	string	指定查詢結果已附加至的儲存名稱。此名稱對應於透過網頁介面進行 CSV 下載和分析時使用的報告名稱。	true
`route`	string(3)	三字元識別碼,指定此次查詢請求所使用的路由。	true

類型	說明
LANDLINE	市話號碼。
MOBILE	行動電話號碼。符合 HLR 查詢資格，可取得額外的連線狀態、網路、攜碼及漫遊資訊。
MOBILE_OR_LANDLINE	市話或行動電話號碼。可能符合 HLR 查詢資格。
TOLL_FREE	免付費電話號碼。
PREMIUM_RATE	付費電話號碼，需支付額外費用。
SHARED_COST	分攤付費電話號碼。通常比付費電話號碼便宜。
VOIP	網路電話號碼。包含 TSoIP 電話號碼（IP 語音服務）。
PAGER	呼叫器號碼。通常不具備語音功能。
UAN	統一接取號碼（公司代表號）。可轉接至特定辦公室，但允許公司使用單一號碼。
VOICEMAIL	語音信箱號碼。
UNKNOWN	無法判定號碼類型。

向上捲動

GET/route受保護

取得在執行 HLR 查詢時未指定 route 參數的情況下自動選擇的路由。

自動路由選擇基於可透過 GET /hlr-coverage 端點取得的路由映射表，該映射表主要源自 GET /routing-map。您可以在帳戶設定中自訂路由映射表並定義自訂規則。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

請求參數

金鑰	類型	說明	預設值	必填
`msisdn`	string	要取得自動選擇路由資訊的 MSISDN。	null	必填

{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

成功回應屬性

姓名	類型	說明	可為空值
`route`	string	建議的路由。	false
`confidence_level`	string	選擇此路由的信心水準,即 `LOW`、`NORMAL`、`HIGH`、`MNP_FALLBACK`。	false
`mccmnc`	string	此號碼基於編號計畫的 MCCMNC。	false
`origin`	string	路由決策所基於的來源，即 `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/routes受保護

此端點會回傳可用的 HLR、MNP 和 NT 路由清單。每個路由及其功能和限制說明請參閱路由詳細資訊頁面。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/routes'

{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

成功回應屬性

姓名	類型	說明	可為空值
`routes`	object	依路由類型分組的路由物件。	false
`HLR\|MNP\|NT`	string[]	包含路由識別碼清單。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/routing-map受保護

取得目前套用於您帳戶 HLR 查詢的自動路由設定。當您提交 HLR 查詢而未指定 route 參數時,將使用此預設設定。您可以在帳戶設定中自訂路由對應並建立自訂規則。

設定層級從國家層級規則向下延伸至 MCCMNC 層級規則,最後到個別電話號碼前綴對應。實際運作時,個別電話號碼前綴對應優先於衝突的 MCCMNC 指定,而 MCCMNC 指定則優先於國家層級規則。請注意,啟用 MNP 備援時,將覆寫任何衝突的自訂規則。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/routing-map'

{
   "routing":{
      "map":{
         "defaultRoute":"V11",
         "mnpFallback":true,
         "mccmncs":[
            {
               "mccmnc":20201,
               "countrycode":"GR",
               "route":"E10",
               "mno":"Cosmote",
               "confidence":"HIGH",
               "origin":"SCORE"
            }
         ],
         "prefixes":[
            {
               "countrycode":"DE",
               "cns":"+4917821",
               "route":"DV8",
               "mccmnc":"26203",
               "mno":"O2"
            }
         ],
         "countries":[
            {
               "countrycode":"US",
               "route":"DV8"
            }
         ]
      }
   }
}

成功回應屬性

姓名	類型	說明	可為空值
`default_route`	string	當無法為 MSISDN 確定偏好路由選項且無自訂路由規則適用時所使用的預設路由。	false
`mnp_fallback`	boolean	指示是否已啟用 MNP 備援。啟用後,當網路不支援 HLR 查詢(連線狀態無法取得)時,系統將改為執行 MNP 查詢。	false
`mccmncs`	array	MCCMNC 代碼與其自動選取路由的對應。對指定 MCCMNC 中的號碼執行 HLR 查詢時,將使用對應的路由。	false
`mccmnc`	string(5\|6)	五位或六位字元的 MCCMNC(行動國家代碼與行動網路代碼組合),用於識別行動網路業者。	false
`countrycode`	string(2)	兩位字元的 ISO 國家代碼,識別網路所屬國家。	false
`route`	string(3)	為該網路選取的路由。	false
`mno`	string	此網路營運所使用的消費者品牌名稱。	false
`confidence`	string	選取時的信賴等級。可能的值為:HIGH、NORMAL、LOW、MNP_REDIRECT。若為後者,系統會將此網路的流量重新導向至 MNP(若您的帳戶已啟用此行為)。否則將使用帳戶中的預設路由。	false
`origin`	string	選取所依據的來源。可能的值為:`SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false
`prefixes`	array	您帳戶中設定的自訂前綴路由規則清單(如有)。	false
`countrycode`	string(2)	兩位字元的 ISO 國家代碼,識別前綴所屬國家。	false
`cns`	string	路由規則適用的前綴。	false
`route`	string(3)	為該前綴選取的路由。	false
`mccmnc`	string(5\|6)	五位或六位字元的 MCCMNC(行動國家代碼與行動網路代碼組合),用於識別行動網路業者。	true
`mno`	string	此網路營運所使用的消費者品牌名稱。	true
`countries`	array	您帳戶中設定的自訂國家規則清單(如有)。	false
`countrycode`	string(2)	兩位字元的 ISO 國家代碼,識別國家。	false
`route`	string(3)	為該國家選取的路由。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/hlr-coverage 受保護

提供 HLR 覆蓋率洞察以支援數據驅動決策。此端點協助您分析跨行動網路的即時 HLR 路由選項,識別目標地區最有效的路徑,並配置自動路由。

來自 GET /route 的推薦路由是基於此處檢索的覆蓋率資料。覆蓋率資料也可在網路覆蓋率頁面查看。您可以在帳戶設定中進一步自訂路由地圖並定義規則。

我們建議您熟悉此指南,以協助解讀結果。

請求成功回應錯誤回應狀態參考

curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

請求參數

金鑰	類型	說明	預設值	必填
`countrycode`	string(2)	必填的兩字母 ISO 國家代碼,用於篩選結果,僅返回與指定國家相關的記錄。	null	必填
`sample_size`	string	指定樣本大小的選填參數。可能的值為 `LARGE`、`MEDIUM`、`SMALL`。較大的樣本涵蓋較長的時間範圍,較小的樣本涵蓋最近的時間範圍。	LARGE	選填

{
   "name":"Germany",
   "countrycode":"DE",
   "prefix":"+49",
   "mccs":[
      "262"
   ],
   "carriers":[
      {
         "mno":"Telekom",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "routes":[
            {
               "route":"V11",
               "selected":true,
               "selection_confidence":"HIGH",
               "n":361579,
               "CONNECTED":275273,
               "CONNECTED_PCT":76.13,
               "ABSENT":21529,
               "ABSENT_PCT":5.95,
               "INVALID_MSISDN":62582,
               "INVALID_MSISDN_PCT":17.3,
               "UNDETERMINED":2195,
               "UNDETERMINED_PCT":0.6
            },
            {
               "route":"E10",
               "selected":false,
               "selection_confidence":null,
               "n":122600,
               "CONNECTED":13721,
               "CONNECTED_PCT":11.19,
               "ABSENT":133,
               "ABSENT_PCT":0.1,
               "INVALID_MSISDN":55,
               "INVALID_MSISDN_PCT":0.04,
               "UNDETERMINED":108691,
               "UNDETERMINED_PCT":88.65
            }
         ]
      }
   ]
}

成功回應屬性

姓名	類型	說明	可為空值
`name`	string	所選國家的英文名稱純文字。	false
`countrycode`	string(2)	所選國家的兩字元 ISO 國家代碼。	false
`prefix`	string	所選國家的國際撥號前綴。	false
`mccs`	string[]	與所選國家相關的 MCC(行動國家代碼)清單。	false
`carriers`	object[]	包含路由特定連線指標的電信業者物件清單。	false
`mno`	string	行動網路業者的英文名稱純文字。	false
`mccmnc`	string	行動網路業者的 MCCMNC。	false
`mcc`	string	行動網路業者的 MCC(行動國家代碼)。	false
`mnc`	string	行動網路業者的 MNC(行動網路代碼)。	false
`routes`	object[]	路由特定連線結果清單。	false
`route`	string	連線資訊所適用的路由。	false
`selected`	bool	指示這是否為自動路由所選擇的路由。	false
`selection_confidence`	string	選擇此路由的信心水準,即 `LOW`、`NORMAL`、`HIGH`、`MNP_FALLBACK`。如果這不是所選路由,則包含 null。	true
`n`	int	此樣本中的查詢總數。	false
`CONNECTED`	int	返回 CONNECTED 狀態的 HLR 查詢數量。	false
`CONNECTED_PCT`	float	返回 CONNECTED 狀態的 HLR 查詢百分比。	false
`ABSENT`	int	返回 ABSENT 狀態的 HLR 查詢數量。	false
`ABSENT_PCT`	float	返回 ABSENT 狀態的 HLR 查詢百分比。	false
`INVALID_MSISDN`	int	返回 INVALID_MSISDN 狀態的 HLR 查詢數量。	false
`INVALID_MSISDN_PCT`	float	返回 INVALID_MSISDN 狀態的 HLR 查詢百分比。	false
`UNDETERMINED`	int	返回 UNDETERMINED 狀態的 HLR 查詢數量。	false
`UNDETERMINED_PCT`	float	返回 UNDETERMINED 狀態的 HLR 查詢百分比。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

狀態	說明
CONNECTED	號碼有效,目標手機目前已連接至行動網路。通話、簡訊及其他服務應能成功送達收件人。
ABSENT	號碼有效,但目標手機目前處於關機狀態或暫時超出網路覆蓋範圍。訊息或通話可能無法送達,直到裝置重新連接至網路為止。
INVALID_MSISDN	號碼無效或目前未分配給行動網路上的任何用戶。撥打此號碼的通話和訊息將無法送達。
UNDETERMINED	無法確定號碼的連線狀態。這可能是由於號碼無效、SS7 錯誤回應或與目標網路業者缺乏連線所致。請檢查錯誤代碼及其描述欄位以獲取更多診斷資訊。

向上捲動

GET/mnp-coverage受保護

此端點返回目前支援行動號碼可攜性查詢的行動網路業者清單,以及其對應的 MCCMNC 識別碼。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

請求參數

金鑰	類型	說明	預設值	必填
`countrycode`	string(2)	選填的兩位字母 ISO 國家代碼,用於篩選 MCCMNC 結果,僅返回與指定國家相關的資料。	null	選填

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

成功回應屬性

姓名	類型	說明	可為空值
`items[]`	array	行動網路營運商清單。	false
`country_name`	string	英文國家名稱。	false
`country_code`	string(2)	兩位字母的 ISO 國家代碼。	false
`mccmnc`	string(5\|6)	五位或六位字元的 MCCMNC(行動國家代碼與行動網路代碼組合),用於識別行動網路業者。	false
`mcc`	string(3)	三位字元的 MCC(行動國家代碼),代表網路所屬國家。	false
`mnc`	string(2\|3)	兩位或三位字元的 MNC(行動網路代碼),代表特定的行動網路業者。	false
`brand`	string	此網路營運所使用的消費者品牌名稱。	true
`operator`	string	行動網路業者的法定名稱。	true

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/price-list受保護

此端點返回僅支援 MNP 查詢的國家列表,這些目的地無法使用 HLR 查詢。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'

{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

成功回應屬性

姓名	類型	說明	可為空值
`countries`	string[]	雙字元 ISO 國家代碼列表。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/mccmncs受保護

此端點返回完整的行動網路營運商清單,包含其對應的 MCCMNC 識別碼及額外的相關資訊。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

請求參數

金鑰	類型	說明	預設值	必填
`countrycode`	string(2)	選填的兩字母 ISO 國家代碼,用於篩選 MCCMNC 結果,僅返回與指定國家相關的記錄。	null	選填

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

成功回應屬性

姓名	類型	說明	可為空值
`items`	object[]	行動網路營運商清單。	false
`country_name`	string	英文完整國家名稱。	false
`country_code`	string(2)	代表行動營運商所在國家的兩字母 ISO 國家代碼。	false
`mccmnc`	string(5\|6)	由五或六個字元組成的 MCCMNC 字串,用於唯一識別行動網路營運商。	false
`mcc`	string(3)	由三個字元組成的行動國家代碼 (MCC),用於識別行動網路所在的國家。	false
`mnc`	string(2\|3)	由兩或三個字元組成的行動網路代碼 (MNC),用於指定特定 MCC 內的行動網路。	false
`brand`	string	網路營運的商業品牌名稱,消費者所認知的品牌。	true
`operator`	string	行動網路營運商的正式名稱,通常為管理該網路的法律實體。	true
`parent_mccmnc`	string(5\|6)	由五或六個字元組成的 MCCMNC 字串,代表母公司行動網路營運商(如有)。	true

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/price受保護

此端點返回 HLR、MNP 或 NT 查詢的價格。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

請求參數

金鑰	類型	說明	預設值	必填
`msisdn`	string	要查詢價格的電話號碼,需使用國際格式。	null	必填
`route_type`	string	路由類型,即 `HLR`、`MNP`、`NT`。	null	必填
`route`	string(3)	應計算價格的路由。預設為自動路由所決定的路由。	null	選填

{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

成功回應屬性

姓名	類型	說明	可為空值
`price`	object	包含定價詳情的物件。	false
`amount`	string	以歐元計價的金額。	false
`msisdn`	string	此價格適用的 MSISDN。	false
`route_type`	string(2\|3)	此價格適用的路由類型。	false
`route`	string(3)	此價格適用的路由。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/price-list受保護

此端點返回您帳戶中的定價資訊。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/price-list'

{
   "pricing":[
      {
         "route":"V11",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0090"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26201",
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26203",
         "cns":"4917821",
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"PTX",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MNP",
         "price":"0.00500"
      },
      ...
      {
         "route":"IP1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MIX",
         "price":"0.01000"
      },
      {
         "route":"LC1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"NT",
         "price":"0.00500"
      }
   ]
}

成功回應屬性

姓名	類型	說明	可為空值
`pricing`	object[]	包含定價資訊的物件清單。	false
`route`	string	此定價適用的路由。	false
`countrycode`	string	此定價適用於對應路由的兩字元 ISO 國家代碼(如有)。	true
`countryname`	string	對應國家代碼的英文國家名稱(如有)。	true
`mccmnc`	string	此定價適用於對應路由的 MCCMNC(如有)。覆蓋國家級定價。	true
`cns`	string	此定價適用於對應路由的撥號前綴(如有)。覆蓋國家級定價和 MCCMNC 級定價。	true
`route_type`	string	對應的路由類型,例如 `HLR`、`MNP`、`NT`。	false
`route_type`	string	對應的歐元價格。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/balance受保護

此端點可查詢您目前的帳戶餘額，讓您能根據信用額度狀態自動化處理流程。此功能與您可在付款頁面設定的低信用額度通知電子郵件完美整合。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/balance'

{
    "balance":"1002.90"
}

成功回應屬性

姓名	類型	說明	可為空值
`balance`	string	您目前的帳戶餘額（以歐元計）。字串型態的小數值。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/ping公開

此端點向 API 發送 ping 請求，提供一個簡單的方法來測試您與 HLR Lookups API 的連線。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/ping'

{
    "success":true
}

成功回應屬性

姓名	類型	說明	可為空值
`success`	boolean	表示請求已成功處理。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/time公開

此端點返回代表 HLR Lookups 伺服器當前時間的 Unix 時間戳記。用於在生成 Digest-Auth 驗證簽章時同步您的伺服器時鐘，確保您的伺服器時間與 HLR Lookups 伺服器時間之間的任何差異得到修正。

請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/time'

{
    "time":1525898643
}

成功回應屬性

姓名	類型	說明	可為空值
`time`	integer	代表當前 HLR Lookups 伺服器時間的 Unix 時間戳記。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

GET/auth-test受保護

此端點用於初步測試您的 Basic-Auth 或建議使用的 Digest-Auth 實作。

基本驗證請求摘要式驗證請求成功回應錯誤回應

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

請求標頭

金鑰	類型	說明
`X-Basic`	string	`YOUR_API_KEY:YOUR_API_SECRET` 的 SHA256 雜湊值。雜湊中需包含冒號符號 (:)。

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

請求標頭

金鑰	類型	說明
`X-Digest-Key`	string	您的 HLR Lookups API 金鑰
`X-Digest-Signature`	string	唯一的摘要式驗證簽章(請參閱驗證)
`X-Digest-Timestamp`	integer	目前的 Unix 時間戳記(另請參閱 `GET /time`)

{
    "success":true
}

成功回應屬性

姓名	類型	說明	可為空值
`success`	boolean	表示請求已成功處理。	false

{
    "errors":[
        "Service unavailable."
    ]
}

錯誤回應參數

姓名	類型	說明	可為空值
`errors[]`	string[]	說明錯誤的字串清單。	false

向上捲動

舊版 API 文件

請注意,舊版 API 已停止維護,並計劃於未來淘汰。我們強烈建議您儘早升級至最新版本。

如果您在 2013 年至 2020 年初期間導入我們的 HLR 查詢 API,您使用的是舊版 API。在此情況下,請參閱我們的舊版 API 文件。

舊版 API 文件

API 文件

快速入門

HLR 查詢

MNP 查詢

NT 查詢

路由

價格方案

工具

快速入門

使用 HLR Lookups API

請求範例

酬載範例

成功回應 application/json

其他查詢服務

行動號碼可攜性 (MNP) 查詢

號碼類型偵測 (NT) 查詢

軟體開發套件 (SDK)

工具

非開發人員?

身份驗證

API 金鑰和 API 密鑰

HTTP 基本驗證

建議:使用 SHA256 的 X-Basic 標頭

基本驗證請求

基本驗證標頭

程式碼範例

請求範例

請求標頭

建立簽章

摘要簽章組成元素

程式碼範例

概念說明

同步 HLR 查詢 API

非同步 HLR 查詢 API

SDK（軟體開發套件）

PHP SDK

NodeJS SDK

Ruby SDK

POST/hlr-lookup受保護

請求內容

請求參數

成功回應屬性

錯誤回應參數

POST/hlr-lookups受保護

請求內容

請求參數

成功回應屬性

錯誤回應參數

處理 Webhook

身份驗證

程式碼範例

確認接收

Webhook 負載

Webhook 承載屬性

POST/mnp-lookup受保護

請求內容

請求參數

成功回應屬性

錯誤回應參數

POST/mnp-lookups受保護

請求內容

請求參數

成功回應屬性

錯誤回應參數

處理 Webhook

身份驗證

程式碼範例

確認接收

Webhook 負載

Webhook 承載屬性

POST/nt-lookup受保護

請求內容

請求參數

成功回應屬性

錯誤回應參數

POST/nt-lookups 受保護

請求內容

請求參數

成功回應屬性

錯誤回應參數