Panduan Permulaan

Infrastruktur rangkaian mudah alih global beroperasi pada sistem yang dikenali sebagai rangkaian isyarat SS7. Rangkaian ini memudahkan pertukaran data pelanggan, penghalaan panggilan, penghantaran SMS, dan kemas kini status sambungan mudah alih masa nyata antara operator. Setiap rangkaian mudah alih menyelenggara Daftar Lokasi Utama (HLR) - pangkalan data teras yang menyimpan butiran penting tentang pelanggannya.

Teknologi HLR Lookup membolehkan perniagaan membuat pertanyaan ke daftar ini dan mendapatkan butiran sambungan dan rangkaian secara langsung untuk sebarang nombor telefon mudah alih. Ini termasuk sama ada telefon dihidupkan, rangkaian mana yang sedang ditetapkan, sama ada ia telah dipindahkan, sama ada nombor itu sah atau dinyahaktifkan, dan sama ada ia dalam perayauan.

API HLR Lookups menyediakan akses lancar dan masa nyata kepada data ini, membolehkan perniagaan mengesahkan nombor mudah alih, mengoptimumkan penghalaan, dan meningkatkan komunikasi pelanggan. Dokumentasi ini akan membimbing anda menyepadukan HLR Lookups ke dalam perisian anda, membolehkan pengambilan automatik maklumat mudah alih masa nyata.

Menggunakan API HLR Lookups

Melaksanakan pertanyaan HLR Lookup adalah pantas, selamat, dan mudah. Setelah anda mendaftar dan mendapatkan Kunci API anda, anda boleh mengesahkan dan memulakan carian segera dengan permintaan HTTP POST yang mudah, melalui POST /hlr-lookup. Sebagai alternatif, anda boleh memproses set data yang besar dengan memilih permintaan API tak segerak yang pantas dengan keputusan dihantar kembali ke pelayan anda melalui webhook, seperti yang dijelaskan dalam bahagian konsep.

Contoh Permintaan

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"

Pengesahan dibekalkan melalui pengepala HTTP, dan payload.json hendaklah (sekurang-kurangnya) mengandungi objek JSON berikut:

Contoh Muatan

{
   "msisdn": "+14156226819"
}

Setelah berjaya dilaksanakan, anda akan menerima respons yang mengandungi butiran sambungan masa nyata untuk nombor mudah alih yang dinyatakan.

Respons Berjaya 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"
}

Untuk pecahan lengkap atribut permintaan dan respons serta status sambungan, lihat POST /hlr-lookup.

Perkhidmatan Carian Tambahan

Carian Kemudahalihan Nombor Mudah Alih (MNP)

Gunakan carian MNP untuk menentukan pemilikan rangkaian dan butiran kemudahalihan tanpa membuat pertanyaan sambungan masa nyata. Jika anda hanya memerlukan MCCMNC sesuatu nombor, rujuk POST /mnp-lookup.

Carian Pengesanan Jenis Nombor (NT)

Tentukan sama ada nombor telefon adalah talian tetap, mudah alih, kadar premium, VoIP, alat kelui, atau julat pelan penomboran lain dengan POST /nt-lookup.

Kit Pembangunan Perisian (SDK)

API HLR Lookups berfungsi dengan mana-mana klien REST dalam sebarang bahasa pengaturcaraan dan kami telah menerbitkan SDK untuk PHP, Ruby, dan NodeJS di GitHub kami untuk membantu anda bermula dengan cepat.

Alatan

Untuk memastikan pengalaman pembangunan yang lancar, kami menawarkan rangkaian alatan yang komprehensif, termasuk pemantauan permintaan API dan webhook dalam pelayar, penyenaraian putih alamat IP, pilihan pengesahan yang kukuh, dan endpoint ujian pengesahan.

Bukan Pembangun?

Carian HLR dan Pertanyaan Kemudahalihan Nombor boleh dilakukan tanpa sebarang pengekodan. Ketahui lebih lanjut tentang klien web perusahaan kami dan ciri pelaporan berasaskan pelayar.

Pengesahan

Untuk memastikan keselamatan dan kawalan akses yang betul, kebanyakan permintaan ke API HLR Lookups memerlukan pengesahan. Endpoint dikategorikan sebagai awam atau dilindungi. Apabila mengakses endpoint yang dilindungi, permintaan anda mesti disahkan menggunakan kunci API dan rahsia anda melalui kaedah Digest-Auth atau Basic-Auth. Digest-Auth adalah pilihan yang lebih selamat dan amat disyorkan. Gunakan endpoint GET /auth-test untuk mengesahkan tetapan pengesahan anda.

Kunci API dan Rahsia API

Dapatkan kunci API dan rahsia anda dari halaman tetapan API. Anda juga boleh mengkonfigurasi kaedah pengesahan pilihan anda dan mengaktifkan senarai putih alamat IP untuk keselamatan yang lebih baik. Jika anda mengesyaki rahsia API anda telah terjejas, anda boleh menjana yang baharu pada bila-bila masa.

Basic Auth Digest Auth Senarai Putih IP

Pengesahan Basic standard mudah dilaksanakan dan disokong secara meluas. Anda boleh mengesahkan dengan menghantar kunci API dan rahsia anda sebagai pasangan user:pass dalam permintaan HTTP.

HTTP Basic Auth

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

Ini menghantar pengepala Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Disyorkan: Pengepala X-Basic dengan SHA256

Untuk keselamatan yang lebih baik, anda boleh menghantar hash SHA256 kelayakan anda dan bukannya menghantarnya secara langsung sebagai base64. Untuk menggunakan kaedah ini, kira hash pasangan YOUR_API_KEY:YOUR_API_SECRET anda dan hantarkannya melalui pengepala X-Basic:

Permintaan Basic Auth

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

Pengepala Pengesahan Basic

Kunci	Jenis	Keterangan
`X-Basic`	string	Hash SHA256 bagi `YOUR_API_KEY:YOUR_API_SECRET`. Sertakan simbol titik bertindih (:) dalam hash.	wajib

Contoh Kod

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

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

Digest-Auth adalah kaedah yang disyorkan untuk melindungi akses ke titik akhir API HLR Lookup yang dilindungi. Setiap permintaan mesti mengandungi pengepala berikut: X-Digest-Key, X-Digest-Signature, dan X-Digest-Timestamp, yang dijelaskan di bawah.

Contoh Permintaan

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"

Pengepala Permintaan

Kunci	Jenis	Keterangan
`X-Digest-Key`	string	Kunci API HLR Lookups unik anda.	wajib
`X-Digest-Signature`	string	Tandatangan pengesahan unik (lihat di bawah).	wajib
`X-Digest-Timestamp`	integer	Cap masa Unix semasa (lihat juga `GET /time`).	wajib

Membina Tandatangan

X-Digest-Signature dicipta menggunakan hash SHA256 HMAC, dengan rahsia API anda sebagai kunci dikongsi.

Rentetan untuk dihash distrukturkan seperti berikut:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Simbol . mewakili penggabungan rentetan.

Komponen Tandatangan Digest

Komponen	Jenis	Keterangan
`ENDPOINT_PATH`	string	Titik akhir API yang diminta, contohnya, `/auth-test` dalam huruf kecil.
`UNIX_TIMESTAMP`	integer	Cap masa Unix semasa (mesti dalam lingkungan 30 saat). Lihat `GET /time`.
`REQUEST_METHOD`	string	Kaedah HTTP yang digunakan, contohnya, `POST` atau `GET`.
`REQUEST_BODY`	string	Data badan permintaan. Tetapkan kepada `null` untuk permintaan `GET`.

Contoh Kod

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)

Tatal ke Atas

Konsep

Melaksanakan Carian HLR dalam mana-mana bahasa pengaturcaraan atau sistem melalui HTTP REST API kami adalah mudah dan cekap. Dengan proses integrasi yang ringkas, anda boleh mula membuat pertanyaan rangkaian mudah alih secara masa nyata untuk mendapatkan maklumat segera tentang kesahihan nombor telefon, status ketersambungan dan butiran penghalaan.

Pemilihan API yang sesuai bergantung kepada kes penggunaan spesifik anda. Jika anda memerlukan hasil carian masa nyata untuk aplikasi seperti telefoni VoIP, pengesanan penipuan atau penghalaan SMS, API segerak adalah pilihan terbaik. Walau bagaimanapun, jika kes penggunaan anda melibatkan pemprosesan volum tinggi, carian pukal atau pengesahan data berskala besar, API tak segerak menawarkan prestasi yang dioptimumkan dengan kecekapan jalur lebar dan keupayaan carian berkelompok.

Konfigurasikan API untuk menggunakan salah satu daripada pilihan penghalaan tersuai kami bagi mengoptimumkan kelajuan, ketepatan dan keberkesanan kos. Anda juga boleh menyimpan hasil carian dalam storan untuk muat turun laporan CSV dan JSON dengan mudah, serta analitik lanjutan melalui antara muka web.

API Carian HLR Segerak

Endpoint POST /hlr-lookup memproses satu nombor telefon mudah alih (MSISDN) setiap permintaan dan mengembalikan hasil secara serta-merta dalam badan respons HTTP. Hasil diformat sebagai JSON dan sesuai untuk aplikasi masa nyata, termasuk pengesahan nombor mudah alih, penghalaan panggilan dan penghantaran mesej SMS.

Panggilan API segerak terdiri daripada permintaan dan respons HTTP secara langsung. Sistem anda mengemukakan satu MSISDN (nombor mudah alih) setiap permintaan dan menerima respons segera yang mengandungi hasil carian HLR masa nyata dalam format JSON. API ini dioptimumkan untuk kes penggunaan yang memerlukan pengesahan segera dan pemeriksaan ketersambungan, seperti pengesanan penipuan, penghalaan panggilan VoIP dan pengoptimuman gateway SMS.

API Carian HLR Tak Segerak

Endpoint POST /hlr-lookups direka untuk pemprosesan pukal dan volum tinggi, membolehkan anda mengemukakan sehingga 1,000 MSISDN setiap permintaan. Daripada mengembalikan hasil secara serta-merta, API ini menggunakan webhook automatik untuk menghantar hasil secara progresif ke pelayan anda. Hasil carian dikembalikan sebagai objek JSON melalui panggilan balik HTTP POST.

API tak segerak dioptimumkan untuk kelajuan, kecekapan dan kebolehskalaan. Ia menghapuskan isu kependaman rangkaian yang berkaitan dengan panggilan segerak, menjadikannya ideal untuk perniagaan yang memerlukan carian daya pemprosesan tinggi. Sistem anda mengemukakan sehingga 1,000 MSISDN setiap permintaan, dan platform kami memprosesnya secara selari, menghantar hasil kembali ke pelayan anda melalui webhook HTTP dalam kumpulan sehingga 1,000 hasil setiap panggilan balik.

