Listarea zonelor de acoperire pentru o țară

După ce alegeți o țară (și, pentru SUA sau Canada, opțional un stat din getstates), apelați getareas pentru a vedea unde sunt oferite numere. Păstrați valoarea câmpului uuid al zonei pentru pasul următor.

Pentru fiecare zonă, urmează unul dintre acești doi pași:

• available > 0: next_function este v3/getprefixes/{uuid}, cu ?state= adăugat la sfârșit atunci când ați filtrat după stat. Folosiți această rută pentru a explora prefixele.
• available = 0: zona are prefixe, dar nu are stoc, iar next_function este v3/order/{uuid}. Consultați documentația pentru comenzi pentru a afla cerințele acestui pas.

available reprezintă totalul pentru întreaga zonă, chiar și atunci când filtrați după stat. Filtrul după stat acceptă un cod sau un nume complet, dar funcționează numai pentru US și CA. Dacă filtrarea după stat returnează No areas found, încercați din nou fără acest filtru. Verificările se efectuează în această ordine: cod de țară lipsă, țară necunoscută, filtru după stat pentru o altă țară, stat nevalid, nicio zonă corespunzătoare. Fiecare dintre aceste situații returnează codul 500 sau 404 în status.code, fără un cod de stare HTTP corespunzător.

Cerere

Obligatoriu: autentificare HTTP Basic sau token Bearer (consultați Autentificare și răspunsuri API). Dacă autentificarea eșuează, se răspunde cu HTTP 401 înainte de efectuarea căutării.

GET cu isocode în cale și parametrii opționali state și pid în șirul de interogare. Dacă segmentul din cale este omis, se citește în schimb un câmp isocode codificat ca formular.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

Răspuns

Structură standard de răspuns. În caz de succes, status.code este 200, status.msg este 'Results: N', status.results este N, iar response este o listă sortată după numele zonei. Câmpuri: uuid (identificator opac al zonei, folosit la pasul următor); country_uuid (identificator opac al țării, de 32 de caractere, care nu este necesar ulterior); name; area_type și number_type (descriptori din catalog; înregistrările nu reprezintă neapărat tipuri de numere locale); country_iso; is_mobile (0 sau 1, pe baza indicatorilor de telefonie mobilă ai zonei; întotdeauna 0 pentru US, cu excepția cazului în care contul dumneavoastră este activat pentru numere mobile din US); available (stocul total pentru toate prefixele corespunzătoare ale zonei, fără a se limita la statul solicitat); sms_coverage (0 sau 1); returns_numbers (0 sau 1, cea mai mare valoare a indicatorului dintre prefixele zonei); latitude și longitude; state_iso; next_function. state_iso: când se folosește un filtru după stat, reprezintă codul determinat pentru acel filtru. Pentru US și CA, fără filtru, reprezintă statul al cărui nume este identic cu numele zonei; în lipsa acestuia, valoarea stocată pentru zonă; iar în lipsa acesteia, un cod derivat din datele prefixelor zonei. Pentru celelalte țări, reprezintă valoarea stocată și poate fi gol. next_function este 'v3/getprefixes/{uuid}' (cu '?state={code}' adăugat atunci când se aplică filtrul) dacă available este mai mare decât 0, iar în caz contrar este 'v3/order/{uuid}'. Zonele care nu au niciun prefix corespunzător sunt omise. Zonele care au prefixe, dar nu au stoc, sunt returnate cu available egal cu 0.

Exemplu de structură a răspunsului; nu reprezintă date în timp real ale contului sau o ofertă de preț actuală.

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

Erori

• 500: msg 'ISO Code parameter is required': isocode lipsește sau este gol. Aceasta este o eroare a cererii care poate fi corectată. Nu se setează un cod de stare HTTP corespunzător.
• 404: msg 'Error: no such country': codul țării este necunoscut. Nu se setează un cod de stare HTTP corespunzător.
• 404: msg 'State filter is only available for US and CA': a fost trimisă o valoare state care nu este goală pentru o altă țară. Nu se setează un cod de stare HTTP corespunzător.
• 404: msg 'Invalid state': state nu este nici un cod cunoscut, nici un nume cunoscut pentru țara respectivă. Nu se setează un cod de stare HTTP corespunzător.
• 404: msg 'No areas found': nicio zonă nu corespunde filtrelor după țară, sursă și stat. Nu se setează un cod de stare HTTP corespunzător.
• 401: autentificarea lipsește sau a eșuat. Se trimite cu codul de stare HTTP 401.

Disponibilitate și efecte secundare

• Doar căutare, pentru conturile clienților. Nu rezervă, nu comandă și nu modifică nimic.
• available are rol informativ și se poate modifica înainte de pasul următor.