Tài liệu API

Bắt Đầu

Sử Dụng API HLR Lookups Xác thực Khái niệm SDK PHP NodeJS Ruby

Tra cứu HLR

POST /hlr-lookup POST /hlr-lookups

Tra cứu MNP

POST /mnp-lookup POST /mnp-lookups

Tra cứu NT

POST /nt-lookup POST /nt-lookups

Định tuyến

GET /route GET /routes GET /routing-map GET /hlr-coverage GET /mnp-coverage GET /mnp-countries GET /mccmncs

Bảng Giá

GET /price GET /price-list GET /balance

Công Cụ

GET /auth-test GET /ping GET /time
Tài liệu API Cũ

 

 
 

Bắt Đầu

Hạ tầng mạng di động toàn cầu hoạt động dựa trên hệ thống được gọi là mạng báo hiệu SS7. Mạng này tạo điều kiện trao đổi dữ liệu thuê bao, định tuyến cuộc gọi, truyền SMS và cập nhật trạng thái kết nối di động theo thời gian thực giữa các nhà mạng. Mỗi mạng di động duy trì một Sổ Đăng Ký Vị Trí Chính (HLR) - cơ sở dữ liệu cốt lõi lưu trữ thông tin thiết yếu về thuê bao của mình.

Công nghệ HLR Lookup cho phép doanh nghiệp truy vấn các sổ đăng ký này và truy xuất thông tin kết nối và mạng trực tiếp cho bất kỳ số điện thoại di động nào. Điều này bao gồm việc điện thoại có đang bật hay không, mạng nào hiện đang được gán, số có được chuyển mạng hay không, số có hợp lệ hay đã bị vô hiệu hóa, và có đang chuyển vùng hay không.

API HLR Lookups cung cấp quyền truy cập liền mạch, theo thời gian thực vào dữ liệu này, cho phép doanh nghiệp xác minh số di động, tối ưu hóa định tuyến và nâng cao giao tiếp khách hàng. Tài liệu này sẽ hướng dẫn bạn tích hợp HLR Lookups vào phần mềm của mình, cho phép truy xuất tự động thông tin di động theo thời gian thực.

Sử Dụng API HLR Lookups

Thực hiện truy vấn HLR Lookup nhanh chóng, an toàn và đơn giản. Sau khi đăng ký và nhận API Key, bạn có thể xác thực và bắt đầu tra cứu tức thì bằng các yêu cầu HTTP POST đơn giản, thông qua POST /hlr-lookup. Ngoài ra, bạn có thể xử lý các tập dữ liệu lớn bằng cách chọn yêu cầu API bất đồng bộ nhanh với kết quả được gửi lại máy chủ của bạn qua webhook, như được giải thích trong phần khái niệm.

Ví Dụ Yêu Cầu

cURL 
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"

Xác thực được cung cấp qua HTTP headers, và payload.json (ở mức tối thiểu) phải chứa đối tượng JSON sau:

Ví Dụ Payload

application/json 
{
   "msisdn": "+14156226819"
}

Khi thực hiện thành công, bạn sẽ nhận được phản hồi chứa thông tin kết nối theo thời gian thực cho số di động được chỉ định.

Phản hồi thành công application/json

200 OK 
{
   "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"
}

Để biết chi tiết đầy đủ về các thuộc tính yêu cầu và phản hồi cũng như trạng thái kết nối, xem POST /hlr-lookup.

Dịch Vụ Tra Cứu Bổ Sung

Tra Cứu Chuyển Mạng Giữ Số (MNP)

Sử dụng tra cứu MNP để xác định quyền sở hữu mạng và thông tin chuyển mạng mà không cần truy vấn kết nối theo thời gian thực. Nếu bạn chỉ cần MCCMNC của một số, tham khảo POST /mnp-lookup.

Tra Cứu Phát Hiện Loại Số (NT)

Xác định xem số điện thoại thuộc về đường dây cố định, di động, cước cao, VoIP, máy nhắn tin hay các phạm vi kế hoạch đánh số khác với POST /nt-lookup.

Bộ Công Cụ Phát Triển Phần Mềm (SDK)

API HLR Lookups hoạt động với bất kỳ REST client nào trong bất kỳ ngôn ngữ lập trình nào và chúng tôi đã xuất bản SDK cho PHP, Ruby và NodeJS trên GitHub để giúp bạn bắt đầu nhanh chóng.

Công Cụ

Để đảm bảo trải nghiệm phát triển liền mạch, chúng tôi cung cấp bộ công cụ toàn diện, bao gồm giám sát yêu cầu API và webhook trên trình duyệt, danh sách trắng địa chỉ IP, tùy chọn xác thực mạnh mẽ và endpoint kiểm tra xác thực.

Không Phải Lập Trình Viên?

HLR Lookups và Truy Vấn Chuyển Mạng Giữ Số có thể được thực hiện mà không cần viết mã. Tìm hiểu thêm về ứng dụng web doanh nghiệp và tính năng báo cáo trên trình duyệt của chúng tôi.

Xác thực

Để đảm bảo bảo mật và kiểm soát truy cập phù hợp, hầu hết các yêu cầu đến HLR Lookups API đều yêu cầu xác thực. Các endpoint được phân loại thành công khai hoặc được bảo vệ. Khi truy cập endpoint được bảo vệ, yêu cầu của bạn phải được xác thực bằng API key và secret thông qua phương thức Digest-Auth hoặc Basic-Auth. Digest-Auth là tùy chọn bảo mật hơn và được khuyến nghị mạnh mẽ. Sử dụng endpoint GET /auth-test để xác minh cấu hình xác thực của bạn.

API Key và API Secret

Lấy API key và secret của bạn từ trang Cài đặt API. Bạn cũng có thể cấu hình phương thức xác thực ưa thích và bật danh sách IP cho phép để tăng cường bảo mật. Nếu bạn nghi ngờ API secret của mình đã bị lộ, bạn có thể tạo mới bất cứ lúc nào.

Lấy API Key
Basic Auth Digest Auth Danh sách IP

Xác thực cơ bản (Basic Authentication) tiêu chuẩn dễ triển khai và được hỗ trợ rộng rãi. Bạn có thể xác thực bằng cách truyền API key và secret dưới dạng cặp user:pass trong yêu cầu HTTP.

HTTP Basic Auth

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

Điều này gửi header Authorization: 

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Khuyến nghị: X-Basic Header với SHA256

Để cải thiện bảo mật, bạn có thể gửi mã băm SHA256 của thông tin xác thực thay vì truyền trực tiếp dưới dạng base64. Để sử dụng phương thức này, tính toán mã băm của cặp YOUR_API_KEY:YOUR_API_SECRET và gửi qua header X-Basic:

Yêu cầu Basic Auth

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

Headers xác thực cơ bản

Khóa Loại Mô tả
X-Basic string Mã băm SHA256 của YOUR_API_KEY:YOUR_API_SECRET. Bao gồm ký tự hai chấm (:) trong mã băm. bắt buộc

PHP Ví dụ mã

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

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

Digest-Auth là phương thức được khuyến nghị để bảo mật truy cập vào các endpoint HLR Lookup API được bảo vệ. Mỗi yêu cầu phải bao gồm các header sau: X-Digest-Key, X-Digest-Signature và X-Digest-Timestamp, được giải thích bên dưới.

Ví dụ yêu cầu

cURL 
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"

Headers yêu cầu

Khóa Loại Mô tả
X-Digest-Key string API Key duy nhất của bạn trên HLR Lookups. bắt buộc
X-Digest-Signature string Chữ ký xác thực duy nhất (xem bên dưới). bắt buộc
X-Digest-Timestamp integer Timestamp Unix hiện tại (xem thêm GET /time). bắt buộc

Tạo chữ ký

X-Digest-Signature được tạo bằng mã băm HMAC SHA256, với API secret của bạn làm khóa chia sẻ.

Chuỗi cần băm được cấu trúc như sau:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Ký hiệu . biểu thị nối chuỗi.

Thành phần chữ ký Digest

Thành phần Loại Mô tả
ENDPOINT_PATH string Endpoint API được yêu cầu, ví dụ: /auth-test viết thường.
UNIX_TIMESTAMP integer Timestamp Unix hiện tại (phải trong vòng 30 giây). Xem GET /time.
REQUEST_METHOD string Phương thức HTTP được sử dụng, ví dụ: POST hoặc GET.
REQUEST_BODY string Dữ liệu body yêu cầu. Đặt thành null cho yêu cầu GET.

Ví dụ mã

PHP PHP NodeJS NodeJS Ruby Ruby
PHP 
$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);
NodeJS 
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');
Ruby 
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)

Sử dụng Cài đặt API để hạn chế truy cập vào các địa chỉ IP cụ thể nhằm tăng cường bảo mật. Điều này đặc biệt được khuyến nghị trong môi trường sản xuất.

Cuộn lên

Khái niệm

Triển khai HLR Lookup trong bất kỳ ngôn ngữ lập trình hoặc hệ thống nào thông qua HTTP REST API của chúng tôi đều đơn giản và hiệu quả. Với quy trình tích hợp đơn giản, bạn có thể bắt đầu truy vấn mạng di động theo thời gian thực để có được thông tin tức thì về tính hợp lệ của số điện thoại, trạng thái kết nối và chi tiết định tuyến.

Việc lựa chọn API phù hợp phụ thuộc vào trường hợp sử dụng cụ thể của bạn. Nếu bạn cần kết quả tra cứu theo thời gian thực cho các ứng dụng như điện thoại VoIP, phát hiện gian lận hoặc định tuyến SMS, API đồng bộ là lựa chọn tốt nhất. Tuy nhiên, nếu trường hợp sử dụng của bạn liên quan đến xử lý khối lượng lớn, tra cứu hàng loạt hoặc xác minh dữ liệu quy mô lớn, API bất đồng bộ mang lại hiệu suất tối ưu với băng thông hiệu quả và khả năng tra cứu theo lô.

Cấu hình API để sử dụng một trong các tùy chọn định tuyến tùy chỉnh của chúng tôi nhằm tối ưu hóa tốc độ, độ chính xác và hiệu quả chi phí. Bạn cũng có thể lưu trữ kết quả tra cứu trong kho lưu trữ để dễ dàng tải xuống báo cáo CSV và JSON, cũng như phân tích nâng cao qua giao diện web.

API HLR Lookup Đồng Bộ

Endpoint POST /hlr-lookup xử lý một số điện thoại di động (MSISDN) mỗi yêu cầu và trả về kết quả ngay lập tức trong nội dung phản hồi HTTP. Kết quả được định dạng dưới dạng JSON và lý tưởng cho các ứng dụng thời gian thực, bao gồm xác thực số di động, định tuyến cuộc gọi và gửi tin nhắn SMS.