SDK (Kit Pembangunan Perisian)

Kit Pembangunan Perisian (SDK) kami untuk PHP, NodeJS, dan Ruby memudahkan proses integrasi, membolehkan anda berhubung dengan API HLR Lookups dengan cekap dan usaha yang minimum.

SDK ini menyediakan fungsi sedia guna, pengendalian pengesahan, dan templat permintaan API berstruktur, mengurangkan masa pembangunan serta memastikan amalan terbaik.

Terokai senarai penuh SDK yang tersedia di GitHub dan mulakan integrasi anda hari ini.

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

Lihat di 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   }

Lihat di 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)

Lihat di GitHub README.md

Tatal ke Atas

POST/hlr-lookupdilindungi

Melaksanakan Carian HLR secara segerak, menyampaikan data kesambungan dan kemudahalihan telefon bimbit secara masa nyata terus daripada pengendali rangkaian. Titik akhir ini sesuai untuk senario trafik langsung di mana aplikasi sensitif masa memerlukan pengesahan segera sama ada nombor telefon boleh dihubungi pada masa ini (bersambung) atau tidak tersedia (dimatikan). Selain itu, ia membantu membezakan nombor aktif daripada nombor yang tidak sah, tidak diketahui, atau palsu.

Untuk pemprosesan pukal set data besar yang tidak memerlukan keputusan segera, pertimbangkan untuk menggunakan POST /hlr-lookups tak segerak, yang dioptimumkan untuk pemprosesan kelompok berkelajuan tinggi.

Jika fokus utama anda adalah mendapatkan data kemudahalihan nombor mudah alih (MCCMNC) dan anda tidak memerlukan status kesambungan langsung, POST /mnp-lookup menyediakan alternatif kos efektif untuk pertanyaan kemudahalihan nombor mudah alih.

Permintaan Respons Berjaya Respons Ralat Rujukan Status

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

