Bir ülkenin kapsama alanlarını listeleme

Bir ülke seçin (ABD veya Kanada için isteğe bağlı olarak getstates üzerinden bir eyalet de seçebilirsiniz); ardından getareas çağrısıyla numaraların hangi alanlarda sunulduğunu görün. Alanın uuid değerini sonraki adım için saklayın.

Her alan, sonraki adım olarak şu iki seçenekten birine yönlendirir:

• available > 0: next_function değeri v3/getprefixes/{uuid} olur; eyalete göre filtrelediğinizde sonuna ?state= eklenir. Önekleri incelemek için bunu kullanın.
• available = 0: alanda önekler vardır ancak stok yoktur ve next_function değeri v3/order/{uuid} olur. Bu adımın gereklilikleri için sipariş belgelerine bakın.

available, eyalete göre filtrelediğinizde bile alan genelindeki toplamdır. Eyalet filtresi bir kod veya tam ad kabul eder, ancak yalnızca US ve CA için çalışır. Eyalet filtresi şu sonucu döndürürse: No areas found, filtreyi kaldırıp yeniden deneyin. Kontroller şu sırayla yapılır: eksik ülke kodu, bilinmeyen ülke, başka bir ülke için eyalet filtresi, geçersiz eyalet, eşleşen alan bulunamaması. Bu durumların her birinde döndürülen kod 500 veya 404 olup status.code alanında yer alır; buna karşılık gelen bir HTTP durum kodu ayarlanmaz.

İstek

Gerekli: HTTP Basic kimlik doğrulaması veya Bearer belirteci (Kimlik doğrulama ve API yanıtları bölümüne bakın). Kimlik doğrulama başarısız olursa sorgulama yapılmadan önce HTTP 401 yanıtı verilir.

Yolda isocode, sorgu dizesinde ise isteğe bağlı state ve pid parametreleriyle GET isteği gönderilir. Yol bölümü belirtilmezse bunun yerine form kodlamalı bir isocode alanı okunur.

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'

Yanıt

Standart yanıt zarfı kullanılır. Başarılı olduğunda status.code değeri 200, status.msg değeri 'Results: N', status.results değeri N olur ve response, alan adına göre sıralanmış bir listedir. Alanlar: uuid (sonraki adımda kullanılan, içeriğinden anlam çıkarılmayan alan tanımlayıcısı); country_uuid (içeriğinden anlam çıkarılmayan, 32 karakterli ülke tanımlayıcısı; sonraki adımlarda gerekli değildir); name; area_type ve number_type (katalog tanımları; kayıtlar her zaman yerel numara türleri değildir); country_iso; is_mobile (0 veya 1; alanın mobil bayraklarından alınır; US için her zaman 0 olur, ancak hesabınızda US mobil numaraları etkinleştirilmişse bu kısıtlama geçerli değildir); available (alanın eşleşen öneklerindeki toplam stok; istenen eyaletle sınırlı değildir); sms_coverage (0 veya 1); returns_numbers (0 veya 1; alanın önekleri arasındaki en yüksek bayrak değeri); latitude ve longitude; state_iso; next_function. state_iso: eyalet filtresi varsa çözümlenen filtre kodudur. US ve CA için filtre yoksa adı alan adıyla aynı olan eyaletin kodu, bu bulunamazsa alanın kayıtlı değeri, o da yoksa alanın önek verilerinden türetilen bir koddur. Diğer ülkeler için kayıtlı değerdir ve boş olabilir. next_function değeri 'v3/getprefixes/{uuid}' olur (filtre uygulandığında sonuna '?state={code}' eklenir), ancak bunun için available değerinin 0'dan büyük olması gerekir; aksi takdirde 'v3/order/{uuid}' olur. Hiçbir eşleşen öneki olmayan alanlar sonuçlara dahil edilmez. Önekleri olan ancak stoku bulunmayan alanlar, available değeri 0 olarak döndürülür.

Yanıt yapısını gösteren bir örnektir; canlı hesap verisi veya güncel bir fiyat teklifi değildir.

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

Hatalar

• 500: msg 'ISO Code parameter is required': isocode eksik veya boştur. Bu, düzeltilebilir bir istek hatasıdır. Buna karşılık gelen bir HTTP durum kodu ayarlanmaz.
• 404: msg 'Error: no such country': ülke kodu tanınmıyor. Buna karşılık gelen bir HTTP durum kodu ayarlanmaz.
• 404: msg 'State filter is only available for US and CA': başka bir ülke için boş olmayan bir state değeri gönderilmiştir. Buna karşılık gelen bir HTTP durum kodu ayarlanmaz.
• 404: msg 'Invalid state': state, ülke için bilinen bir kod da bilinen bir ad da değildir. Buna karşılık gelen bir HTTP durum kodu ayarlanmaz.
• 404: msg 'No areas found': ülke, kaynak ve eyalet filtreleriyle eşleşen alan yoktur. Buna karşılık gelen bir HTTP durum kodu ayarlanmaz.
• 401: Kimlik doğrulama eksik veya başarısızdır. HTTP durum kodu 401 ile gönderilir.

Kullanılabilirlik ve yan etkiler

• Yalnızca müşteri hesapları için sorgulama yapar. Hiçbir şeyi rezerve etmez, sipariş etmez veya değiştirmez.
• available bilgi amaçlıdır ve sonraki adımdan önce değişebilir.