Một lệnh gọi API đồng bộ bao gồm một yêu cầu và phản hồi HTTP trực tiếp. Hệ thống của bạn gửi một MSISDN (số di động) duy nhất mỗi yêu cầu và nhận phản hồi ngay lập tức chứa kết quả tra cứu HLR theo thời gian thực ở định dạng JSON. API này được tối ưu hóa cho các trường hợp sử dụng yêu cầu xác minh tức thì và kiểm tra kết nối, chẳng hạn như phát hiện gian lận, định tuyến cuộc gọi VoIP và tối ưu hóa cổng SMS.

API Tra cứu HLR Bất đồng bộ

Endpoint POST /hlr-lookups được thiết kế cho xử lý hàng loạt và khối lượng lớn, cho phép bạn gửi tối đa 1,000 MSISDN mỗi yêu cầu. Thay vì trả về kết quả ngay lập tức, API này sử dụng webhook tự động để gửi kết quả dần dần đến máy chủ của bạn. Kết quả tra cứu được trả về dưới dạng đối tượng JSON thông qua callback HTTP POST.

API bất đồng bộ được tối ưu hóa về tốc độ, hiệu quả và khả năng mở rộng. Nó loại bỏ các vấn đề về độ trễ mạng liên quan đến các lệnh gọi đồng bộ, khiến nó trở nên lý tưởng cho các doanh nghiệp cần tra cứu với thông lượng cao. Hệ thống của bạn gửi tối đa 1,000 MSISDN mỗi yêu cầu, và nền tảng của chúng tôi xử lý chúng song song, gửi kết quả trả về máy chủ của bạn qua webhook HTTP theo lô tối đa 1,000 kết quả mỗi callback.

SDK (Bộ Công Cụ Phát Triển Phần Mềm)

Các Bộ Công Cụ Phát Triển Phần Mềm (SDK) của chúng tôi cho PHP, NodeJS và Ruby giúp đơn giản hóa quy trình tích hợp, cho phép bạn kết nối với API HLR Lookups một cách hiệu quả và với nỗ lực tối thiểu.

Các SDK này cung cấp các hàm được xây dựng sẵn, xử lý xác thực và mẫu yêu cầu API có cấu trúc, giúp giảm thời gian phát triển và đảm bảo các phương pháp thực hành tốt nhất.

Khám phá danh sách đầy đủ các SDK có sẵn của chúng tôi trên GitHub và bắt đầu tích hợp ngay hôm nay.

PHP PHP NodeJS NodeJS Ruby Ruby
Logo PHP

SDK PHP

Tích hợp API tức thì cho PHP 
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);
Xem trên GitHub README.md
Logo NodeJS

SDK NodeJS

Tích hợp API tức thì cho NodeJS 
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   }
Xem trên GitHub README.md
Logo Ruby

SDK Ruby

Tích hợp API tức thì cho Ruby 
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)
Xem trên GitHub README.md
Cuộn lên

POST/hlr-lookupđược bảo vệ

Thực hiện Tra cứu HLR đồng bộ, cung cấp dữ liệu kết nối và chuyển mạng giữ số điện thoại di động theo thời gian thực trực tiếp từ các nhà khai thác mạng. Endpoint này lý tưởng cho các tình huống lưu lượng trực tiếp khi ứng dụng nhạy cảm về thời gian cần xác minh ngay lập tức xem số điện thoại hiện có thể liên lạc được (đang kết nối) hay không khả dụng (đã tắt máy). Ngoài ra, endpoint này giúp phân biệt số hoạt động với số không hợp lệ, không xác định hoặc giả mạo.

Để xử lý hàng loạt các tập dữ liệu lớn không yêu cầu kết quả tức thì, hãy cân nhắc sử dụng POST /hlr-lookups bất đồng bộ, được tối ưu hóa cho xử lý hàng loạt tốc độ cao.

Nếu mục tiêu chính của bạn là truy xuất dữ liệu chuyển mạng giữ số di động (MCCMNC) và không yêu cầu trạng thái kết nối trực tiếp, POST /mnp-lookup cung cấp giải pháp thay thế tiết kiệm chi phí cho các truy vấn chuyển mạng giữ số di động.

Yêu cầu Phản hồi thành công Phản hồi lỗi Tham Chiếu Trạng Thái
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

Dữ liệu gửi