Muatan

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`msisdn`	string	Nombor telefon bimbit (MSISDN) yang akan dicari, disediakan dalam format antarabangsa (contohnya, +14156226819 atau 0014156226819). Kod negara mesti disertakan.	null	wajib
`route`	string(3)	Pengenal tiga aksara pilihan yang menentukan laluan untuk carian ini. Tetapkan kepada `null` atau abaikan parameter ini untuk menggunakan peta laluan tersuai anda atau biarkan sistem kami menentukan secara automatik laluan terbaik untuk carian ini.	null	pilihan
`storage`	string	Pengenal penyimpanan pilihan yang menentukan laporan di mana keputusan akan disimpan untuk semakan manual, analitik, dan pelaporan. Sistem secara automatik menambah cap waktu dengan bulan semasa. Jika diabaikan atau ditetapkan kepada `null`, sistem akan mengumpulkan keputusan mengikut bulan secara automatik untuk tujuan pelaporan.	null	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`id`	string(12)	Pengecam unik yang diberikan kepada permintaan carian ini.	false
`msisdn`	string	Nombor telefon bimbit yang dicari, diformat dalam format antarabangsa (contohnya, +14156226819 atau 0014156226819).	false
`connectivity_status`	string	Menunjukkan sama ada status sambungan nombor tersebut berjaya diperoleh. Nilai yang mungkin: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` , atau `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Kod Negara Mudah Alih (MCC) dan Kod Rangkaian Mudah Alih (MNC) lima atau enam digit yang mengenal pasti rangkaian yang kini dikaitkan dengan nombor telefon tersebut.	true
`mcc`	string(3)	Kod Negara Mudah Alih (MCC) tiga digit yang mengenal pasti negara di mana nombor telefon tersebut didaftarkan.	true
`mnc`	string(2\|3)	Kod Rangkaian Mudah Alih (MNC) dua atau tiga digit yang mengenal pasti rangkaian khusus yang dimiliki oleh nombor telefon tersebut.	true
`imsi`	string	Identiti Pelanggan Mudah Alih Antarabangsa (IMSI), pengecam unik untuk kad SIM yang dikaitkan dengan nombor ini. Ketersediaan bergantung kepada konfigurasi rangkaian.	true
`msin`	string(10)	Nombor Pengenalan Langganan Mudah Alih (MSIN) dalam pangkalan data pengendali mudah alih. Ketersediaan bergantung kepada konfigurasi rangkaian.	true
`msc`	string(12)	Pusat Pensuisan Mudah Alih (MSC) yang kini mengendalikan komunikasi pelanggan ini. Ketersediaan bergantung kepada konfigurasi rangkaian.	true
`original_network_name`	string	Nama pengendali rangkaian asal (natif) yang dikaitkan dengan nombor ini.	true
`original_country_name`	string	Nama penuh negara di mana nombor telefon bimbit tersebut pada asalnya didaftarkan, disediakan dalam Bahasa Inggeris.	true
`original_country_code`	string(2)	Kod negara ISO dua aksara yang mewakili negara di mana nombor telefon tersebut mula-mula diberikan.	true
`original_country_prefix`	string	Kod dail antarabangsa (kod panggilan negara) yang sepadan dengan negara asal nombor telefon bimbit tersebut.	true
`is_ported`	boolean	Menunjukkan sama ada nombor mudah alih telah dipindahkan daripada rangkaian asalnya kepada pengendali lain.	true
`ported_network_name`	string	Nama pengendali rangkaian yang mana nombor mudah alih telah dipindahkan, jika berkenaan.	true
`ported_country_name`	string	Nama negara di mana nombor mudah alih telah dipindahkan, jika berkenaan.	true
`ported_country_code`	string(2)	Kod negara ISO dua aksara yang mewakili negara di mana nombor mudah alih telah dipindahkan, jika berkenaan.	true
`ported_country_prefix`	string	Kod dail antarabangsa (kod panggilan negara) untuk negara di mana nombor mudah alih telah dipindahkan, jika berkenaan.	true
`is_roaming`	boolean	Menunjukkan sama ada nombor mudah alih sedang merayau di rangkaian asing. Ketersediaan status merayau bergantung kepada pengendali rangkaian mudah alih.	true
`roaming_network_name`	string	Nama rangkaian di mana nombor mudah alih sedang merayau pada masa ini, jika berkenaan.	true
`roaming_country_name`	string	Nama negara di mana nombor mudah alih sedang merayau pada masa ini, jika berkenaan.	true
`roaming_country_code`	string(2)	Kod negara ISO dua aksara bagi negara di mana nombor mudah alih sedang merayau pada masa ini, jika berkenaan.	true
`roaming_country_prefix`	string	Kod dail antarabangsa (kod panggilan negara) bagi negara di mana nombor mudah alih sedang merayau pada masa ini, jika berkenaan.	true
`cost`	string	Nilai perpuluhan yang diwakili sebagai rentetan, menunjukkan kos carian dalam EUR.	true
`timestamp`	string	Cap masa berformat W3C termasuk zon waktu, yang menentukan bila carian telah selesai.	true
`storage`	string	Nama storan di mana keputusan carian telah disimpan. Ini sepadan dengan nama laporan dan muat turun CSV yang tersedia melalui antara muka web.	true
`route`	string(3)	Pengecam tiga aksara yang menunjukkan kaedah penghalaan yang digunakan untuk permintaan carian ini.	true
`processing_status`	string	Hasil pemprosesan carian. Nilai yang mungkin: `COMPLETED` (berjaya), `REJECTED` (rangkaian tidak dapat dicapai, tiada caj dikenakan), atau `FAILED` (ralat berlaku semasa pemprosesan).	false
`error_code`	integer	Kod ralat dalaman pilihan yang memberikan maklumat diagnostik tambahan untuk sokongan pelanggan.	true
`error_description`	string	Penjelasan ringkas tentang kod ralat yang diberikan (jika ada) dalam teks biasa Bahasa Inggeris.	true
`data_source`	string	Sumber data yang digunakan untuk permintaan ini. Nilai yang mungkin: `LIVE_HLR` (pertanyaan HLR masa nyata) atau `MNP_DB` (pangkalan data kemudahalihan nombor mudah alih statik). Rujuk pilihan penghalaan untuk butiran lanjut.	false
`routing_instruction`	string	Rentetan yang dipisahkan dengan titik bertindih yang menerangkan arahan penghalaan yang digunakan dalam permintaan. Komponen pertama ialah `STATIC` apabila anda menentukan laluan atau `AUTO` untuk penghalaan automatik; komponen kedua ialah pengecam laluan, dan untuk permintaan penghalaan automatik, komponen ketiga menunjukkan asal yang menjadi asas keputusan penghalaan (iaitu `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."
    ]
}

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Status	Keterangan
CONNECTED	Nombor ini sah dan peranti sasaran sedang bersambung ke rangkaian mudah alih. Panggilan, SMS dan perkhidmatan lain seharusnya berjaya sampai kepada penerima.
ABSENT	Nombor ini sah, tetapi peranti sasaran sama ada dimatikan atau berada di luar liputan rangkaian buat sementara waktu. Mesej atau panggilan mungkin tidak dapat dihantar sehingga peranti bersambung semula ke rangkaian.
INVALID_MSISDN	Nombor ini tidak sah atau tidak diperuntukkan kepada mana-mana pelanggan pada rangkaian mudah alih. Panggilan dan mesej ke nombor ini akan gagal.
UNDETERMINED	Status sambungan nombor ini tidak dapat ditentukan. Ini mungkin disebabkan oleh nombor yang tidak sah, respons ralat SS7, atau kekurangan sambungan dengan pengendali rangkaian sasaran. Periksa kod ralat dan medan penerangan untuk diagnostik tambahan.

Tatal ke Atas

POST/hlr-lookupsdilindungi

Memulakan kumpulan carian HLR tak segerak, mendapatkan data sambungan telefon bimbit langsung dan data mudah alih daripada pengendali rangkaian. Keputusan dihantar melalui webhook ke pelayan anda. Kaedah ini dioptimumkan untuk memproses sejumlah besar nombor yang tidak memerlukan respons segera, seperti pembersihan dan pengesahan pangkalan data. Untuk aplikasi masa nyata seperti penghalaan panggilan atau penghantaran SMS, pertimbangkan untuk menggunakan endpoint POST /hlr-lookup.

Endpoint ini sesuai untuk pemprosesan pukal apabila matlamatnya adalah untuk mengenal pasti nombor telefon yang boleh dihubungi pada masa ini (bersambung) atau tidak tersedia (telefon dimatikan) sambil menapis nombor yang tidak sah, tidak ditetapkan atau palsu. Selain itu, ia menyediakan status mudah alih langsung (MCCMNC) bersama butiran sambungan.

Sebelum menggunakan endpoint ini, pastikan URL webhook dikonfigurasikan untuk menerima keputusan carian secara tak segerak. Anda boleh menetapkan ini dalam tetapan API anda.

Permintaan Respons Berjaya Respons Ralat Webhooks Rujukan Status

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

Muatan

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`msisdns`	array	Senarai nombor telefon bimbit (MSISDN) dalam format antarabangsa (cth. +14156226819 atau 0014156226819). Anda boleh memasukkan sehingga 1000 nombor setiap permintaan.	null	wajib
`route`	string(3)	Pengenal tiga aksara pilihan yang menentukan laluan untuk carian ini. Tetapkan kepada `null` atau abaikan parameter ini untuk menggunakan peta laluan tersuai anda atau biarkan sistem kami menentukan secara automatik laluan terbaik untuk carian ini.	null	pilihan
`storage`	string	Pengenal penyimpanan pilihan yang menentukan laporan di mana keputusan akan disimpan untuk semakan manual, analitik, dan pelaporan. Sistem secara automatik menambah cap waktu dengan bulan semasa. Jika diabaikan atau ditetapkan kepada `null`, sistem akan mengumpulkan keputusan mengikut bulan secara automatik untuk tujuan pelaporan.	null	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`accepted`	array	Senarai objek yang mengandungi pengecam unik dan MSISDN yang telah diterima untuk diproses.	false
`accepted_count`	integer	Jumlah keseluruhan MSISDN yang berjaya diterima untuk diproses.	false
`rejected`	array	Senarai objek yang mengandungi pengecam unik dan MSISDN yang telah ditolak untuk diproses, biasanya disebabkan oleh nombor yang tidak sah. Tiada caj dikenakan untuk entri yang ditolak.	false
`rejected_count`	integer	Jumlah keseluruhan MSISDN yang ditolak kerana ralat pengesahan.	false
`total_count`	integer	Jumlah keseluruhan MSISDN yang diterima dan ditolak yang telah diserahkan untuk diproses.	false
`cost`	string	Nilai perpuluhan yang diwakili sebagai rentetan, menunjukkan jumlah kos dalam EUR untuk carian yang diterima.	false
`storage`	string	Nama storan di mana keputusan carian ditambahkan, digunakan untuk pelaporan dan muat turun CSV melalui antara muka web.	false
`route`	string(3\|4)	Pengecam tiga atau empat aksara yang menentukan laluan yang digunakan untuk permintaan carian ini. Mengandungi AUTO jika penghalaan automatik berasaskan nombor diminta.	false
`webhook_urls`	array	URL webhook yang dikonfigurasikan dalam tetapan API anda. Keputusan dihantar kembali ke sini.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Memproses Webhook

Setelah diserahkan, platform kami akan mula memproses nombor telefon yang diberikan dan menghantar keputusan ke URL webhook yang telah ditetapkan sebelumnya pada pelayan anda. Keputusan dihantar sebagai permintaan HTTP POST dengan objek JSON dalam badan permintaan.

Pengesahan

Sahkan webhook dengan memeriksa pengepala HTTP X-Signatures.

Pengepala X-Signatures mengandungi senarai tandatangan yang dipisahkan dengan koma bertitik. Setiap tandatangan dalam senarai dijana menggunakan salah satu rahsia API yang dikonfigurasi dalam akaun anda. Untuk mengesahkan webhook, jana hash SHA-256 menggunakan kunci API, rahsia, dan badan HTTP mentah anda - kemudian bandingkan dengan tandatangan dalam senarai.

Padanan mengesahkan bahawa permintaan adalah tulen dan ditandatangani dengan rahsia yang anda kawal.

Contoh Kod

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

Permintaan adalah sah jika mana-mana tandatangan yang diberikan dalam pengepala sepadan dengan hash SHA256 yang dikira ke atas rentetan gabungan kunci API, rahsia, dan badan HTTP anda.

Mengesahkan Penerimaan

Pelayan anda dijangka memberi respons dengan kod status HTTP 200 OK untuk mengesahkan penerimaan berjaya. Jika sebarang kod respons lain dikembalikan, masa tamat berlaku (10 saat), atau sebarang isu penghantaran lain timbul, sistem akan secara automatik mencuba semula webhook selepas satu minit. Jika permintaan terus gagal, percubaan semula akan mengikuti strategi backoff eksponen, dengan percubaan seterusnya selepas 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minit.

Mekanisme percubaan semula ini memastikan kebolehpercayaan maksimum dalam menyampaikan keputusan carian ke infrastruktur anda. Ia meminimumkan risiko kehilangan data akibat isu rangkaian sementara atau masa henti pelayan.

Muatan 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"
      }
   ]
}

Atribut Muatan Webhook

Objek JSON mengandungi atribut type => HLR bersama atribut results yang merangkumi senarai objek carian, seperti yang didokumenkan di bawah.

Nama	Jenis	Keterangan	Boleh Null
`id`	string(12)	Pengecam unik yang diberikan kepada permintaan carian ini.	false
`msisdn`	string	Nombor telefon bimbit yang dicari, diformat dalam format antarabangsa (contohnya, +14156226819 atau 0014156226819).	false
`connectivity_status`	string	Menunjukkan sama ada status sambungan nombor tersebut berjaya diperoleh. Nilai yang mungkin: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` , atau `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Kod Negara Mudah Alih (MCC) dan Kod Rangkaian Mudah Alih (MNC) lima atau enam digit yang mengenal pasti rangkaian yang kini dikaitkan dengan nombor telefon tersebut.	true
`mcc`	string(3)	Kod Negara Mudah Alih (MCC) tiga digit yang mengenal pasti negara di mana nombor telefon tersebut didaftarkan.	true
`mnc`	string(2\|3)	Kod Rangkaian Mudah Alih (MNC) dua atau tiga digit yang mengenal pasti rangkaian khusus yang dimiliki oleh nombor telefon tersebut.	true
`imsi`	string	Identiti Pelanggan Mudah Alih Antarabangsa (IMSI), pengecam unik untuk kad SIM yang dikaitkan dengan nombor ini. Ketersediaan bergantung kepada konfigurasi rangkaian.	true
`msin`	string(10)	Nombor Pengenalan Langganan Mudah Alih (MSIN) dalam pangkalan data pengendali mudah alih. Ketersediaan bergantung kepada konfigurasi rangkaian.	true
`msc`	string(12)	Pusat Pensuisan Mudah Alih (MSC) yang kini mengendalikan komunikasi pelanggan ini. Ketersediaan bergantung kepada konfigurasi rangkaian.	true
`original_network_name`	string	Nama pengendali rangkaian asal (natif) yang dikaitkan dengan nombor ini.	true
`original_country_name`	string	Nama penuh negara di mana nombor telefon bimbit tersebut pada asalnya didaftarkan, disediakan dalam Bahasa Inggeris.	true
`original_country_code`	string(2)	Kod negara ISO dua aksara yang mewakili negara di mana nombor telefon tersebut mula-mula diberikan.	true
`original_country_prefix`	string	Kod dail antarabangsa (kod panggilan negara) yang sepadan dengan negara asal nombor telefon bimbit tersebut.	true
`is_ported`	boolean	Menunjukkan sama ada nombor mudah alih telah dipindahkan daripada rangkaian asalnya kepada pengendali lain.	true
`ported_network_name`	string	Nama pengendali rangkaian yang mana nombor mudah alih telah dipindahkan, jika berkenaan.	true
`ported_country_name`	string	Nama negara di mana nombor mudah alih telah dipindahkan, jika berkenaan.	true
`ported_country_code`	string(2)	Kod negara ISO dua aksara yang mewakili negara di mana nombor mudah alih telah dipindahkan, jika berkenaan.	true
`ported_country_prefix`	string	Kod dail antarabangsa (kod panggilan negara) untuk negara di mana nombor mudah alih telah dipindahkan, jika berkenaan.	true
`is_roaming`	boolean	Menunjukkan sama ada nombor mudah alih sedang merayau di rangkaian asing. Ketersediaan status merayau bergantung kepada pengendali rangkaian mudah alih.	true
`roaming_network_name`	string	Nama rangkaian di mana nombor mudah alih sedang merayau pada masa ini, jika berkenaan.	true
`roaming_country_name`	string	Nama negara di mana nombor mudah alih sedang merayau pada masa ini, jika berkenaan.	true
`roaming_country_code`	string(2)	Kod negara ISO dua aksara bagi negara di mana nombor mudah alih sedang merayau pada masa ini, jika berkenaan.	true
`roaming_country_prefix`	string	Kod dail antarabangsa (kod panggilan negara) bagi negara di mana nombor mudah alih sedang merayau pada masa ini, jika berkenaan.	true
`cost`	string	Nilai perpuluhan yang diwakili sebagai rentetan, menunjukkan kos carian dalam EUR.	true
`timestamp`	string	Cap masa berformat W3C termasuk zon waktu, yang menentukan bila carian telah selesai.	true
`storage`	string	Nama storan di mana keputusan carian telah disimpan. Ini sepadan dengan nama laporan dan muat turun CSV yang tersedia melalui antara muka web.	true
`route`	string(3)	Pengecam tiga aksara yang menunjukkan kaedah penghalaan yang digunakan untuk permintaan carian ini.	true
`processing_status`	string	Hasil pemprosesan carian. Nilai yang mungkin: `COMPLETED` (berjaya), `REJECTED` (rangkaian tidak dapat dicapai, tiada caj dikenakan), atau `FAILED` (ralat berlaku semasa pemprosesan).	false
`error_code`	integer	Kod ralat dalaman pilihan yang memberikan maklumat diagnostik tambahan untuk sokongan pelanggan.	true
`error_description`	string	Penjelasan ringkas tentang kod ralat yang diberikan (jika ada) dalam teks biasa Bahasa Inggeris.	true
`data_source`	string	Sumber data yang digunakan untuk permintaan ini. Nilai yang mungkin: `LIVE_HLR` (pertanyaan HLR masa nyata) atau `MNP_DB` (pangkalan data kemudahalihan nombor mudah alih statik). Rujuk pilihan penghalaan untuk butiran lanjut.	false
`routing_instruction`	string	Rentetan yang dipisahkan dengan titik bertindih yang menerangkan arahan penghalaan yang digunakan dalam permintaan. Komponen pertama ialah `STATIC` apabila anda menentukan laluan atau `AUTO` untuk penghalaan automatik; komponen kedua ialah pengecam laluan, dan untuk permintaan penghalaan automatik, komponen ketiga menunjukkan asal yang menjadi asas keputusan penghalaan (iaitu `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

Status	Keterangan
CONNECTED	Nombor ini sah dan peranti sasaran sedang bersambung ke rangkaian mudah alih. Panggilan, SMS dan perkhidmatan lain seharusnya berjaya sampai kepada penerima.
ABSENT	Nombor ini sah, tetapi peranti sasaran sama ada dimatikan atau berada di luar liputan rangkaian buat sementara waktu. Mesej atau panggilan mungkin tidak dapat dihantar sehingga peranti bersambung semula ke rangkaian.
INVALID_MSISDN	Nombor ini tidak sah atau tidak diperuntukkan kepada mana-mana pelanggan pada rangkaian mudah alih. Panggilan dan mesej ke nombor ini akan gagal.
UNDETERMINED	Status sambungan nombor ini tidak dapat ditentukan. Ini mungkin disebabkan oleh nombor yang tidak sah, respons ralat SS7, atau kekurangan sambungan dengan pengendali rangkaian sasaran. Periksa kod ralat dan medan penerangan untuk diagnostik tambahan.

Tatal ke Atas

POST/mnp-lookupdilindungi

Melaksanakan carian MNP segerak dan menyediakan maklumat kebolehpindahan nombor mudah alih serta rangkaian. Endpoint ini sesuai jika matlamat utama anda adalah untuk mendapatkan MCCMNC semasa bagi nombor telefon mudah alih tertentu dan mengenal pasti rangkaian asal dan semasa secara masa nyata.

Untuk pemprosesan pukal set data besar yang tidak memerlukan keputusan segera, pertimbangkan untuk menggunakan POST /mnp-lookups tak segerak, yang dioptimumkan untuk pemprosesan kelompok berkelajuan tinggi.

Pertanyaan MNP menentukan maklumat kebolehpindahan dan rangkaian dengan tepat tetapi tidak menunjukkan sama ada telefon mudah alih sasaran sedang bersambung ke rangkaian dan boleh dihubungi. Untuk mendapatkan maklumat sambungan secara langsung, sila gunakan endpoint POST /hlr-lookup.

Permintaan Respons Berjaya Respons Ralat

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

Muatan

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`msisdn`	string	Nombor telefon bimbit (MSISDN) yang akan dicari, disediakan dalam format antarabangsa (contohnya, +14156226819 atau 0014156226819). Kod negara mesti disertakan.	null	wajib
`route`	string(3)	Pengenal tiga aksara pilihan yang menentukan laluan untuk carian ini. Tetapkan kepada `null` atau abaikan parameter ini untuk menggunakan peta laluan tersuai anda atau biarkan sistem kami menentukan secara automatik laluan terbaik untuk carian ini.	null	pilihan
`storage`	string	Pengenal penyimpanan pilihan yang menentukan laporan di mana keputusan akan disimpan untuk semakan manual, analitik, dan pelaporan. Sistem secara automatik menambah cap waktu dengan bulan semasa. Jika diabaikan atau ditetapkan kepada `null`, sistem akan mengumpulkan keputusan mengikut bulan secara automatik untuk tujuan pelaporan.	null	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`id`	string(12)	Pengenal pasti unik 12 aksara untuk carian ini.	false
`msisdn`	string	Nombor telefon bimbit yang dinilai dalam permintaan carian ini.	false
`query_status`	string	Menunjukkan sama ada pengambilan maklumat kemudahalihan dan rangkaian berjaya. Nilai yang mungkin ialah `OK` atau `FAILED`.	false
`mccmnc`	string(5\|6)	MCCMNC lima atau enam aksara (gabungan kod negara mudah alih dan kod rangkaian mudah alih) yang mengenal pasti rangkaian di mana nombor telefon bimbit ini kini berada.	true
`mcc`	string(3)	MCC tiga aksara (kod negara mudah alih) yang mewakili negara yang berkaitan dengan rangkaian semasa nombor telefon bimbit.	true
`mnc`	string(2\|3)	MNC dua atau tiga aksara (kod rangkaian mudah alih) yang mengenal pasti pengendali rangkaian semasa untuk nombor telefon bimbit.	true
`is_ported`	boolean	Menunjukkan sama ada nombor telefon telah dialihkan daripada rangkaian asalnya kepada pengendali baharu.	true
`original_network_name`	string	Rentetan sewenang-wenangnya (dalam Bahasa Inggeris) yang menyatakan nama pengendali rangkaian asal nombor telefon bimbit yang diperiksa.	true
`original_country_name`	string	Rentetan sewenang-wenangnya (dalam Bahasa Inggeris) yang menunjukkan negara asal nombor telefon bimbit yang diperiksa.	true
`original_country_code`	string(2)	Kod negara ISO dua aksara yang mewakili negara asal nombor telefon bimbit yang diperiksa.	true
`original_country_prefix`	string	Kod dail negara asal yang berkaitan dengan nombor telefon bimbit yang diperiksa.	true
`ported_network_name`	string	Menyatakan pengendali rangkaian di mana nombor telefon bimbit yang diperiksa telah dialihkan, jika berkenaan.	true
`ported_country_name`	string	Menyatakan negara di mana nombor telefon bimbit yang diperiksa telah dialihkan, jika berkenaan.	true
`ported_country_code`	string(2)	Kod negara ISO dua aksara yang mewakili negara di mana nombor telefon bimbit yang diperiksa telah dialihkan, jika berkenaan.	true
`ported_country_prefix`	string	Kod dail untuk negara di mana nombor telefon bimbit yang diperiksa telah dialihkan, jika berkenaan.	true
`extra`	string	Rentetan sewenang-wenangnya yang memberikan butiran tambahan pilihan tentang nombor telefon.	true
`cost`	string	Nilai perpuluhan, diwakili sebagai rentetan, yang menunjukkan kos dalam EUR untuk carian ini.	true
`timestamp`	string	Cap masa berformat W3C, termasuk maklumat zon waktu, yang menunjukkan bila carian telah selesai.	true
`storage`	string	Nama penyimpanan (atau nama laporan) di mana hasil carian telah ditambahkan. Ini digunakan untuk muat turun CSV dan pelaporan melalui antara muka web.	true
`route`	string(3)	Pengenal pasti tiga aksara yang menyatakan laluan yang digunakan untuk permintaan carian ini.	true
`error_code`	integer	Kod ralat dalaman pilihan yang memberikan konteks tambahan untuk diagnostik sokongan pelanggan.	true

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

POST/mnp-lookupsdilindungi

Memulakan kumpulan carian MNP (mudah alih nombor mudah alih) tak segerak, mendapatkan MCCMNC semasa dan mengenal pasti rangkaian asal dan semasa secara masa nyata. Keputusan dihantar melalui webhook ke pelayan anda. Kaedah ini dioptimumkan untuk memproses sejumlah besar nombor yang tidak memerlukan respons segera, seperti pembersihan dan pengesahan pangkalan data. Untuk aplikasi masa nyata seperti penghalaan panggilan atau penghantaran SMS, pertimbangkan untuk menggunakan endpoint POST /mnp-lookup.

Pertanyaan MNP menentukan maklumat kebolehpindahan dan rangkaian dengan tepat tetapi tidak menunjukkan sama ada telefon mudah alih sasaran sedang bersambung ke rangkaian dan boleh dihubungi. Untuk mendapatkan maklumat sambungan secara langsung, sila gunakan endpoint POST /hlr-lookups.

Sebelum menggunakan endpoint ini, pastikan URL webhook dikonfigurasikan untuk menerima keputusan carian secara tak segerak. Anda boleh menetapkan ini dalam tetapan API anda.

Permintaan Respons Berjaya Respons Ralat Webhooks

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

Muatan

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`msisdns`	array	Senarai nombor telefon bimbit (MSISDN) dalam format antarabangsa (cth. +14156226819 atau 0014156226819). Anda boleh memasukkan sehingga 1000 nombor setiap permintaan.	null	wajib
`route`	string(3)	Pengenal tiga aksara pilihan yang menentukan laluan untuk carian ini. Tetapkan kepada `null` atau abaikan parameter ini untuk menggunakan peta laluan tersuai anda atau biarkan sistem kami menentukan secara automatik laluan terbaik untuk permintaan ini.	null	pilihan
`storage`	string	Pengenal penyimpanan pilihan yang menentukan laporan di mana keputusan akan disimpan untuk semakan manual, analitik, dan pelaporan. Sistem secara automatik menambah cap waktu dengan bulan semasa. Jika diabaikan atau ditetapkan kepada `null`, sistem akan mengumpulkan keputusan mengikut bulan secara automatik untuk tujuan pelaporan.	null	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`accepted`	array	Senarai objek yang mengandungi pengecam unik dan MSISDN yang telah diterima untuk diproses.	false
`accepted_count`	integer	Jumlah keseluruhan MSISDN yang berjaya diterima untuk diproses.	false
`rejected`	array	Senarai objek yang mengandungi pengecam unik dan MSISDN yang telah ditolak untuk diproses, biasanya disebabkan oleh nombor yang tidak sah. Tiada caj dikenakan untuk entri yang ditolak.	false
`rejected_count`	integer	Jumlah keseluruhan MSISDN yang ditolak kerana ralat pengesahan.	false
`total_count`	integer	Jumlah keseluruhan MSISDN yang diterima dan ditolak yang telah diserahkan untuk diproses.	false
`cost`	string	Nilai perpuluhan yang diwakili sebagai rentetan, menunjukkan jumlah kos dalam EUR untuk carian yang diterima.	false
`storage`	string	Nama storan di mana keputusan carian ditambahkan, digunakan untuk pelaporan dan muat turun CSV melalui antara muka web.	false
`route`	string(3)	Pengenal pasti tiga aksara yang menyatakan laluan yang digunakan untuk permintaan carian ini.	false
`webhook_urls`	array	URL webhook yang dikonfigurasikan dalam tetapan API anda. Keputusan dihantar kembali ke sini.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Memproses Webhook

Setelah diserahkan, platform kami akan mula memproses nombor telefon yang diberikan dan menghantar keputusan ke URL webhook yang telah ditetapkan sebelumnya pada pelayan anda. Keputusan dihantar sebagai permintaan HTTP POST dengan objek JSON dalam badan permintaan.

Pengesahan

Sahkan webhook dengan memeriksa pengepala HTTP X-Signatures.

Pengepala X-Signatures mengandungi senarai tandatangan yang dipisahkan dengan koma bertitik. Setiap tandatangan dalam senarai dijana menggunakan salah satu rahsia API yang dikonfigurasi dalam akaun anda. Untuk mengesahkan webhook, jana hash SHA-256 menggunakan kunci API, rahsia, dan badan HTTP mentah anda - kemudian bandingkan dengan tandatangan dalam senarai.

Padanan mengesahkan bahawa permintaan adalah tulen dan ditandatangani dengan rahsia yang anda kawal.

Contoh Kod

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

Permintaan adalah sah jika mana-mana tandatangan yang diberikan dalam pengepala sepadan dengan hash SHA256 yang dikira ke atas rentetan gabungan kunci API, rahsia, dan badan HTTP anda.

Mengesahkan Penerimaan

Pelayan anda dijangka memberi respons dengan kod status HTTP 200 OK untuk mengesahkan penerimaan berjaya. Jika sebarang kod respons lain dikembalikan, masa tamat berlaku (10 saat), atau sebarang isu penghantaran lain timbul, sistem akan secara automatik mencuba semula webhook selepas satu minit. Jika permintaan terus gagal, percubaan semula akan mengikuti strategi backoff eksponen, dengan percubaan seterusnya selepas 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minit.

Mekanisme percubaan semula ini memastikan kebolehpercayaan maksimum dalam menyampaikan keputusan carian ke infrastruktur anda. Ia meminimumkan risiko kehilangan data akibat isu rangkaian sementara atau masa henti pelayan.

Muatan 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
        }
    ]
}

