Aloitus

Maailmanlaajuinen matkaviestinverkkoinfrastruktuuri toimii SS7-signalointiverkkona tunnetun järjestelmän avulla. Tämä verkko mahdollistaa tilaajatietojen vaihdon, puhelujen reitityksen, SMS-viestien välityksen ja reaaliaikaisten matkaviestinyhteyden tilapäivitysten vaihdon operaattoreiden välillä. Jokainen matkaviestinverkko ylläpitää HLR-rekisteriä (Home Location Register) - keskitettyä tietokantaa, joka tallentaa olennaisia tietoja sen tilaajista.

HLR Lookup -teknologia mahdollistaa yrityksille näiden rekistereiden kyselyn ja reaaliaikaisten yhteys- ja verkkatietojen hakemisen mille tahansa matkapuhelinnumerolle. Tämä sisältää tiedon siitä, onko puhelin päällä, mihin verkkoon se on tällä hetkellä liitetty, onko numero siirretty, onko numero voimassa vai poistettu käytöstä, sekä onko numero roamingissa.

HLR Lookups API tarjoaa saumattoman, reaaliaikaisen pääsyn näihin tietoihin, mahdollistaen yrityksille matkapuhelinnumeroiden vahvistamisen, reitityksen optimoinnin ja asiakasviestinnän tehostamisen. Tämä dokumentaatio opastaa sinut HLR Lookups -palvelun integroimisessa ohjelmistoosi, mahdollistaen reaaliaikaisen matkaviestintiedon automaattisen haun.

HLR Lookups API:n käyttö

HLR Lookup -kyselyiden suorittaminen on nopeaa, turvallista ja suoraviivaista. Kun olet rekisteröitynyt ja hankkinut API-avaimesi, voit tunnistautua ja aloittaa välittömät haut yksinkertaisilla HTTP POST -pyynnöillä, käyttäen POST /hlr-lookup -rajapintaa. Vaihtoehtoisesti voit käsitellä suuria tietomääriä valitsemalla nopeat asynkroniset API-pyynnöt, joiden tulokset lähetetään takaisin palvelimellesi webhookin kautta, kuten käsitteet-osiossa selitetään.

Esimerkkipyyntö

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"

Tunnistautuminen toimitetaan HTTP-otsakkeina, ja payload.json -tiedoston tulisi (vähintään) sisältää seuraava JSON-objekti:

Esimerkkisisältö

{
   "msisdn": "+14156226819"
}

Onnistuneen suorituksen jälkeen saat vastauksen, joka sisältää reaaliaikaiset yhteystiedot määritetylle matkapuhelinnumerolle.

Onnistunut vastaus 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"
}

Täydellinen erittely pyynnön ja vastauksen attribuuteista sekä yhteystiloista löytyy osiosta POST /hlr-lookup.

Lisähakupalvelut

Numeronsiirtopalvelun (MNP) haut

Käytä MNP-hakuja selvittääksesi verkon omistajuuden ja siirrettävyyden tiedot ilman reaaliaikaisen yhteyden kyselyä. Jos tarvitset vain numeron MCCMNC-koodin, tutustu osioon POST /mnp-lookup.

Numerotyypin tunnistus (NT) -haut

Selvitä, kuuluuko puhelinnumero lankapuhelimeen, matkapuhelimeen, maksulliseen palvelunumeroon, VoIP-palveluun, hakulaitteeseen tai muihin numerointisuunnitelman alueisiin käyttäen POST /nt-lookup -rajapintaa.

Ohjelmistokehityspaketit (SDK)

HLR Lookups API toimii minkä tahansa REST-asiakkaan kanssa missä tahansa ohjelmointikielessä, ja olemme julkaisseet SDK:t PHP:lle, Rubylle ja NodeJS:lle GitHub-sivustollamme auttaaksemme sinua pääsemään nopeasti alkuun.

Työkalut

Sujuvan kehityskokemuksen varmistamiseksi tarjoamme kattavan työkalukokoelman, joka sisältää selainpohjaisen API-pyyntöjen ja webhook-seurannan, IP-osoitteiden sallittujen listauksen, vankat tunnistautumisvaihtoehdot sekä tunnistautumisen testausrajapinnan.

Etkö ole kehittäjä?

HLR-haut ja numeronsiirtopalvelun kyselyt voidaan suorittaa ilman ohjelmointia. Lue lisää yritysverkkosovelluksestamme ja selainpohjaisista raportointiominaisuuksista.

Todennus

Turvallisuuden ja asianmukaisen pääsynhallinnan varmistamiseksi useimmat HLR Lookups API -pyynnöt vaativat todennuksen. Päätepisteet on luokiteltu joko julkisiksi tai suojatuiksi. Suojattuun päätepisteeseen pääsyä varten pyyntösi on todennettava API-avaimellasi ja salaisuudellasi käyttäen joko Digest-Auth- tai Basic-Auth-menetelmää. Digest-Auth on turvallisempi vaihtoehto ja sitä suositellaan vahvasti. Käytä GET /auth-test-päätepistettä todennusasetustesi tarkistamiseen.

API-avain ja API-salaisuus

Hanki API-avaimesi ja salaisuutesi API-asetukset-sivulta. Voit myös määrittää haluamasi todennusmenetelmän ja ottaa käyttöön IP-osoitteiden sallittujen luettelon turvallisuuden parantamiseksi. Jos epäilet, että API-salaisuutesi on vaarantunut, voit luoda uuden milloin tahansa.

Basic Auth Digest Auth IP-sallitut osoitteet

Tavanomainen Basic-todennus on helppo toteuttaa ja laajalti tuettu. Voit todentaa lähettämällä API-avaimesi ja salaisuutesi user:pass-parina HTTP-pyynnössä.

HTTP Basic Auth

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

Tämä lähettää Authorization-otsakkeen:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Suositeltu: X-Basic-otsake SHA256:lla

Turvallisuuden parantamiseksi voit lähettää tunnistietojesi SHA256-tiivisteen sen sijaan, että lähettäisit ne suoraan base64-muodossa. Käyttääksesi tätä menetelmää, laske YOUR_API_KEY:YOUR_API_SECRET-parisi tiiviste ja lähetä se X-Basic-otsakkeen kautta:

Basic Auth -pyyntö

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

Basic-todennuksen otsakkeet

Avain	Tyyppi	Kuvaus
`X-Basic`	string	`YOUR_API_KEY:YOUR_API_SECRET`-merkkijonon SHA256-tiiviste. Sisällytä kaksoispistemerkki (:) tiivisteeseen.	pakollinen

Koodiesimerkki

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

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

Digest-Auth on suositeltu menetelmä suojattujen HLR Lookup API -päätepisteiden käyttöoikeuden turvaamiseen. Jokaisen pyynnön on sisällettävä seuraavat otsakkeet: X-Digest-Key, X-Digest-Signature ja X-Digest-Timestamp, jotka on selitetty alla.

Pyyntöesimerkki

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"

Pyynnön otsakkeet

Avain	Tyyppi	Kuvaus
`X-Digest-Key`	string	Yksilöllinen HLR Lookups API -avaimesi.	pakollinen
`X-Digest-Signature`	string	Yksilöllinen todennusallekirjoitus (katso alla).	pakollinen
`X-Digest-Timestamp`	integer	Nykyinen Unix-aikaleima (katso myös `GET /time`).	pakollinen

Allekirjoituksen muodostaminen

X-Digest-Signature luodaan käyttämällä SHA256 HMAC -tiivistettä, jossa API-salaisuutesi toimii jaettuna avaimena.

Tiivistettävä merkkijono on rakenteeltaan seuraava:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

.-symboli tarkoittaa merkkijonojen yhdistämistä.

Digest-allekirjoituksen komponentit

Komponentti	Tyyppi	Kuvaus
`ENDPOINT_PATH`	string	Pyydetty API-päätepiste, esim. `/auth-test` pienaakkosin.
`UNIX_TIMESTAMP`	integer	Nykyinen Unix-aikaleima (on oltava 30 sekunnin sisällä). Katso `GET /time`.
`REQUEST_METHOD`	string	Käytetty HTTP-metodi, esim. `POST` tai `GET`.
`REQUEST_BODY`	string	Pyynnön sisältödata. Aseta arvoksi `null` `GET`-pyynnöissä.

Koodiesimerkit

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)

Vieritä ylös

Käsitteet

HLR-kyselyiden käyttöönotto missä tahansa ohjelmointikielessä tai järjestelmässä HTTP REST API:n kautta on suoraviivaista ja tehokasta. Yksinkertaisen integrointiprosessin ansiosta voit aloittaa matkaviestinverkkojen reaaliaikaisen kyselemisen ja saada välittömästi tietoa puhelinnumeroiden kelvollisuudesta, yhteystilasta ja reititystiedoista.

Sopivan API:n valinta riippuu käyttötarkoituksestasi. Jos tarvitset reaaliaikaisia kyselytuloksia sovelluksiin kuten VoIP-puhelinpalveluihin, petostentunnistukseen tai SMS-reititys, synkroninen API on paras valinta. Jos käyttötarkoituksesi kuitenkin sisältää suurivolyymista käsittelyä, massakyselyitä tai laajamittaista tietojen vahvistusta, asynkroninen API tarjoaa optimoidun suorituskyvyn kaistanleveystehokkuudella ja eräkyselyominaisuuksilla.

Määritä API käyttämään jotakin mukautetuista reititysvalinnoistamme optimoidaksesi nopeuden, tarkkuuden ja kustannustehokkuuden. Voit myös tallentaa kyselytulokset tallennustiloihin helppoa CSV- ja JSON-raporttien latausta sekä edistynyttä analytiikkaa varten verkkokäyttöliittymän kautta.

Synkroninen HLR-kysely API

POST /hlr-lookup-päätepiste käsittelee yhden matkapuhelinnumeron (MSISDN) per pyyntö ja palauttaa tulokset välittömästi HTTP-vastauksen rungossa. Tulokset muotoillaan JSON-muotoon ja soveltuvat erinomaisesti reaaliaikaisiin sovelluksiin, kuten matkapuhelinnumeroiden vahvistukseen, puhelujen reititys ja SMS-viestien toimitukseen.

Synkroninen API-kutsu koostuu suorasta HTTP-pyynnöstä ja -vastauksesta. Järjestelmäsi lähettää yhden MSISDN-numeron (matkapuhelinnumeron) per pyyntö ja vastaanottaa välittömän vastauksen, joka sisältää reaaliaikaiset HLR-kyselytulokset JSON-muodossa. Tämä API on optimoitu käyttötarkoituksiin, jotka vaativat välitöntä vahvistusta ja yhteystarkistuksia, kuten petostentunnistukseen, VoIP-puhelujen reititys ja SMS-yhdyskäytävien optimointiin.

Asynkroninen HLR-kyselyrajapinta

POST /hlr-lookups-päätepiste on suunniteltu massa- ja suurivolyymiseen käsittelyyn, jolloin voit lähettää jopa 1,000 MSISDN-numeroa per pyyntö. Sen sijaan, että palauttaisi tulokset välittömästi, tämä API käyttää automatisoituja webhookeja lähettääkseen tulokset asteittain palvelimellesi. Kyselytulokset palautetaan JSON-objekteina HTTP POST -takaisinkutsujen kautta.