application/json 
{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
msisdn string Số điện thoại di động (MSISDN) cần truy vấn, được cung cấp ở định dạng quốc tế (ví dụ: +14156226819 hoặc 0014156226819). Phải bao gồm mã quốc gia. null bắt buộc
route string(3) Mã định danh ba ký tự tùy chọn chỉ định tuyến đường cho tra cứu này. Đặt thành null hoặc bỏ qua tham số này để áp dụng bản đồ định tuyến tùy chỉnh của bạn hoặc để hệ thống tự động xác định tuyến đường tốt nhất cho tra cứu này. null tùy chọn
storage string Mã định danh lưu trữ tùy chọn chỉ định báo cáo nơi kết quả sẽ được lưu trữ để xem xét thủ công, phân tích và báo cáo. Hệ thống tự động thêm dấu thời gian với tháng hiện tại. Nếu bỏ qua hoặc đặt thành null, hệ thống sẽ tự động nhóm kết quả theo tháng cho mục đích báo cáo. null tùy chọn
200 OK 
{
   "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"
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
id string(12) Mã định danh duy nhất được gán cho yêu cầu tra cứu này. false
msisdn string Số điện thoại di động đang được truy vấn, được định dạng theo chuẩn quốc tế (ví dụ: +14156226819 hoặc 0014156226819). false
connectivity_status string Cho biết liệu trạng thái kết nối của số điện thoại có được truy xuất thành công hay không. Các giá trị có thể: CONNECTED , ABSENT , INVALID_MSISDN hoặc UNDETERMINED . false
mccmnc string(5|6) Mã quốc gia di động (MCC) và mã mạng di động (MNC) gồm năm hoặc sáu chữ số, xác định mạng hiện đang liên kết với số điện thoại. true
mcc string(3) Mã quốc gia di động (MCC) gồm ba chữ số, xác định quốc gia nơi số điện thoại được đăng ký. true
mnc string(2|3) Mã mạng di động (MNC) gồm hai hoặc ba chữ số, xác định mạng cụ thể mà số điện thoại thuộc về. true
imsi string Mã nhận dạng thuê bao di động quốc tế (IMSI), mã định danh duy nhất cho thẻ SIM liên kết với số này. Tính khả dụng phụ thuộc vào cấu hình mạng. true
msin string(10) Số nhận dạng thuê bao di động (MSIN) trong cơ sở dữ liệu của nhà mạng. Tính khả dụng phụ thuộc vào cấu hình mạng. true
msc string(12) Trung tâm chuyển mạch di động (MSC) hiện đang xử lý liên lạc của thuê bao này. Tính khả dụng phụ thuộc vào cấu hình mạng. true
original_network_name string Tên nhà mạng gốc (ban đầu) liên kết với số này. true
original_country_name string Tên đầy đủ của quốc gia nơi số điện thoại di động được đăng ký ban đầu, được cung cấp bằng tiếng Anh. true
original_country_code string(2) Mã quốc gia ISO gồm hai ký tự, đại diện cho quốc gia nơi số điện thoại được cấp phát lần đầu. true
original_country_prefix string Mã gọi quốc tế (mã vùng quốc gia) tương ứng với quốc gia gốc của số điện thoại di động. true
is_ported boolean Cho biết liệu số di động có được chuyển mạng từ mạng gốc sang nhà mạng khác hay không. true
ported_network_name string Tên nhà mạng mà số di động đã được chuyển đến, nếu có. true
ported_country_name string Tên quốc gia nơi số di động được chuyển mạng đến, nếu có. true
ported_country_code string(2) Mã quốc gia ISO gồm hai ký tự, đại diện cho quốc gia nơi số di động được chuyển mạng đến, nếu có. true
ported_country_prefix string Mã gọi quốc tế (mã vùng quốc gia) của quốc gia nơi số di động được chuyển mạng đến, nếu có. true
is_roaming boolean Cho biết liệu số di động hiện có đang chuyển vùng trên mạng nước ngoài hay không. Tính khả dụng của trạng thái chuyển vùng phụ thuộc vào nhà mạng di động. true
roaming_network_name string Tên mạng mà số di động hiện đang chuyển vùng, nếu có. true
roaming_country_name string Tên quốc gia nơi số di động hiện đang chuyển vùng, nếu có. true
roaming_country_code string(2) Mã quốc gia ISO gồm hai ký tự của quốc gia nơi số di động hiện đang chuyển vùng, nếu có. true
roaming_country_prefix string Mã gọi quốc tế (mã vùng quốc gia) của quốc gia nơi số di động hiện đang chuyển vùng, nếu có. true
cost string Giá trị thập phân được biểu diễn dưới dạng chuỗi, cho biết chi phí tra cứu tính bằng EUR. true
timestamp string Dấu thời gian theo định dạng W3C bao gồm múi giờ, chỉ định thời điểm hoàn tất tra cứu. true
storage string Tên kho lưu trữ nơi kết quả tra cứu được lưu. Tên này tương ứng với tên báo cáo và tệp CSV có thể tải xuống qua giao diện web. true
route string(3) Mã định danh gồm ba ký tự cho biết phương thức định tuyến được sử dụng cho yêu cầu tra cứu này. true
processing_status string Kết quả xử lý của tra cứu. Các giá trị có thể: COMPLETED (thành công), REJECTED (không thể kết nối mạng, không tính phí) hoặc FAILED (xảy ra lỗi trong quá trình xử lý). false
error_code integer Mã lỗi nội bộ tùy chọn cung cấp thông tin chẩn đoán bổ sung cho bộ phận hỗ trợ khách hàng. true
error_description string Giải thích ngắn gọn về mã lỗi đã cho (nếu có) bằng văn bản tiếng Anh. true
data_source string Nguồn dữ liệu được sử dụng cho yêu cầu này. Các giá trị có thể: LIVE_HLR (truy vấn HLR thời gian thực) hoặc MNP_DB (cơ sở dữ liệu chuyển mạng giữ số tĩnh). Tham khảo tùy chọn định tuyến để biết chi tiết. false
routing_instruction string Chuỗi phân tách bằng dấu hai chấm mô tả hướng dẫn định tuyến được sử dụng trong yêu cầu. Thành phần đầu tiên là STATIC khi bạn chỉ định tuyến đường hoặc AUTO cho định tuyến tự động; thành phần thứ hai là mã định danh tuyến đường, và đối với yêu cầu định tuyến tự động, thành phần thứ ba hiển thị nguồn gốc mà quyết định định tuyến dựa trên (tức là 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
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Trạng thái Mô tả
CONNECTED Số điện thoại hợp lệ và thiết bị di động đích hiện đang kết nối với mạng di động. Cuộc gọi, tin nhắn SMS và các dịch vụ khác sẽ được gửi đến người nhận thành công.
ABSENT Số điện thoại hợp lệ, nhưng thiết bị di động đích đang tắt nguồn hoặc tạm thời nằm ngoài vùng phủ sóng mạng. Tin nhắn hoặc cuộc gọi có thể không được gửi đến cho đến khi thiết bị kết nối lại với mạng.
INVALID_MSISDN Số điện thoại không hợp lệ hoặc hiện không được gán cho bất kỳ thuê bao nào trên mạng di động. Cuộc gọi và tin nhắn đến số này sẽ thất bại.
UNDETERMINED Không thể xác định trạng thái kết nối của số điện thoại. Nguyên nhân có thể do số không hợp lệ, phản hồi lỗi SS7, hoặc thiếu kết nối với nhà mạng đích. Vui lòng kiểm tra mã lỗi và trường mô tả để có thêm thông tin chẩn đoán.
Cuộn lên

POST/hlr-lookupsđược bảo vệ

Khởi tạo một lô tra cứu HLR bất đồng bộ, truy xuất dữ liệu kết nối và chuyển mạng giữ số của điện thoại di động trực tiếp từ các nhà khai thác mạng. Kết quả được gửi qua webhook đến máy chủ của bạn. Phương thức này được tối ưu hóa để xử lý khối lượng lớn số điện thoại không yêu cầu phản hồi tức thời, chẳng hạn như làm sạch và xác minh cơ sở dữ liệu. Đối với các ứng dụng thời gian thực như định tuyến cuộc gọi hoặc gửi SMS, hãy cân nhắc sử dụng endpoint POST /hlr-lookup thay thế.

Endpoint này lý tưởng cho xử lý hàng loạt khi mục tiêu là xác định các số điện thoại hiện có thể kết nối (đang bật) hoặc không khả dụng (điện thoại đã tắt) đồng thời lọc ra các số không hợp lệ, chưa được cấp phát hoặc giả mạo. Ngoài ra, nó cung cấp trạng thái chuyển mạng giữ số trực tiếp (MCCMNC) cùng với thông tin chi tiết về kết nối.

Trước khi sử dụng endpoint này, hãy đảm bảo rằng URL webhook đã được cấu hình để nhận kết quả tra cứu bất đồng bộ. Bạn có thể thiết lập điều này trong cài đặt API của mình.

Yêu cầu Phản hồi thành công Phản hồi lỗi Webhooks Tham Chiếu Trạng Thái
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

Dữ liệu gửi

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

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
msisdns array Một mảng các số điện thoại di động (MSISDN) ở định dạng quốc tế (ví dụ: +14156226819 hoặc 0014156226819). Bạn có thể bao gồm tối đa 1000 số trong mỗi yêu cầu. null bắt buộc
route string(3) Mã định danh ba ký tự tùy chọn chỉ định tuyến đường cho tra cứu này. Đặt thành null hoặc bỏ qua tham số này để áp dụng bản đồ định tuyến tùy chỉnh của bạn hoặc để hệ thống tự động xác định tuyến đường tốt nhất cho tra cứu này. null tùy chọn
storage string Mã định danh lưu trữ tùy chọn chỉ định báo cáo nơi kết quả sẽ được lưu trữ để xem xét thủ công, phân tích và báo cáo. Hệ thống tự động thêm dấu thời gian với tháng hiện tại. Nếu bỏ qua hoặc đặt thành null, hệ thống sẽ tự động nhóm kết quả theo tháng cho mục đích báo cáo. null tùy chọn
200 OK 
{
   "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"
   ]
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
accepted array Danh sách các đối tượng chứa mã định danh duy nhất và MSISDN đã được chấp nhận để xử lý. false
accepted_count integer Tổng số MSISDN được chấp nhận thành công để xử lý. false
rejected array Danh sách các đối tượng chứa mã định danh duy nhất và MSISDN đã bị từ chối xử lý, thường do số không hợp lệ. Không có phí nào được áp dụng cho các mục bị từ chối. false
rejected_count integer Tổng số MSISDN bị từ chối do lỗi xác thực. false
total_count integer Tổng số MSISDN được chấp nhận và bị từ chối đã được gửi để xử lý. false
cost string Giá trị thập phân được biểu diễn dưới dạng chuỗi, cho biết tổng chi phí bằng EUR cho các tra cứu được chấp nhận. false
storage string Tên của kho lưu trữ nơi kết quả tra cứu được thêm vào, được sử dụng để báo cáo và tải xuống CSV qua giao diện web. false
route string(3|4) Mã định danh ba hoặc bốn ký tự chỉ định tuyến đường được sử dụng cho yêu cầu tra cứu này. Chứa AUTO nếu định tuyến tự động dựa trên số được yêu cầu. false
webhook_urls array Các URL webhook được cấu hình trong cài đặt API của bạn. Kết quả được gửi trả về đây. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false

Xử lý Webhook

Sau khi gửi, nền tảng của chúng tôi sẽ bắt đầu xử lý các số điện thoại được cung cấp và gửi kết quả đến URL webhook đã chỉ định trước đó trên máy chủ của bạn. Kết quả được truyền dưới dạng yêu cầu HTTP POST với đối tượng JSON trong nội dung yêu cầu.

Xác thực

Xác thực webhook bằng cách kiểm tra HTTP header X-Signatures.

Header X-Signatures chứa danh sách các chữ ký được phân tách bằng dấu chấm phẩy. Mỗi chữ ký trong danh sách được tạo bằng một trong các API secret được cấu hình trong tài khoản của bạn. Để xác minh webhook, hãy tạo hash SHA-256 sử dụng API key, secret và nội dung HTTP thô của bạn - sau đó so sánh với các chữ ký trong danh sách.

Kết quả khớp xác nhận yêu cầu là xác thực và được ký bằng secret do bạn kiểm soát.

PHP Ví dụ mã

PHP 
$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;
    }
}

Yêu cầu hợp lệ nếu bất kỳ chữ ký nào trong header bằng với hash SHA256 được tính toán trên chuỗi nối của API key, secret và nội dung HTTP của bạn.

Xác nhận Đã Nhận

Máy chủ của bạn cần phản hồi bằng mã trạng thái HTTP 200 OK để xác nhận đã nhận thành công. Nếu trả về bất kỳ mã phản hồi nào khác, xảy ra timeout (10 giây), hoặc bất kỳ vấn đề giao hàng nào khác phát sinh, hệ thống sẽ tự động thử lại webhook sau một phút. Nếu yêu cầu tiếp tục thất bại, các lần thử lại sẽ tuân theo chiến lược exponential backoff, với các lần thử tiếp theo sau 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 phút.

Cơ chế thử lại này đảm bảo độ tin cậy tối đa trong việc gửi kết quả tra cứu đến hạ tầng của bạn. Điều này giảm thiểu rủi ro mất dữ liệu do sự cố mạng tạm thời hoặc máy chủ ngừng hoạt động.

Nội dung Webhook

HTTP POST (application/json) 
{
   "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"
      }
   ]
}

Thuộc Tính Dữ Liệu Webhook

Đối tượng JSON chứa thuộc tính type => HLR cùng với thuộc tính results bao gồm danh sách các đối tượng tra cứu, như được ghi chép bên dưới.

