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

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

{
   "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.

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 '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 '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

Ví dụ mã

$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 '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

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)

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

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);

Xem trên 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   }

Xem trên 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)

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 -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

Dữ liệu gửi

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

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

{
    "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 -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

Dữ liệu gửi

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

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

{
    "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.

Ví dụ mã

$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

{
   "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 -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

Dữ liệu gửi

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

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

{
    "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 -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

Dữ liệu gửi

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

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

{
    "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.

Ví dụ mã

$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

{
    "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 -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

Dữ liệu gửi

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

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

{
    "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 -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

Dữ liệu gửi

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

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

{
    "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.

Ví dụ mã

$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

{
   "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 '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

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

{
    "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 'https://www.hlr-lookups.com/api/v2/routes'

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

{
    "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 '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"
            }
         ]
      }
   }
}

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

{
    "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 '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

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

{
    "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 '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

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

{
    "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 'https://www.hlr-lookups.com/api/v2/mnp-countries'

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

{
    "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 '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

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

{
    "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 '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

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

{
    "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 '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"
      }
   ]
}

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

{
    "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 'https://www.hlr-lookups.com/api/v2/balance'

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

{
    "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 'https://www.hlr-lookups.com/api/v2/ping'

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

{
    "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 'https://www.hlr-lookups.com/api/v2/time'

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

{
    "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 '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 '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`)

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

{
    "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ũ

Tài liệu API

Bắt Đầu

Tra cứu HLR

Tra cứu MNP

Tra cứu NT

Định tuyến

Bảng Giá

Công Cụ

Bắt Đầu

Sử Dụng API HLR Lookups

Ví Dụ Yêu Cầu

Ví Dụ Payload

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

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

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

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

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

Công Cụ

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

Xác thực

API Key và API Secret

HTTP Basic Auth

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

Yêu cầu Basic Auth

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

Ví dụ mã

Ví dụ yêu cầu

Headers yêu cầu

Tạo chữ ký

Thành phần chữ ký Digest

Ví dụ mã

Khái niệm

API HLR Lookup Đồng Bộ

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

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

SDK PHP

SDK NodeJS

SDK Ruby

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

Dữ liệu gửi

Tham Số Yêu Cầu

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

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

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

Dữ liệu gửi

Tham Số Yêu Cầu

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

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

Xử lý Webhook

Xác thực

Ví dụ mã

Xác nhận Đã Nhận

Nội dung Webhook

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

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

Dữ liệu gửi

Tham Số Yêu Cầu

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

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

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

Dữ liệu gửi

Tham Số Yêu Cầu

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

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

Xử lý Webhook

Xác thực

Ví dụ mã

Xác nhận Đã Nhận

Nội dung Webhook

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

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

Dữ liệu gửi

Tham Số Yêu Cầu

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

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

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

Dữ liệu gửi

Tham Số Yêu Cầu

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

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