Asynkroninen API on optimoitu nopeuden, tehokkuuden ja skaalautuvuuden kannalta. Se poistaa synkronisiin kutsuihin liittyvät verkkoviiveongolmat, mikä tekee siitä ihanteellisen yrityksille, jotka tarvitsevat suuren suoritustehon kyselyitä. Järjestelmäsi lähettää jopa 1,000 MSISDN-numeroa per pyyntö, ja alustamme käsittelee ne rinnakkain palauttaen tulokset palvelimellesi HTTP-webhookien kautta erissä, jotka sisältävät jopa 1,000 tulosta per takaisinkutsu.

SDK:t (ohjelmistokehityspakkaukset)

Ohjelmistokehityspakkaukset (SDK:t) PHP:lle, NodeJS:lle ja Rubylle tehostavat integrointiprosessia ja mahdollistavat yhteyden HLR Lookups API:in vaivattomasti ja pienellä vaivalla.

Nämä SDK:t tarjoavat valmiit funktiot, autentikoinnin hallinnan ja jäsennellyt API-pyyntömallit, mikä lyhentää kehitysaikaa ja varmistaa parhaat käytännöt.

Tutustu kaikkiin saatavilla oleviin SDK:ihin GitHubissa ja aloita integrointi jo tänään.

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

Näytä GitHubissa 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   }

Näytä GitHubissa 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)

Näytä GitHubissa README.md

Vieritä ylös

POST/hlr-lookupsuojattu

Suorittaa synkronisen HLR-kyselyn, joka toimittaa reaaliaikaisia matkapuhelimen yhteys- ja siirrettävyystietoja suoraan verkko-operaattoreilta. Tämä rajapinta soveltuu erinomaisesti reaaliaikaisiin käyttötapauksiin, joissa aikakriittiset sovellukset vaativat välitöntä vahvistusta siitä, onko puhelinnumero tällä hetkellä tavoitettavissa (yhteydessä) vai ei-tavoitettavissa (pois päältä). Lisäksi se auttaa erottamaan aktiiviset numerot virheellisistä, tuntemattomista tai väärennetyistä numeroista.

Suurten tietojoukkojen massaprosessointiin, joka ei vaadi välittömiä tuloksia, suosittelemme asynkronista POST /hlr-lookups-rajapintaa, joka on optimoitu nopean eräkäsittelyn tarpeisiin.

Jos pääasiallinen tarpeesi on matkapuhelinnumeron siirrettävyystietojen (MCCMNC) hakeminen etkä tarvitse reaaliaikaista yhteystilan tietoa, POST /mnp-lookup tarjoaa kustannustehokkaan vaihtoehdon numeron siirrettävyyskyselyihin.

Pyyntö Onnistunut vastaus Virhevastaus Tilaviite

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