Tên Loại Mô tả Có thể null
id string(12) Mã định danh duy nhất được gán cho yêu cầu tra cứu này. false
msisdn string Số điện thoại di động đang được truy vấn, được định dạng theo chuẩn quốc tế (ví dụ: +14156226819 hoặc 0014156226819). false
connectivity_status string Cho biết liệu trạng thái kết nối của số điện thoại có được truy xuất thành công hay không. Các giá trị có thể: CONNECTED , ABSENT , INVALID_MSISDN hoặc UNDETERMINED . false
mccmnc string(5|6) Mã quốc gia di động (MCC) và mã mạng di động (MNC) gồm năm hoặc sáu chữ số, xác định mạng hiện đang liên kết với số điện thoại. true
mcc string(3) Mã quốc gia di động (MCC) gồm ba chữ số, xác định quốc gia nơi số điện thoại được đăng ký. true
mnc string(2|3) Mã mạng di động (MNC) gồm hai hoặc ba chữ số, xác định mạng cụ thể mà số điện thoại thuộc về. true
imsi string Mã nhận dạng thuê bao di động quốc tế (IMSI), mã định danh duy nhất cho thẻ SIM liên kết với số này. Tính khả dụng phụ thuộc vào cấu hình mạng. true
msin string(10) Số nhận dạng thuê bao di động (MSIN) trong cơ sở dữ liệu của nhà mạng. Tính khả dụng phụ thuộc vào cấu hình mạng. true
msc string(12) Trung tâm chuyển mạch di động (MSC) hiện đang xử lý liên lạc của thuê bao này. Tính khả dụng phụ thuộc vào cấu hình mạng. true
original_network_name string Tên nhà mạng gốc (ban đầu) liên kết với số này. true
original_country_name string Tên đầy đủ của quốc gia nơi số điện thoại di động được đăng ký ban đầu, được cung cấp bằng tiếng Anh. true
original_country_code string(2) Mã quốc gia ISO gồm hai ký tự, đại diện cho quốc gia nơi số điện thoại được cấp phát lần đầu. true
original_country_prefix string Mã gọi quốc tế (mã vùng quốc gia) tương ứng với quốc gia gốc của số điện thoại di động. true
is_ported boolean Cho biết liệu số di động có được chuyển mạng từ mạng gốc sang nhà mạng khác hay không. true
ported_network_name string Tên nhà mạng mà số di động đã được chuyển đến, nếu có. true
ported_country_name string Tên quốc gia nơi số di động được chuyển mạng đến, nếu có. true
ported_country_code string(2) Mã quốc gia ISO gồm hai ký tự, đại diện cho quốc gia nơi số di động được chuyển mạng đến, nếu có. true
ported_country_prefix string Mã gọi quốc tế (mã vùng quốc gia) của quốc gia nơi số di động được chuyển mạng đến, nếu có. true
is_roaming boolean Cho biết liệu số di động hiện có đang chuyển vùng trên mạng nước ngoài hay không. Tính khả dụng của trạng thái chuyển vùng phụ thuộc vào nhà mạng di động. true
roaming_network_name string Tên mạng mà số di động hiện đang chuyển vùng, nếu có. true
roaming_country_name string Tên quốc gia nơi số di động hiện đang chuyển vùng, nếu có. true
roaming_country_code string(2) Mã quốc gia ISO gồm hai ký tự của quốc gia nơi số di động hiện đang chuyển vùng, nếu có. true
roaming_country_prefix string Mã gọi quốc tế (mã vùng quốc gia) của quốc gia nơi số di động hiện đang chuyển vùng, nếu có. true
cost string Giá trị thập phân được biểu diễn dưới dạng chuỗi, cho biết chi phí tra cứu tính bằng EUR. true
timestamp string Dấu thời gian theo định dạng W3C bao gồm múi giờ, chỉ định thời điểm hoàn tất tra cứu. true
storage string Tên kho lưu trữ nơi kết quả tra cứu được lưu. Tên này tương ứng với tên báo cáo và tệp CSV có thể tải xuống qua giao diện web. true
route string(3) Mã định danh gồm ba ký tự cho biết phương thức định tuyến được sử dụng cho yêu cầu tra cứu này. true
processing_status string Kết quả xử lý của tra cứu. Các giá trị có thể: COMPLETED (thành công), REJECTED (không thể kết nối mạng, không tính phí) hoặc FAILED (xảy ra lỗi trong quá trình xử lý). false
error_code integer Mã lỗi nội bộ tùy chọn cung cấp thông tin chẩn đoán bổ sung cho bộ phận hỗ trợ khách hàng. true
error_description string Giải thích ngắn gọn về mã lỗi đã cho (nếu có) bằng văn bản tiếng Anh. true
data_source string Nguồn dữ liệu được sử dụng cho yêu cầu này. Các giá trị có thể: LIVE_HLR (truy vấn HLR thời gian thực) hoặc MNP_DB (cơ sở dữ liệu chuyển mạng giữ số tĩnh). Tham khảo tùy chọn định tuyến để biết chi tiết. false
routing_instruction string Chuỗi phân tách bằng dấu hai chấm mô tả hướng dẫn định tuyến được sử dụng trong yêu cầu. Thành phần đầu tiên là STATIC khi bạn chỉ định tuyến đường hoặc AUTO cho định tuyến tự động; thành phần thứ hai là mã định danh tuyến đường, và đối với yêu cầu định tuyến tự động, thành phần thứ ba hiển thị nguồn gốc mà quyết định định tuyến dựa trên (tức là 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
Trạng thái Mô tả
CONNECTED Số điện thoại hợp lệ và thiết bị di động đích hiện đang kết nối với mạng di động. Cuộc gọi, tin nhắn SMS và các dịch vụ khác sẽ được gửi đến người nhận thành công.
ABSENT Số điện thoại hợp lệ, nhưng thiết bị di động đích đang tắt nguồn hoặc tạm thời nằm ngoài vùng phủ sóng mạng. Tin nhắn hoặc cuộc gọi có thể không được gửi đến cho đến khi thiết bị kết nối lại với mạng.
INVALID_MSISDN Số điện thoại không hợp lệ hoặc hiện không được gán cho bất kỳ thuê bao nào trên mạng di động. Cuộc gọi và tin nhắn đến số này sẽ thất bại.
UNDETERMINED Không thể xác định trạng thái kết nối của số điện thoại. Nguyên nhân có thể do số không hợp lệ, phản hồi lỗi SS7, hoặc thiếu kết nối với nhà mạng đích. Vui lòng kiểm tra mã lỗi và trường mô tả để có thêm thông tin chẩn đoán.
Cuộn lên

POST/mnp-lookupđược bảo vệ

Thực hiện tra cứu MNP đồng bộ và cung cấp thông tin về khả năng chuyển mạng giữ số và mạng di động. Endpoint này phù hợp nếu mục tiêu chính của bạn là trích xuất MCCMNC hiện tại của một số điện thoại di động và xác định chính xác mạng gốc cũng như mạng hiện tại theo thời gian thực.

Để xử lý hàng loạt các tập dữ liệu lớn không yêu cầu kết quả tức thì, hãy cân nhắc sử dụng POST /mnp-lookups bất đồng bộ, được tối ưu hóa cho xử lý hàng loạt tốc độ cao.

Truy vấn MNP xác định một cách đáng tin cậy thông tin về khả năng chuyển mạng và mạng lưới nhưng không cho biết liệu điện thoại di động đích hiện có đang kết nối với mạng và có thể liên lạc được hay không. Để trích xuất thông tin kết nối trực tiếp, vui lòng sử dụng endpoint POST /hlr-lookup.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

Dữ liệu gửi

application/json 
{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
msisdn string Số điện thoại di động (MSISDN) cần truy vấn, được cung cấp ở định dạng quốc tế (ví dụ: +14156226819 hoặc 0014156226819). Phải bao gồm mã quốc gia. null bắt buộc
route string(3) Mã định danh ba ký tự tùy chọn chỉ định tuyến đường cho tra cứu này. Đặt thành null hoặc bỏ qua tham số này để áp dụng bản đồ định tuyến tùy chỉnh của bạn hoặc để hệ thống tự động xác định tuyến đường tốt nhất cho tra cứu này. null tùy chọn
storage string Mã định danh lưu trữ tùy chọn chỉ định báo cáo nơi kết quả sẽ được lưu trữ để xem xét thủ công, phân tích và báo cáo. Hệ thống tự động thêm dấu thời gian với tháng hiện tại. Nếu bỏ qua hoặc đặt thành null, hệ thống sẽ tự động nhóm kết quả theo tháng cho mục đích báo cáo. null tùy chọn
200 OK 
{
   "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
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
id string(12) Mã định danh duy nhất gồm 12 ký tự cho truy vấn này. false
msisdn string Số điện thoại di động được kiểm tra trong yêu cầu truy vấn này. false
query_status string Cho biết việc truy xuất thông tin chuyển mạng và mạng có thành công hay không. Các giá trị có thể là OK hoặc FAILED. false
mccmnc string(5|6) Mã MCCMNC gồm năm hoặc sáu ký tự (bộ mã quốc gia di động và mã mạng di động) xác định mạng mà số điện thoại di động hiện đang thuộc về. true
mcc string(3) Mã MCC gồm ba ký tự (mã quốc gia di động) đại diện cho quốc gia liên kết với mạng hiện tại của số điện thoại di động. true
mnc string(2|3) Mã MNC gồm hai hoặc ba ký tự (mã mạng di động) xác định nhà mạng hiện tại của số điện thoại di động. true
is_ported boolean Cho biết số điện thoại đã được chuyển mạng từ mạng gốc sang nhà mạng mới hay chưa. true
original_network_name string Chuỗi tùy ý (bằng tiếng Anh) chỉ định tên nhà mạng gốc của số điện thoại di động được kiểm tra. true
original_country_name string Chuỗi tùy ý (bằng tiếng Anh) cho biết quốc gia gốc của số điện thoại di động được kiểm tra. true
original_country_code string(2) Mã quốc gia ISO gồm hai ký tự đại diện cho quốc gia gốc của số điện thoại di động được kiểm tra. true
original_country_prefix string Mã quay số của quốc gia gốc liên kết với số điện thoại di động được kiểm tra. true
ported_network_name string Chỉ định nhà mạng mà số điện thoại di động được kiểm tra đã chuyển đến, nếu có. true
ported_country_name string Chỉ định quốc gia mà số điện thoại di động được kiểm tra đã chuyển đến, nếu có. true
ported_country_code string(2) Mã quốc gia ISO gồm hai ký tự đại diện cho quốc gia mà số điện thoại di động được kiểm tra đã chuyển đến, nếu có. true
ported_country_prefix string Mã quay số của quốc gia mà số điện thoại di động được kiểm tra đã chuyển đến, nếu có. true
extra string Chuỗi tùy ý cung cấp thông tin chi tiết bổ sung về số điện thoại, nếu có. true
cost string Giá trị thập phân, được biểu thị dưới dạng chuỗi, cho biết chi phí bằng EUR cho truy vấn này. true
timestamp string Dấu thời gian theo định dạng W3C, bao gồm thông tin múi giờ, cho biết thời điểm hoàn thành truy vấn. true
storage string Tên lưu trữ (hoặc tên báo cáo) mà kết quả truy vấn được thêm vào. Được sử dụng để tải xuống CSV và báo cáo qua giao diện web. true
route string(3) Mã định danh gồm ba ký tự chỉ định tuyến đường được sử dụng cho yêu cầu truy vấn này. true
error_code integer Mã lỗi nội bộ tùy chọn cung cấp thêm ngữ cảnh cho chẩn đoán hỗ trợ khách hàng. true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

POST/mnp-lookupsđược bảo vệ

Khởi tạo một loạt tra cứu MNP (chuyển mạng giữ số) không đồng bộ, truy xuất MCCMNC hiện tại và xác định chính xác mạng gốc cũng như mạng hiện tại theo thời gian thực. Kết quả được gửi qua webhook đến máy chủ của bạn. Phương thức này được tối ưu hóa để xử lý khối lượng lớn số điện thoại không yêu cầu phản hồi tức thời, chẳng hạn như làm sạch và xác minh cơ sở dữ liệu. Đối với các ứng dụng thời gian thực như định tuyến cuộc gọi hoặc gửi SMS, hãy cân nhắc sử dụng endpoint POST /mnp-lookup thay thế.

Truy vấn MNP xác định một cách đáng tin cậy thông tin về khả năng chuyển mạng và mạng lưới nhưng không cho biết liệu điện thoại di động đích hiện có đang kết nối với mạng và có thể liên lạc được hay không. Để trích xuất thông tin kết nối trực tiếp, vui lòng sử dụng endpoint POST /hlr-lookups.

Trước khi sử dụng endpoint này, hãy đảm bảo rằng URL webhook đã được cấu hình để nhận kết quả tra cứu bất đồng bộ. Bạn có thể thiết lập điều này trong cài đặt API của mình.

Yêu cầu Phản hồi thành công Phản hồi lỗi Webhooks
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

Dữ liệu gửi

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

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
msisdns array Một mảng các số điện thoại di động (MSISDN) ở định dạng quốc tế (ví dụ: +14156226819 hoặc 0014156226819). Bạn có thể bao gồm tối đa 1000 số trong mỗi yêu cầu. null bắt buộc
route string(3) Mã định danh ba ký tự tùy chọn chỉ định tuyến đường cho tra cứu này. Đặt thành null hoặc bỏ qua tham số này để áp dụng sơ đồ định tuyến tùy chỉnh của bạn hoặc để hệ thống của chúng tôi tự động xác định các tuyến đường tốt nhất cho yêu cầu này. null tùy chọn
storage string Mã định danh lưu trữ tùy chọn chỉ định báo cáo nơi kết quả sẽ được lưu trữ để xem xét thủ công, phân tích và báo cáo. Hệ thống tự động thêm dấu thời gian với tháng hiện tại. Nếu bỏ qua hoặc đặt thành null, hệ thống sẽ tự động nhóm kết quả theo tháng cho mục đích báo cáo. null tùy chọn
200 OK 
{
   "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"
   ]
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
accepted array Danh sách các đối tượng chứa mã định danh duy nhất và MSISDN đã được chấp nhận để xử lý. false
accepted_count integer Tổng số MSISDN được chấp nhận thành công để xử lý. false
rejected array Danh sách các đối tượng chứa mã định danh duy nhất và MSISDN đã bị từ chối xử lý, thường do số không hợp lệ. Không có phí nào được áp dụng cho các mục bị từ chối. false
rejected_count integer Tổng số MSISDN bị từ chối do lỗi xác thực. false
total_count integer Tổng số MSISDN được chấp nhận và bị từ chối đã được gửi để xử lý. false
cost string Giá trị thập phân được biểu diễn dưới dạng chuỗi, cho biết tổng chi phí bằng EUR cho các tra cứu được chấp nhận. false
storage string Tên của kho lưu trữ nơi kết quả tra cứu được thêm vào, được sử dụng để báo cáo và tải xuống CSV qua giao diện web. false
route string(3) Mã định danh gồm ba ký tự chỉ định tuyến đường được sử dụng cho yêu cầu truy vấn này. false
webhook_urls array Các URL webhook được cấu hình trong cài đặt API của bạn. Kết quả được gửi trả về đây. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false

Xử lý Webhook

Sau khi gửi, nền tảng của chúng tôi sẽ bắt đầu xử lý các số điện thoại được cung cấp và gửi kết quả đến URL webhook đã chỉ định trước đó trên máy chủ của bạn. Kết quả được truyền dưới dạng yêu cầu HTTP POST với đối tượng JSON trong nội dung yêu cầu.

Xác thực

Xác thực webhook bằng cách kiểm tra HTTP header X-Signatures.

Header X-Signatures chứa danh sách các chữ ký được phân tách bằng dấu chấm phẩy. Mỗi chữ ký trong danh sách được tạo bằng một trong các API secret được cấu hình trong tài khoản của bạn. Để xác minh webhook, hãy tạo hash SHA-256 sử dụng API key, secret và nội dung HTTP thô của bạn - sau đó so sánh với các chữ ký trong danh sách.

Kết quả khớp xác nhận yêu cầu là xác thực và được ký bằng secret do bạn kiểm soát.

PHP Ví dụ mã

PHP 
$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;
    }
}

Yêu cầu hợp lệ nếu bất kỳ chữ ký nào trong header bằng với hash SHA256 được tính toán trên chuỗi nối của API key, secret và nội dung HTTP của bạn.

Xác nhận Đã Nhận

Máy chủ của bạn cần phản hồi bằng mã trạng thái HTTP 200 OK để xác nhận đã nhận thành công. Nếu trả về bất kỳ mã phản hồi nào khác, xảy ra timeout (10 giây), hoặc bất kỳ vấn đề giao hàng nào khác phát sinh, hệ thống sẽ tự động thử lại webhook sau một phút. Nếu yêu cầu tiếp tục thất bại, các lần thử lại sẽ tuân theo chiến lược exponential backoff, với các lần thử tiếp theo sau 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 phút.

Cơ chế thử lại này đảm bảo độ tin cậy tối đa trong việc gửi kết quả tra cứu đến hạ tầng của bạn. Điều này giảm thiểu rủi ro mất dữ liệu do sự cố mạng tạm thời hoặc máy chủ ngừng hoạt động.

Nội dung Webhook

HTTP POST (application/json) 
{
    "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
        }
    ]
}

