Listoni zonat e mbulimit për një vend

Pasi të zgjidhni një vend (dhe, për SHBA-në ose Kanadanë, sipas dëshirës një shtet nga getstates), thirrni getareas për të parë se ku ofrohen numra. Për zonën, ruani vlerën uuid për hapin e ardhshëm.

Çdo zonë çon te njëri nga dy hapat e ardhshëm:

• available > 0: next_function është v3/getprefixes/{uuid}, me ?state= të shtuar në fund kur keni filtruar sipas shtetit. Përdoreni për të shfletuar prefikset.
• available = 0: zona ka prefikse, por nuk ka stok, dhe next_function është v3/order/{uuid}. Shihni dokumentacionin e porositjes për kërkesat e këtij hapi.

available është totali për të gjithë zonën, edhe kur filtroni sipas shtetit. Filtri sipas shtetit pranon një kod ose një emër të plotë, por funksionon vetëm për US dhe CA. Nëse një filtër sipas shtetit kthen No areas found, provoni sërish pa të. Kontrollet kryhen në këtë rend: mungon kodi i vendit, vend i panjohur, filtër sipas shtetit për një vend tjetër, shtet i pavlefshëm, asnjë zonë që përputhet. Secili prej këtyre rasteve kthen kodin 500 ose 404 në status.code, pa një status HTTP përkatës.

Kërkesa

Kërkohet: autentikim HTTP Basic ose token Bearer (shihni Autentikimi dhe përgjigjet e API-së). Autentikimit të dështuar i përgjigjet me HTTP 401 përpara se të kryhet kërkimi.

GET me isocode në shteg dhe parametrat opsionalë state dhe pid në vargun e pyetjes. Nëse segmenti i shtegut lihet jashtë, në vend të tij lexohet një fushë isocode e koduar si 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'

Përgjigjja

Strukturë mbështjellëse standarde. Në rast suksesi, status.code është 200, status.msg është 'Results: N', status.results është N dhe response është një listë e renditur sipas emrit të zonës. Fushat: uuid (identifikues opak i zonës që përdoret në hapin e ardhshëm); country_uuid (identifikues opak i vendit me 32 karaktere, i panevojshëm më vonë); name; area_type dhe number_type (përshkrues të katalogut; zërat nuk janë domosdoshmërisht lloje numrash lokalë); country_iso; is_mobile (0 ose 1, nga treguesit e zonës për numrat celularë; gjithmonë 0 për US, përveçse kur llogaria juaj është aktivizuar për numra celularë të US); available (stoku total në të gjitha prefikset përkatëse të zonës, pa u kufizuar te shteti i kërkuar); sms_coverage (0 ose 1); returns_numbers (0 ose 1, vlera më e lartë e treguesit ndër prefikset e zonës); latitude dhe longitude; state_iso; next_function. state_iso: me një filtër sipas shtetit, është kodi i përcaktuar për filtrin. Për US dhe CA pa filtër, është shteti emri i të cilit është i njëjtë me emrin e zonës; në të kundërt, vlera e ruajtur e zonës; në mungesë të saj, një kod i nxjerrë nga të dhënat e prefikseve të zonës. Për vendet e tjera, është vlera e ruajtur dhe mund të jetë e zbrazët. next_function është 'v3/getprefixes/{uuid}' (me '?state={code}' të shtuar kur aplikohet filtri) kur available është më e madhe se 0, përndryshe është 'v3/order/{uuid}'. Zonat që nuk kanë asnjë prefiks përkatës lihen jashtë. Zonat me prefikse, por pa stok, kthehen me available 0.

Strukturë ilustruese e përgjigjes; nuk përmban të dhëna të drejtpërdrejta të llogarisë dhe nuk është ofertë çmimi aktuale.

{
  "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"
    }
  ]
}

Gabimet

• 500: msg 'ISO Code parameter is required': isocode mungon ose është i zbrazët. Ky është një gabim i kërkesës që mund të korrigjohet. Nuk caktohet asnjë status HTTP përkatës.
• 404: msg 'Error: no such country': kodi i vendit është i panjohur. Nuk caktohet asnjë status HTTP përkatës.
• 404: msg 'State filter is only available for US and CA': u dërgua një vlerë jo e zbrazët për state për një vend tjetër. Nuk caktohet asnjë status HTTP përkatës.
• 404: msg 'Invalid state': state nuk është as kod i njohur dhe as emër i njohur për vendin. Nuk caktohet asnjë status HTTP përkatës.
• 404: msg 'No areas found': asnjë zonë nuk përputhet me filtrat e vendit, burimit dhe shtetit. Nuk caktohet asnjë status HTTP përkatës.
• 401: Autentikimi mungon ose ka dështuar. Dërgohet me statusin HTTP 401.

Disponueshmëria dhe efektet anësore

• Vetëm kërkim për llogaritë e klientëve. Nuk rezervon, nuk porosit dhe nuk ndryshon asgjë.
• available është një vlerë informuese dhe mund të ndryshojë përpara hapit të ardhshëm.