Pyyntödata

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`msisdn`	string	Kyseltävä matkapuhelinnumero (MSISDN) kansainvälisessä muodossa (esim. +14156226819 tai 0014156226819). Maakoodi on pakollinen.	null	pakollinen
`route`	string(3)	Valinnainen kolmimerkkinen tunniste, joka määrittää tämän kyselyn reitin. Aseta arvoksi `null` tai jätä parametri pois käyttääksesi mukautettua reitityskarttaasi tai antaaksesi järjestelmän määrittää automaattisesti parhaan reitin tälle kyselylle.	null	valinnainen
`storage`	string	Valinnainen tallennustunniste, joka määrittää raportin, johon tulokset tallennetaan manuaalista tarkastelua, analysointia ja raportointia varten. Järjestelmä lisää automaattisesti aikaleiman kuluvalla kuukaudella. Jos parametri jätetään pois tai asetetaan arvoon `null`, järjestelmä ryhmittelee tulokset automaattisesti kuukausittain raportointia varten.	null	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`id`	string(12)	Tälle hakulle määritetty yksilöllinen tunniste.	false
`msisdn`	string	Kyseltävä matkapuhelinnumero kansainvälisessä muodossa (esim. +14156226819 tai 0014156226819).	false
`connectivity_status`	string	Ilmoittaa, onnistuiko numeron yhteystilan haku. Mahdolliset arvot: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` tai `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Viisi- tai kuusinumeroinen Mobile Country Code (MCC) ja Mobile Network Code (MNC), joka tunnistaa puhelinnumeroon tällä hetkellä liitetyn verkon.	true
`mcc`	string(3)	Kolminumeroinen Mobile Country Code (MCC), joka tunnistaa maan, johon puhelinnumero on rekisteröity.	true
`mnc`	string(2\|3)	Kaksi- tai kolminumeroinen Mobile Network Code (MNC), joka tunnistaa verkon, johon puhelinnumero kuuluu.	true
`imsi`	string	International Mobile Subscriber Identity (IMSI), tähän numeroon liitetyn SIM-kortin yksilöllinen tunniste. Saatavuus riippuu verkon kokoonpanosta.	true
`msin`	string(10)	Mobile Subscription Identification Number (MSIN) matkapuhelinoperaattorin tietokannassa. Saatavuus riippuu verkon kokoonpanosta.	true
`msc`	string(12)	Mobile Switching Center (MSC), joka käsittelee tämän tilaajan viestintää. Saatavuus riippuu verkon kokoonpanosta.	true
`original_network_name`	string	Tähän numeroon liitetyn alkuperäisen verkko-operaattorin nimi.	true
`original_country_name`	string	Sen maan koko nimi englanniksi, johon matkapuhelinnumero alun perin rekisteröitiin.	true
`original_country_code`	string(2)	Kaksimerkinen ISO-maakoodi, joka edustaa maata, johon puhelinnumero alun perin määritettiin.	true
`original_country_prefix`	string	Kansainvälinen suuntanumero (maan puhelinnumero), joka vastaa matkapuhelinnumeron alkuperäistä maata.	true
`is_ported`	boolean	Ilmoittaa, onko matkapuhelinnumero siirretty alkuperäisestä verkostaan toiselle operaattorille.	true
`ported_network_name`	string	Sen verkko-operaattorin nimi, jolle matkapuhelinnumero on siirretty, jos sovellettavissa.	true
`ported_country_name`	string	Sen maan nimi, johon matkapuhelinnumero siirrettiin, jos sovellettavissa.	true
`ported_country_code`	string(2)	Kaksimerkinen ISO-maakoodi, joka edustaa maata, johon matkapuhelinnumero siirrettiin, jos sovellettavissa.	true
`ported_country_prefix`	string	Kansainvälinen suuntanumero (maan puhelinnumero) maalle, johon matkapuhelinnumero siirrettiin, jos sovellettavissa.	true
`is_roaming`	boolean	Ilmoittaa, onko matkapuhelinnumero tällä hetkellä verkkovierailussa ulkomaisessa verkossa. Verkkovierailutilan saatavuus riippuu matkapuhelinoperaattorista.	true
`roaming_network_name`	string	Sen verkon nimi, jossa matkapuhelinnumero on tällä hetkellä verkkovierailussa, jos sovellettavissa.	true
`roaming_country_name`	string	Sen maan nimi, jossa matkapuhelinnumero on tällä hetkellä verkkovierailussa, jos sovellettavissa.	true
`roaming_country_code`	string(2)	Kaksimerkinen ISO-maakoodi maalle, jossa matkapuhelinnumero on tällä hetkellä verkkovierailussa, jos sovellettavissa.	true
`roaming_country_prefix`	string	Kansainvälinen suuntanumero (maan puhelinnumero) maalle, jossa matkapuhelinnumero on tällä hetkellä verkkovierailussa, jos sovellettavissa.	true
`cost`	string	Merkkijonona esitetty desimaaliarvo, joka ilmaisee haun hinnan euroina.	true
`timestamp`	string	W3C-muotoinen aikaleima aikavyöhykkeineen, joka määrittää haun valmistumisajankohdan.	true
`storage`	string	Sen tallennustilan nimi, johon hakutulokset tallennettiin. Tämä vastaa raporttinimiä ja CSV-latauksia, jotka ovat saatavilla verkkokäyttöliittymän kautta.	true
`route`	string(3)	Kolmimerkkinen tunniste, joka ilmaisee tälle hakulle käytetyn reititystavan.	true
`processing_status`	string	Haun käsittelyn lopputulos. Mahdolliset arvot: `COMPLETED` (onnistunut), `REJECTED` (verkko ei tavoitettavissa, veloitusta ei tehty) tai `FAILED` (virhe käsittelyn aikana).	false
`error_code`	integer	Valinnainen sisäinen virhekoodi, joka tarjoaa lisädiagnostiikkatietoja asiakastukea varten.	true
`error_description`	string	Lyhyt selitys annetusta virhekoodista (jos saatavilla) englanniksi selkokielisenä tekstinä.	true
`data_source`	string	Tälle pyynnölle käytetty tietolähde. Mahdolliset arvot: `LIVE_HLR` (reaaliaikainen HLR-kysely) tai `MNP_DB` (staattinen matkapuhelinnumeron siirrettävyyden tietokanta). Katso lisätietoja reititysvaihtoehtojen kohdalta.	false
`routing_instruction`	string	Kaksoispisteellä erotettu merkkijono, joka kuvaa pyynnössä käytettyä reititysohjeistusta. Ensimmäinen osa on `STATIC`, kun määritit reitin, tai `AUTO` automaattiselle reititykselle. Toinen osa on reitin tunniste, ja automaattisissa reitituspyynnöissä kolmas osa näyttää alkuperän, johon reititysratkaisu perustuu (eli `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."
    ]
}

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Tila	Kuvaus
CONNECTED	Numero on voimassa ja kohdelaite on tällä hetkellä yhteydessä matkapuhelinverkkoon. Puhelut, tekstiviestit ja muut palvelut tavoittavat vastaanottajan onnistuneesti.
ABSENT	Numero on voimassa, mutta kohdelaite on joko sammutettuna tai tilapäisesti verkon kuuluvuusalueen ulkopuolella. Viestit tai puhelut eivät välttämättä tavoita vastaanottajaa ennen kuin laite muodostaa yhteyden verkkoon uudelleen.
INVALID_MSISDN	Numero on virheellinen tai sitä ei ole tällä hetkellä määritetty millekään matkapuhelinverkon tilaajalle. Puhelut ja viestit tähän numeroon epäonnistuvat.
UNDETERMINED	Numeron yhteystilaa ei voitu määrittää. Tämä voi johtua virheellisestä numerosta, SS7-virhevastauksesta tai yhteyden puutteesta kohdeverkko-operaattoriin. Tarkista virhekoodin ja sen kuvauksen kenttä lisädiagnostiikkaa varten.

Vieritä ylös

POST/hlr-lookupssuojattu

Käynnistää asynkronisten HLR-kyselyiden erän, joka hakee reaaliaikaisia matkapuhelinten yhteystietoja ja siirrettävyystietoja verkko-operaattoreilta. Tulokset toimitetaan webhookien kautta palvelimellesi. Tämä menetelmä on optimoitu suurten numeromäärien käsittelyyn, jotka eivät vaadi välittömiä vastauksia, kuten tietokantojen puhdistus ja varmennus. Reaaliaikaisiin sovelluksiin, kuten puhelujen reititys tai SMS-toimitukseen, kannattaa harkita POST /hlr-lookup-päätepisteen käyttöä.

Tämä päätepiste on ihanteellinen massaprosessointiin, kun tavoitteena on tunnistaa puhelinnumerot, jotka ovat tällä hetkellä tavoitettavissa (yhdistetty) tai tavoittamattomissa (puhelin pois päältä), samalla kun suodatetaan pois virheelliset, määrittämättömät tai väärennetyt numerot. Lisäksi se tarjoaa reaaliaikaisen siirrettävyystilan (MCCMNC) yhteystietojen ohella.

Ennen tämän päätepisteen käyttöä varmista, että webhook-URL on määritetty vastaanottamaan kyselytulokset asynkronisesti. Voit määrittää tämän API-asetuksissasi.

Pyyntö Onnistunut vastaus Virhevastaus Webhookit Tilaviite

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

Pyyntödata

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`msisdns`	array	Taulukko matkapuhelinnumeroista (MSISDN) kansainvälisessä muodossa (esim. +14156226819 tai 0014156226819). Voit sisällyttää enintään 1000 numeroa per pyyntö.	null	pakollinen
`route`	string(3)	Valinnainen kolmimerkkinen tunniste, joka määrittää tämän kyselyn reitin. Aseta arvoksi `null` tai jätä parametri pois käyttääksesi mukautettua reitityskarttaasi tai antaaksesi järjestelmän määrittää automaattisesti parhaan reitin tälle kyselylle.	null	valinnainen
`storage`	string	Valinnainen tallennustunniste, joka määrittää raportin, johon tulokset tallennetaan manuaalista tarkastelua, analysointia ja raportointia varten. Järjestelmä lisää automaattisesti aikaleiman kuluvalla kuukaudella. Jos parametri jätetään pois tai asetetaan arvoon `null`, järjestelmä ryhmittelee tulokset automaattisesti kuukausittain raportointia varten.	null	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`accepted`	array	Luettelo objekteista, jotka sisältävät yksilölliset tunnisteet ja MSISDN:t, jotka on hyväksytty käsiteltäväksi.	false
`accepted_count`	integer	MSISDN:ien kokonaismäärä, jotka on onnistuneesti hyväksytty käsiteltäväksi.	false
`rejected`	array	Luettelo objekteista, jotka sisältävät yksilölliset tunnisteet ja MSISDN:t, jotka on hylätty käsittelystä, tyypillisesti virheellisten numeroiden vuoksi. Hylätyistä merkinnöistä ei veloiteta.	false
`rejected_count`	integer	MSISDN:ien kokonaismäärä, jotka on hylätty validointivirheiden vuoksi.	false
`total_count`	integer	Hyväksyttyjen ja hylättyjen MSISDN:ien kokonaismäärä, jotka lähetettiin käsiteltäväksi.	false
`cost`	string	Merkkijonona esitetty desimaaliarvo, joka ilmaisee hyväksyttyjen kyselyiden kokonaiskustannukset euroina.	false
`storage`	string	Tallennustilan nimi, johon kyselytulokset lisätään, käytetään raportoinnissa ja CSV-latauksissa verkkokäyttöliittymän kautta.	false
`route`	string(3\|4)	Kolme- tai nelimerkkinen tunniste, joka määrittää tähän kyselypyyntöön käytetyn reitin. Sisältää AUTO, jos numeropohjaisesti automaattinen reititys pyydettiin.	false
`webhook_urls`	array	Webhook-URL:t, jotka on määritetty API-asetuksissasi. Tulokset lähetetään takaisin tänne.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Webhookien käsittely

Lähetyksen jälkeen alustamme aloittaa annettujen puhelinnumeroiden käsittelyn ja lähettää tulokset aiemmin määritettyyn webhook-osoitteeseen palvelimellasi. Tulokset lähetetään HTTP POST-pyyntönä, jossa pyynnön sisältönä on JSON-objekti.

Todennus

Todenna webhook tarkistamalla X-Signatures HTTP-otsake.

X-Signatures-otsake sisältää puolipisteillä erotetun listan allekirjoituksia. Jokainen listan allekirjoitus luodaan käyttäen yhtä tilillesi määritetyistä API-salaisuuksista. Vahvista webhook luomalla SHA-256-tiiviste API-avaimellasi, salaisuudellasi ja HTTP-sisällöllä - vertaa sitä sitten listan allekirjoituksiin.

Täsmäävyys vahvistaa, että pyyntö on aito ja allekirjoitettu hallitsemallasi salaisuudella.

Koodiesimerkki

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

Pyyntö on kelvollinen, jos mikä tahansa otsakeessa annetuista allekirjoituksista vastaa SHA256-tiivistettä, joka on laskettu API-avaimesi, salaisuutesi ja HTTP-sisällön yhdistetystä merkkijonosta.

Vastaanoton vahvistaminen

Palvelimesi odotetaan vastaavan HTTP-tilakoodilla 200 OK vahvistaakseen onnistuneen vastaanoton. Jos palautetaan jokin muu vastauskoodi, tapahtuu aikakatkaisu (10 sekuntia) tai ilmenee mikä tahansa muu toimitusvirhe, järjestelmä yrittää webhookin lähettämistä automaattisesti uudelleen minuutin kuluttua. Jos pyyntö epäonnistuu edelleen, uudelleenyritykset noudattavat eksponentiaalista viivästysstrategiaa, ja seuraavat yritykset tapahtuvat 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minuutin kuluttua.

Tämä uudelleenyritysmekanismi varmistaa maksimaalisen luotettavuuden hakutulosten toimittamisessa infrastruktuuriisi. Se minimoi tietojen menetyksen riskin tilapäisten verkko-ongelmien tai palvelimen käyttökatkojen vuoksi.

Webhook-sisältö

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

Webhook-kuorman attribuutit

JSON-objekti sisältää attribuutin type => HLR sekä attribuutin results, joka sisältää luettelon kyselyobjekteista, kuten alla dokumentoitu.

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`id`	string(12)	Tälle hakulle määritetty yksilöllinen tunniste.	false
`msisdn`	string	Kyseltävä matkapuhelinnumero kansainvälisessä muodossa (esim. +14156226819 tai 0014156226819).	false
`connectivity_status`	string	Ilmoittaa, onnistuiko numeron yhteystilan haku. Mahdolliset arvot: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` tai `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Viisi- tai kuusinumeroinen Mobile Country Code (MCC) ja Mobile Network Code (MNC), joka tunnistaa puhelinnumeroon tällä hetkellä liitetyn verkon.	true
`mcc`	string(3)	Kolminumeroinen Mobile Country Code (MCC), joka tunnistaa maan, johon puhelinnumero on rekisteröity.	true
`mnc`	string(2\|3)	Kaksi- tai kolminumeroinen Mobile Network Code (MNC), joka tunnistaa verkon, johon puhelinnumero kuuluu.	true
`imsi`	string	International Mobile Subscriber Identity (IMSI), tähän numeroon liitetyn SIM-kortin yksilöllinen tunniste. Saatavuus riippuu verkon kokoonpanosta.	true
`msin`	string(10)	Mobile Subscription Identification Number (MSIN) matkapuhelinoperaattorin tietokannassa. Saatavuus riippuu verkon kokoonpanosta.	true
`msc`	string(12)	Mobile Switching Center (MSC), joka käsittelee tämän tilaajan viestintää. Saatavuus riippuu verkon kokoonpanosta.	true
`original_network_name`	string	Tähän numeroon liitetyn alkuperäisen verkko-operaattorin nimi.	true
`original_country_name`	string	Sen maan koko nimi englanniksi, johon matkapuhelinnumero alun perin rekisteröitiin.	true
`original_country_code`	string(2)	Kaksimerkinen ISO-maakoodi, joka edustaa maata, johon puhelinnumero alun perin määritettiin.	true
`original_country_prefix`	string	Kansainvälinen suuntanumero (maan puhelinnumero), joka vastaa matkapuhelinnumeron alkuperäistä maata.	true
`is_ported`	boolean	Ilmoittaa, onko matkapuhelinnumero siirretty alkuperäisestä verkostaan toiselle operaattorille.	true
`ported_network_name`	string	Sen verkko-operaattorin nimi, jolle matkapuhelinnumero on siirretty, jos sovellettavissa.	true
`ported_country_name`	string	Sen maan nimi, johon matkapuhelinnumero siirrettiin, jos sovellettavissa.	true
`ported_country_code`	string(2)	Kaksimerkinen ISO-maakoodi, joka edustaa maata, johon matkapuhelinnumero siirrettiin, jos sovellettavissa.	true
`ported_country_prefix`	string	Kansainvälinen suuntanumero (maan puhelinnumero) maalle, johon matkapuhelinnumero siirrettiin, jos sovellettavissa.	true
`is_roaming`	boolean	Ilmoittaa, onko matkapuhelinnumero tällä hetkellä verkkovierailussa ulkomaisessa verkossa. Verkkovierailutilan saatavuus riippuu matkapuhelinoperaattorista.	true
`roaming_network_name`	string	Sen verkon nimi, jossa matkapuhelinnumero on tällä hetkellä verkkovierailussa, jos sovellettavissa.	true
`roaming_country_name`	string	Sen maan nimi, jossa matkapuhelinnumero on tällä hetkellä verkkovierailussa, jos sovellettavissa.	true
`roaming_country_code`	string(2)	Kaksimerkinen ISO-maakoodi maalle, jossa matkapuhelinnumero on tällä hetkellä verkkovierailussa, jos sovellettavissa.	true
`roaming_country_prefix`	string	Kansainvälinen suuntanumero (maan puhelinnumero) maalle, jossa matkapuhelinnumero on tällä hetkellä verkkovierailussa, jos sovellettavissa.	true
`cost`	string	Merkkijonona esitetty desimaaliarvo, joka ilmaisee haun hinnan euroina.	true
`timestamp`	string	W3C-muotoinen aikaleima aikavyöhykkeineen, joka määrittää haun valmistumisajankohdan.	true
`storage`	string	Sen tallennustilan nimi, johon hakutulokset tallennettiin. Tämä vastaa raporttinimiä ja CSV-latauksia, jotka ovat saatavilla verkkokäyttöliittymän kautta.	true
`route`	string(3)	Kolmimerkkinen tunniste, joka ilmaisee tälle hakulle käytetyn reititystavan.	true
`processing_status`	string	Haun käsittelyn lopputulos. Mahdolliset arvot: `COMPLETED` (onnistunut), `REJECTED` (verkko ei tavoitettavissa, veloitusta ei tehty) tai `FAILED` (virhe käsittelyn aikana).	false
`error_code`	integer	Valinnainen sisäinen virhekoodi, joka tarjoaa lisädiagnostiikkatietoja asiakastukea varten.	true
`error_description`	string	Lyhyt selitys annetusta virhekoodista (jos saatavilla) englanniksi selkokielisenä tekstinä.	true
`data_source`	string	Tälle pyynnölle käytetty tietolähde. Mahdolliset arvot: `LIVE_HLR` (reaaliaikainen HLR-kysely) tai `MNP_DB` (staattinen matkapuhelinnumeron siirrettävyyden tietokanta). Katso lisätietoja reititysvaihtoehtojen kohdalta.	false
`routing_instruction`	string	Kaksoispisteellä erotettu merkkijono, joka kuvaa pyynnössä käytettyä reititysohjeistusta. Ensimmäinen osa on `STATIC`, kun määritit reitin, tai `AUTO` automaattiselle reititykselle. Toinen osa on reitin tunniste, ja automaattisissa reitituspyynnöissä kolmas osa näyttää alkuperän, johon reititysratkaisu perustuu (eli `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

Tila	Kuvaus
CONNECTED	Numero on voimassa ja kohdelaite on tällä hetkellä yhteydessä matkapuhelinverkkoon. Puhelut, tekstiviestit ja muut palvelut tavoittavat vastaanottajan onnistuneesti.
ABSENT	Numero on voimassa, mutta kohdelaite on joko sammutettuna tai tilapäisesti verkon kuuluvuusalueen ulkopuolella. Viestit tai puhelut eivät välttämättä tavoita vastaanottajaa ennen kuin laite muodostaa yhteyden verkkoon uudelleen.
INVALID_MSISDN	Numero on virheellinen tai sitä ei ole tällä hetkellä määritetty millekään matkapuhelinverkon tilaajalle. Puhelut ja viestit tähän numeroon epäonnistuvat.
UNDETERMINED	Numeron yhteystilaa ei voitu määrittää. Tämä voi johtua virheellisestä numerosta, SS7-virhevastauksesta tai yhteyden puutteesta kohdeverkko-operaattoriin. Tarkista virhekoodin ja sen kuvauksen kenttä lisädiagnostiikkaa varten.

Vieritä ylös

POST/mnp-lookupsuojattu

Suorittaa synkronisen MNP-kyselyn ja tarjoaa tiedot numerosiirtopalvelusta sekä verkosta. Tämä päätepiste sopii tilanteisiin, joissa päätavoitteena on selvittää matkapuhelinnumeron nykyinen MCCMNC ja tunnistaa alkuperäinen sekä nykyinen verkko reaaliajassa.

Suurten tietojoukkojen massaprosessointiin, joka ei vaadi välittömiä tuloksia, suosittelemme asynkronista POST /mnp-lookups-rajapintaa, joka on optimoitu nopean eräkäsittelyn tarpeisiin.

MNP-kyselyt määrittävät luotettavasti numerosiirtopalvelun ja verkkotiedot, mutta eivät kerro, onko kohdelaite tällä hetkellä yhteydessä verkkoon ja tavoitettavissa. Reaaliaikaisten yhteystietojen selvittämiseen käytä sen sijaan POST /hlr-lookup-päätepistettä.

Pyyntö Onnistunut vastaus Virhevastaus

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

Pyyntödata

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`msisdn`	string	Kyseltävä matkapuhelinnumero (MSISDN) kansainvälisessä muodossa (esim. +14156226819 tai 0014156226819). Maakoodi on pakollinen.	null	pakollinen
`route`	string(3)	Valinnainen kolmimerkkinen tunniste, joka määrittää tämän kyselyn reitin. Aseta arvoksi `null` tai jätä parametri pois käyttääksesi mukautettua reitityskarttaasi tai antaaksesi järjestelmän määrittää automaattisesti parhaan reitin tälle kyselylle.	null	valinnainen
`storage`	string	Valinnainen tallennustunniste, joka määrittää raportin, johon tulokset tallennetaan manuaalista tarkastelua, analysointia ja raportointia varten. Järjestelmä lisää automaattisesti aikaleiman kuluvalla kuukaudella. Jos parametri jätetään pois tai asetetaan arvoon `null`, järjestelmä ryhmittelee tulokset automaattisesti kuukausittain raportointia varten.	null	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`id`	string(12)	Yksilöllinen 12-merkkinen tunniste tälle kyselylle.	false
`msisdn`	string	Tässä kyselypyynnössä tarkistettu matkapuhelinnumero.	false
`query_status`	string	Ilmoittaa, onnistuiko siirrettävyys- ja verkkotietojen haku. Mahdolliset arvot ovat `OK` tai `FAILED`.	false
`mccmnc`	string(5\|6)	Viisi- tai kuusimerkkinen MCCMNC (maakoodi ja verkkokoodi -pari), joka tunnistaa verkon, johon matkapuhelinnumero tällä hetkellä kuuluu.	true
`mcc`	string(3)	Kolmimerkkinen MCC (maakoodi), joka edustaa matkapuhelinnumeron nykyiseen verkkoon liittyvää maata.	true
`mnc`	string(2\|3)	Kaksi- tai kolmimerkkinen MNC (verkkokoodi), joka tunnistaa matkapuhelinnumeron nykyisen verkko-operaattorin.	true
`is_ported`	boolean	Ilmoittaa, onko puhelinnumero siirretty alkuperäisestä verkosta uudelle operaattorille.	true
`original_network_name`	string	Vapaamuotoinen merkkijono (englanniksi), joka määrittää tarkistetun matkapuhelinnumeron alkuperäisen verkko-operaattorin nimen.	true
`original_country_name`	string	Vapaamuotoinen merkkijono (englanniksi), joka ilmoittaa tarkistetun matkapuhelinnumeron alkuperäisen maan.	true
`original_country_code`	string(2)	Kaksimerkkinen ISO-maakoodi, joka edustaa tarkistetun matkapuhelinnumeron alkuperäistä maata.	true
`original_country_prefix`	string	Tarkistettuun matkapuhelinnumeroon liittyvän alkuperäisen maan suuntanumero.	true
`ported_network_name`	string	Määrittää verkko-operaattorin, jolle tarkistettu matkapuhelinnumero on siirretty, mikäli sovellettavissa.	true
`ported_country_name`	string	Määrittää maan, johon tarkistettu matkapuhelinnumero on siirretty, mikäli sovellettavissa.	true
`ported_country_code`	string(2)	Kaksimerkkinen ISO-maakoodi, joka edustaa maata, johon tarkistettu matkapuhelinnumero on siirretty, mikäli sovellettavissa.	true
`ported_country_prefix`	string	Maan suuntanumero, johon tarkistettu matkapuhelinnumero on siirretty, mikäli sovellettavissa.	true
`extra`	string	Vapaamuotoinen merkkijono, joka tarjoaa valinnaisia lisätietoja puhelinnumerosta.	true
`cost`	string	Desimaaliarvo merkkijonona, joka ilmoittaa tämän kyselyn kustannukset euroina.	true
`timestamp`	string	W3C-muotoinen aikaleima aikavyöhyketietoineen, joka ilmoittaa kyselyn valmistumisajankohdan.	true
`storage`	string	Tallennusnimi (tai raportin nimi), johon kyselyn tulokset liitettiin. Tätä käytetään CSV-latauksiin ja raportointiin web-käyttöliittymän kautta.	true
`route`	string(3)	Kolmimerkkinen tunniste, joka määrittää tähän kyselypyyntöön käytetyn reitin.	true
`error_code`	integer	Valinnainen sisäinen virhekoodi, joka tarjoaa lisätietoja asiakastuen diagnostiikkaa varten.	true

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

POST/mnp-lookupssuojattu

Käynnistää asynkronisten MNP-kyselyiden (numerosiirrettävyys) erän, joka hakee ajantasaisen MCCMNC-tunnisteen ja paikantaa alkuperäisen ja nykyisen verkon reaaliajassa. Tulokset toimitetaan webhookien kautta palvelimellesi. Tämä menetelmä on optimoitu suurten numeromäärien käsittelyyn, jotka eivät vaadi välittömiä vastauksia, kuten tietokantojen puhdistus ja varmennus. Reaaliaikaisiin sovelluksiin, kuten puhelujen reititys tai SMS-toimitukseen, kannattaa harkita POST /mnp-lookup-päätepisteen käyttöä.

MNP-kyselyt määrittävät luotettavasti numerosiirtopalvelun ja verkkotiedot, mutta eivät kerro, onko kohdelaite tällä hetkellä yhteydessä verkkoon ja tavoitettavissa. Reaaliaikaisten yhteystietojen selvittämiseen käytä sen sijaan POST /hlr-lookups-päätepistettä.

Ennen tämän päätepisteen käyttöä varmista, että webhook-URL on määritetty vastaanottamaan kyselytulokset asynkronisesti. Voit määrittää tämän API-asetuksissasi.

Pyyntö Onnistunut vastaus Virhevastaus Webhookit

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

Pyyntödata

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`msisdns`	array	Taulukko matkapuhelinnumeroista (MSISDN) kansainvälisessä muodossa (esim. +14156226819 tai 0014156226819). Voit sisällyttää enintään 1000 numeroa per pyyntö.	null	pakollinen
`route`	string(3)	Valinnainen kolmimerkkinen tunniste, joka määrittää tämän kyselyn reitin. Aseta arvoksi `null` tai jätä parametri pois käyttääksesi mukautettua reitityskarttaasi tai antaaksesi järjestelmämme määrittää automaattisesti parhaat reitit tälle pyynnölle.	null	valinnainen
`storage`	string	Valinnainen tallennustunniste, joka määrittää raportin, johon tulokset tallennetaan manuaalista tarkastelua, analysointia ja raportointia varten. Järjestelmä lisää automaattisesti aikaleiman kuluvalla kuukaudella. Jos parametri jätetään pois tai asetetaan arvoon `null`, järjestelmä ryhmittelee tulokset automaattisesti kuukausittain raportointia varten.	null	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`accepted`	array	Luettelo objekteista, jotka sisältävät yksilölliset tunnisteet ja MSISDN:t, jotka on hyväksytty käsiteltäväksi.	false
`accepted_count`	integer	MSISDN:ien kokonaismäärä, jotka on onnistuneesti hyväksytty käsiteltäväksi.	false
`rejected`	array	Luettelo objekteista, jotka sisältävät yksilölliset tunnisteet ja MSISDN:t, jotka on hylätty käsittelystä, tyypillisesti virheellisten numeroiden vuoksi. Hylätyistä merkinnöistä ei veloiteta.	false
`rejected_count`	integer	MSISDN:ien kokonaismäärä, jotka on hylätty validointivirheiden vuoksi.	false
`total_count`	integer	Hyväksyttyjen ja hylättyjen MSISDN:ien kokonaismäärä, jotka lähetettiin käsiteltäväksi.	false
`cost`	string	Merkkijonona esitetty desimaaliarvo, joka ilmaisee hyväksyttyjen kyselyiden kokonaiskustannukset euroina.	false
`storage`	string	Tallennustilan nimi, johon kyselytulokset lisätään, käytetään raportoinnissa ja CSV-latauksissa verkkokäyttöliittymän kautta.	false
`route`	string(3)	Kolmimerkkinen tunniste, joka määrittää tähän kyselypyyntöön käytetyn reitin.	false
`webhook_urls`	array	Webhook-URL:t, jotka on määritetty API-asetuksissasi. Tulokset lähetetään takaisin tänne.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Webhookien käsittely

Lähetyksen jälkeen alustamme aloittaa annettujen puhelinnumeroiden käsittelyn ja lähettää tulokset aiemmin määritettyyn webhook-osoitteeseen palvelimellasi. Tulokset lähetetään HTTP POST-pyyntönä, jossa pyynnön sisältönä on JSON-objekti.

Todennus

Todenna webhook tarkistamalla X-Signatures HTTP-otsake.

X-Signatures-otsake sisältää puolipisteillä erotetun listan allekirjoituksia. Jokainen listan allekirjoitus luodaan käyttäen yhtä tilillesi määritetyistä API-salaisuuksista. Vahvista webhook luomalla SHA-256-tiiviste API-avaimellasi, salaisuudellasi ja HTTP-sisällöllä - vertaa sitä sitten listan allekirjoituksiin.

Täsmäävyys vahvistaa, että pyyntö on aito ja allekirjoitettu hallitsemallasi salaisuudella.

Koodiesimerkki

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

Pyyntö on kelvollinen, jos mikä tahansa otsakeessa annetuista allekirjoituksista vastaa SHA256-tiivistettä, joka on laskettu API-avaimesi, salaisuutesi ja HTTP-sisällön yhdistetystä merkkijonosta.

Vastaanoton vahvistaminen

Palvelimesi odotetaan vastaavan HTTP-tilakoodilla 200 OK vahvistaakseen onnistuneen vastaanoton. Jos palautetaan jokin muu vastauskoodi, tapahtuu aikakatkaisu (10 sekuntia) tai ilmenee mikä tahansa muu toimitusvirhe, järjestelmä yrittää webhookin lähettämistä automaattisesti uudelleen minuutin kuluttua. Jos pyyntö epäonnistuu edelleen, uudelleenyritykset noudattavat eksponentiaalista viivästysstrategiaa, ja seuraavat yritykset tapahtuvat 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minuutin kuluttua.

Tämä uudelleenyritysmekanismi varmistaa maksimaalisen luotettavuuden hakutulosten toimittamisessa infrastruktuuriisi. Se minimoi tietojen menetyksen riskin tilapäisten verkko-ongelmien tai palvelimen käyttökatkojen vuoksi.

Webhook-sisältö

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

Webhook-kuorman attribuutit

JSON-objekti sisältää attribuutin type => MNP sekä attribuutin results, joka sisältää luettelon kyselyobjekteista, kuten alla dokumentoitu.

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`id`	string(12)	Yksilöllinen 12-merkkinen tunniste tälle kyselylle.	false
`msisdn`	string	Tässä kyselypyynnössä tarkistettu matkapuhelinnumero.	false
`query_status`	string	Ilmoittaa, onnistuiko siirrettävyys- ja verkkotietojen haku. Mahdolliset arvot ovat `OK` tai `FAILED`.	false
`mccmnc`	string(5\|6)	Viisi- tai kuusimerkkinen MCCMNC (maakoodi ja verkkokoodi -pari), joka tunnistaa verkon, johon matkapuhelinnumero tällä hetkellä kuuluu.	true
`mcc`	string(3)	Kolmimerkkinen MCC (maakoodi), joka edustaa matkapuhelinnumeron nykyiseen verkkoon liittyvää maata.	true
`mnc`	string(2\|3)	Kaksi- tai kolmimerkkinen MNC (verkkokoodi), joka tunnistaa matkapuhelinnumeron nykyisen verkko-operaattorin.	true
`is_ported`	boolean	Ilmoittaa, onko puhelinnumero siirretty alkuperäisestä verkosta uudelle operaattorille.	true
`original_network_name`	string	Vapaamuotoinen merkkijono (englanniksi), joka määrittää tarkistetun matkapuhelinnumeron alkuperäisen verkko-operaattorin nimen.	true
`original_country_name`	string	Vapaamuotoinen merkkijono (englanniksi), joka ilmoittaa tarkistetun matkapuhelinnumeron alkuperäisen maan.	true
`original_country_code`	string(2)	Kaksimerkkinen ISO-maakoodi, joka edustaa tarkistetun matkapuhelinnumeron alkuperäistä maata.	true
`original_country_prefix`	string	Tarkistettuun matkapuhelinnumeroon liittyvän alkuperäisen maan suuntanumero.	true
`ported_network_name`	string	Määrittää verkko-operaattorin, jolle tarkistettu matkapuhelinnumero on siirretty, mikäli sovellettavissa.	true
`ported_country_name`	string	Määrittää maan, johon tarkistettu matkapuhelinnumero on siirretty, mikäli sovellettavissa.	true
`ported_country_code`	string(2)	Kaksimerkkinen ISO-maakoodi, joka edustaa maata, johon tarkistettu matkapuhelinnumero on siirretty, mikäli sovellettavissa.	true
`ported_country_prefix`	string	Maan suuntanumero, johon tarkistettu matkapuhelinnumero on siirretty, mikäli sovellettavissa.	true
`extra`	string	Vapaamuotoinen merkkijono, joka tarjoaa valinnaisia lisätietoja puhelinnumerosta.	true
`cost`	string	Desimaaliarvo merkkijonona, joka ilmoittaa tämän kyselyn kustannukset euroina.	true
`timestamp`	string	W3C-muotoinen aikaleima aikavyöhyketietoineen, joka ilmoittaa kyselyn valmistumisajankohdan.	true
`storage`	string	Tallennusnimi (tai raportin nimi), johon kyselyn tulokset liitettiin. Tätä käytetään CSV-latauksiin ja raportointiin web-käyttöliittymän kautta.	true
`route`	string(3)	Kolmimerkkinen tunniste, joka määrittää tähän kyselypyyntöön käytetyn reitin.	true
`error_code`	integer	Valinnainen sisäinen virhekoodi, joka tarjoaa lisätietoja asiakastuen diagnostiikkaa varten.	true

Vieritä ylös

POST/nt-lookupsuojattu

Suorittaa synkronisen numerotyypin (NT) kyselyn. Tämä päätepiste on ihanteellinen, jos ensisijainen tavoitteesi on selvittää reaaliajassa, kuuluvatko annetut puhelinnumerot kiinteän verkon, mobiili-, maksullisten palvelujen, VoIP-, hakulaite- tai muihin numerointisuunnitelman alueisiin.

NT-kyselyt tunnistavat luotettavasti puhelinnumeron tyypin, mutta ne eivät ilmoita, onko kohdenumero tällä hetkellä yhteydessä verkkoon ja tavoitettavissa. Reaaliaikaisten yhteystietojen saamiseksi käytä POST /hlr-lookup-päätepistettä.

Jos käyttötapauksesi vaatii tarkkoja verkko- ja siirrettävyystietoja (MCCMNC) mutta ei reaaliaikaista yhteystilaa, käytä POST /mnp-lookup-päätepistettä matkapuhelinnumeron siirrettävyyskyselyihin.

Pyyntö Onnistunut vastaus Virhevastaus Tyyppireferenssi

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

Pyyntödata

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`number`	string	Puhelinnumero kansainvälisessä muodossa (esim. +4989702626 tai 004989702626).	null	mandatory
`route`	string(3)	Valinnainen kolmimerkkinen tunniste, joka määrittää tämän kyselyn reitin. Aseta arvoksi `null` tai jätä tämä parametri pois käyttääksesi mukautettua reitityskarttaasi tai antaaksesi järjestelmämme määrittää automaattisesti parhaat reitit tälle pyynnölle.	null	valinnainen
`storage`	string	Valinnainen tallennustunniste, joka määrittää raportin, johon tulokset tallennetaan manuaalista tarkastelua, analysointia ja raportointia varten. Järjestelmä lisää automaattisesti aikaleiman kuluvalla kuukaudella. Jos parametri jätetään pois tai asetetaan arvoon `null`, järjestelmä ryhmittelee tulokset automaattisesti kuukausittain raportointia varten.	null	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`id`	string(12)	Tälle hakulle määritetty yksilöllinen tunniste.	false
`number`	string	Puhelinnumero, joka arvioitiin tämän haun aikana.	false
`number_type`	string	Havaittu numerotyppi. Mahdollisia arvoja ovat: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Ilmoittaa, onnistuiko numerotyypin tietojen haku. Palauttaa arvon `OK`, jos onnistui, tai `FAILED`, jos haku epäonnistui.	false
`is_valid`	boolean	Ilmoittaa, onko puhelinnumero syntaktisesti kelvollinen.	true
`invalid_reason`	string	Englanninkielinen selkotekstiviesti, joka kertoo, miksi puhelinnumeroa pidetään virheellisenä (esim. "too short" tai "invalid prefix"), tai `null`, jos numero on kelvollinen.	true
`is_possibly_ported`	boolean	Ilmoittaa, onko puhelinnumero mahdollisesti siirretty alkuperäiseltä operaattorilta toiselle. Varman siirrettävyystiedon saamiseksi käytä MNP-hakuja.	true
`is_vanity_number`	boolean	Ilmoittaa, onko puhelinnumero vanity-numero eli sisältääkö se aakkosia.	true
`qualifies_for_hlr_lookup`	boolean	Ilmoittaa, soveltuuko puhelinnumero lisäkyselyihin HLR-hauilla.	true
`mccmnc`	string(5\|6)	Viisi- tai kuusimerkkinen merkkijono, joka edustaa MCCMNC-paria (mobiilimaatunnus ja mobiiliverkkotunnus) ja tunnistaa matkapuhelinnumeron alkuperäisen verkon.	true
`mcc`	string(3)	Kolmimerkkinen merkkijono, joka edustaa MCC:tä (mobiilimaatunnus) ja tunnistaa puhelinnumeron alkuperäiseen mobiiliverkkoon liittyvän maan.	true
`mnc`	string(2\|3)	Kaksi- tai kolmimerkkinen merkkijono, joka edustaa MNC:tä (mobiiliverkkotunnus) ja tunnistaa puhelinnumeron alkuperäisen mobiiliverkko-operaattorin.	true
`original_network_name`	string	Englanninkielinen selkotekstimerkkijono, joka ilmoittaa tarkastetun matkapuhelinnumeron alkuperäisen verkko-operaattorin nimen.	true
`original_country_name`	string	Englanninkielinen selkotekstimerkkijono, joka ilmoittaa tarkastettuun matkapuhelinnumeroon liittyvän alkuperäisen maan.	true
`original_country_code`	string(2)	Kaksimerkkinen ISO-maatunnus, joka ilmoittaa tarkastetun matkapuhelinnumeron alkuperäisen maan.	true
`regions`	array	Luettelo englanninkielisistä, ihmisluettavista merkkijonoista, jotka ilmoittavat tähän puhelinnumeroon liittyvät maantieteelliset alueet.	true
`timezones`	array	Luettelo aikavyöhykkeistä (Olson-muodossa), jotka liittyvät tähän puhelinnumeroon.	true
`info_text`	string	Vapaamuotoinen merkkijono, joka voi sisältää lisätietoja puhelinnumerosta.	true
`cost`	string	Merkkijonona esitetty desimaaliarvo, joka ilmoittaa tämän haun kustannuksen (euroina).	true
`timestamp`	string	W3C-muotoinen aikaleima (aikavyöhyke mukaan lukien), joka ilmoittaa, milloin haku valmistui.	true
`storage`	string	Määrittää tallennuspaikan nimen, johon hakutulokset on lisätty. Tämä vastaa raportin nimeä, jota käytetään CSV-latauksissa ja analytiikassa verkkokäyttöliittymän kautta.	true
`route`	string(3)	Kolmimerkkinen tunniste, joka määrittää tähän kyselypyyntöön käytetyn reitin.	true

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Tyyppi	Kuvaus
LANDLINE	Kiinteän verkon puhelinnumero.
MOBILE	Matkapuhelinnumero. Soveltuu HLR-kyselyihin yhteyden tilan, verkon, siirrettävyyden ja verkkovierailutietojen hakemiseen.
MOBILE_OR_LANDLINE	Kiinteän verkon tai matkapuhelinnumero. Saattaa soveltua HLR-kyselyyn.
TOLL_FREE	Maksuton palvelunumero.
PREMIUM_RATE	Maksullinen palvelunumero lisämaksuilla.
SHARED_COST	Jaetun kustannuksen palvelunumero. Tyypillisesti edullisempi kuin maksullinen palvelunumero.
VOIP	Voice over IP -puhelinnumero. Sisältää TSoIP-puhelinnumerot (Telephony Service over IP).
PAGER	Hakulaitteen numero. Tyypillisesti ei äänipuhelutoimintoa.
UAN	Yleinen palvelunumero (yrityksen numero). Voidaan reitittää tiettyihin toimipisteisiin, mutta mahdollistaa yhden numeron käytön koko yritykselle.
VOICEMAIL	Vastaajan numero.
UNKNOWN	Numerotyyppiä ei voitu määrittää.

Vieritä ylös

POST/nt-lookups suojattu

Tämä päätepiste suorittaa sarjan asynkronisia numerotyyppihakuja, joiden tulokset lähetetään takaisin palvelimellesi webhookin kautta. Se soveltuu tilanteisiin, joissa ensisijainen tavoitteesi on selvittää, kuuluvatko annetut puhelinnumerot kiinteän verkon, matkapuhelin-, maksullisten palveluiden, VoIP-, hakulaite- tai muihin numerointisuunnitelman alueisiin. Suurten numeromäärien nopeaan käsittelyyn optimoitu päätepiste on ihanteellinen massatoimintoihin (esim. tietokannan puhdistus). Reaaliaikaiseen liikenteeseen ja aikakriittisiin käyttötapauksiin suosittelemme käyttämään POST /nt-lookup-päätepistettä.

Sinun tulee määrittää webhook-URL API-asetuksissa edellytyksenä tämän päätepisteen käyttämiselle.

Pyyntö Onnistunut vastaus Virhevastaus Webhookit Tyyppireferenssi

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

Pyyntödata

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`numbers`	array	Taulukko puhelinnumeroista kansainvälisessä muodossa (esim. +14156226819 tai 004989702626). Yhdessä pyynnössä voidaan sisällyttää enintään 1000 numeroa.	null	pakollinen
`route`	string(3)	Valinnainen kolmimerkkinen tunniste, joka määrittää tämän haun reitin. Aseta arvoksi `null` tai jätä tämä parametri pois käyttääksesi mukautettua reitityskarttaasi tai antaaksesi järjestelmämme määrittää automaattisesti parhaan reitin tälle pyynnölle.	null	valinnainen
`storage`	string	Valinnainen tallennustunniste, joka määrittää raportin, johon tulokset tallennetaan manuaalista tarkastelua, analysointia ja raportointia varten. Järjestelmä lisää automaattisesti aikaleiman kuluvalla kuukaudella. Jos parametri jätetään pois tai asetetaan arvoon `null`, järjestelmä ryhmittelee tulokset automaattisesti kuukausittain raportointia varten.	null	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`accepted`	array	Taulukko objekteja, joista jokainen sisältää yksilöllisen tunnisteen ja puhelinnumeron, joka on hyväksytty käsittelyyn.	false
`accepted_count`	integer	Käsittelyyn hyväksyttyjen puhelinnumeroiden kokonaismäärä.	false
`rejected`	array	Taulukko objekteja, joista jokainen sisältää yksilöllisen tunnisteen ja puhelinnumeron, joka hylättiin käsittelystä. Tyypillisesti nämä numerot ovat virheellisiä, eikä niistä veloiteta.	false
`rejected_count`	integer	Käsittelystä hylättyjen puhelinnumeroiden kokonaismäärä.	false
`total_count`	integer	Käsittelyyn lähetettyjen hyväksyttyjen ja hylättyjen puhelinnumeroiden kokonaismäärä.	false
`cost`	string	Merkkijono, joka edustaa desimaalilukua ja ilmaisee näiden hakujen kustannukset euroina.	false
`storage`	string	Tallennustilan (raportin) nimi, johon hakutulokset on lisätty. Tätä nimeä käytetään CSV-latauksiin ja analytiikkaan verkkokäyttöliittymässä.	false
`route`	string(3)	Kolmimerkkinen tunniste, joka määrittää tässä hakupyynnössä käytetyn reitin.	false
`webhook_urls`	array	Webhook-URL:t, jotka on määritetty API-asetuksissasi. Tulokset lähetetään takaisin tänne.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Webhookien käsittely

Lähetyksen jälkeen alustamme aloittaa annettujen puhelinnumeroiden käsittelyn ja lähettää tulokset aiemmin määritettyyn webhook-osoitteeseen palvelimellasi. Tulokset lähetetään HTTP POST-pyyntönä, jossa pyynnön sisältönä on JSON-objekti.

Todennus

Todenna webhook tarkistamalla X-Signatures HTTP-otsake.

X-Signatures-otsake sisältää puolipisteillä erotetun listan allekirjoituksia. Jokainen listan allekirjoitus luodaan käyttäen yhtä tilillesi määritetyistä API-salaisuuksista. Vahvista webhook luomalla SHA-256-tiiviste API-avaimellasi, salaisuudellasi ja HTTP-sisällöllä - vertaa sitä sitten listan allekirjoituksiin.

Täsmäävyys vahvistaa, että pyyntö on aito ja allekirjoitettu hallitsemallasi salaisuudella.

Koodiesimerkki

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

Pyyntö on kelvollinen, jos mikä tahansa otsakeessa annetuista allekirjoituksista vastaa SHA256-tiivistettä, joka on laskettu API-avaimesi, salaisuutesi ja HTTP-sisällön yhdistetystä merkkijonosta.

Vastaanoton vahvistaminen

Palvelimesi odotetaan vastaavan HTTP-tilakoodilla 200 OK vahvistaakseen onnistuneen vastaanoton. Jos palautetaan jokin muu vastauskoodi, tapahtuu aikakatkaisu (10 sekuntia) tai ilmenee mikä tahansa muu toimitusvirhe, järjestelmä yrittää webhookin lähettämistä automaattisesti uudelleen minuutin kuluttua. Jos pyyntö epäonnistuu edelleen, uudelleenyritykset noudattavat eksponentiaalista viivästysstrategiaa, ja seuraavat yritykset tapahtuvat 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minuutin kuluttua.

Tämä uudelleenyritysmekanismi varmistaa maksimaalisen luotettavuuden hakutulosten toimittamisessa infrastruktuuriisi. Se minimoi tietojen menetyksen riskin tilapäisten verkko-ongelmien tai palvelimen käyttökatkojen vuoksi.

Webhook-sisältö

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

Webhook-kuorman attribuutit

JSON-objekti sisältää attribuutin type => NT sekä attribuutin results, joka sisältää luettelon kyselyobjekteista, kuten alla dokumentoitu.

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`id`	string(12)	Tälle hakulle määritetty yksilöllinen tunniste.	false
`number`	string	Puhelinnumero, joka arvioitiin tämän haun aikana.	false
`number_type`	string	Havaittu numerotyppi. Mahdollisia arvoja ovat: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Ilmoittaa, onnistuiko numerotyypin tietojen haku. Palauttaa arvon `OK`, jos onnistui, tai `FAILED`, jos haku epäonnistui.	false
`is_valid`	boolean	Ilmoittaa, onko puhelinnumero syntaktisesti kelvollinen.	true
`invalid_reason`	string	Englanninkielinen selkotekstiviesti, joka kertoo, miksi puhelinnumeroa pidetään virheellisenä (esim. "too short" tai "invalid prefix"), tai `null`, jos numero on kelvollinen.	true
`is_possibly_ported`	boolean	Ilmoittaa, onko puhelinnumero mahdollisesti siirretty alkuperäiseltä operaattorilta toiselle. Varman siirrettävyystiedon saamiseksi käytä MNP-hakuja.	true
`is_vanity_number`	boolean	Ilmoittaa, onko puhelinnumero vanity-numero eli sisältääkö se aakkosia.	true
`qualifies_for_hlr_lookup`	boolean	Ilmoittaa, soveltuuko puhelinnumero lisäkyselyihin HLR-hauilla.	true
`mccmnc`	string(5\|6)	Viisi- tai kuusimerkkinen merkkijono, joka edustaa MCCMNC-paria (mobiilimaatunnus ja mobiiliverkkotunnus) ja tunnistaa matkapuhelinnumeron alkuperäisen verkon.	true
`mcc`	string(3)	Kolmimerkkinen merkkijono, joka edustaa MCC:tä (mobiilimaatunnus) ja tunnistaa puhelinnumeron alkuperäiseen mobiiliverkkoon liittyvän maan.	true
`mnc`	string(2\|3)	Kaksi- tai kolmimerkkinen merkkijono, joka edustaa MNC:tä (mobiiliverkkotunnus) ja tunnistaa puhelinnumeron alkuperäisen mobiiliverkko-operaattorin.	true
`original_network_name`	string	Englanninkielinen selkotekstimerkkijono, joka ilmoittaa tarkastetun matkapuhelinnumeron alkuperäisen verkko-operaattorin nimen.	true
`original_country_name`	string	Englanninkielinen selkotekstimerkkijono, joka ilmoittaa tarkastettuun matkapuhelinnumeroon liittyvän alkuperäisen maan.	true
`original_country_code`	string(2)	Kaksimerkkinen ISO-maatunnus, joka ilmoittaa tarkastetun matkapuhelinnumeron alkuperäisen maan.	true
`regions`	array	Luettelo englanninkielisistä, ihmisluettavista merkkijonoista, jotka ilmoittavat tähän puhelinnumeroon liittyvät maantieteelliset alueet.	true
`timezones`	array	Luettelo aikavyöhykkeistä (Olson-muodossa), jotka liittyvät tähän puhelinnumeroon.	true
`info_text`	string	Vapaamuotoinen merkkijono, joka voi sisältää lisätietoja puhelinnumerosta.	true
`cost`	string	Merkkijonona esitetty desimaaliarvo, joka ilmoittaa tämän haun kustannuksen (euroina).	true
`timestamp`	string	W3C-muotoinen aikaleima (aikavyöhyke mukaan lukien), joka ilmoittaa, milloin haku valmistui.	true
`storage`	string	Määrittää tallennuspaikan nimen, johon hakutulokset on lisätty. Tämä vastaa raportin nimeä, jota käytetään CSV-latauksissa ja analytiikassa verkkokäyttöliittymän kautta.	true
`route`	string(3)	Kolmimerkkinen tunniste, joka määrittää tähän kyselypyyntöön käytetyn reitin.	true

Tyyppi	Kuvaus
LANDLINE	Kiinteän verkon puhelinnumero.
MOBILE	Matkapuhelinnumero. Soveltuu HLR-kyselyihin yhteyden tilan, verkon, siirrettävyyden ja verkkovierailutietojen hakemiseen.
MOBILE_OR_LANDLINE	Kiinteän verkon tai matkapuhelinnumero. Saattaa soveltua HLR-kyselyyn.
TOLL_FREE	Maksuton palvelunumero.
PREMIUM_RATE	Maksullinen palvelunumero lisämaksuilla.
SHARED_COST	Jaetun kustannuksen palvelunumero. Tyypillisesti edullisempi kuin maksullinen palvelunumero.
VOIP	Voice over IP -puhelinnumero. Sisältää TSoIP-puhelinnumerot (Telephony Service over IP).
PAGER	Hakulaitteen numero. Tyypillisesti ei äänipuhelutoimintoa.
UAN	Yleinen palvelunumero (yrityksen numero). Voidaan reitittää tiettyihin toimipisteisiin, mutta mahdollistaa yhden numeron käytön koko yritykselle.
VOICEMAIL	Vastaajan numero.
UNKNOWN	Numerotyyppiä ei voitu määrittää.

Vieritä ylös

GET/routesuojattu

Hakee reitin, joka valitaan automaattisesti, kun suoritat HLR-haun määrittämättä route-parametria.

Automaattinen reitinvalinta perustuu reitityskarttaan, joka on haettavissa GET /hlr-coverage-päätepisteestä ja joka pohjautuu ensisijaisesti GET /routing-map-tietoihin. Voit mukauttaa reitityskarttaasi ja määrittää mukautettuja sääntöjä tiliasetuksissa.

Pyyntö Onnistunut vastaus Virhevastaus

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`msisdn`	string	MSISDN, jolle automaattisesti valitut reititystiedot haetaan.	null	pakollinen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`route`	string	Suositeltu reitti.	false
`confidence_level`	string	Luottamustaso, jolla tämä reitti valittiin, eli `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	Numerointisuunnitelmaan perustuva MCCMNC tälle numerolle.	false
`origin`	string	Lähde, johon reititysvalinta perustuu, eli `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."
    ]
}

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/routessuojattu