Thuộc Tính Dữ Liệu Webhook

Đối tượng JSON chứa thuộc tính type => MNP cùng với thuộc tính results bao gồm danh sách các đối tượng tra cứu, như được ghi chép bên dưới.

Tên Loại Mô tả Có thể null
id string(12) Mã định danh duy nhất gồm 12 ký tự cho truy vấn này. false
msisdn string Số điện thoại di động được kiểm tra trong yêu cầu truy vấn này. false
query_status string Cho biết việc truy xuất thông tin chuyển mạng và mạng có thành công hay không. Các giá trị có thể là OK hoặc FAILED. false
mccmnc string(5|6) Mã MCCMNC gồm năm hoặc sáu ký tự (bộ mã quốc gia di động và mã mạng di động) xác định mạng mà số điện thoại di động hiện đang thuộc về. true
mcc string(3) Mã MCC gồm ba ký tự (mã quốc gia di động) đại diện cho quốc gia liên kết với mạng hiện tại của số điện thoại di động. true
mnc string(2|3) Mã MNC gồm hai hoặc ba ký tự (mã mạng di động) xác định nhà mạng hiện tại của số điện thoại di động. true
is_ported boolean Cho biết số điện thoại đã được chuyển mạng từ mạng gốc sang nhà mạng mới hay chưa. true
original_network_name string Chuỗi tùy ý (bằng tiếng Anh) chỉ định tên nhà mạng gốc của số điện thoại di động được kiểm tra. true
original_country_name string Chuỗi tùy ý (bằng tiếng Anh) cho biết quốc gia gốc của số điện thoại di động được kiểm tra. true
original_country_code string(2) Mã quốc gia ISO gồm hai ký tự đại diện cho quốc gia gốc của số điện thoại di động được kiểm tra. true
original_country_prefix string Mã quay số của quốc gia gốc liên kết với số điện thoại di động được kiểm tra. true
ported_network_name string Chỉ định nhà mạng mà số điện thoại di động được kiểm tra đã chuyển đến, nếu có. true
ported_country_name string Chỉ định quốc gia mà số điện thoại di động được kiểm tra đã chuyển đến, nếu có. true
ported_country_code string(2) Mã quốc gia ISO gồm hai ký tự đại diện cho quốc gia mà số điện thoại di động được kiểm tra đã chuyển đến, nếu có. true
ported_country_prefix string Mã quay số của quốc gia mà số điện thoại di động được kiểm tra đã chuyển đến, nếu có. true
extra string Chuỗi tùy ý cung cấp thông tin chi tiết bổ sung về số điện thoại, nếu có. true
cost string Giá trị thập phân, được biểu thị dưới dạng chuỗi, cho biết chi phí bằng EUR cho truy vấn này. true
timestamp string Dấu thời gian theo định dạng W3C, bao gồm thông tin múi giờ, cho biết thời điểm hoàn thành truy vấn. true
storage string Tên lưu trữ (hoặc tên báo cáo) mà kết quả truy vấn được thêm vào. Được sử dụng để tải xuống CSV và báo cáo qua giao diện web. true
route string(3) Mã định danh gồm ba ký tự chỉ định tuyến đường được sử dụng cho yêu cầu truy vấn này. true
error_code integer Mã lỗi nội bộ tùy chọn cung cấp thêm ngữ cảnh cho chẩn đoán hỗ trợ khách hàng. true
Cuộn lên

POST/nt-lookupđược bảo vệ

Thực hiện tra cứu loại số (NT) đồng bộ. Endpoint này lý tưởng nếu mục tiêu chính của bạn là xác định các số điện thoại được cung cấp thuộc dải số cố định, di động, cước cao, VoIP, máy nhắn tin hay các dải số khác trong kế hoạch đánh số theo thời gian thực.

Truy vấn NT phát hiện chính xác loại số điện thoại; tuy nhiên, chúng không cho biết liệu số đích hiện có đang kết nối với mạng và có thể liên lạc được hay không. Để trích xuất thông tin kết nối trực tiếp, vui lòng sử dụng endpoint POST /hlr-lookup.

Nếu trường hợp sử dụng của bạn yêu cầu thông tin mạng và chuyển mạng giữ số (MCCMNC) chính xác nhưng không cần trạng thái kết nối trực tiếp, vui lòng sử dụng endpoint POST /mnp-lookup để truy vấn chuyển mạng giữ số di động.

Yêu cầu Phản hồi thành công Phản hồi lỗi Tham Chiếu Loại
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

Dữ liệu gửi

