Comandați numere de telefon dintr-un prefix

Comandați dintr-un prefix

Folosiți această operațiune când catalogul de prefixe vă îndrumă să comandați o cantitate dintr-un prefix în loc să alegeți individual numere disponibile. Începeți cu țări, zone sau state și prefixe. Păstrați identificatorul prefixului și planul tarifar din același rezultat proaspăt obținut. Pentru un anumit număr selectat dintr-o listă de numere disponibile, folosiți Cumpărați un număr de telefon selectat.

Această cerere poate cumpăra numere și poate genera costuri. Nu reprezintă o ofertă de preț, o rezervare sau o simulare. Înainte de trimitere, verificați taxele de configurare și cele lunare, tarifele pe minut pentru apelurile primite, minutele incluse, canalele, cerințele de înregistrare și limitele de cumpărare ale contului. Un rezultat din catalog nu rezervă stocul și nu fixează prețurile. Verificările privind alimentarea contului pot avea loc înainte de onorarea comenzii; o eroare nu dovedește, prin ea însăși, că nu a avut loc nicio cumpărare sau alimentare a contului.

Trimiteți cererea de cumpărare

Folosiți un cont API activat, prin HTTPS, de la o adresă IP sursă permisă. Setați variabilele conform selecției curente din catalog și configurației aprobate pentru livrare. Comanda următoare cumpără un număr.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

Mai sus este prezentată o cerere POST cu date de formular. Coordonatorul citește și un obiect JSON atunci când Content-Type este application/json. Câmpurile JSON suprascriu câmpurile corespunzătoare din formular/cerere. Folosiți consecvent o singură codificare; nu trimiteți valori contradictorii în parametrii de interogare și în corpul cererii.

Setări de livrare și reînnoire

Alegeți aceleași setări de livrare pe care le-ați folosi pentru număr în portal. Acestea sunt valori de configurare avansată, nu instrucțiuni pentru crearea unei centrale PBX găzduite sau a unui trunchi de originare. Refolosiți o configurație a contului despre care știți că funcționează și verificați numărul salvat după cumpărare. Simpla acceptare a cumpărării nu confirmă funcționarea livrării apelurilor vocale sau a SMS-urilor.

Aceste câmpuri sunt normalizate și transmise procesului de finalizare a cumpărării, dar salvarea lor diferă în funcție de fluxul aferent stocului. Ruta actuală de comandă nu pune la dispoziție câmpurile stricte de plafonare a ofertei de preț din ghidul de cumpărare a unui număr selectat ca mecanisme de protecție echivalente. Folosiți permisiunile de cumpărare și limitele de preț ale contului și verificați configurația rezultată a numărului.

Citiți rezultatul complet

Analizați corpul JSON și verificați status.code și status.msg chiar și atunci când cererea HTTP reușește. Această rută își scrie propriul răspuns JSON, iar funcția auxiliară comună pentru răspunsuri nu transpune nici ea neapărat codul aplicației în codul de stare HTTP. Codurile aplicației pot fi numere JSON sau șiruri numerice. Nu impuneți prezența câmpului status.results; acesta nu este prezent în rezultatul normal al comenzii.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

Identificatorul, numărul și prețurile de mai sus sunt fictive. Tratați ID-ul comenzii ca pe o valoare opacă. numbers enumeră numerele pe care acest răspuns le raportează ca fiind cumpărate; comparați lungimea listei cu cantitatea solicitată. Sumele prețurilor sunt șiruri de caractere, iar acest răspuns rotunjește tarifele monetare la două zecimale, inclusiv per_minute; folosiți catalogul proaspăt obținut pentru precizia originală a tarifelor. Minutele incluse și canalele pot fi primite ca valori numerice sau șiruri numerice.

Blocul de preț descrie planul selectat folosit la construirea răspunsului, nu o factură detaliată pentru fiecare număr sau totalul comenzii. Numerele candidate din stoc pot avea planuri diferite. Verificați concordanța numerelor cumpărate individual și a tranzacțiilor contului, în loc să înmulțiți valorile din acest bloc și să presupuneți că astfel este dovedit totalul final.

Cumpărări parțiale și rezultate incerte

Un cod al aplicației de 200 poate fi însoțit de un avertisment și de mai puține numere decât s-au solicitat. O eroare ulterioară nu anulează cumpărarea numerelor deja cumpărate. Păstrați ID-ul comenzii, numerele și mesajul returnate. Verificați aceste numere în inventarul dumneavoastră și în tranzacțiile contului înainte de a decide dacă să comandați cantitatea rămasă.

O expirare a timpului de așteptare, o cerere întreruptă prin deconectare, un răspuns incorect formatat sau o eroare după trimitere nu dovedesc că nu s-a întâmplat nimic. Nu trimiteți automat o altă cerere de cumpărare, nici măcar cu aceeași referință. Păstrați cererea inițială, referința și orice ID de comandă returnat, verificați inventarul și tranzacțiile contului și contactați asistența dacă rezultatul rămâne incert.

O comandă neconfirmată poate returna codul aplicației 400 cu un mesaj care indică faptul că este încă în curs de confirmare. Păstrați ID-ul comenzii returnat și verificați concordanța acelei cumpărări cu evidențele; acesta nu este un îndemn de a o trimite din nou. Recuperarea comenzilor înregistrate urmărește intern comanda inițială. O cerere nouă către această operațiune creează o încercare separată de cumpărare, în loc să reia o comandă pe baza referinței dumneavoastră, deci poate cumpăra mai multe numere și poate genera costuri pentru ele. Nu folosiți cereri repetate de cumpărare pentru a verifica starea sau pentru a căuta în stoc.

Înregistrare și activare

Un număr cumpărat sau alocat poate necesita în continuare înregistrare sau activare. Dacă needs_registration este 1, verificați restrictions și registration_requirements. Cel din urmă câmp poate indica v3/get_requirements cu valori pentru country și number_type. Parcurgeți fluxul aplicabil pentru identitate/adresă și confirmați starea numărului înainte de a vă baza pe apelurile primite sau pe mesagerie.

features descrie capabilitățile anunțate; nu confirmă rutarea efectivă, aprobarea campaniilor, livrarea SMS-urilor sau recepția faxurilor. Verificați setările de livrare salvate și efectuați testul de serviciu adecvat când numărul este activ.

Notificări de retur pentru comenzi

Notificările de retur trimit prin POST date JSON care conțin starea și răspunsul comenzii, la care se adaugă referința dumneavoastră dacă a fost furnizată. Acestea sunt trimise pentru cumpărările raportate, inclusiv pentru rezultatele parțiale. Eșecul unei notificări de retur nu anulează cumpărarea. Livrarea poate fi reîncercată, așadar gestionați duplicatele pe baza ID-ului comenzii și verificați concordanța numerelor cu evidențele, în loc să inițiați o altă cumpărare.

Această rută nu adaugă o semnătură criptografică notificărilor de retur. Tratați o notificare de retur ca pe o înștiințare de a verifica concordanța cu inventarul accesat prin autentificare, nu ca pe o autorizare independentă de a percepe sume, de a furniza servicii sau de a acorda acces. Nu includeți datele de autentificare API în adresa URL pentru notificările de retur. Trimiterea unei alte cereri de cumpărare cu o adresă URL diferită pentru notificările de retur nu actualizează comanda inițială; creează o încercare separată de cumpărare. Păstrați ID-ul comenzii inițiale când solicitați asistenței să investigheze notificarea de retur a acesteia.

Erori care trebuie gestionate