Atribut Muatan Webhook

Objek JSON mengandungi atribut type => MNP bersama atribut results yang merangkumi senarai objek carian, seperti yang didokumenkan di bawah.

Nama	Jenis	Keterangan	Boleh Null
`id`	string(12)	Pengenal pasti unik 12 aksara untuk carian ini.	false
`msisdn`	string	Nombor telefon bimbit yang dinilai dalam permintaan carian ini.	false
`query_status`	string	Menunjukkan sama ada pengambilan maklumat kemudahalihan dan rangkaian berjaya. Nilai yang mungkin ialah `OK` atau `FAILED`.	false
`mccmnc`	string(5\|6)	MCCMNC lima atau enam aksara (gabungan kod negara mudah alih dan kod rangkaian mudah alih) yang mengenal pasti rangkaian di mana nombor telefon bimbit ini kini berada.	true
`mcc`	string(3)	MCC tiga aksara (kod negara mudah alih) yang mewakili negara yang berkaitan dengan rangkaian semasa nombor telefon bimbit.	true
`mnc`	string(2\|3)	MNC dua atau tiga aksara (kod rangkaian mudah alih) yang mengenal pasti pengendali rangkaian semasa untuk nombor telefon bimbit.	true
`is_ported`	boolean	Menunjukkan sama ada nombor telefon telah dialihkan daripada rangkaian asalnya kepada pengendali baharu.	true
`original_network_name`	string	Rentetan sewenang-wenangnya (dalam Bahasa Inggeris) yang menyatakan nama pengendali rangkaian asal nombor telefon bimbit yang diperiksa.	true
`original_country_name`	string	Rentetan sewenang-wenangnya (dalam Bahasa Inggeris) yang menunjukkan negara asal nombor telefon bimbit yang diperiksa.	true
`original_country_code`	string(2)	Kod negara ISO dua aksara yang mewakili negara asal nombor telefon bimbit yang diperiksa.	true
`original_country_prefix`	string	Kod dail negara asal yang berkaitan dengan nombor telefon bimbit yang diperiksa.	true
`ported_network_name`	string	Menyatakan pengendali rangkaian di mana nombor telefon bimbit yang diperiksa telah dialihkan, jika berkenaan.	true
`ported_country_name`	string	Menyatakan negara di mana nombor telefon bimbit yang diperiksa telah dialihkan, jika berkenaan.	true
`ported_country_code`	string(2)	Kod negara ISO dua aksara yang mewakili negara di mana nombor telefon bimbit yang diperiksa telah dialihkan, jika berkenaan.	true
`ported_country_prefix`	string	Kod dail untuk negara di mana nombor telefon bimbit yang diperiksa telah dialihkan, jika berkenaan.	true
`extra`	string	Rentetan sewenang-wenangnya yang memberikan butiran tambahan pilihan tentang nombor telefon.	true
`cost`	string	Nilai perpuluhan, diwakili sebagai rentetan, yang menunjukkan kos dalam EUR untuk carian ini.	true
`timestamp`	string	Cap masa berformat W3C, termasuk maklumat zon waktu, yang menunjukkan bila carian telah selesai.	true
`storage`	string	Nama penyimpanan (atau nama laporan) di mana hasil carian telah ditambahkan. Ini digunakan untuk muat turun CSV dan pelaporan melalui antara muka web.	true
`route`	string(3)	Pengenal pasti tiga aksara yang menyatakan laluan yang digunakan untuk permintaan carian ini.	true
`error_code`	integer	Kod ralat dalaman pilihan yang memberikan konteks tambahan untuk diagnostik sokongan pelanggan.	true

