Autentikasi dan respons API

Gunakan kredensial API

Kirim permintaan v3 melalui HTTPS ke https://api.multitel.net. Setiap endpoint dalam panduan ini memerlukan autentikasi. Simpan kredensial di server Anda, dan jangan pernah menaruhnya di JavaScript peramban, halaman publik, tangkapan layar, atau kontrol sumber.

Gunakan salah satu bentuk kredensial berikut:

• HTTP Basic dengan nama pengguna dan kata sandi API yang dikonfigurasi untuk akun MultiTEL Anda.
• token Bearer dalam header Authorization: Bearer YOUR_API_TOKEN, untuk akun API aktif yang dikonfigurasi untuk autentikasi token. Permintaan token hanya diterima dari alamat yang diizinkan untuk akun API tersebut.

Jika daftar izin IP dikonfigurasi untuk akun API Anda, kirim semua permintaan dari alamat yang diizinkan.

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

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

Variabel dalam contoh ini adalah tempat penampung untuk kredensial yang Anda simpan secara pribadi di lingkungan Anda.

Tangani kegagalan autentikasi

Kegagalan autentikasi dikirim dengan status HTTP 401. Isi menggunakan amplop standar, dengan status.code diatur ke 401 dan string kosong sebagai response.

• Tidak ada kredensial: status.msg adalah Username and password are required, dan respons mencakup tantangan autentikasi Basic.
• token Bearer ditolak: jika header Authorization menggunakan skema Bearer dan token tidak dikenal, dinonaktifkan, atau tidak diizinkan dari alamat Anda, status.msg adalah Invalid bearer token. Tidak ada kredensial lain yang dicoba ketika header Bearer ada.
• Kredensial Basic tidak valid: status.msg dimulai dengan A valid username and password pair are required., dan respons mencakup tantangan autentikasi Basic. Pesan dapat berisi teks diagnostik tambahan, jadi jangan uraikan.

Jangan coba lagi secara otomatis dengan kredensial yang sama. Banyak upaya gagal dari satu alamat dalam waktu singkat dapat menyebabkan permintaan lebih lanjut dari alamat tersebut diblokir.

Baca isi respons

Sebagian besar endpoint v3, termasuk getcountries, getstates, getareas dan other, mengembalikan JSON dalam amplop ini:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

Ini adalah respons daftar negara ilustratif, bukan pernyataan tentang inventaris atau kemampuan saat ini.

Respons kesalahan terlihat seperti ini:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

Jika respons tidak dapat dienkode, isinya memiliki status.code 500, status.msg Response encoding error, dan objek kosong sebagai response.

Endpoint lawas GET /v3/countries mengembalikan {"code": 200, "data": [...]} sebagai gantinya. Periksa respons terdokumentasi setiap endpoint. Jika isi tidak valid JSON, misalnya setelah kegagalan server yang tidak terduga, perlakukan permintaan sebagai gagal dan coba lagi nanti.

Kode hasil API dan status HTTP

status.code adalah kode hasil API. Ini bukan status HTTP. Kegagalan autentikasi dikirim dengan HTTP 401. Jika tidak, endpoint penemuan melaporkan hasil seperti 404 dan 500 hanya di status.code dan tidak menetapkan status HTTP yang cocok. Hasil tidak ditemukan atau parameter hilang dapat tiba dengan status HTTP yang berhasil. Selalu periksa status.code sebelum menggunakan response.

Kode hasil 500 dengan pesan ISO Code parameter is required berarti parameter wajib tidak ada. Perbaiki permintaan alih-alih memperlakukannya sebagai gangguan server.

Ikuti next_function

Hasil penemuan mencakup next_function. Ini adalah jalur relatif tanpa garis miring di depan, terkadang dengan string kueri, seperti v3/getareas/US atau v3/getareas/US?state=NY. Awali dengan https://api.multitel.net/ untuk membuat permintaan berikutnya, dan autentikasikan permintaan tersebut dengan cara yang sama. Filter opsional yang Anda kirim, seperti pid, tidak dibawa ke next_function. Tambahkan lagi jika Anda membutuhkannya.

Pemilih inventaris opsional (pid)

getcountries, getstates dan getareas menerima pid sebagai parameter kueri opsional yang mempersempit hasil ke satu sumber inventaris. Gunakan hanya dengan nilai yang diberikan oleh MultiTEL, baik dalam bentuk numeriknya maupun bentuk heksadesimal 32-karakter. Hilangkan untuk penggunaan normal. Kirim pid dalam string kueri. Jika endpoint tidak mengenali atau menerima nilai, endpoint mengabaikannya tanpa kesalahan, dan permintaan berperilaku seolah-olah pid telah dihilangkan.

Pisahkan penemuan dari pesanan

Pencarian negara, negara bagian, dan area tidak mengubah akun Anda. Katalog nomor khusus (other) menyegarkan detail katalog dan menyimpan penawaran harga untuk akun Anda, tetapi tidak menempatkan pesanan. Tidak ada permintaan penemuan yang memesan nomor, dan inventaris dapat berubah di antara permintaan. Tinjau persyaratan dan harga untuk nomor sebelum menggunakan endpoint pemesanan.

Untuk pembelian, penugasan, pesan, pengiriman faks, dan tindakan lainnya, ikuti aturan percobaan ulang endpoint tersebut. Jika tindakan kehabisan waktu setelah pengiriman, periksa statusnya atau catatan akun Anda sebelum mengulanginya. Respons yang hilang tidak membuktikan bahwa tindakan gagal.