Alegeți un prefix individual
Folosiți apelurile de identificare a țărilor și a zonelor de acoperire din catalog, apoi getprefixes fără grupare. Copiați valoarea câmpului uuid al prefixului selectat. Dacă returns_numbers este 0, prefixul alocă un număr la plasarea comenzii; folosiți valoarea returnată în next_function în loc să solicitați obligatoriu o listă de numere individuale.
Consultați un lot cu dimensiune limitată
Pentru o căutare obișnuită, folosiți compact=1 și specificați dimensiunea dorită a lotului atât în cale, cât și în parametrul de interogare quantity, așa cum se arată mai jos. Nu există un parametru de pagină sau de cursor. Un rezultat compact este un eșantion; repetarea unei cereri nu garantează o pagină următoare fără suprapuneri. Nu interpretați un rezultat gol sau cu puține elemente ca fiind numărul total de numere din stoc.
Găsiți un tipar de cifre ușor de reținut
Specificați number_filter_mode=contains sau ends_with împreună cu number_filter_value. Valoarea trebuie să conțină 1–15 cifre. O căutare poate prelua loturi limitate de numere candidate înainte de aplicarea filtrului, astfel încât poate omite alte numere din stoc care corespund criteriilor. Dacă aveți nevoie de o sursă compatibilă pentru a aplica căutarea necesară, obțineți un selector pid de la MultiTEL și folosiți filter_required=1; dacă selecția lipsește sau nu este acceptată, API-ul returnează o eroare.
Verificați numărul selectat
Citiți number, info.uuid, valoarea selectată pentru price[].uuid, denumirile funcționalităților disponibile și cerințele de înregistrare din același rezultat. Tabloul price poate oferi mai multe planuri cu numere de canale și tarife diferite. Câmpurile monetare și cantitățile pot fi codificate ca șiruri de caractere. Metadatele opționale, inclusiv info.state, diferă de la o sursă la alta; nu impuneți o structură universală pentru câmpul de stat și nu deduceți prețurile dintr-un ID.
În fluxul de procesare fără transmitere progresivă, duplicatele sunt eliminate din numerele candidate, iar alocarea se face între surse înainte ca lotul selectat să fie sortat după prețul lunar al primului plan. Alte fluxuri de procesare pot începe transmiterea progresivă mai devreme, astfel încât nu există o garanție de sortare globală sau de eliminare a duplicatelor valabilă pentru fiecare cerere. De asemenea, sortarea nu dovedește că eșantionul returnat conține cel mai ieftin număr din întregul catalog.
Plasați comanda separat și confirmați rezultatul
O căutare nu cumpără și nu rezervă nimic. Păstrați identificatorii returnați pentru număr și plan pentru procesul de comandă din același cont. Verificați planul efectiv, cerințele și costurile înainte de a trimite o comandă. Cerințele de înregistrare pot întârzia activarea; rezultatul unei căutări nu stabilește un termen fix de activare.
Cerere
Folosiți un cont API MultiTEL activat: date de autentificare HTTP Basic pentru un cont cu parolă sau Authorization: Bearer pentru un cont cu token. Se aplică permisiunile contului și restricțiile sale privind adresele IP. Consultați instrucțiunile generale de autentificare.
Parametri de cale și parametri de interogare URL. Folosiți GET pentru procesul public de căutare. Componenta de procesare acceptă și anumite valori din formular/cerere, dar nu este un API de căutare cu corpul cererii în format 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"| Nume | Tip | Obligatoriu | Descriere |
|---|---|---|---|
prefix_id | string | Da | ID-ul unui prefix individual, returnat de un răspuns getprefixes fără grupare. Copiați-l exact; nu îl înlocuiți cu ID-ul unei țări, al unei zone de acoperire din catalog, al unui prefix grupat sau al unui plan tarifar. |
quantity | integer | Nu | Numărul vizat la preluare, implicit 1. Valorile mai mici sau egale cu zero devin 1. Parametrul quantity din cale, folosit singur, nu reprezintă o limită sigură pentru numărul total de rezultate: o căutare fără o sursă fixată și fără parametrul de interogare quantity își poate extinde preluarea și poate returna până la 50 de înregistrări per sursă înainte de alte prelucrări. Pentru consultarea obișnuită a unor loturi limitate, folosiți compact=1 și repetați cantitatea dorită în interogare, ca în exemplu. |
| Nume | Tip | Obligatoriu | Descriere |
|---|---|---|---|
quantity | integer | Nu | Dimensiunea finală solicitată a lotului. Valorile care nu sunt goale sunt convertite în numere întregi, cu un minim de 1. În fluxul de procesare fără sursă fixată și fără transmitere progresivă, aceasta limitează alocarea finală. Nu obligă serviciul să găsească atât de multe numere. Căutările compacte cu o sursă fixată pot returna lotul compact al sursei în loc să respecte această limită. |
compact | string | Nu | Folosiți 1, true sau on pentru un răspuns mai mic, fără transmitere progresivă, cu până la 10 înregistrări per sursă înainte de alocarea finală. Rezultatele sunt un eșantion al stocului preluat în acel moment, nu un catalog complet. |
number_filter_mode | string | Nu | Mod opțional de căutare după un tipar de cifre: contains sau ends_with. Specificați și number_filter_value. Rezultatele sunt verificate pe baza cifrelor normalizate ale numerelor de telefon; căutarea nu parcurge întregul stoc pentru a garanta găsirea tuturor potrivirilor posibile. |
number_filter_value | string | Nu | Între 1 și 15 cifre, fără spații, + sau semne de punctuație. Zerourile de la început sunt semnificative; trimiteți valoarea ca text. |
filter_required | string | Nu | Avansat: valoarea 1, true, yes sau on impune selectarea explicită a unei surse de stoc compatibile cu modul de filtrare. În caz contrar, API-ul returnează status.code 422. Acest lucru nu este necesar pentru consultarea obișnuită a catalogului. |
pid | string | Nu | Selector avansat de stoc furnizat de MultiTEL. Sunt acceptate formele numerice și formele hexazecimale compatibile de 32 de caractere; valorile nerecunoscute sunt ignorate fără notificare. Omiteți-l pentru utilizarea obișnuită. Nu deduceți selectori din ID-urile prețurilor și nu presupuneți că un selector arbitrar restrânge stocul în mod exclusiv. |
Răspuns
Un singur obiect JSON care conține status și response. În caz de succes, status.code este 200, iar response este un tablou de înregistrări de numere. status.results reprezintă numărul de elemente din tabloul returnat; status.msg poate fi Results: N sau OK pentru un răspuns transmis progresiv. Fără compact=1, unele căutări scriu tabloul response treptat și încheie cu status, așadar așteptați primirea întregului corp JSON. Acesta nu este JSON delimitat prin linii noi. Verificați status.code chiar și atunci când transportul HTTP reușește. Mai jos sunt prezentate câmpurile uzuale; metadatele specifice sursei și câmpurile opționale variază. Tratați fiecare identificator ca pe o valoare opacă și păstrați împreună numărul și valoarea price[].uuid selectată pentru acesta.
Structură ilustrativă a răspunsului; nu reprezintă date reale ale contului sau o ofertă de preț actuală.
{
"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"
}
]
}Erori
- 401: Autentificarea a eșuat. Datele de autentificare nevalide sau absente și refuzarea accesului contului API nu produc rezultate de căutare.
- 404: Invalid prefix ID, Invalid country, Invalid area sau No numbers found. Citiți status.msg; un răspuns de eroare nu este un tablou de numere.
- 400: NUMBER_FILTER_INVALID în response.code: mod nevalid, o valoare care nu constă în 1–15 cifre sau filter_required fără specificarea atât a modului, cât și a valorii.
- 422: NUMBER_FILTER_UNSUPPORTED în response.code: fie prefixul alocă un număr la plasarea comenzii (reason=order_only_prefix, iar next_function identifică ruta de comandă), fie sursa selectată explicit nu poate aplica filtrul obligatoriu.
Disponibilitate și efecte secundare
- Această componentă de procesare efectuează căutări și pregătește oferte de preț; nu trimite o comandă de număr și nu debitează un cost de achiziție a unui număr. Poate actualiza memoriile cache ale catalogului, elimina stocul învechit din cache, salva planuri tarifare asociate contului și scrie jurnale de căutare.
- Disponibilitatea reflectă situația la un anumit moment, nu reprezintă o rezervare. O comandă ulterioară poate eșua sau poate indica o disponibilitate diferită. Verificați și reconciliați rezultatul comenzii înainte de a reîncerca o achiziție.
- Prețurile sunt specifice contului. Păstrați ID-ul planului selectat pentru același cont și verificați separat condițiile și costurile comenzii; acest punct de acces, de unul singur, nu dovedește că un preț va rămâne valabil până la o comandă ulterioară.
- Numărul și prețurile din exemplu sunt fictive și ilustrează structura răspunsului, nu reprezintă o ofertă de preț în timp real. Funcționalitățile, numărul de canale, durata contractuală și informațiile de înregistrare trebuie citite din rezultatul efectiv selectat.
- Unele descrieri ale cerințelor de înregistrare conțin text formatat sau linkuri. Tratați șirurile returnate ca date care nu sunt de încredere atunci când le afișați în propria aplicație.
- Disponibilitatea numerelor mobile și indicatoarele aferente depind de eligibilitatea contului și de stoc. Un prefix din catalog sau indicatorul is_mobile, luat separat, nu stabilește funcționalitățile mobile ale unui anumit număr.