application/json 
{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
number string Số điện thoại ở định dạng quốc tế (ví dụ: +4989702626 hoặc 004989702626). null mandatory
route string(3) Mã định danh ba ký tự tùy chọn chỉ định tuyến đường cho tra cứu này. Đặt thành null hoặc bỏ qua tham số này để áp dụng sơ đồ định tuyến tùy chỉnh của bạn hoặc để hệ thống của chúng tôi tự động xác định các tuyến đường tốt nhất cho yêu cầu này. null tùy chọn
storage string Mã định danh lưu trữ tùy chọn chỉ định báo cáo nơi kết quả sẽ được lưu trữ để xem xét thủ công, phân tích và báo cáo. Hệ thống tự động thêm dấu thời gian với tháng hiện tại. Nếu bỏ qua hoặc đặt thành null, hệ thống sẽ tự động nhóm kết quả theo tháng cho mục đích báo cáo. null tùy chọn
200 OK 
{
     "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"
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
id string(12) Mã định danh duy nhất được gán cho yêu cầu tra cứu này. false
number string Số điện thoại được đánh giá trong yêu cầu tra cứu này. false
number_type string Loại số được phát hiện. Các giá trị có thể bao gồm: LANDLINE , MOBILE , MOBILE_OR_LANDLINE , TOLL_FREE , PREMIUM_RATE , SHARED_COST , VOIP , PAGER , UAN , VOICEMAIL , UNKNOWN . false
query_status string Cho biết liệu thông tin loại số có được lấy thành công hay không. Trả về OK nếu thành công, hoặc FAILED nếu tra cứu thất bại. false
is_valid boolean Cho biết liệu số điện thoại có hợp lệ về mặt cú pháp hay không. true
invalid_reason string Thông báo văn bản thuần túy bằng tiếng Anh chỉ rõ lý do số điện thoại được coi là không hợp lệ (ví dụ: "too short" hoặc "invalid prefix"), hoặc null nếu số hợp lệ. true
is_possibly_ported boolean Cho biết liệu số điện thoại có thể đã được chuyển mạng từ nhà mạng ban đầu sang nhà mạng khác hay không. Để có thông tin chuyển mạng chính xác, vui lòng sử dụng tra cứu MNP. true
is_vanity_number boolean Cho biết liệu số điện thoại có phải là số vanity hay không, nghĩa là có chứa các ký tự chữ cái. true
qualifies_for_hlr_lookup boolean Cho biết liệu số điện thoại có đủ điều kiện để thực hiện các truy vấn bổ sung thông qua tra cứu HLR hay không. true
mccmnc string(5|6) Chuỗi năm hoặc sáu ký tự đại diện cho bộ MCCMNC (mã quốc gia di động và mã mạng di động) xác định mạng ban đầu của số điện thoại di động. true
mcc string(3) Chuỗi ba ký tự đại diện cho MCC (mã quốc gia di động) xác định quốc gia liên kết với mạng di động ban đầu của số điện thoại. true
mnc string(2|3) Chuỗi hai hoặc ba ký tự đại diện cho MNC (mã mạng di động) xác định nhà mạng di động ban đầu của số điện thoại. true
original_network_name string Chuỗi văn bản thuần túy bằng tiếng Anh chỉ định tên nhà mạng ban đầu của số điện thoại di động được kiểm tra. true
original_country_name string Chuỗi văn bản thuần túy bằng tiếng Anh chỉ định quốc gia ban đầu liên kết với số điện thoại di động được kiểm tra. true
original_country_code string(2) Mã quốc gia ISO hai ký tự cho biết quốc gia ban đầu của số điện thoại di động được kiểm tra. true
regions array Danh sách các chuỗi dễ đọc bằng tiếng Anh chỉ định (các) khu vực địa lý liên kết với số điện thoại này. true
timezones array Danh sách các múi giờ (theo định dạng Olson) liên kết với số điện thoại này. true
info_text string Chuỗi tùy ý có thể chứa thông tin bổ sung về số điện thoại. true
cost string Giá trị thập phân được biểu diễn dưới dạng chuỗi, cho biết chi phí (tính bằng EUR) của lần tra cứu này. true
timestamp string Dấu thời gian theo định dạng W3C (bao gồm múi giờ) cho biết thời điểm hoàn tất tra cứu. true
storage string Chỉ định tên kho lưu trữ nơi kết quả tra cứu đã được thêm vào. Tên này tương ứng với tên báo cáo được sử dụng để tải xuống CSV và phân tích thông qua giao diện web. true
route string(3) Mã định danh gồm ba ký tự chỉ định tuyến đường được sử dụng cho yêu cầu truy vấn này. true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Loại Mô tả
LANDLINE Số điện thoại cố định.
MOBILE Số điện thoại di động. Đủ điều kiện cho tra cứu HLR để lấy thông tin bổ sung về trạng thái kết nối, mạng, tính khả chuyển và chuyển vùng.
MOBILE_OR_LANDLINE Số điện thoại cố định hoặc di động. Có thể đủ điều kiện cho tra cứu HLR.
TOLL_FREE Số điện thoại miễn phí.
PREMIUM_RATE Số điện thoại cước cao với phí bổ sung.
SHARED_COST Số điện thoại chia sẻ chi phí. Thường rẻ hơn số điện thoại cước cao.
VOIP Số điện thoại Voice over IP. Bao gồm số điện thoại TSoIP (Telephony Service over IP).
PAGER Số máy nhắn tin. Thường không có chức năng thoại.
UAN Số Truy Cập Chung (Số Công Ty). Có thể được chuyển đến các văn phòng cụ thể nhưng cho phép sử dụng một số duy nhất cho toàn công ty.
VOICEMAIL Số điện thoại hộp thư thoại.
UNKNOWN Không thể xác định loại số.
Cuộn lên

POST/nt-lookups được bảo vệ

Endpoint này thực hiện một loạt tra cứu loại số bất đồng bộ với kết quả được gửi về máy chủ của bạn qua webhook. Phù hợp nếu mục tiêu chính của bạn là xác định các số điện thoại đã cho thuộc dải số cố định, di động, cước cao, VoIP, máy nhắn tin hay các dải số khác trong kế hoạch đánh số. Được tối ưu hóa để xử lý nhanh khối lượng lớn số điện thoại, endpoint này lý tưởng cho các thao tác hàng loạt (ví dụ: làm sạch cơ sở dữ liệu). Đối với lưu lượng trực tiếp và các trường hợp quan trọng về thời gian, vui lòng sử dụng endpoint POST /nt-lookup thay thế.

Bạn cần chỉ định URL webhook trong cài đặt API của mình như là điều kiện tiên quyết để gọi endpoint này.

Yêu cầu Phản hồi thành công Phản hồi lỗi Webhooks Tham Chiếu Loại
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

Dữ liệu gửi

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

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
numbers array Một mảng các số điện thoại ở định dạng quốc tế (ví dụ: +14156226819 hoặc 004989702626). Tối đa 1000 số có thể được bao gồm trong mỗi yêu cầu. null bắt buộc
route string(3) Mã định danh ba ký tự tùy chọn chỉ định tuyến đường cho tra cứu này. Đặt thành null hoặc bỏ qua tham số này để áp dụng bản đồ định tuyến tùy chỉnh của bạn hoặc để hệ thống của chúng tôi tự động xác định tuyến đường tốt nhất cho yêu cầu này. null tùy chọn
storage string Mã định danh lưu trữ tùy chọn chỉ định báo cáo nơi kết quả sẽ được lưu trữ để xem xét thủ công, phân tích và báo cáo. Hệ thống tự động thêm dấu thời gian với tháng hiện tại. Nếu bỏ qua hoặc đặt thành null, hệ thống sẽ tự động nhóm kết quả theo tháng cho mục đích báo cáo. null tùy chọn
200 OK 
{
   "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"
   ]
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
accepted array Một mảng các đối tượng, mỗi đối tượng chứa một mã định danh duy nhất và một số điện thoại đã được chấp nhận để xử lý. false
accepted_count integer Tổng số lượng số điện thoại được chấp nhận để xử lý. false
rejected array Một mảng các đối tượng, mỗi đối tượng chứa một mã định danh duy nhất và một số điện thoại đã bị từ chối xử lý. Thông thường, các số này không hợp lệ và không áp dụng phí. false
rejected_count integer Tổng số lượng số điện thoại đã bị từ chối xử lý. false
total_count integer Tổng số lượng số điện thoại được chấp nhận và bị từ chối đã được gửi để xử lý. false
cost string Một chuỗi đại diện cho giá trị thập phân cho biết chi phí bằng EUR cho các tra cứu này. false
storage string Tên của kho lưu trữ (báo cáo) nơi kết quả tra cứu đã được thêm vào. Tên này được sử dụng để tải xuống CSV và phân tích qua giao diện web. false
route string(3) Mã định danh ba ký tự chỉ định tuyến đường được sử dụng cho yêu cầu tra cứu này. false
webhook_urls array Các URL webhook được cấu hình trong cài đặt API của bạn. Kết quả được gửi trả về đây. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false

Xử lý Webhook

Sau khi gửi, nền tảng của chúng tôi sẽ bắt đầu xử lý các số điện thoại được cung cấp và gửi kết quả đến URL webhook đã chỉ định trước đó trên máy chủ của bạn. Kết quả được truyền dưới dạng yêu cầu HTTP POST với đối tượng JSON trong nội dung yêu cầu.

Xác thực

Xác thực webhook bằng cách kiểm tra HTTP header X-Signatures.

Header X-Signatures chứa danh sách các chữ ký được phân tách bằng dấu chấm phẩy. Mỗi chữ ký trong danh sách được tạo bằng một trong các API secret được cấu hình trong tài khoản của bạn. Để xác minh webhook, hãy tạo hash SHA-256 sử dụng API key, secret và nội dung HTTP thô của bạn - sau đó so sánh với các chữ ký trong danh sách.

Kết quả khớp xác nhận yêu cầu là xác thực và được ký bằng secret do bạn kiểm soát.

PHP Ví dụ mã

PHP 
$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;
    }
}

Yêu cầu hợp lệ nếu bất kỳ chữ ký nào trong header bằng với hash SHA256 được tính toán trên chuỗi nối của API key, secret và nội dung HTTP của bạn.

Xác nhận Đã Nhận

Máy chủ của bạn cần phản hồi bằng mã trạng thái HTTP 200 OK để xác nhận đã nhận thành công. Nếu trả về bất kỳ mã phản hồi nào khác, xảy ra timeout (10 giây), hoặc bất kỳ vấn đề giao hàng nào khác phát sinh, hệ thống sẽ tự động thử lại webhook sau một phút. Nếu yêu cầu tiếp tục thất bại, các lần thử lại sẽ tuân theo chiến lược exponential backoff, với các lần thử tiếp theo sau 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 phút.

Cơ chế thử lại này đảm bảo độ tin cậy tối đa trong việc gửi kết quả tra cứu đến hạ tầng của bạn. Điều này giảm thiểu rủi ro mất dữ liệu do sự cố mạng tạm thời hoặc máy chủ ngừng hoạt động.

Nội dung Webhook

HTTP POST (application/json) 
{
   "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"
      }
   ]
}

Thuộc Tính Dữ Liệu Webhook

Đối tượng JSON chứa thuộc tính type => NT cùng với thuộc tính results bao gồm danh sách các đối tượng tra cứu, như được ghi chép bên dưới.

Tên Loại Mô tả Có thể null
id string(12) Mã định danh duy nhất được gán cho yêu cầu tra cứu này. false
number string Số điện thoại được đánh giá trong yêu cầu tra cứu này. false
number_type string Loại số được phát hiện. Các giá trị có thể bao gồm: LANDLINE , MOBILE , MOBILE_OR_LANDLINE , TOLL_FREE , PREMIUM_RATE , SHARED_COST , VOIP , PAGER , UAN , VOICEMAIL , UNKNOWN . false
query_status string Cho biết liệu thông tin loại số có được lấy thành công hay không. Trả về OK nếu thành công, hoặc FAILED nếu tra cứu thất bại. false
is_valid boolean Cho biết liệu số điện thoại có hợp lệ về mặt cú pháp hay không. true
invalid_reason string Thông báo văn bản thuần túy bằng tiếng Anh chỉ rõ lý do số điện thoại được coi là không hợp lệ (ví dụ: "too short" hoặc "invalid prefix"), hoặc null nếu số hợp lệ. true
is_possibly_ported boolean Cho biết liệu số điện thoại có thể đã được chuyển mạng từ nhà mạng ban đầu sang nhà mạng khác hay không. Để có thông tin chuyển mạng chính xác, vui lòng sử dụng tra cứu MNP. true
is_vanity_number boolean Cho biết liệu số điện thoại có phải là số vanity hay không, nghĩa là có chứa các ký tự chữ cái. true
qualifies_for_hlr_lookup boolean Cho biết liệu số điện thoại có đủ điều kiện để thực hiện các truy vấn bổ sung thông qua tra cứu HLR hay không. true
mccmnc string(5|6) Chuỗi năm hoặc sáu ký tự đại diện cho bộ MCCMNC (mã quốc gia di động và mã mạng di động) xác định mạng ban đầu của số điện thoại di động. true
mcc string(3) Chuỗi ba ký tự đại diện cho MCC (mã quốc gia di động) xác định quốc gia liên kết với mạng di động ban đầu của số điện thoại. true
mnc string(2|3) Chuỗi hai hoặc ba ký tự đại diện cho MNC (mã mạng di động) xác định nhà mạng di động ban đầu của số điện thoại. true
original_network_name string Chuỗi văn bản thuần túy bằng tiếng Anh chỉ định tên nhà mạng ban đầu của số điện thoại di động được kiểm tra. true
original_country_name string Chuỗi văn bản thuần túy bằng tiếng Anh chỉ định quốc gia ban đầu liên kết với số điện thoại di động được kiểm tra. true
original_country_code string(2) Mã quốc gia ISO hai ký tự cho biết quốc gia ban đầu của số điện thoại di động được kiểm tra. true
regions array Danh sách các chuỗi dễ đọc bằng tiếng Anh chỉ định (các) khu vực địa lý liên kết với số điện thoại này. true
timezones array Danh sách các múi giờ (theo định dạng Olson) liên kết với số điện thoại này. true
info_text string Chuỗi tùy ý có thể chứa thông tin bổ sung về số điện thoại. true
cost string Giá trị thập phân được biểu diễn dưới dạng chuỗi, cho biết chi phí (tính bằng EUR) của lần tra cứu này. true
timestamp string Dấu thời gian theo định dạng W3C (bao gồm múi giờ) cho biết thời điểm hoàn tất tra cứu. true
storage string Chỉ định tên kho lưu trữ nơi kết quả tra cứu đã được thêm vào. Tên này tương ứng với tên báo cáo được sử dụng để tải xuống CSV và phân tích thông qua giao diện web. true
route string(3) Mã định danh gồm ba ký tự chỉ định tuyến đường được sử dụng cho yêu cầu truy vấn này. true
Loại Mô tả
LANDLINE Số điện thoại cố định.
MOBILE Số điện thoại di động. Đủ điều kiện cho tra cứu HLR để lấy thông tin bổ sung về trạng thái kết nối, mạng, tính khả chuyển và chuyển vùng.
MOBILE_OR_LANDLINE Số điện thoại cố định hoặc di động. Có thể đủ điều kiện cho tra cứu HLR.
TOLL_FREE Số điện thoại miễn phí.
PREMIUM_RATE Số điện thoại cước cao với phí bổ sung.
SHARED_COST Số điện thoại chia sẻ chi phí. Thường rẻ hơn số điện thoại cước cao.
VOIP Số điện thoại Voice over IP. Bao gồm số điện thoại TSoIP (Telephony Service over IP).
PAGER Số máy nhắn tin. Thường không có chức năng thoại.
UAN Số Truy Cập Chung (Số Công Ty). Có thể được chuyển đến các văn phòng cụ thể nhưng cho phép sử dụng một số duy nhất cho toàn công ty.
VOICEMAIL Số điện thoại hộp thư thoại.
UNKNOWN Không thể xác định loại số.
Cuộn lên