Tatal ke Atas

POST/nt-lookupdilindungi

Melaksanakan carian jenis nombor (NT) secara segerak. Endpoint ini sesuai jika matlamat utama anda adalah untuk menentukan sama ada nombor telefon yang diberikan tergolong dalam julat pelan penomboran talian tetap, mudah alih, kadar premium, VoIP, alat kelui, atau lain-lain secara masa nyata.

Pertanyaan NT mengesan jenis nombor telefon dengan tepat; namun, ia tidak menunjukkan sama ada nombor sasaran sedang disambungkan ke rangkaian dan boleh dihubungi. Untuk mendapatkan maklumat kesambungan secara langsung, sila gunakan endpoint POST /hlr-lookup.

Jika kes penggunaan anda memerlukan maklumat rangkaian dan kemudahalihan (MCCMNC) yang tepat tetapi bukan status kesambungan langsung, sila gunakan endpoint POST /mnp-lookup untuk pertanyaan kemudahalihan nombor mudah alih.

Permintaan Respons Berjaya Respons Ralat Rujukan Jenis

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

Muatan

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`number`	string	Nombor telefon dalam format antarabangsa (cth. +4989702626 atau 004989702626).	null	mandatory
`route`	string(3)	Pengecam tiga aksara pilihan yang menentukan laluan untuk carian ini. Tetapkan kepada `null` atau abaikan parameter ini untuk menggunakan peta laluan tersuai anda atau biarkan sistem kami menentukan secara automatik laluan terbaik untuk permintaan ini.	null	pilihan
`storage`	string	Pengenal penyimpanan pilihan yang menentukan laporan di mana keputusan akan disimpan untuk semakan manual, analitik, dan pelaporan. Sistem secara automatik menambah cap waktu dengan bulan semasa. Jika diabaikan atau ditetapkan kepada `null`, sistem akan mengumpulkan keputusan mengikut bulan secara automatik untuk tujuan pelaporan.	null	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`id`	string(12)	Pengecam unik yang diberikan kepada permintaan carian ini.	false
`number`	string	Nombor telefon yang dinilai semasa permintaan carian ini.	false
`number_type`	string	Jenis nombor yang dikesan. Nilai yang mungkin termasuk: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Menunjukkan sama ada maklumat jenis nombor berjaya diperoleh. Mengembalikan `OK` jika berjaya, atau `FAILED` jika carian gagal.	false
`is_valid`	boolean	Menunjukkan sama ada nombor telefon adalah sah dari segi sintaks.	true
`invalid_reason`	string	Mesej teks biasa dalam bahasa Inggeris yang menyatakan sebab nombor telefon dianggap tidak sah (contohnya "too short" atau "invalid prefix"), atau `null` jika nombor adalah sah.	true
`is_possibly_ported`	boolean	Menunjukkan sama ada nombor telefon mungkin telah dipindahkan daripada operator asalnya kepada pembawa yang berbeza. Untuk maklumat portabiliti yang pasti, gunakan carian MNP.	true
`is_vanity_number`	boolean	Menunjukkan sama ada nombor telefon adalah nombor vaniti, bermakna ia mengandungi aksara abjad.	true
`qualifies_for_hlr_lookup`	boolean	Menunjukkan sama ada nombor telefon layak untuk pertanyaan tambahan melalui carian HLR.	true
`mccmnc`	string(5\|6)	Rentetan lima atau enam aksara yang mewakili tupel MCCMNC (kod negara mudah alih dan kod rangkaian mudah alih) yang mengenal pasti rangkaian asal nombor telefon mudah alih.	true
`mcc`	string(3)	Rentetan tiga aksara yang mewakili MCC (kod negara mudah alih) yang mengenal pasti negara yang berkaitan dengan rangkaian mudah alih asal nombor telefon.	true
`mnc`	string(2\|3)	Rentetan dua atau tiga aksara yang mewakili MNC (kod rangkaian mudah alih) yang mengenal pasti operator rangkaian mudah alih asal nombor telefon.	true
`original_network_name`	string	Rentetan teks biasa dalam bahasa Inggeris yang menyatakan nama operator rangkaian asal nombor telefon mudah alih yang diperiksa.	true
`original_country_name`	string	Rentetan teks biasa dalam bahasa Inggeris yang menyatakan negara asal yang berkaitan dengan nombor telefon mudah alih yang diperiksa.	true
`original_country_code`	string(2)	Kod negara ISO dua aksara yang menunjukkan negara asal nombor telefon mudah alih yang diperiksa.	true
`regions`	array	Senarai rentetan yang mudah dibaca dalam bahasa Inggeris yang menyatakan kawasan geografi yang berkaitan dengan nombor telefon ini.	true
`timezones`	array	Senarai zon waktu (dalam format Olson) yang berkaitan dengan nombor telefon ini.	true
`info_text`	string	Rentetan sewenang-wenangnya yang mungkin mengandungi maklumat tambahan tentang nombor telefon.	true
`cost`	string	Nilai perpuluhan yang diwakili sebagai rentetan, menunjukkan kos (dalam EUR) bagi carian ini.	true
`timestamp`	string	Cap masa berformat W3C (termasuk zon waktu) yang menunjukkan bila carian telah selesai.	true
`storage`	string	Menyatakan nama storan di mana hasil carian telah ditambahkan. Ini sepadan dengan nama laporan yang digunakan untuk muat turun CSV dan analitik melalui antara muka web.	true
`route`	string(3)	Pengenal pasti tiga aksara yang menyatakan laluan yang digunakan untuk permintaan carian ini.	true

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Jenis	Keterangan
LANDLINE	Nombor telefon talian tetap.
MOBILE	Nombor telefon mudah alih. Layak untuk carian HLR bagi mendapatkan maklumat tambahan mengenai status sambungan, rangkaian, kemudahalihan dan perayauan.
MOBILE_OR_LANDLINE	Nombor telefon talian tetap atau mudah alih. Mungkin layak untuk carian HLR.
TOLL_FREE	Nombor telefon bebas tol.
PREMIUM_RATE	Nombor telefon kadar premium dengan caj tambahan.
SHARED_COST	Nombor telefon kos kongsi. Biasanya lebih murah daripada nombor telefon kadar premium.
VOIP	Nombor telefon Voice over IP. Termasuk nombor telefon TSoIP (Perkhidmatan Telefoni melalui IP).
PAGER	Nombor telefon alat kelui. Biasanya tiada fungsi suara.
UAN	Nombor Akses Sejagat (Nombor Syarikat). Mungkin diarahkan ke pejabat tertentu tetapi membolehkan satu nombor digunakan untuk syarikat.
VOICEMAIL	Nombor telefon mel suara.
UNKNOWN	Jenis nombor tidak dapat ditentukan.

