Listează statele SUA sau provinciile canadiene cu numere în stoc

Folosește acest pas opțional pentru Statele Unite sau Canada pentru a restrânge căutarea la un stat sau o provincie. Sunt acceptate doar US și CA.

• Fiecare înregistrare descrie prefixele aflate în stoc pentru statul respectiv la momentul cererii.
• Urmează next_function pentru a lista zonele statului. Acesta include deja filtrul state, dar nu și pid.
• Căutarea zonelor corelează informațiile despre stat într-un mod ușor diferit. Dacă, pentru un stat, next_function returnează No areas found, apelează getareas fără a specifica un stat.
• Verifică status.code înainte de a citi response. O țară neacceptată sau o țară fără stoc corespunzător returnează codul 404 fără un cod de stare HTTP corespunzător.
• O listă goală cu codul 200 înseamnă că există stoc, dar acesta nu conține informații despre stat. Apelează getareas fără a specifica un stat.

Cerere

Obligatoriu: autentificare HTTP Basic sau token Bearer (vezi 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. Dacă segmentul din cale este omis, se citește în schimb câmpul isocode codificat ca date de formular. Parametrul opțional pid este trimis în șirul de interogare.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getstates/US'

Răspuns

Structură standard de răspuns. În caz de succes, status.code este 200, status.msg este gol, iar status.results reprezintă numărul de înregistrări. response este o listă sortată după name (fără distincție între majuscule și minuscule), apoi după codul state. Câmpuri: state (codul statului sau al provinciei preluat din datele despre stat ale prefixelor, de obicei format din două litere; valorile neobișnuite sunt transmise fără modificări); name (numele din catalog sau codul, dacă în catalog nu există un nume pentru acesta); country_iso; available (stocul total pentru prefixele luate în calcul, întotdeauna mai mare decât 0); prefix_count (numărul de prefixe în stoc luate în calcul); is_mobile (1 dacă cel puțin un prefix luat în calcul acceptă telefonie mobilă; întotdeauna 0 pentru US, cu excepția cazului în care contul tău este activat pentru numere mobile din SUA); sms_coverage (1 dacă cel puțin un prefix luat în calcul are acoperire SMS); returns_numbers (1 dacă cel puțin un prefix luat în calcul are indicatorul de returnare a numerelor activat sau nu are nicio valoare pentru acesta); next_function ('v3/getareas/{isocode}?state={state}'). Dacă există prefixe în stoc, dar niciunul nu conține informații despre stat, rezultatul este status.code 200 cu o listă goală și status.results 0.

Structură de răspuns cu rol ilustrativ; nu reprezintă date în timp real ale contului sau o ofertă de preț actuală.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 2
  },
  "response": [
    {
      "state": "NY",
      "name": "New York",
      "country_iso": "US",
      "available": 120,
      "prefix_count": 8,
      "is_mobile": 0,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=NY"
    },
    {
      "state": "TX",
      "name": "Texas",
      "country_iso": "US",
      "available": 45,
      "prefix_count": 3,
      "is_mobile": 0,
      "sms_coverage": 0,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=TX"
    }
  ]
}

Erori

• 500: msg 'ISO Code parameter is required': isocode lipsește sau este gol. Aceasta este o eroare de cerere care poate fi corectată. Nu se setează un cod de stare HTTP corespunzător; citește status.code.
• 404: msg 'getstates is only available for US and CA': orice alt cod de țară. Nu se setează un cod de stare HTTP corespunzător.
• 404: msg 'No states found': niciun prefix în stoc nu corespunde filtrelor pentru țară și sursă. 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. Nu rezervă, nu comandă și nu modifică nimic. available are rol informativ și nu blochează numere pentru rezervare.