GET/routeđược bảo vệ

Truy xuất tuyến đường sẽ được tự động chọn khi bạn thực hiện tra cứu HLR mà không chỉ định tham số route.

Việc chọn tuyến đường tự động dựa trên bản đồ định tuyến có thể truy xuất qua endpoint GET /hlr-coverage, chủ yếu được lấy từ GET /routing-map. Bạn có thể tùy chỉnh bản đồ định tuyến và thiết lập các quy tắc tùy chỉnh trong cài đặt tài khoản của mình.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
msisdn string Số MSISDN để truy xuất thông tin định tuyến được chọn tự động. null bắt buộc
200 OK 
{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
route string Tuyến đường được đề xuất. false
confidence_level string Mức độ tin cậy mà tuyến đường này được chọn, tức là LOW, NORMAL, HIGH, MNP_FALLBACK. false
mccmnc string Mã MCCMNC dựa trên kế hoạch đánh số cho số này. false
origin string Nguồn gốc mà quyết định định tuyến dựa vào, tức là 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
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/routesđược bảo vệ

Endpoint này trả về danh sách các tuyến HLR, MNP và NT khả dụng. Mỗi tuyến, cùng với các tính năng và hạn chế của nó, được giải thích trên trang chi tiết định tuyến.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/routes'
200 OK 
{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
routes object Một đối tượng với các tuyến được nhóm theo loại tuyến. false
HLR|MNP|NT string[] Chứa danh sách các mã định danh tuyến. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/routing-mapđược bảo vệ

Truy xuất cấu hình định tuyến tự động hiện đang được áp dụng cho các truy vấn HLR của tài khoản bạn. Cấu hình mặc định này được sử dụng khi bạn gửi truy vấn HLR mà không chỉ định tham số route. Bạn có thể tùy chỉnh bản đồ định tuyến và tạo quy tắc tùy chỉnh trong cài đặt tài khoản.

Hệ thống phân cấp cấu hình được áp dụng theo thứ tự từ quy tắc cấp quốc gia đến quy tắc cấp MCCMNC, và cuối cùng là ánh xạ theo tiền tố số điện thoại cụ thể. Trong thực tế, điều này có nghĩa là ánh xạ theo tiền tố số điện thoại cụ thể sẽ được ưu tiên hơn các phân bổ MCCMNC xung đột, và các phân bổ MCCMNC lại ghi đè quy tắc cấp quốc gia. Lưu ý rằng MNP fallback sẽ ghi đè mọi quy tắc tùy chỉnh xung đột khi được kích hoạt.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/routing-map'
200 OK 
{
   "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"
            }
         ]
      }
   }
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
default_route string Tuyến đường mặc định được sử dụng khi không thể xác định được tùy chọn định tuyến ưu tiên cho MSISDN và không có quy tắc định tuyến tùy chỉnh nào được áp dụng. false
mnp_fallback boolean Cho biết MNP fallback có được kích hoạt hay không. Khi được kích hoạt và truy vấn HLR không được hỗ trợ bởi mạng (trạng thái kết nối không khả dụng), hệ thống sẽ thực hiện tra cứu MNP thay thế. false
mccmncs array Ánh xạ các mã MCCMNC với tuyến đường được chọn tự động. Khi thực hiện tra cứu HLR cho số thuộc MCCMNC nhất định, tuyến đường tương ứng sẽ được sử dụng. false
mccmnc string(5|6) Mã MCCMNC năm hoặc sáu ký tự (kết hợp mã quốc gia di động và mã mạng di động) xác định nhà khai thác mạng di động. false
countrycode string(2) Mã quốc gia ISO gồm hai ký tự, xác định quốc gia của mạng. false
route string(3) Tuyến đường được chọn cho mạng. false
mno string Thương hiệu hướng đến người tiêu dùng mà mạng này hoạt động dưới tên. false
confidence string Mức độ tin cậy của lựa chọn. Các giá trị có thể là: HIGH, NORMAL, LOW, MNP_REDIRECT. Trong trường hợp giá trị cuối cùng, hệ thống chuyển hướng lưu lượng đến mạng này sang MNP nếu hành vi này được kích hoạt trong tài khoản của bạn. Nếu không, hệ thống sử dụng tuyến đường mặc định trong tài khoản. false
origin string Nguồn gốc mà lựa chọn dựa trên. Các giá trị có thể là: 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 Danh sách các quy tắc định tuyến tùy chỉnh theo tiền tố được cấu hình trong tài khoản của bạn, nếu có. false
countrycode string(2) Mã quốc gia ISO gồm hai ký tự, xác định quốc gia của tiền tố. false
cns string Tiền tố mà quy tắc định tuyến áp dụng. false
route string(3) Tuyến đường được chọn cho tiền tố. false
mccmnc string(5|6) Mã MCCMNC năm hoặc sáu ký tự (kết hợp mã quốc gia di động và mã mạng di động) xác định nhà khai thác mạng di động. true
mno string Thương hiệu hướng đến người tiêu dùng mà mạng này hoạt động dưới tên. true
countries array Danh sách các quy tắc tùy chỉnh theo quốc gia được cấu hình trong tài khoản của bạn, nếu có. false
countrycode string(2) Mã quốc gia ISO gồm hai ký tự, xác định quốc gia. false
route string(3) Tuyến đường được chọn cho quốc gia. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/hlr-coverage được bảo vệ

Trả về thông tin chi tiết về phạm vi phủ sóng HLR để hỗ trợ ra quyết định dựa trên dữ liệu. Endpoint này giúp bạn phân tích các tùy chọn định tuyến HLR theo thời gian thực trên các mạng di động, xác định các tuyến đường hiệu quả nhất cho khu vực mục tiêu của bạn và cấu hình định tuyến tự động.

Các tuyến đường được đề xuất từ GET /route dựa trên dữ liệu phạm vi phủ sóng được truy xuất tại đây. Dữ liệu phạm vi phủ sóng cũng có sẵn trên trang phạm vi phủ sóng mạng. Bạn có thể tùy chỉnh thêm sơ đồ định tuyến và xác định các quy tắc trong cài đặt tài khoản của bạn.

Chúng tôi khuyến nghị bạn làm quen với hướng dẫn này để giúp diễn giải kết quả.

Yêu cầu Phản hồi thành công Phản hồi lỗi Tham Chiếu Trạng Thái
cURL 
curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
countrycode string(2) Mã quốc gia ISO hai chữ cái bắt buộc được sử dụng để lọc kết quả, chỉ trả về các bản ghi liên quan đến quốc gia được chỉ định. null bắt buộc
sample_size string Tham số tùy chọn chỉ định kích thước mẫu. Các giá trị có thể là LARGE, MEDIUM, SMALL. Mẫu lớn hơn bao phủ khung thời gian dài hơn, mẫu nhỏ hơn bao phủ khung thời gian gần đây nhất. LARGE tùy chọn
200 OK 
{
   "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
            }
         ]
      }
   ]
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
name string Tên quốc gia đã chọn bằng tiếng Anh văn bản thuần túy. false
countrycode string(2) Mã quốc gia ISO hai ký tự của quốc gia đã chọn. false
prefix string Mã vùng quốc tế của quốc gia đã chọn. false
mccs string[] Danh sách các MCC (mã quốc gia di động) liên quan đến quốc gia đã chọn. false
carriers object[] Danh sách các đối tượng nhà mạng với các chỉ số kết nối theo tuyến đường cụ thể. false
mno string Tên nhà khai thác mạng di động bằng tiếng Anh văn bản thuần túy. false
mccmnc string MCCMNC của nhà khai thác mạng di động. false
mcc string MCC (mã quốc gia di động) của nhà khai thác mạng di động. false
mnc string MNC (mã mạng di động) của nhà khai thác mạng di động. false
routes object[] Danh sách các kết quả kết nối theo tuyến đường cụ thể. false
route string Tuyến đường mà thông tin kết nối áp dụng. false
selected bool Cho biết đây có phải là tuyến đường được chọn cho định tuyến tự động hay không. false
selection_confidence string Mức độ tin cậy mà tuyến đường này được chọn, tức là LOW, NORMAL, HIGH, MNP_FALLBACK. Chứa null nếu đây không phải là tuyến đường được chọn. true
n int Tổng số lượng tra cứu trong mẫu này. false
CONNECTED int Số lượng tra cứu HLR trả về trạng thái CONNECTED. false
CONNECTED_PCT float Tỷ lệ phần trăm tra cứu HLR trả về trạng thái CONNECTED. false
ABSENT int Số lượng tra cứu HLR trả về trạng thái ABSENT. false
ABSENT_PCT float Tỷ lệ phần trăm tra cứu HLR trả về trạng thái ABSENT. false
INVALID_MSISDN int Số lượng tra cứu HLR trả về trạng thái INVALID_MSISDN. false
INVALID_MSISDN_PCT float Tỷ lệ phần trăm tra cứu HLR trả về trạng thái INVALID_MSISDN. false
UNDETERMINED int Số lượng tra cứu HLR trả về trạng thái UNDETERMINED. false
UNDETERMINED_PCT float Tỷ lệ phần trăm tra cứu HLR trả về trạng thái UNDETERMINED. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Trạng thái Mô tả
CONNECTED Số điện thoại hợp lệ và thiết bị di động đích hiện đang kết nối với mạng di động. Cuộc gọi, tin nhắn SMS và các dịch vụ khác sẽ được gửi đến người nhận thành công.
ABSENT Số điện thoại hợp lệ, nhưng thiết bị di động đích đang tắt nguồn hoặc tạm thời nằm ngoài vùng phủ sóng mạng. Tin nhắn hoặc cuộc gọi có thể không được gửi đến cho đến khi thiết bị kết nối lại với mạng.
INVALID_MSISDN Số điện thoại không hợp lệ hoặc hiện không được gán cho bất kỳ thuê bao nào trên mạng di động. Cuộc gọi và tin nhắn đến số này sẽ thất bại.
UNDETERMINED Không thể xác định trạng thái kết nối của số điện thoại. Nguyên nhân có thể do số không hợp lệ, phản hồi lỗi SS7, hoặc thiếu kết nối với nhà mạng đích. Vui lòng kiểm tra mã lỗi và trường mô tả để có thêm thông tin chẩn đoán.
Cuộn lên

