Daftar area cakupan untuk suatu negara

Setelah memilih negara (dan, untuk AS atau Kanada, secara opsional memilih negara bagian dari getstates), panggil getareas untuk melihat di mana nomor ditawarkan. Simpan pengenal area uuid untuk langkah berikutnya.

Setiap area mengarah ke salah satu dari dua langkah berikut:

• available > 0: next_function bernilai v3/getprefixes/{uuid}, dengan ?state= ditambahkan di akhir jika Anda memfilter berdasarkan negara bagian. Gunakan untuk menelusuri prefiks.
• available = 0: area memiliki prefiks tetapi tidak memiliki stok, dan next_function bernilai v3/order/{uuid}. Lihat dokumentasi pemesanan untuk mengetahui persyaratan langkah ini.

available adalah total di seluruh area, bahkan ketika Anda memfilter berdasarkan negara bagian. Filter negara bagian menerima kode atau nama lengkap, tetapi hanya berlaku untuk US dan CA. Jika filter negara bagian mengembalikan No areas found, coba lagi tanpa filter tersebut. Pemeriksaan dijalankan dalam urutan berikut: kode negara tidak disertakan, negara tidak dikenal, filter negara bagian untuk negara lain, negara bagian tidak valid, tidak ada area yang cocok. Masing-masing kondisi ini mengembalikan kode 500 atau 404 dalam status.code, tanpa status HTTP yang sesuai.

Permintaan

Wajib: autentikasi HTTP Basic atau token Bearer (lihat Autentikasi dan respons API). Autentikasi yang gagal dijawab dengan HTTP 401 sebelum pencarian dijalankan.

GET dengan isocode di jalur serta parameter opsional state dan pid di string kueri. Jika segmen jalur tidak disertakan, kolom isocode yang dikodekan sebagai formulir akan dibaca sebagai gantinya.

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'

Respons

Struktur pembungkus standar. Jika berhasil, status.code bernilai 200, status.msg bernilai 'Results: N', status.results bernilai N, dan response berupa daftar yang diurutkan berdasarkan nama area. Kolom: uuid (pengenal area opak yang digunakan pada langkah berikutnya); country_uuid (pengenal negara opak sepanjang 32 karakter, tidak diperlukan selanjutnya); name; area_type dan number_type (deskriptor katalog; entri tidak selalu merupakan jenis nomor lokal); country_iso; is_mobile (0 atau 1, dari penanda seluler area; selalu 0 untuk US kecuali akun Anda diaktifkan untuk nomor seluler US); available (total stok dari seluruh prefiks yang cocok di area tersebut, tidak terbatas pada negara bagian yang diminta); sms_coverage (0 atau 1); returns_numbers (0 atau 1, nilai penanda tertinggi di antara prefiks area tersebut); latitude dan longitude; state_iso; next_function. state_iso: jika filter negara bagian digunakan, nilainya adalah kode hasil resolusi filter. Untuk US dan CA tanpa filter, nilainya adalah negara bagian yang namanya sama dengan nama area; jika tidak ada, nilai area yang tersimpan; jika itu juga tidak ada, kode yang diturunkan dari data prefiks area tersebut. Untuk negara lain, nilainya adalah nilai yang tersimpan dan dapat kosong. next_function bernilai 'v3/getprefixes/{uuid}' (ditambah '?state={code}' jika difilter) ketika available lebih besar dari 0; jika tidak, nilainya 'v3/order/{uuid}'. Area yang sama sekali tidak memiliki prefiks yang cocok tidak disertakan. Area yang memiliki prefiks tetapi tidak memiliki stok dikembalikan dengan available bernilai 0.

Contoh struktur respons; bukan data akun langsung atau penawaran harga terkini.

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

Kesalahan

• 500: msg 'ISO Code parameter is required': isocode tidak disertakan atau kosong. Ini adalah kesalahan permintaan yang dapat diperbaiki. Tidak ada status HTTP yang sesuai yang ditetapkan.
• 404: msg 'Error: no such country': kode negara tidak dikenal. Tidak ada status HTTP yang sesuai yang ditetapkan.
• 404: msg 'State filter is only available for US and CA': state yang tidak kosong dikirim untuk negara lain. Tidak ada status HTTP yang sesuai yang ditetapkan.
• 404: msg 'Invalid state': state bukan kode maupun nama yang dikenal untuk negara tersebut. Tidak ada status HTTP yang sesuai yang ditetapkan.
• 404: msg 'No areas found': tidak ada area yang cocok dengan filter negara, sumber, dan negara bagian. Tidak ada status HTTP yang sesuai yang ditetapkan.
• 401: Autentikasi tidak disertakan atau gagal. Dikirim dengan status HTTP 401.

Ketersediaan dan efek samping

• Hanya melakukan pencarian untuk akun pelanggan. Tidak mencadangkan, memesan, atau mengubah apa pun.
• available bersifat informatif dan dapat berubah sebelum langkah berikutnya.