Tämä päätepiste palauttaa listan saatavilla olevista HLR-, MNP- ja NT-reiteistä. Jokainen reitti ominaisuuksineen ja rajoituksineen on selitetty reititysten tiedot -sivulla.

Pyyntö Onnistunut vastaus Virhevastaus

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

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`routes`	object	Objekti, jossa reitit on ryhmitelty reittityypin mukaan.	false
`HLR\|MNP\|NT`	string[]	Sisältää listan reittitunnisteista.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/routing-mapsuojattu

Hakee tilillesi tällä hetkellä sovelletun automaattisen reitityksen konfiguraation HLR-hauille. Tätä oletuskonfiguraatiota käytetään aina, kun lähetät HLR-hakuja määrittämättä route-parametria. Voit mukauttaa reitityskarttaasi ja luoda mukautettuja sääntöjä tiliasetuksissasi.

Konfiguraatiohierarkia etenee maatason säännöistä MCCMNC-tason sääntöihin ja lopulta yksittäisiin puhelinnumeroprefiksien määrityksiin. Käytännössä tämä tarkoittaa, että yksittäiset puhelinnumeroprefiksien määritykset ohittavat ristiriitaiset MCCMNC-määritykset, jotka puolestaan ohittavat maatason säännöt. Huomioithan, että MNP-varajärjestelmä ohittaa kaikki ristiriitaiset mukautetut säännöt ollessaan käytössä.

