Pasirinkite atskirą prefiksą
Naudokite šalių ir aprėpties sričių paieškos užklausas, tada iškvieskite getprefixes be grupavimo. Nukopijuokite pasirinkto prefikso uuid. Jei returns_numbers yra 0, numeris pagal šį prefiksą priskiriamas užsakymo metu; naudokite grąžintą next_function ir nereikalaukite atskirų numerių sąrašo.
Peržiūrėkite riboto dydžio rezultatų rinkinį
Įprastai paieškai naudokite compact=1 ir norimą rinkinio dydį nurodykite tiek kelyje, tiek užklausos parametre quantity, kaip parodyta toliau. Puslapio ar žymeklio parametro nėra. Kompaktiškas rezultatas yra imtis; pakartojus užklausą negarantuojama, kad bus grąžintas kitas puslapis be pasikartojančių įrašų. Tuščio ar mažo rezultato nelaikykite bendru turimų numerių skaičiumi.
Raskite lengvai įsimenamą skaitmenų derinį
Nurodykite number_filter_mode=contains arba ends_with kartu su number_filter_value. Reikšmę turi sudaryti 1–15 skaitmenų. Prieš pritaikydama filtrą paieška gali gauti riboto dydžio kandidatų rinkinius, todėl gali neaptikti kitų sąlygą atitinkančių turimų numerių. Jei būtina, kad reikiamą paiešką atliktų ją palaikantis šaltinis, gaukite pid parinkiklį iš MultiTEL ir naudokite filter_required=1; nepasirinkus šaltinio arba pasirinkus nepalaikomą šaltinį, grąžinama API klaida.
Peržiūrėkite pasirinktą numerį
Tame pačiame rezultate perskaitykite number, info.uuid, pasirinkto plano price[].uuid, galimų funkcijų pavadinimus ir registracijos reikalavimus. Masyve price gali būti siūlomi keli planai su skirtingu kanalų skaičiumi ir tarifais. Piniginės reikšmės ir kiekiai gali būti užkoduoti kaip eilutės. Neprivalomi metaduomenys, įskaitant info.state, skiriasi priklausomai nuo šaltinio; nereikalaukite vienos universalios būsenos duomenų struktūros ir nespręskite apie kainas iš identifikatoriaus.
Kai atsakymas nesiunčiamas srautu, prieš rūšiuojant pasirinktą rinkinį pagal pirmojo plano mėnesio kainą pašalinami pasikartojantys kandidatai ir paskirstomas iš skirtingų šaltinių įtraukiamų kandidatų skaičius. Kitais apdorojimo būdais duomenys gali būti pradėti siųsti srautu anksčiau, todėl ne kiekvienai užklausai garantuojamas bendras visų rezultatų surikiavimas ar pasikartojimų pašalinimas. Rūšiavimas taip pat neįrodo, kad grąžintoje imtyje yra pigiausias numeris visame kataloge.
Užsakykite atskirai ir patvirtinkite rezultatą
Paieška nieko nenuperka ir nerezervuoja. Išsaugokite grąžintus numerio ir plano identifikatorius, kad galėtumėte pateikti užsakymą naudodami tą pačią paskyrą. Prieš pateikdami užsakymą peržiūrėkite tikrąjį planą, reikalavimus ir mokesčius. Dėl registracijos reikalavimų aktyvinimas gali užtrukti; paieškos rezultatas nenustato jokio fiksuoto aktyvinimo termino.
Užklausa
Naudokite įjungtą MultiTEL API paskyrą: paskyrai su slaptažodžiu naudokite HTTP Basic prisijungimo duomenis, o paskyrai su prieigos raktu – Authorization: Bearer. Taikomi paskyros leidimai ir jos IP apribojimai. Žr. bendrąsias autentifikavimo gaires.
Kelio parametrai ir URL užklausos parametrai. Viešajai paieškai naudokite GET. Užklausų apdorojimo kodas taip pat priima tam tikras formos ar užklausos reikšmes, tačiau tai nėra paieškos API, priimanti JSON užklausos turinį.
curl --fail-with-body --get \
--user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
--data-urlencode "compact=1" \
--data-urlencode "quantity=10" \
"https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"| Pavadinimas | Tipas | Privalomas | Aprašymas |
|---|---|---|---|
prefix_id | string | Taip | Atskiro prefikso identifikatorius, grąžintas nesugrupuotame getprefixes atsakyme. Nukopijuokite jį tiksliai; nekeiskite jo šalies, aprėpties srities, sugrupuoto prefikso ar kainų plano identifikatoriumi. |
quantity | integer | Ne | Siekiamas gauti kiekis, numatytoji reikšmė – 1. Neteigiamos reikšmės pakeičiamos į 1. Vien kelio parametras quantity nėra patikima bendro rezultatų skaičiaus riba: prie konkretaus šaltinio nepririšta paieška be užklausos parametro quantity gali išplėsti gaunamų duomenų apimtį ir prieš kitą apdorojimą grąžinti iki 50 įrašų iš kiekvieno šaltinio. Įprastai riboto dydžio rezultatų peržiūrai naudokite compact=1 ir pakartokite norimą kiekį užklausoje, kaip parodyta pavyzdyje. |
| Pavadinimas | Tipas | Privalomas | Aprašymas |
|---|---|---|---|
quantity | integer | Ne | Prašomas galutinio rinkinio dydis. Netuščios reikšmės konvertuojamos į sveikuosius skaičius, mažiausia reikšmė – 1. Kai paieška nepririšta prie konkretaus šaltinio ir atsakymas nesiunčiamas srautu, tai riboja galutinį paskirstytų įrašų skaičių. Tai neįpareigoja paslaugos rasti tiek numerių. Prie šaltinio pririštos kompaktiškos paieškos gali grąžinti kompaktišką šaltinio rinkinį, užuot taikiusios šią ribą. |
compact | string | Ne | Naudokite 1, true arba on, kad gautumėte mažesnį, srautu nesiunčiamą atsakymą, kuriame prieš galutinį paskirstymą būtų iki 10 įrašų iš kiekvieno šaltinio. Rezultatai yra šiuo metu gautų turimų numerių imtis, o ne visas katalogas. |
number_filter_mode | string | Ne | Neprivalomas skaitmenų derinio paieškos režimas: contains arba ends_with. Taip pat nurodykite number_filter_value. Tikrinama, ar normalizuoti telefono numerių skaitmenys atitinka sąlygą; paieška neperžiūri visų turimų numerių, kad garantuotų kiekvieną galimą atitiktį. |
number_filter_value | string | Ne | Nuo 1 iki 15 skaitmenų, be tarpų, + ar skyrybos ženklų. Pradžioje esantys nuliai yra reikšmingi; siųskite reikšmę kaip tekstą. |
filter_required | string | Ne | Išplėstinis nustatymas: nurodžius 1, true, yes arba on, būtina aiškiai pasirinkti numerių šaltinį, palaikantį filtro režimą. Priešingu atveju API grąžina status.code 422. Įprastai katalogo peržiūrai to nereikia. |
pid | string | Ne | Išplėstinis turimų numerių šaltinio parinkiklis, kurį pateikia MultiTEL. Priimamos skaitinės ir palaikomos 32 simbolių šešioliktainės formos; neatpažintos reikšmės ignoruojamos be pranešimo. Įprastai naudodami jo nenurodykite. Nekurkite parinkiklių iš kainų identifikatorių ir nemanykite, kad bet kuris parinkiklis apriboja paiešką tik vienu numerių šaltiniu. |
Atsakymas
Vienas JSON objektas, kuriame yra status ir response. Sėkmės atveju status.code yra 200, o response yra numerių įrašų masyvas. status.results nurodo grąžinto masyvo įrašų skaičių; status.msg gali būti Results: N arba, kai atsakymas siunčiamas srautu, OK. Nenaudojant compact=1, kai kurios paieškos masyvą response išveda dalimis ir užbaigia lauku status, todėl palaukite viso JSON turinio. Tai nėra naujos eilutės ženklais atskirtas JSON. Tikrinkite status.code net ir tada, kai HTTP perdavimas sėkmingas. Toliau parodyti tipiniai laukai; konkretiems šaltiniams būdingi metaduomenys ir neprivalomi laukai skiriasi. Kiekvieną identifikatorių laikykite neinterpretuojama reikšme ir kartu išsaugokite numerį bei jo pasirinkto plano price[].uuid.
Pavyzdinė atsakymo struktūra; tai nėra tikri paskyros duomenys ar šiuo metu galiojantis kainos pasiūlymas.
{
"status": {
"code": 200,
"msg": "Results: 1",
"results": 1
},
"response": [
{
"number": "12125550123",
"info": {
"uuid": "NUMBER_ID_FROM_RESPONSE",
"prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
"area_uuid": "AREA_ID_FROM_RESPONSE",
"country_uuid": "COUNTRY_ID_FROM_RESPONSE",
"country_iso": "US",
"prefix": "+1212",
"name": "Example area",
"state": "US"
},
"price": [
{
"uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
"per_minute": "0.01",
"per_sms": "0",
"per_mms": "0",
"free_minutes": "0",
"setup_price": "1.00",
"monthly_price": "2.00",
"yearly_price": "0",
"channels": "2"
}
],
"contract": {
"term": "1 month",
"renewal": "monthly",
"notice": "none"
},
"restrictions": {
"needs_registration": "0",
"restrictions": ""
},
"features": [
"voice"
],
"overflow": "0"
}
]
}Klaidos
- 401: autentifikavimas nepavyko. Jei prisijungimo duomenys neteisingi arba jų nėra ar prieiga prie API paskyros atmesta, paieškos rezultatai negrąžinami.
- 404: Invalid prefix ID, Invalid country, Invalid area arba No numbers found. Perskaitykite status.msg; klaidos atsakymas nėra numerių masyvas.
- 400: NUMBER_FILTER_INVALID lauke response.code: netinkamas režimas, reikšmę sudaro ne 1–15 skaitmenų arba nurodytas filter_required, bet nepateiktas ir režimas, ir reikšmė.
- 422: NUMBER_FILTER_UNSUPPORTED lauke response.code: arba numeris pagal prefiksą priskiriamas užsakymo metu (reason=order_only_prefix, o next_function nurodo užsakymo maršrutą), arba aiškiai pasirinktas šaltinis negali palaikyti reikalaujamo filtro.
Prieinamumas ir šalutiniai poveikiai
- Šis užklausų apdorojimo kodas atlieka paiešką ir parengia kainų pasiūlymus; jis nepateikia numerio užsakymo ir nenuskaito numerio pirkimo mokesčio. Jis gali atnaujinti katalogo podėlius, pašalinti pasenusius podėlyje saugomus numerių įrašus, išsaugoti paskyrai skirtus kainų planus ir rašyti paieškos žurnalus.
- Prieinamumas yra konkretaus momento rezultatas, o ne rezervacija. Vėlesnis užsakymas gali nepavykti arba gali būti grąžinta kitokia prieinamumo informacija. Prieš kartodami pirkimą patikrinkite ir suderinkite užsakymo rezultatą.
- Kainos taikomos konkrečiai paskyrai. Išsaugokite pasirinkto plano identifikatorių naudoti su ta pačia paskyra ir atskirai peržiūrėkite užsakymo sąlygas bei mokesčius; vien šis API galinis taškas neįrodo, kad kaina liks galioti iki vėlesnio užsakymo.
- Pavyzdyje pateiktas numeris ir kainos yra išgalvoti atsakymo struktūros pavyzdžiai, o ne dabartinis kainos pasiūlymas. Informaciją apie galimybes, kanalų skaičių, sutarties trukmę ir registraciją būtina perskaityti tikrajame pasirinktame rezultate.
- Kai kuriuose registracijos aprašymuose yra formatuoto teksto arba nuorodų. Atvaizduodami grąžintas eilutes savo programoje, laikykite jas nepatikimais duomenimis.
- Mobiliojo ryšio numerių prieinamumas ir žymos priklauso nuo to, ar paskyra atitinka taikomas sąlygas, ir nuo turimų numerių. Vien katalogo prefiksas ar žyma is_mobile nepatvirtina konkretaus numerio mobiliojo ryšio galimybių.