Tatal ke Atas

POST/nt-lookups dilindungi

Endpoint ini melaksanakan siri carian jenis nombor secara asinkron dengan keputusan dihantar kembali ke pelayan anda melalui webhook. Ia sesuai jika matlamat utama anda adalah untuk menentukan sama ada nombor telefon yang diberikan tergolong dalam kategori talian tetap, mudah alih, kadar premium, VoIP, alat kelui, atau julat pelan penomboran lain. Dioptimumkan untuk pemprosesan pantas bagi jumlah nombor yang besar, endpoint ini sesuai untuk operasi pukal (contohnya pembersihan pangkalan data). Untuk trafik langsung dan kes penggunaan yang kritikal masa, sila gunakan endpoint POST /nt-lookup sebaliknya.

Anda perlu menyatakan URL webhook dalam tetapan API anda sebagai prasyarat untuk menggunakan endpoint ini.

Permintaan Respons Berjaya Respons Ralat Webhooks Rujukan Jenis

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

Muatan

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`numbers`	array	Satu susunan nombor telefon dalam format antarabangsa (contohnya +14156226819 atau 004989702626). Maksimum 1000 nombor boleh disertakan bagi setiap permintaan.	null	wajib
`route`	string(3)	Pengecam tiga aksara pilihan yang menyatakan laluan untuk carian ini. Tetapkan kepada `null` atau abaikan parameter ini untuk menggunakan peta penghalaan tersuai anda atau biarkan sistem kami menentukan secara automatik laluan terbaik untuk permintaan ini.	null	pilihan
`storage`	string	Pengenal penyimpanan pilihan yang menentukan laporan di mana keputusan akan disimpan untuk semakan manual, analitik, dan pelaporan. Sistem secara automatik menambah cap waktu dengan bulan semasa. Jika diabaikan atau ditetapkan kepada `null`, sistem akan mengumpulkan keputusan mengikut bulan secara automatik untuk tujuan pelaporan.	null	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`accepted`	array	Satu susunan objek, setiap satunya mengandungi pengecam unik dan nombor telefon yang telah diterima untuk diproses.	false
`accepted_count`	integer	Jumlah keseluruhan nombor telefon yang diterima untuk diproses.	false
`rejected`	array	Satu susunan objek, setiap satunya mengandungi pengecam unik dan nombor telefon yang ditolak untuk diproses. Biasanya, nombor-nombor ini tidak sah dan tiada caj dikenakan.	false
`rejected_count`	integer	Jumlah keseluruhan nombor telefon yang ditolak untuk diproses.	false
`total_count`	integer	Jumlah keseluruhan nombor telefon yang diterima dan ditolak yang telah dikemukakan untuk diproses.	false
`cost`	string	Rentetan yang mewakili nilai perpuluhan yang menunjukkan kos dalam EUR untuk carian ini.	false
`storage`	string	Nama storan (laporan) di mana keputusan carian telah ditambah. Nama ini digunakan untuk muat turun CSV dan analitik melalui antara muka web.	false
`route`	string(3)	Pengecam tiga aksara yang menyatakan laluan yang digunakan untuk permintaan carian ini.	false
`webhook_urls`	array	URL webhook yang dikonfigurasikan dalam tetapan API anda. Keputusan dihantar kembali ke sini.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Memproses Webhook

Setelah diserahkan, platform kami akan mula memproses nombor telefon yang diberikan dan menghantar keputusan ke URL webhook yang telah ditetapkan sebelumnya pada pelayan anda. Keputusan dihantar sebagai permintaan HTTP POST dengan objek JSON dalam badan permintaan.

Pengesahan

Sahkan webhook dengan memeriksa pengepala HTTP X-Signatures.

Pengepala X-Signatures mengandungi senarai tandatangan yang dipisahkan dengan koma bertitik. Setiap tandatangan dalam senarai dijana menggunakan salah satu rahsia API yang dikonfigurasi dalam akaun anda. Untuk mengesahkan webhook, jana hash SHA-256 menggunakan kunci API, rahsia, dan badan HTTP mentah anda - kemudian bandingkan dengan tandatangan dalam senarai.

Padanan mengesahkan bahawa permintaan adalah tulen dan ditandatangani dengan rahsia yang anda kawal.

Contoh Kod

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

Permintaan adalah sah jika mana-mana tandatangan yang diberikan dalam pengepala sepadan dengan hash SHA256 yang dikira ke atas rentetan gabungan kunci API, rahsia, dan badan HTTP anda.

Mengesahkan Penerimaan

Pelayan anda dijangka memberi respons dengan kod status HTTP 200 OK untuk mengesahkan penerimaan berjaya. Jika sebarang kod respons lain dikembalikan, masa tamat berlaku (10 saat), atau sebarang isu penghantaran lain timbul, sistem akan secara automatik mencuba semula webhook selepas satu minit. Jika permintaan terus gagal, percubaan semula akan mengikuti strategi backoff eksponen, dengan percubaan seterusnya selepas 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minit.

Mekanisme percubaan semula ini memastikan kebolehpercayaan maksimum dalam menyampaikan keputusan carian ke infrastruktur anda. Ia meminimumkan risiko kehilangan data akibat isu rangkaian sementara atau masa henti pelayan.

Muatan 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"
      }
   ]
}

Atribut Muatan Webhook

Objek JSON mengandungi atribut type => NT bersama atribut results yang merangkumi senarai objek carian, seperti yang didokumenkan di bawah.

Nama	Jenis	Keterangan	Boleh Null
`id`	string(12)	Pengecam unik yang diberikan kepada permintaan carian ini.	false
`number`	string	Nombor telefon yang dinilai semasa permintaan carian ini.	false
`number_type`	string	Jenis nombor yang dikesan. Nilai yang mungkin termasuk: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Menunjukkan sama ada maklumat jenis nombor berjaya diperoleh. Mengembalikan `OK` jika berjaya, atau `FAILED` jika carian gagal.	false
`is_valid`	boolean	Menunjukkan sama ada nombor telefon adalah sah dari segi sintaks.	true
`invalid_reason`	string	Mesej teks biasa dalam bahasa Inggeris yang menyatakan sebab nombor telefon dianggap tidak sah (contohnya "too short" atau "invalid prefix"), atau `null` jika nombor adalah sah.	true
`is_possibly_ported`	boolean	Menunjukkan sama ada nombor telefon mungkin telah dipindahkan daripada operator asalnya kepada pembawa yang berbeza. Untuk maklumat portabiliti yang pasti, gunakan carian MNP.	true
`is_vanity_number`	boolean	Menunjukkan sama ada nombor telefon adalah nombor vaniti, bermakna ia mengandungi aksara abjad.	true
`qualifies_for_hlr_lookup`	boolean	Menunjukkan sama ada nombor telefon layak untuk pertanyaan tambahan melalui carian HLR.	true
`mccmnc`	string(5\|6)	Rentetan lima atau enam aksara yang mewakili tupel MCCMNC (kod negara mudah alih dan kod rangkaian mudah alih) yang mengenal pasti rangkaian asal nombor telefon mudah alih.	true
`mcc`	string(3)	Rentetan tiga aksara yang mewakili MCC (kod negara mudah alih) yang mengenal pasti negara yang berkaitan dengan rangkaian mudah alih asal nombor telefon.	true
`mnc`	string(2\|3)	Rentetan dua atau tiga aksara yang mewakili MNC (kod rangkaian mudah alih) yang mengenal pasti operator rangkaian mudah alih asal nombor telefon.	true
`original_network_name`	string	Rentetan teks biasa dalam bahasa Inggeris yang menyatakan nama operator rangkaian asal nombor telefon mudah alih yang diperiksa.	true
`original_country_name`	string	Rentetan teks biasa dalam bahasa Inggeris yang menyatakan negara asal yang berkaitan dengan nombor telefon mudah alih yang diperiksa.	true
`original_country_code`	string(2)	Kod negara ISO dua aksara yang menunjukkan negara asal nombor telefon mudah alih yang diperiksa.	true
`regions`	array	Senarai rentetan yang mudah dibaca dalam bahasa Inggeris yang menyatakan kawasan geografi yang berkaitan dengan nombor telefon ini.	true
`timezones`	array	Senarai zon waktu (dalam format Olson) yang berkaitan dengan nombor telefon ini.	true
`info_text`	string	Rentetan sewenang-wenangnya yang mungkin mengandungi maklumat tambahan tentang nombor telefon.	true
`cost`	string	Nilai perpuluhan yang diwakili sebagai rentetan, menunjukkan kos (dalam EUR) bagi carian ini.	true
`timestamp`	string	Cap masa berformat W3C (termasuk zon waktu) yang menunjukkan bila carian telah selesai.	true
`storage`	string	Menyatakan nama storan di mana hasil carian telah ditambahkan. Ini sepadan dengan nama laporan yang digunakan untuk muat turun CSV dan analitik melalui antara muka web.	true
`route`	string(3)	Pengenal pasti tiga aksara yang menyatakan laluan yang digunakan untuk permintaan carian ini.	true

Jenis	Keterangan
LANDLINE	Nombor telefon talian tetap.
MOBILE	Nombor telefon mudah alih. Layak untuk carian HLR bagi mendapatkan maklumat tambahan mengenai status sambungan, rangkaian, kemudahalihan dan perayauan.
MOBILE_OR_LANDLINE	Nombor telefon talian tetap atau mudah alih. Mungkin layak untuk carian HLR.
TOLL_FREE	Nombor telefon bebas tol.
PREMIUM_RATE	Nombor telefon kadar premium dengan caj tambahan.
SHARED_COST	Nombor telefon kos kongsi. Biasanya lebih murah daripada nombor telefon kadar premium.
VOIP	Nombor telefon Voice over IP. Termasuk nombor telefon TSoIP (Perkhidmatan Telefoni melalui IP).
PAGER	Nombor telefon alat kelui. Biasanya tiada fungsi suara.
UAN	Nombor Akses Sejagat (Nombor Syarikat). Mungkin diarahkan ke pejabat tertentu tetapi membolehkan satu nombor digunakan untuk syarikat.
VOICEMAIL	Nombor telefon mel suara.
UNKNOWN	Jenis nombor tidak dapat ditentukan.