Pyyntö Onnistunut vastaus Virhevastaus

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`default_route`	string	Oletusreitti, jota käytetään, kun MSISDN-numerolle ei voida määrittää ensisijaista reititysasetusta eikä mukautettuja reitityssääntöjä ole.	false
`mnp_fallback`	boolean	Ilmaisee, onko MNP-varajärjestelmä käytössä. Kun se on käytössä ja verkko ei tue HLR-kyselyitä (yhteyden tila ei saatavilla), järjestelmä suorittaa sen sijaan MNP-haun.	false
`mccmncs`	array	MCCMNC-koodien ja niiden automaattisesti valittujen reittien välinen määritys. Kun suoritetaan HLR-haku tietyn MCCMNC:n numerolle, käytetään vastaavaa reittiä.	false
`mccmnc`	string(5\|6)	Viisi- tai kuusimerkkinen MCCMNC (matkapuhelinmaakoodin ja matkapuhelinverkkokoodin yhdistelmä), joka yksilöi matkapuhelinoperaattorin.	false
`countrycode`	string(2)	Kaksimerkkinen ISO-maakoodi, joka tunnistaa verkon maan.	false
`route`	string(3)	Verkolle valittu reitti.	false
`mno`	string	Kuluttajille näkyvä brändi, jonka alla tämä verkko toimii.	false
`confidence`	string	Valinnan luotettavuustaso. Mahdolliset arvot ovat: HIGH, NORMAL, LOW, MNP_REDIRECT. Viimeksi mainitussa tapauksessa järjestelmä ohjaa tämän verkon liikenteen MNP:lle, jos tämä toiminto on käytössä tililläsi. Muussa tapauksessa se käyttää tilin oletusreittiä.	false
`origin`	string	Lähde, johon valinta perustuu. Mahdolliset arvot ovat: `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	Luettelo tilillesi määritetyistä mukautetuista prefiksiin perustuvista reitityssäännöistä, jos niitä on.	false
`countrycode`	string(2)	Kaksimerkkinen ISO-maakoodi, joka tunnistaa prefiksin maan.	false
`cns`	string	Prefiksi, johon reitityssääntö koskee.	false
`route`	string(3)	Prefiksille valittu reitti.	false
`mccmnc`	string(5\|6)	Viisi- tai kuusimerkkinen MCCMNC (matkapuhelinmaakoodin ja matkapuhelinverkkokoodin yhdistelmä), joka yksilöi matkapuhelinoperaattorin.	true
`mno`	string	Kuluttajille näkyvä brändi, jonka alla tämä verkko toimii.	true
`countries`	array	Luettelo tilillesi määritetyistä mukautetuista maaperusteisista säännöistä, jos niitä on.	false
`countrycode`	string(2)	Kaksimerkkinen ISO-maakoodi, joka tunnistaa maan.	false
`route`	string(3)	Maalle valittu reitti.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/hlr-coverage suojattu

Palauttaa HLR-kattavuustietoja tukemaan tietopohjaiseen päätöksentekoon. Tämä päätetoiminto auttaa analysoimaan reaaliaikaisia HLR-reititysvaihtoehtojen mobiiliverkkojen välillä, tunnistamaan tehokkaimmat reitit kohdealueillesi ja konfiguroimaan automaattisen reitityksesi.

Suositellut reitit GET /route-päätteestä perustuvat tässä haettuihin kattavuustietoihin. Kattavuustiedot ovat saatavilla myös verkon kattavuus -sivulla. Voit edelleen mukauttaa reitityskarttaasi ja määrittää säännöt tiliasetuksissasi.

Suosittelemme tutustumaan tähän oppaaseen, joka auttaa tulosten tulkinnassa.

Pyyntö Onnistunut vastaus Virhevastaus Tilaviite

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`countrycode`	string(2)	Pakollinen kaksikirjaiminen ISO-maakoodi, jota käytetään tulosten suodattamiseen ja palauttamaan vain määritettyyn maahan liittyvät tietueet.	null	pakollinen
`sample_size`	string	Valinnainen parametri, joka määrittää otoskoon. Mahdolliset arvot ovat `LARGE`, `MEDIUM`, `SMALL`. Suuremmat otokset kattavat pidemmän aikavälin, pienemmät otokset kattavat hyvin lähiaikaisen aikavälin.	LARGE	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`name`	string	Valitun maan nimi englanniksi.	false
`countrycode`	string(2)	Valitun maan kaksikirjaiminen ISO-maakoodi.	false
`prefix`	string	Valitun maan kansainvälinen suuntanumero.	false
`mccs`	string[]	Luettelo valittuun maahan liittyvistä MCC-koodeista (mobiilimaakoodit).	false
`carriers`	object[]	Luettelo operaattoriobjekteista, jotka sisältävät reittikohtaiset yhteystiedot.	false
`mno`	string	Matkaviestinoperaattorin nimi englanniksi.	false
`mccmnc`	string	Matkaviestinoperaattorin MCCMNC.	false
`mcc`	string	Matkaviestinoperaattorin MCC (mobiilimaakoodi).	false
`mnc`	string	Matkaviestinoperaattorin MNC (mobiiliverkkokoodi).	false
`routes`	object[]	Luettelo reittikohtaisista yhteystuloksista.	false
`route`	string	Reitti, johon yhteystiedot liittyvät.	false
`selected`	bool	Ilmaisee, onko tämä automaattiseen reitityksen valittu reitti.	false
`selection_confidence`	string	Luottamustaso, jolla tämä reitti valittiin, eli `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Sisältää null-arvon, jos tämä ei ole valittu reitti.	true
`n`	int	Hakujen kokonaismäärä tässä otoksessa.	false
`CONNECTED`	int	HLR-hakujen määrä, jotka palauttivat CONNECTED-tilan.	false
`CONNECTED_PCT`	float	HLR-hakujen prosenttiosuus, jotka palauttivat CONNECTED-tilan.	false
`ABSENT`	int	HLR-hakujen määrä, jotka palauttivat ABSENT-tilan.	false
`ABSENT_PCT`	float	HLR-hakujen prosenttiosuus, jotka palauttivat ABSENT-tilan.	false
`INVALID_MSISDN`	int	HLR-hakujen määrä, jotka palauttivat INVALID_MSISDN-tilan.	false
`INVALID_MSISDN_PCT`	float	HLR-hakujen prosenttiosuus, jotka palauttivat INVALID_MSISDN-tilan.	false
`UNDETERMINED`	int	HLR-hakujen määrä, jotka palauttivat UNDETERMINED-tilan.	false
`UNDETERMINED_PCT`	float	HLR-hakujen prosenttiosuus, jotka palauttivat UNDETERMINED-tilan.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Tila	Kuvaus
CONNECTED	Numero on voimassa ja kohdelaite on tällä hetkellä yhteydessä matkapuhelinverkkoon. Puhelut, tekstiviestit ja muut palvelut tavoittavat vastaanottajan onnistuneesti.
ABSENT	Numero on voimassa, mutta kohdelaite on joko sammutettuna tai tilapäisesti verkon kuuluvuusalueen ulkopuolella. Viestit tai puhelut eivät välttämättä tavoita vastaanottajaa ennen kuin laite muodostaa yhteyden verkkoon uudelleen.
INVALID_MSISDN	Numero on virheellinen tai sitä ei ole tällä hetkellä määritetty millekään matkapuhelinverkon tilaajalle. Puhelut ja viestit tähän numeroon epäonnistuvat.
UNDETERMINED	Numeron yhteystilaa ei voitu määrittää. Tämä voi johtua virheellisestä numerosta, SS7-virhevastauksesta tai yhteyden puutteesta kohdeverkko-operaattoriin. Tarkista virhekoodin ja sen kuvauksen kenttä lisädiagnostiikkaa varten.

