Zgjidhni një prefiks individual
Përdorni thirrjet për gjetjen e shteteve dhe zonave të mbulimit, pastaj getprefixes pa grupim. Kopjoni vlerën e prefiksit të zgjedhur për uuid. Nëse returns_numbers është 0, prefiksi cakton një numër kur bëhet porosia; përdorni vlerën e kthyer të next_function në vend që të kërkoni detyrimisht një listë numrash individualë.
Shfletoni një grup me madhësi të kufizuar
Për një kërkim të zakonshëm, përdorni compact=1 dhe vendosni madhësinë e dëshiruar të grupit si në shtegun e URL-së, ashtu edhe në parametrin e kërkimit quantity, siç tregohet më poshtë. Nuk ka parametër faqeje ose kursori. Një rezultat kompakt është një mostër; përsëritja e një kërkese nuk garanton një faqe pasuese pa mbivendosje me të mëparshmen. Mos e interpretoni një rezultat bosh ose të vogël si numrin e përgjithshëm të numrave në inventar.
Gjeni një model shifrash që mbahet mend lehtë
Jepni number_filter_mode=contains ose ends_with së bashku me number_filter_value. Vlera duhet të përmbajë 1–15 shifra. Një kërkim mund të marrë grupe të kufizuara numrash kandidatë përpara se të zbatojë filtrin, prandaj mund të mos gjejë numra të tjerë të inventarit që përputhen. Nëse ju duhet një burim i mbështetur për të kryer kërkimin e kërkuar, merrni një pid si përzgjedhës nga MultiTEL dhe përdorni filter_required=1; nëse përzgjedhja mungon ose nuk mbështetet, kthehet një gabim i API-së.
Shqyrtoni numrin e zgjedhur
Lexoni number, info.uuid, vlerën e zgjedhur të price[].uuid, emrat e funksionaliteteve të disponueshme dhe kërkesat e regjistrimit nga i njëjti rezultat. Vargu price mund të ofrojë disa plane me numër të ndryshëm kanalesh dhe tarifa të ndryshme. Fushat monetare dhe sasitë mund të kodohen si vargje teksti. Metatëdhënat opsionale, përfshirë info.state, ndryshojnë nga një burim te tjetri; mos kërkoni detyrimisht një strukturë universale për gjendjen dhe mos nxirrni çmime nga një ID.
Në rrjedhën e përpunimit pa transmetim gradual, hiqen dublikatat e kandidatëve dhe bëhet shpërndarja e tyre ndërmjet burimeve, përpara se grupi i zgjedhur të renditet sipas çmimit mujor të planit të parë. Rrjedha të tjera mund të fillojnë transmetimin më herët, prandaj nuk ka garanci për renditje globale ose heqje dublikatash që të vlejë për çdo kërkesë. Renditja gjithashtu nuk provon se mostra e kthyer përmban numrin më të lirë në të gjithë katalogun.
Porositni veçmas dhe konfirmoni rezultatin
Një kërkim nuk blen dhe nuk rezervon asgjë. Ruani identifikuesit e kthyer të numrit dhe të planit për procesin e porositjes me të njëjtën llogari. Shqyrtoni planin konkret, kërkesat dhe tarifat përpara se të dërgoni një porosi. Kërkesat e regjistrimit mund ta vonojnë aktivizimin; një rezultat kërkimi nuk përcakton ndonjë afat fiks aktivizimi.
Kërkesa
Përdorni një llogari të aktivizuar të API-së MultiTEL: kredenciale HTTP Basic për një llogari me fjalëkalim, ose Authorization: Bearer për një llogari me token. Zbatohen lejet e llogarisë dhe kufizimet e saj sipas IP-së. Shihni udhëzimet e përgjithshme për autentikimin.
Parametrat e shtegut dhe parametrat e kërkimit në URL. Përdorni GET për procesin publik të kërkimit. Trajtuesi pranon edhe disa vlera të formularit/kërkesës, por nuk është një API kërkimi me trup JSON.
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"| Emri | Tipi | I detyrueshëm | Përshkrimi |
|---|---|---|---|
prefix_id | string | Po | Një ID prefiksi individual e kthyer nga një përgjigje e pagrupuar e getprefixes. Kopjojeni saktësisht; mos e zëvendësoni me një ID shteti, zone mbulimi, prefiksi të grupuar ose plani tarifor. |
quantity | integer | Jo | Sasia e synuar për t'u marrë, me vlerë të parazgjedhur 1. Vlerat jopozitive bëhen 1. Vetëm parametri quantity në shteg nuk është një kufi i besueshëm për numrin e përgjithshëm të rezultateve: një kërkim pa burim të fiksuar dhe pa parametrin e kërkimit quantity mund ta zgjerojë marrjen dhe të kthejë deri në 50 elemente për burim përpara përpunimit të mëtejshëm. Për shfletim të zakonshëm me madhësi të kufizuar, përdorni compact=1 dhe përsëritni sasinë e dëshiruar te parametrat e kërkimit, si në shembull. |
| Emri | Tipi | I detyrueshëm | Përshkrimi |
|---|---|---|---|
quantity | integer | Jo | Madhësia përfundimtare e kërkuar e grupit. Vlerat jo të zbrazëta shndërrohen në numra të plotë, me minimum 1. Në rrjedhën pa transmetim gradual dhe pa burim të fiksuar, kjo kufizon shpërndarjen përfundimtare. Nuk e detyron shërbimin të gjejë aq numra. Kërkimet kompakte të fiksuara te një burim mund të kthejnë grupin kompakt të atij burimi në vend që të zbatojnë këtë kufi. |
compact | string | Jo | Përdorni 1, true ose on për një përgjigje më të vogël pa transmetim gradual, me deri në 10 elemente për burim përpara shpërndarjes përfundimtare. Rezultatet janë një mostër e inventarit të marrë në atë moment, jo një katalog i plotë. |
number_filter_mode | string | Jo | Mënyrë opsionale për modelin e shifrave: contains ose ends_with. Jepni edhe number_filter_value. Rezultatet kontrollohen kundrejt shifrave të normalizuara të numrit të telefonit; kërkimi nuk e shqyrton të gjithë inventarin për të garantuar çdo përputhje të mundshme. |
number_filter_value | string | Jo | Nga 1 deri në 15 shifra, pa hapësira, + ose shenja pikësimi. Zerot në fillim kanë rëndësi; dërgojeni si tekst. |
filter_required | string | Jo | Cilësim i avancuar: vlera 1, true, yes ose on kërkon një burim inventari të zgjedhur shprehimisht, i cili mbështet mënyrën e filtrimit. Përndryshe API-ja kthen status.code 422. Kjo nuk nevojitet për shfletimin e zakonshëm të katalogut. |
pid | string | Jo | Përzgjedhës i avancuar inventari i ofruar nga MultiTEL. Pranohen format numerike dhe format heksadecimale të mbështetura me 32 karaktere; vlerat e panjohura shpërfillen pa njoftim. Mos e përfshini për përdorim të zakonshëm. Mos nxirrni përzgjedhës nga ID-të e çmimeve dhe mos supozoni se një përzgjedhës çfarëdo e kufizon inventarin vetëm te një burim. |
Përgjigjja
Një objekt JSON që përmban status dhe response. Në rast suksesi, status.code është 200 dhe response është një varg elementesh që përfaqësojnë numra. status.results është numri i elementeve të vargut të kthyer; status.msg mund të jetë Results: N ose OK për një përgjigje me transmetim gradual. Pa compact=1, disa kërkime e shkruajnë vargun response pjesë-pjesë dhe përfundojnë me status, prandaj prisni trupin e plotë JSON. Ky nuk është JSON me elemente të ndara sipas rreshtave. Kontrolloni status.code edhe kur transporti HTTP përfundon me sukses. Fushat tipike tregohen më poshtë; metatëdhënat specifike për burimin dhe fushat opsionale ndryshojnë. Trajtojeni çdo identifikues si vlerë opake dhe ruajeni numrin së bashku me vlerën e tij të zgjedhur të price[].uuid.
Strukturë ilustruese e përgjigjes; nuk janë të dhëna të drejtpërdrejta të llogarisë dhe as ofertë çmimi aktuale.
{
"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"
}
]
}Gabimet
- 401: Autentikimi dështoi. Kredencialet e pavlefshme ose që mungojnë dhe refuzimi i qasjes së llogarisë së API-së nuk japin rezultate kërkimi.
- 404: Invalid prefix ID, Invalid country, Invalid area, ose No numbers found. Lexoni status.msg; një përgjigje gabimi nuk është një varg numrash.
- 400: NUMBER_FILTER_INVALID në response.code: mënyrë e pavlefshme, një vlerë që nuk përbëhet nga 1–15 shifra, ose filter_required pa dhënë si mënyrën, ashtu edhe vlerën.
- 422: NUMBER_FILTER_UNSUPPORTED në response.code: ose prefiksi cakton një numër në momentin e porositjes (reason=order_only_prefix dhe next_function identifikon rrugën e porositjes), ose burimi i zgjedhur shprehimisht nuk mund ta mbështesë filtrin e kërkuar.
Disponueshmëria dhe efektet anësore
- Ky trajtues kërkon dhe përgatit oferta çmimesh; nuk dërgon porosi numrash dhe nuk debiton tarifa për blerjen e numrave. Ai mund të rifreskojë memoriet e përkohshme të katalogut, të heqë inventarin e vjetruar nga këto memorie, të ruajë plane tarifore të lidhura me llogarinë dhe të shkruajë regjistra kërkimi.
- Disponueshmëria është një rezultat për një moment të caktuar, jo një rezervim. Një porosi e mëvonshme mund të dështojë ose të kthejë disponueshmëri të ndryshme. Verifikoni rezultatin e porosisë dhe përputheni me të dhënat tuaja përpara se të provoni sërish një blerje.
- Çmimet janë specifike për llogarinë. Ruani ID-në e planit të zgjedhur për të njëjtën llogari dhe shqyrtoni veçmas kushtet dhe tarifat e porosisë; vetëm kjo pikë fundore nuk provon se një çmim do të mbetet i vlefshëm deri në një porosi të mëvonshme.
- Numri dhe çmimet e shembullit janë shembuj të sajuar të strukturës së përgjigjes, jo një ofertë çmimi në kohë reale. Aftësitë, numri i kanaleve, afati i kontratës dhe informacioni i regjistrimit duhen lexuar nga rezultati konkret i zgjedhur.
- Disa përshkrime regjistrimi përmbajnë tekst të formatuar ose lidhje. Trajtojini vargjet e tekstit të kthyera si të dhëna të pabesueshme kur i shfaqni në aplikacionin tuaj.
- Disponueshmëria e numrave celularë dhe treguesit përkatës varen nga kriteret që plotëson llogaria dhe nga inventari. Vetëm një prefiks katalogu ose treguesi is_mobile nuk përcakton aftësitë celulare të një numri të caktuar.