Tatal ke Atas

GET/routedilindungi

Mendapatkan laluan yang akan dipilih secara automatik apabila anda menjalankan carian HLR tanpa menyatakan parameter route.

Pemilihan laluan automatik adalah berdasarkan peta penghalaan yang boleh diambil dengan endpoint GET /hlr-coverage, yang terutamanya diperolehi daripada GET /routing-map. Anda boleh menyesuaikan peta penghalaan anda dan menentukan peraturan tersuai dalam tetapan akaun anda.

Permintaan Respons Berjaya Respons Ralat

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`msisdn`	string	MSISDN untuk mendapatkan maklumat penghalaan yang dipilih secara automatik.	null	wajib

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`route`	string	Laluan yang disyorkan.	false
`confidence_level`	string	Tahap keyakinan di mana laluan ini dipilih, iaitu `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	MCCMNC berasaskan pelan penomboran untuk nombor ini.	false
`origin`	string	Asal yang menjadi asas keputusan penghalaan, iaitu `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."
    ]
}

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/routesdilindungi

Endpoint ini mengembalikan senarai laluan HLR, MNP, dan NT yang tersedia. Setiap laluan, bersama ciri dan batasannya, dijelaskan di halaman butiran penghalaan.

Permintaan Respons Berjaya Respons Ralat

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

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`routes`	object	Objek dengan laluan yang dikumpulkan mengikut jenis laluan.	false
`HLR\|MNP\|NT`	string[]	Mengandungi senarai pengecam laluan.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/routing-mapdilindungi

Mendapatkan konfigurasi penghalaan automatik yang sedang digunakan untuk Carian HLR bagi akaun anda. Konfigurasi lalai ini digunakan apabila anda menghantar carian HLR tanpa menyatakan parameter route. Anda boleh menyesuaikan peta penghalaan anda dan mencipta peraturan tersuai dalam tetapan akaun anda.

Hierarki konfigurasi mengalir dari peraturan peringkat negara kepada peraturan peringkat MCCMNC, dan akhirnya kepada pemetaan awalan nombor telefon individu. Dalam praktiknya, ini bermakna pemetaan awalan nombor telefon individu mengambil keutamaan berbanding tugasan MCCMNC yang bercanggah, yang seterusnya mengatasi peraturan peringkat negara. Sila ambil perhatian bahawa sandaran MNP mengatasi sebarang peraturan tersuai yang bercanggah semasa diaktifkan.

Permintaan Respons Berjaya Respons Ralat

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`default_route`	string	Laluan lalai yang digunakan apabila tiada pilihan penghalaan pilihan dapat ditentukan untuk sesuatu MSISDN dan tiada peraturan penghalaan tersuai digunakan.	false
`mnp_fallback`	boolean	Menunjukkan sama ada sandaran MNP diaktifkan. Apabila diaktifkan dan pertanyaan HLR tidak disokong oleh rangkaian (status sambungan tidak tersedia), sistem akan melakukan carian MNP sebaliknya.	false
`mccmncs`	array	Pemetaan kod MCCMNC kepada laluan yang dipilih secara automatik. Apabila melakukan carian HLR untuk nombor dalam MCCMNC tertentu, laluan yang berkaitan akan digunakan.	false
`mccmnc`	string(5\|6)	MCCMNC lima atau enam aksara (gabungan kod negara mudah alih dan kod rangkaian mudah alih) yang mengenal pasti pengendali rangkaian mudah alih.	false
`countrycode`	string(2)	Kod negara ISO dua aksara, mengenal pasti negara rangkaian.	false
`route`	string(3)	Laluan yang dipilih untuk rangkaian.	false
`mno`	string	Jenama yang dihadapi pengguna di mana rangkaian ini beroperasi.	false
`confidence`	string	Tahap keyakinan pemilihan dibuat. Nilai yang mungkin adalah: HIGH, NORMAL, LOW, MNP_REDIRECT. Dalam kes yang terakhir, sistem mengalihkan trafik ke rangkaian ini kepada MNP, jika tingkah laku ini diaktifkan dalam akaun anda. Jika tidak, ia menggunakan laluan lalai dalam akaun.	false
`origin`	string	Asal yang menjadi asas pemilihan. Nilai yang mungkin adalah: `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	Senarai peraturan penghalaan berasaskan awalan tersuai yang dikonfigurasikan dalam akaun anda, jika ada.	false
`countrycode`	string(2)	Kod negara ISO dua aksara, mengenal pasti negara awalan.	false
`cns`	string	Awalan yang mana peraturan penghalaan digunakan.	false
`route`	string(3)	Laluan yang dipilih untuk awalan.	false
`mccmnc`	string(5\|6)	MCCMNC lima atau enam aksara (gabungan kod negara mudah alih dan kod rangkaian mudah alih) yang mengenal pasti pengendali rangkaian mudah alih.	true
`mno`	string	Jenama yang dihadapi pengguna di mana rangkaian ini beroperasi.	true
`countries`	array	Senarai peraturan berasaskan negara tersuai yang dikonfigurasikan dalam akaun anda, jika ada.	false
`countrycode`	string(2)	Kod negara ISO dua aksara, mengenal pasti negara.	false
`route`	string(3)	Laluan yang dipilih untuk negara.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/hlr-coverage dilindungi

Mengembalikan pandangan liputan HLR untuk menyokong pembuatan keputusan berasaskan data. Endpoint ini membantu anda menganalisis pilihan penghalaan HLR masa nyata merentasi rangkaian mudah alih, mengenal pasti laluan paling berkesan untuk kawasan sasaran anda, dan mengkonfigurasi penghalaan automatik anda.

Laluan yang disyorkan daripada GET /route adalah berdasarkan data liputan yang diperoleh di sini. Data liputan juga tersedia di halaman liputan rangkaian. Anda boleh menyesuaikan lagi peta penghalaan anda dan menentukan peraturan dalam tetapan akaun anda.

Kami mengesyorkan agar anda membiasakan diri dengan panduan ini untuk membantu mentafsir keputusan.

Permintaan Respons Berjaya Respons Ralat Rujukan Status

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`countrycode`	string(2)	Kod negara ISO dua huruf yang wajib digunakan untuk menapis hasil, mengembalikan hanya rekod yang berkaitan dengan negara yang ditentukan.	null	wajib
`sample_size`	string	Parameter pilihan yang menentukan saiz sampel. Nilai yang mungkin ialah `LARGE`, `MEDIUM`, `SMALL`. Sampel yang lebih besar merangkumi jangka masa yang lebih panjang, sampel yang lebih kecil merangkumi jangka masa yang sangat terkini.	LARGE	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`name`	string	Nama negara yang dipilih dalam teks biasa Bahasa Inggeris.	false
`countrycode`	string(2)	Kod negara ISO dua aksara bagi negara yang dipilih.	false
`prefix`	string	Awalan pendailan antarabangsa bagi negara yang dipilih.	false
`mccs`	string[]	Senarai MCC (kod negara mudah alih) yang berkaitan dengan negara yang dipilih.	false
`carriers`	object[]	Senarai objek pembawa dengan metrik ketersambungan khusus laluan.	false
`mno`	string	Nama pengendali rangkaian mudah alih dalam teks biasa Bahasa Inggeris.	false
`mccmnc`	string	MCCMNC pengendali rangkaian mudah alih.	false
`mcc`	string	MCC (kod negara mudah alih) pengendali rangkaian mudah alih.	false
`mnc`	string	MNC (kod rangkaian mudah alih) pengendali rangkaian mudah alih.	false
`routes`	object[]	Senarai keputusan ketersambungan khusus laluan.	false
`route`	string	Laluan yang mana maklumat ketersambungan digunakan.	false
`selected`	bool	Menunjukkan sama ada ini adalah laluan yang dipilih untuk penghalaan automatik.	false
`selection_confidence`	string	Tahap keyakinan di mana laluan ini dipilih, iaitu `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Mengandungi null jika ini bukan laluan yang dipilih.	true
`n`	int	Jumlah keseluruhan carian dalam sampel ini.	false
`CONNECTED`	int	Bilangan carian HLR yang mengembalikan status CONNECTED.	false
`CONNECTED_PCT`	float	Peratusan carian HLR yang mengembalikan status CONNECTED.	false
`ABSENT`	int	Bilangan carian HLR yang mengembalikan status ABSENT.	false
`ABSENT_PCT`	float	Peratusan carian HLR yang mengembalikan status ABSENT.	false
`INVALID_MSISDN`	int	Bilangan carian HLR yang mengembalikan status INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	Peratusan carian HLR yang mengembalikan status INVALID_MSISDN.	false
`UNDETERMINED`	int	Bilangan carian HLR yang mengembalikan status UNDETERMINED.	false
`UNDETERMINED_PCT`	float	Peratusan carian HLR yang mengembalikan status UNDETERMINED.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Status	Keterangan
CONNECTED	Nombor ini sah dan peranti sasaran sedang bersambung ke rangkaian mudah alih. Panggilan, SMS dan perkhidmatan lain seharusnya berjaya sampai kepada penerima.
ABSENT	Nombor ini sah, tetapi peranti sasaran sama ada dimatikan atau berada di luar liputan rangkaian buat sementara waktu. Mesej atau panggilan mungkin tidak dapat dihantar sehingga peranti bersambung semula ke rangkaian.
INVALID_MSISDN	Nombor ini tidak sah atau tidak diperuntukkan kepada mana-mana pelanggan pada rangkaian mudah alih. Panggilan dan mesej ke nombor ini akan gagal.
UNDETERMINED	Status sambungan nombor ini tidak dapat ditentukan. Ini mungkin disebabkan oleh nombor yang tidak sah, respons ralat SS7, atau kekurangan sambungan dengan pengendali rangkaian sasaran. Periksa kod ralat dan medan penerangan untuk diagnostik tambahan.

Tatal ke Atas

GET/mnp-coveragedilindungi

Endpoint ini mengembalikan senarai pengendali rangkaian mudah alih, berserta pengecam MCCMNC yang berkaitan, yang kini disokong untuk carian kemudahalihan nombor mudah alih.