Vieritä ylös

GET/mnp-coveragesuojattu

Tämä päätepiste palauttaa luettelon matkapuhelinoperaattoreista sekä niiden MCCMNC-tunnisteista, jotka ovat tällä hetkellä tuettuja numeronsiirrettävyyshauissa.

Pyyntö Onnistunut vastaus Virhevastaus

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`countrycode`	string(2)	Valinnainen kaksikirjaiminen ISO-maakoodi, jota käytetään MCCMNC-tulosten suodattamiseen ja joka palauttaa vain määritettyä maata koskevat tiedot.	null	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`items[]`	array	Luettelo matkaviestinoperaattoreista.	false
`country_name`	string	Maan nimi englanniksi.	false
`country_code`	string(2)	Kaksikirjaiminen ISO-maakoodi.	false
`mccmnc`	string(5\|6)	Viisi- tai kuusimerkkinen MCCMNC (matkapuhelinmaakoodin ja matkapuhelinverkkokoodin yhdistelmä), joka yksilöi matkapuhelinoperaattorin.	false
`mcc`	string(3)	Kolmimerkkinen MCC (matkapuhelinmaakoodi), joka edustaa verkon maata.	false
`mnc`	string(2\|3)	Kaksi- tai kolmimerkkinen MNC (matkapuhelinverkkokoodi), joka edustaa tiettyä matkapuhelinoperaattoria.	false
`brand`	string	Kuluttajille näkyvä brändi, jonka alla tämä verkko toimii.	true
`operator`	string	Matkapuhelinoperaattorin virallinen nimi.	true

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/price-listsuojattu