GET/mnp-coverageđược bảo vệ

Endpoint này trả về danh sách các nhà khai thác mạng di động, cùng với mã định danh MCCMNC tương ứng, hiện đang được hỗ trợ cho tra cứu chuyển mạng giữ số.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
countrycode string(2) Mã quốc gia ISO hai ký tự tùy chọn dùng để lọc kết quả MCCMNC, chỉ trả về dữ liệu liên quan đến quốc gia được chỉ định. null tùy chọn
200 OK 
{
   "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"
      }
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
items[] array Danh sách các nhà mạng di động. false
country_name string Tên quốc gia bằng tiếng Anh. false
country_code string(2) Mã quốc gia ISO hai ký tự. false
mccmnc string(5|6) Mã MCCMNC năm hoặc sáu ký tự (kết hợp mã quốc gia di động và mã mạng di động) xác định nhà khai thác mạng di động. false
mcc string(3) Mã MCC ba ký tự (mã quốc gia di động) đại diện cho quốc gia của mạng. false
mnc string(2|3) Mã MNC hai hoặc ba ký tự (mã mạng di động) đại diện cho nhà khai thác mạng di động cụ thể. false
brand string Thương hiệu hướng đến người tiêu dùng mà mạng này hoạt động dưới tên. true
operator string Tên pháp lý của nhà khai thác mạng di động. true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/price-listđược bảo vệ

Endpoint này trả về danh sách các quốc gia chỉ hỗ trợ tra cứu MNP, trong khi truy vấn HLR không khả dụng cho các điểm đến này.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'
200 OK 
{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
countries string[] Danh sách mã quốc gia ISO gồm hai ký tự. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/mccmncsđược bảo vệ

Endpoint này trả về danh sách đầy đủ các nhà mạng di động cùng với mã định danh MCCMNC tương ứng và thông tin ngữ cảnh bổ sung.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
countrycode string(2) Mã quốc gia ISO hai chữ cái tùy chọn được sử dụng để lọc kết quả MCCMNC, chỉ trả về các bản ghi liên quan đến quốc gia được chỉ định. null tùy chọn
200 OK 
{
   "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"
      }
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
items object[] Danh sách các nhà mạng di động. false
country_name string Tên đầy đủ của quốc gia bằng tiếng Anh. false
country_code string(2) Mã quốc gia ISO hai chữ cái đại diện cho quốc gia của nhà mạng di động. false
mccmnc string(5|6) Chuỗi năm hoặc sáu ký tự đại diện cho MCCMNC, định danh duy nhất của nhà mạng di động. false
mcc string(3) Mã quốc gia di động (MCC) ba ký tự xác định quốc gia nơi mạng di động hoạt động. false
mnc string(2|3) Mã mạng di động (MNC) hai hoặc ba ký tự chỉ định mạng di động trong MCC đã cho. false
brand string Tên thương hiệu thương mại mà mạng hoạt động và được người tiêu dùng biết đến. true
operator string Tên chính thức của nhà mạng di động, thường là pháp nhân quản lý mạng. true
parent_mccmnc string(5|6) Chuỗi năm hoặc sáu ký tự đại diện cho MCCMNC của nhà mạng di động mẹ, nếu có. true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/priceđược bảo vệ

Endpoint này trả về giá cho tra cứu HLR, MNP hoặc NT.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

Tham Số Yêu Cầu

Khóa Loại Mô tả Mặc Định Bắt Buộc
msisdn string Số điện thoại cần tra cứu giá. Theo định dạng quốc tế. null bắt buộc
route_type string Loại tuyến đường, ví dụ: HLR, MNP, NT. null bắt buộc
route string(3) Tuyến đường được sử dụng để tính giá. Mặc định là tuyến đường được xác định bởi định tuyến tự động. null tùy chọn
200 OK 
{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
price object Đối tượng chứa thông tin chi tiết về giá. false
amount string Số tiền tính bằng EUR. false
msisdn string Số MSISDN mà giá này áp dụng. false
route_type string(2|3) Loại tuyến đường mà giá này áp dụng. false
route string(3) Tuyến đường mà giá này áp dụng. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/price-listđược bảo vệ

Endpoint này trả về bảng giá trong tài khoản của bạn.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/price-list'
200 OK 
{
   "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"
      }
   ]
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
pricing object[] Danh sách các đối tượng chứa thông tin giá cả. false
route string Loại dịch vụ mà giá này áp dụng. false
countrycode string Mã quốc gia ISO hai ký tự mà giá này áp dụng cho loại dịch vụ tương ứng, nếu có. true
countryname string Tên quốc gia bằng tiếng Anh tương ứng với mã quốc gia, nếu có. true
mccmnc string Mã MCCMNC mà giá này áp dụng cho loại dịch vụ tương ứng, nếu có. Ghi đè giá cấp quốc gia. true
cns string Mã vùng quay số mà giá này áp dụng cho loại dịch vụ tương ứng, nếu có. Ghi đè giá cấp quốc gia và giá cấp MCCMNC. true
route_type string Loại dịch vụ tương ứng, ví dụ: HLR, MNP, NT. false
route_type string Giá tương ứng tính bằng EUR. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/balanceđược bảo vệ

Endpoint này truy xuất số dư tài khoản hiện tại của bạn, cho phép bạn tự động hóa các quy trình dựa trên trạng thái tín dụng. Tính năng này hoạt động liền mạch với email thông báo tín dụng thấp mà bạn có thể cấu hình trên trang thanh toán.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/balance'
200 OK 
{
    "balance":"1002.90"
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
balance string Số dư tài khoản hiện tại của bạn tính bằng EUR. Giá trị thập phân dạng chuỗi. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/pingcông khai

Endpoint này gửi yêu cầu ping đến API, cung cấp phương thức đơn giản để kiểm tra kết nối của bạn với HLR Lookups API.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/ping'
200 OK 
{
    "success":true
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
success boolean Cho biết yêu cầu đã được xử lý thành công. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/timecông khai

Endpoint này trả về dấu thời gian Unix đại diện cho thời gian hiện tại trên máy chủ HLR Lookups. Sử dụng endpoint này để đồng bộ hóa đồng hồ máy chủ của bạn khi tạo chữ ký Digest-Auth để xác thực, đảm bảo mọi sự chênh lệch giữa thời gian máy chủ của bạn và thời gian máy chủ HLR Lookups được điều chỉnh.

Yêu cầu Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/time'
200 OK 
{
    "time":1525898643
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
time integer Dấu thời gian Unix đại diện cho thời gian hiện tại của máy chủ HLR Lookups. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

GET/auth-testđược bảo vệ

Endpoint này phục vụ như một bài kiểm tra ban đầu cho việc triển khai Basic-Auth hoặc tốt hơn là Digest-Auth của bạn.

Yêu cầu Basic Auth Yêu cầu Digest Auth Phản hồi thành công Phản hồi lỗi
cURL 
curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

Headers yêu cầu

Khóa Loại Mô tả
X-Basic string Mã băm SHA256 của YOUR_API_KEY:YOUR_API_SECRET. Bao gồm ký tự hai chấm (:) trong mã băm.
cURL (Digest-Auth) 
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"

Headers yêu cầu

Khóa Loại Mô tả
X-Digest-Key string API Key của bạn trên HLR Lookups
X-Digest-Signature string Chữ ký Digest-Auth duy nhất (xem xác thực)
X-Digest-Timestamp integer Dấu thời gian Unix hiện tại (cũng xem GET /time)
200 OK 
{
    "success":true
}

Thuộc tính phản hồi thành công

Tên Loại Mô tả Có thể null
success boolean Cho biết yêu cầu đã được xử lý thành công. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Tham Số Phản Hồi Lỗi

Tên Loại Mô tả Có thể null
errors[] string[] Danh sách các chuỗi giải thích lỗi. false
Cuộn lên

Tài liệu API Cũ

Xin lưu ý rằng API cũ đã ngừng hỗ trợ và sẽ được loại bỏ trong tương lai. Chúng tôi đặc biệt khuyến nghị nâng cấp lên phiên bản mới nhất sớm nhất có thể.

Nếu bạn đã triển khai API HLR Lookups của chúng tôi từ năm 2013 đến đầu năm 2020, bạn đang sử dụng API cũ. Trong trường hợp đó, vui lòng tham khảo tài liệu API cũ của chúng tôi.

Tài liệu API Cũ

Nâng cao Trí tuệ Di động với Nền tảng HLR Lookups Hàng đầu


Liên Hệ
Ngôn ngữ한국어ภาษาไทยBahasa IndonesiaČeštinaDanskDeutschEestiEnglishEspañolFilipinoFrançaisItalianoLatviešuLietuviųMagyarNederlandsNorskPolskiPortuguêsRomânăSuomiSvenskaTiếng ViệtTürkçeΕλληνικάБългарскиРуccкийУкраїнськаहिन्दीবাংলা日本語简体中文繁体中文
© Velocity Made Good Ltd. 2013-2026 · Điều khoản Dịch vụ · Chính sách Bảo mật · Thỏa Thuận Xử Lý Dữ Liệu
Biểu tượng Tải Ảnh Gif Trong suốt