Permintaan Respons Berjaya Respons Ralat

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`countrycode`	string(2)	Kod negara ISO dua huruf pilihan yang digunakan untuk menapis hasil MCCMNC, mengembalikan hanya data yang berkaitan dengan negara yang dinyatakan.	null	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`items[]`	array	Senarai pengendali rangkaian mudah alih.	false
`country_name`	string	Nama negara dalam Bahasa Inggeris.	false
`country_code`	string(2)	Kod negara ISO dua huruf.	false
`mccmnc`	string(5\|6)	MCCMNC lima atau enam aksara (gabungan kod negara mudah alih dan kod rangkaian mudah alih) yang mengenal pasti pengendali rangkaian mudah alih.	false
`mcc`	string(3)	MCC tiga aksara (kod negara mudah alih) yang mewakili negara rangkaian tersebut.	false
`mnc`	string(2\|3)	MNC dua atau tiga aksara (kod rangkaian mudah alih) yang mewakili pengendali rangkaian mudah alih tertentu.	false
`brand`	string	Jenama yang dihadapi pengguna di mana rangkaian ini beroperasi.	true
`operator`	string	Nama sah pengendali rangkaian mudah alih.	true

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/price-listdilindungi

Endpoint ini mengembalikan senarai negara di mana hanya carian MNP disokong, dan pertanyaan HLR tidak tersedia untuk destinasi tersebut.

Permintaan Respons Berjaya Respons Ralat

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

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`countries`	string[]	Senarai kod negara ISO dua aksara.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/mccmncsdilindungi

Titik akhir ini mengembalikan senarai lengkap pengendali rangkaian mudah alih beserta pengecam MCCMNC yang berkaitan dan maklumat kontekstual tambahan.

Permintaan Respons Berjaya Respons Ralat

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`countrycode`	string(2)	Kod negara ISO dua huruf pilihan yang digunakan untuk menapis hasil MCCMNC, mengembalikan hanya rekod yang berkaitan dengan negara yang dinyatakan.	null	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`items`	object[]	Senarai pengendali rangkaian mudah alih.	false
`country_name`	string	Nama penuh negara dalam bahasa Inggeris.	false
`country_code`	string(2)	Kod negara ISO dua huruf yang mewakili negara pengendali mudah alih.	false
`mccmnc`	string(5\|6)	Rentetan lima atau enam aksara yang mewakili MCCMNC, yang mengenal pasti pengendali rangkaian mudah alih secara unik.	false
`mcc`	string(3)	Kod Negara Mudah Alih (MCC) tiga aksara yang mengenal pasti negara di mana rangkaian mudah alih beroperasi.	false
`mnc`	string(2\|3)	Kod Rangkaian Mudah Alih (MNC) dua atau tiga aksara yang menentukan rangkaian mudah alih dalam MCC yang diberikan.	false
`brand`	string	Nama jenama komersial di mana rangkaian beroperasi dan dikenali oleh pengguna.	true
`operator`	string	Nama rasmi pengendali rangkaian mudah alih, biasanya entiti undang-undang yang menguruskan rangkaian tersebut.	true
`parent_mccmnc`	string(5\|6)	Rentetan lima atau enam aksara yang mewakili MCCMNC pengendali rangkaian mudah alih induk, jika ada.	true

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/pricedilindungi

Endpoint ini mengembalikan harga untuk carian HLR, MNP, atau NT.

Permintaan Respons Berjaya Respons Ralat

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

Parameter Permintaan

Kunci	Jenis	Keterangan	Lalai	Wajib
`msisdn`	string	Nombor telefon yang harganya ingin diperoleh. Dalam format antarabangsa.	null	wajib
`route_type`	string	Jenis laluan, iaitu `HLR`, `MNP`, `NT`.	null	wajib
`route`	string(3)	Laluan yang harganya perlu dikira. Secara lalai menggunakan laluan yang ditentukan oleh penghalaan automatik.	null	pilihan

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`price`	object	Objek dengan butiran harga.	false
`amount`	string	Jumlah dalam EUR.	false
`msisdn`	string	MSISDN yang mana harga ini terpakai.	false
`route_type`	string(2\|3)	Jenis laluan yang mana harga ini terpakai.	false
`route`	string(3)	Laluan yang mana harga ini terpakai.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/price-listdilindungi

Endpoint ini mengembalikan harga dalam akaun anda.

Permintaan Respons Berjaya Respons Ralat

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

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`pricing`	object[]	Senarai objek dengan maklumat harga.	false
`route`	string	Laluan yang mana harga ini dikenakan.	false
`countrycode`	string	Kod negara ISO dua aksara yang mana harga ini dikenakan untuk laluan yang berkaitan, jika ada.	true
`countryname`	string	Nama negara dalam Bahasa Inggeris yang sepadan dengan kod negara, jika ada.	true
`mccmnc`	string	MCCMNC yang mana harga ini dikenakan untuk laluan yang berkaitan, jika ada. Mengatasi harga peringkat negara.	true
`cns`	string	Awalan pendailan yang mana harga ini dikenakan untuk laluan yang berkaitan, jika ada. Mengatasi harga peringkat negara dan harga peringkat MCCMNC.	true
`route_type`	string	Jenis laluan yang berkaitan, iaitu `HLR`, `MNP`, `NT`.	false
`route_type`	string	Harga yang berkaitan dalam EUR.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/balancedilindungi

Endpoint ini mendapatkan baki akaun semasa anda, membolehkan anda mengautomasikan proses berdasarkan status kredit anda. Ia berfungsi dengan lancar bersama notifikasi e-mel kredit rendah yang boleh anda konfigurasikan di halaman pembayaran anda.

Permintaan Respons Berjaya Respons Ralat

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

{
    "balance":"1002.90"
}

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`balance`	string	Baki akaun semasa anda dalam EUR. Nilai perpuluhan dalam format string.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/pingawam

Endpoint ini menghantar permintaan ping ke API, menyediakan kaedah mudah untuk menguji sambungan anda ke API HLR Lookups.

Permintaan Respons Berjaya Respons Ralat

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

{
    "success":true
}

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`success`	boolean	Menunjukkan bahawa permintaan telah diproses dengan jayanya.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/timeawam

Endpoint ini mengembalikan cap masa Unix yang mewakili masa semasa pada pelayan HLR Lookups. Gunakan untuk menyegerakkan jam pelayan anda semasa menjana tandatangan Digest-Auth untuk pengesahan, memastikan sebarang percanggahan antara masa pelayan anda dan masa pelayan HLR Lookups diperbetulkan.

Permintaan Respons Berjaya Respons Ralat

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

{
    "time":1525898643
}

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`time`	integer	Cap masa Unix yang mewakili masa semasa pelayan HLR Lookups.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

GET/auth-testdilindungi

Endpoint ini berfungsi sebagai ujian awal untuk pelaksanaan Basic-Auth atau, lebih baik lagi, Digest-Auth anda.

Permintaan Basic Auth Permintaan Digest Auth Respons Berjaya Respons Ralat

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

Pengepala Permintaan

Kunci	Jenis	Keterangan
`X-Basic`	string	Hash SHA256 bagi `YOUR_API_KEY:YOUR_API_SECRET`. Sertakan simbol titik bertindih (:) dalam hash.

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"

Pengepala Permintaan

Kunci	Jenis	Keterangan
`X-Digest-Key`	string	Kunci API HLR Lookups Anda
`X-Digest-Signature`	string	Tandatangan Digest-Auth yang unik (lihat pengesahan)
`X-Digest-Timestamp`	integer	Cap waktu Unix semasa (lihat juga `GET /time`)

{
    "success":true
}

Atribut Respons Berjaya

Nama	Jenis	Keterangan	Boleh Null
`success`	boolean	Menunjukkan bahawa permintaan telah diproses dengan jayanya.	false

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

Parameter Respons Ralat

Nama	Jenis	Keterangan	Boleh Null
`errors[]`	string[]	Senarai rentetan yang menerangkan ralat.	false

Tatal ke Atas

Dokumentasi API Lama

Sila ambil perhatian bahawa API lama ini telah ditamatkan dan dijadualkan untuk dihentikan pada masa hadapan. Kami amat mengesyorkan agar anda menaik taraf ke versi terkini secepat mungkin.

Jika anda melaksanakan API HLR Lookups kami antara tahun 2013 dan awal 2020, anda menggunakan API lama kami. Sila rujuk dokumentasi API lama kami dalam kes tersebut.

Dokumentasi API Lama

Dokumentasi API

Panduan Permulaan

Carian HLR

Carian MNP

Carian NT

Penghalaan

Harga

Alatan

Panduan Permulaan

Menggunakan API HLR Lookups

Contoh Permintaan

Contoh Muatan

Respons Berjaya application/json

Perkhidmatan Carian Tambahan

Carian Kemudahalihan Nombor Mudah Alih (MNP)

Carian Pengesanan Jenis Nombor (NT)

Kit Pembangunan Perisian (SDK)

Alatan

Bukan Pembangun?

Pengesahan

Kunci API dan Rahsia API

HTTP Basic Auth

Disyorkan: Pengepala X-Basic dengan SHA256

Permintaan Basic Auth

Pengepala Pengesahan Basic

Contoh Kod

Contoh Permintaan

Pengepala Permintaan

Membina Tandatangan

Komponen Tandatangan Digest

Contoh Kod

Konsep

API Carian HLR Segerak

API Carian HLR Tak Segerak

SDK (Kit Pembangunan Perisian)

SDK PHP

SDK NodeJS

SDK Ruby

POST/hlr-lookupdilindungi

Muatan

Parameter Permintaan

Atribut Respons Berjaya

Parameter Respons Ralat

POST/hlr-lookupsdilindungi

Muatan

Parameter Permintaan

Atribut Respons Berjaya

Parameter Respons Ralat

Memproses Webhook

Pengesahan

Contoh Kod

Mengesahkan Penerimaan

Muatan Webhook

Atribut Muatan Webhook

POST/mnp-lookupdilindungi

Muatan

Parameter Permintaan

Atribut Respons Berjaya

Parameter Respons Ralat

POST/mnp-lookupsdilindungi

Muatan

Parameter Permintaan

Atribut Respons Berjaya

Parameter Respons Ralat

Memproses Webhook

Pengesahan

Contoh Kod

Mengesahkan Penerimaan

Muatan Webhook

Atribut Muatan Webhook

POST/nt-lookupdilindungi

Muatan

Parameter Permintaan

Atribut Respons Berjaya

Parameter Respons Ralat

POST/nt-lookups dilindungi

Muatan

Parameter Permintaan

Atribut Respons Berjaya

Parameter Respons Ralat