Tämä päätepiste palauttaa luettelon maista, joissa vain MNP-kyselyt ovat tuettuja ja HLR-kyselyt eivät ole saatavilla näihin kohteisiin.

Pyyntö Onnistunut vastaus Virhevastaus

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

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`countries`	string[]	Luettelo kaksimerkkisistä ISO-maakodeista.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/mccmncssuojattu

Tämä päätepiste palauttaa kattavan luettelon matkaviestinoperaattoreista sekä niiden vastaavat MCCMNC-tunnisteet ja muut kontekstuaaliset tiedot.

Pyyntö Onnistunut vastaus Virhevastaus

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`countrycode`	string(2)	Valinnainen kaksikirjaiminen ISO-maakoodi, jolla MCCMNC-tulokset suodatetaan palauttaen vain määritettyyn maahan liittyvät tietueet.	null	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`items`	object[]	Luettelo matkaviestinoperaattoreista.	false
`country_name`	string	Maan koko nimi englanniksi.	false
`country_code`	string(2)	Kaksikirjaiminen ISO-maakoodi, joka edustaa matkaviestinoperaattorin maata.	false
`mccmnc`	string(5\|6)	Viisi- tai kuusimerkkinen merkkijono, joka edustaa MCCMNC-tunnistetta ja yksilöi matkaviestinoperaattorin.	false
`mcc`	string(3)	Kolmimerkkinen maakoodi (MCC), joka tunnistaa maan, jossa matkaviestinverkko toimii.	false
`mnc`	string(2\|3)	Kaksi- tai kolmimerkkinen verkkokoodi (MNC), joka määrittää matkaviestinverkon annetun MCC:n sisällä.	false
`brand`	string	Kaupallinen tuotenimi, jolla verkko toimii ja jonka kuluttajat tunnistavat.	true
`operator`	string	Matkaviestinoperaattorin virallinen nimi, tyypillisesti verkkoa hallinnoiva oikeushenkilö.	true
`parent_mccmnc`	string(5\|6)	Viisi- tai kuusimerkkinen merkkijono, joka edustaa emoyhtiön MCCMNC-tunnistetta, mikäli sellainen on.	true

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/pricesuojattu

Tämä päätepiste palauttaa hinnan HLR-, MNP- tai NT-kyselylle.

Pyyntö Onnistunut vastaus Virhevastaus

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

Pyyntöparametrit

Avain	Tyyppi	Kuvaus	Oletus	Pakollinen
`msisdn`	string	Puhelinnumero, jolle hinta haetaan. Kansainvälisessä muodossa.	null	pakollinen
`route_type`	string	Reitityyppi, eli `HLR`, `MNP`, `NT`.	null	pakollinen
`route`	string(3)	Reitti, jolle hinta lasketaan. Oletusarvoisesti automaattisen reitityksen määrittämä reitti.	null	valinnainen

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`price`	object	Hintatiedot sisältävä objekti.	false
`amount`	string	Summa euroina.	false
`msisdn`	string	MSISDN, johon tämä hinta kohdistuu.	false
`route_type`	string(2\|3)	Reitityyppi, johon tämä hinta kohdistuu.	false
`route`	string(3)	Reitti, johon tämä hinta kohdistuu.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/price-listsuojattu

Tämä päätepiste palauttaa tilisi hinnoittelun.

Pyyntö Onnistunut vastaus Virhevastaus

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

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`pricing`	object[]	Lista objekteista, jotka sisältävät hinnoittelutiedot.	false
`route`	string	Reitti, johon tämä hinnoittelu kohdistuu.	false
`countrycode`	string	Kaksikirjaiminen ISO-maakoodi, johon tämä hinnoittelu kohdistuu vastaavalla reitillä, mikäli määritelty.	true
`countryname`	string	Maakoodia vastaava englanninkielinen maan nimi, mikäli määritelty.	true
`mccmnc`	string	MCCMNC, johon tämä hinnoittelu kohdistuu vastaavalla reitillä, mikäli määritelty. Ohittaa maatason hinnoittelun.	true
`cns`	string	Suuntanumero, johon tämä hinnoittelu kohdistuu vastaavalla reitillä, mikäli määritelty. Ohittaa maatason hinnoittelun ja MCCMNC-tason hinnoittelun.	true
`route_type`	string	Vastaava reitityyppi, eli `HLR`, `MNP`, `NT`.	false
`route_type`	string	Vastaava hinta euroina.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/balancesuojattu

Tämä päätepiste hakee nykyisen tilisi saldon, jolloin voit automatisoida prosesseja luottotilanteesi perusteella. Se toimii saumattomasti alhaisen saldon ilmoitussähköpostien kanssa, jotka voit määrittää maksusivullasi.

Pyyntö Onnistunut vastaus Virhevastaus

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

{
    "balance":"1002.90"
}

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`balance`	string	Nykyinen tilisi saldo euroissa. Desimaaliarvo merkkijonomuodossa.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/pingjulkinen

Tämä päätepiste lähettää ping-pyynnön API:lle tarjoten yksinkertaisen tavan testata yhteyttäsi HLR Lookups API:in.

Pyyntö Onnistunut vastaus Virhevastaus

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

{
    "success":true
}

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`success`	boolean	Osoittaa, että pyyntö käsiteltiin onnistuneesti.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/timejulkinen

Tämä päätepiste palauttaa Unix-aikaleiman, joka edustaa HLR Lookups -palvelimen nykyistä aikaa. Käytä sitä palvelimesi kellon synkronointiin luodessasi Digest-Auth-allekirjoitusta todennusta varten, jotta mahdolliset erot palvelimesi ajan ja HLR Lookups -palvelimen ajan välillä korjataan.

Pyyntö Onnistunut vastaus Virhevastaus

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

{
    "time":1525898643
}

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`time`	integer	Unix-aikaleima, joka edustaa HLR Lookups -palvelimen nykyistä aikaa.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

GET/auth-testsuojattu

Tämä päätepiste toimii alkutestinä Basic-Auth- tai mieluiten Digest-Auth-toteutuksellesi.

Basic Auth -pyyntö Digest Auth -pyyntö Onnistunut vastaus Virhevastaus

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

Pyynnön otsakkeet

Avain	Tyyppi	Kuvaus
`X-Basic`	string	`YOUR_API_KEY:YOUR_API_SECRET`-merkkijonon SHA256-tiiviste. Sisällytä kaksoispistemerkki (:) tiivisteeseen.

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"

Pyynnön otsakkeet

Avain	Tyyppi	Kuvaus
`X-Digest-Key`	string	HLR Lookups API-avaimesi
`X-Digest-Signature`	string	Yksilöllinen Digest-Auth-allekirjoitus (katso autentikointi)
`X-Digest-Timestamp`	integer	Nykyinen Unix-aikaleima (katso myös `GET /time`)

{
    "success":true
}

Onnistuneen vastauksen attribuutit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`success`	boolean	Osoittaa, että pyyntö käsiteltiin onnistuneesti.	false

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

Virhevastauksen parametrit

Nimi	Tyyppi	Kuvaus	Tyhjäarvoinen
`errors[]`	string[]	Lista merkkijonoista, jotka selittävät virheen.	false

Vieritä ylös

Vanhan API:n dokumentaatio

Huomioithan, että vanha API on vanhentunut ja poistetaan käytöstä tulevaisuudessa. Suosittelemme vahvasti päivittämään uusimpaan versioon mahdollisimman pian.

Jos olet ottanut HLR Lookups API:n käyttöön vuosien 2013 ja 2020 välillä, käytät vanhaa API:a. Tutustu tässä tapauksessa vanhan API:n dokumentaatioon.

Vanhan API:n dokumentaatio

API-dokumentaatio

Aloitus

HLR-kyselyt

MNP-kyselyt

NT-kyselyt

Reititys

Hinnoittelu

Työkalut

Aloitus

HLR Lookups API:n käyttö

Esimerkkipyyntö

Esimerkkisisältö

Onnistunut vastaus application/json

Lisähakupalvelut

Numeronsiirtopalvelun (MNP) haut

Numerotyypin tunnistus (NT) -haut

Ohjelmistokehityspaketit (SDK)

Työkalut

Etkö ole kehittäjä?

Todennus

API-avain ja API-salaisuus

HTTP Basic Auth

Suositeltu: X-Basic-otsake SHA256:lla

Basic Auth -pyyntö

Basic-todennuksen otsakkeet

Koodiesimerkki

Pyyntöesimerkki

Pyynnön otsakkeet

Allekirjoituksen muodostaminen

Digest-allekirjoituksen komponentit

Koodiesimerkit

Käsitteet

Synkroninen HLR-kysely API

Asynkroninen HLR-kyselyrajapinta

SDK:t (ohjelmistokehityspakkaukset)

PHP SDK

NodeJS SDK

Ruby SDK

POST/hlr-lookupsuojattu

Pyyntödata

Pyyntöparametrit

Onnistuneen vastauksen attribuutit

Virhevastauksen parametrit

POST/hlr-lookupssuojattu

Pyyntödata

Pyyntöparametrit

Onnistuneen vastauksen attribuutit

Virhevastauksen parametrit

Webhookien käsittely

Todennus

Koodiesimerkki

Vastaanoton vahvistaminen

Webhook-sisältö

Webhook-kuorman attribuutit

POST/mnp-lookupsuojattu

Pyyntödata

Pyyntöparametrit

Onnistuneen vastauksen attribuutit

Virhevastauksen parametrit

POST/mnp-lookupssuojattu

Pyyntödata

Pyyntöparametrit

Onnistuneen vastauksen attribuutit

Virhevastauksen parametrit

Webhookien käsittely

Todennus

Koodiesimerkki

Vastaanoton vahvistaminen

Webhook-sisältö

Webhook-kuorman attribuutit

POST/nt-lookupsuojattu

Pyyntödata

Pyyntöparametrit

Onnistuneen vastauksen attribuutit

Virhevastauksen parametrit

POST/nt-lookups suojattu

Pyyntödata

Pyyntöparametrit

Onnistuneen vastauksen attribuutit

Virhevastauksen parametrit