Pilih satu prefiks individual
Gunakan panggilan penelusuran negara dan area cakupan, lalu panggil getprefixes tanpa pengelompokan. Salin pengenal prefiks yang dipilih, yaitu uuid. Jika returns_numbers bernilai 0, prefiks tersebut menetapkan nomor saat dipesan; gunakan nilai yang dikembalikan dalam next_function alih-alih mengharuskan adanya daftar nomor individual.
Telusuri sekumpulan hasil dengan jumlah terbatas
Untuk pencarian biasa, gunakan compact=1 dan cantumkan jumlah hasil yang diinginkan pada jalur maupun parameter kueri quantity, seperti ditunjukkan di bawah. Tidak ada parameter halaman atau kursor. Hasil ringkas merupakan sampel; mengulangi permintaan tidak menjamin halaman berikutnya berisi hasil yang seluruhnya berbeda. Jangan menganggap hasil kosong atau sedikit sebagai jumlah keseluruhan persediaan.
Cari pola digit yang mudah diingat
Sertakan number_filter_mode=contains atau ends_with bersama number_filter_value. Nilainya harus berisi 1–15 digit. Pencarian dapat mengambil sejumlah kandidat dalam kelompok terbatas sebelum menerapkan filter, sehingga persediaan lain yang cocok dapat terlewat. Jika Anda memerlukan sumber yang didukung untuk menerapkan pencarian yang diwajibkan, dapatkan pemilih pid dari MultiTEL dan gunakan filter_required=1; jika pilihan tidak disertakan atau tidak didukung, API mengembalikan kesalahan.
Tinjau nomor yang dipilih
Baca number, info.uuid, pengenal paket terpilih price[].uuid, nama fitur yang tersedia, dan persyaratan pendaftaran dari hasil yang sama. Larik price dapat menawarkan beberapa paket dengan jumlah kanal dan tarif yang berbeda. Kolom nilai uang dan jumlah dapat dikodekan sebagai string. Metadata opsional, termasuk info.state, berbeda antar sumber; jangan mengharuskan satu struktur state yang berlaku universal atau menyimpulkan harga dari ID.
Pada alur tanpa streaming, duplikat kandidat dihapus dan alokasi dilakukan lintas sumber sebelum kumpulan yang dipilih diurutkan berdasarkan harga bulanan paket pertama. Alur lain dapat mulai mengirimkan data melalui streaming lebih awal, sehingga tidak ada jaminan pengurutan global atau penghapusan duplikat yang berlaku untuk setiap permintaan. Pengurutan juga tidak membuktikan bahwa sampel yang dikembalikan memuat nomor termurah di seluruh katalog.
Pesan secara terpisah dan konfirmasikan hasilnya
Pencarian tidak membeli atau mencadangkan apa pun. Simpan pengenal nomor dan paket yang dikembalikan untuk alur pemesanan dengan akun yang sama. Tinjau paket, persyaratan, dan biaya yang sebenarnya sebelum mengajukan pesanan. Persyaratan pendaftaran dapat menunda aktivasi; hasil pencarian tidak menetapkan tenggat aktivasi yang pasti.
Permintaan
Gunakan akun API MultiTEL yang telah diaktifkan: kredensial HTTP Basic untuk akun dengan kata sandi, atau Authorization: Bearer untuk akun dengan token. Izin akun dan pembatasan IP akun tersebut berlaku. Lihat panduan autentikasi umum.
Parameter jalur dan parameter kueri URL. Gunakan GET untuk alur pencarian publik. Penangan ini juga menerima nilai formulir/permintaan tertentu, tetapi bukan API pencarian dengan badan JSON.
curl --fail-with-body --get \
--user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
--data-urlencode "compact=1" \
--data-urlencode "quantity=10" \
"https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"| Nama | Tipe | Wajib | Deskripsi |
|---|---|---|---|
prefix_id | string | Ya | ID prefiks individual yang dikembalikan oleh respons getprefixes tanpa pengelompokan. Salin persis sebagaimana adanya; jangan menggantinya dengan ID negara, area cakupan, prefiks yang dikelompokkan, atau paket harga. |
quantity | integer | Tidak | Target jumlah yang diambil, dengan nilai bawaan 1. Nilai nol atau negatif diubah menjadi 1. quantity pada jalur saja tidak dapat diandalkan sebagai batas jumlah hasil keseluruhan: pencarian yang tidak dikunci ke sumber tertentu dan tanpa parameter kueri quantity dapat memperluas pengambilan dan mengembalikan hingga 50 entri per sumber sebelum pemrosesan lainnya. Untuk penelusuran biasa dengan jumlah terbatas, gunakan compact=1 dan cantumkan kembali jumlah yang diinginkan dalam kueri, seperti pada contoh. |
| Nama | Tipe | Wajib | Deskripsi |
|---|---|---|---|
quantity | integer | Tidak | Jumlah hasil akhir yang diminta. Nilai yang tidak kosong dikonversi menjadi bilangan bulat, dengan nilai minimum 1. Pada alur tanpa streaming yang tidak dikunci ke sumber tertentu, nilai ini membatasi alokasi akhir. Nilai ini tidak memaksa layanan untuk menemukan nomor sebanyak itu. Pencarian ringkas yang dikunci ke suatu sumber dapat mengembalikan kumpulan ringkas dari sumber tersebut alih-alih mengikuti batas ini. |
compact | string | Tidak | Gunakan 1, true atau on untuk respons tanpa streaming yang lebih kecil, dengan hingga 10 entri per sumber sebelum alokasi akhir. Hasilnya merupakan sampel persediaan yang diambil saat itu, bukan katalog lengkap. |
number_filter_mode | string | Tidak | Mode pola digit opsional: contains atau ends_with. Sertakan juga number_filter_value. Hasil diperiksa berdasarkan digit nomor telepon yang telah dinormalisasi; pencarian tidak menelusuri seluruh persediaan satu per satu untuk menjamin semua kemungkinan kecocokan ditemukan. |
number_filter_value | string | Tidak | Antara 1 dan 15 digit, tanpa spasi, + atau tanda baca. Angka nol di awal memiliki arti; kirim nilainya sebagai teks. |
filter_required | string | Tidak | Lanjutan: nilai 1, true, yes atau on mengharuskan sumber persediaan yang mendukung mode filter tersebut dan dipilih secara eksplisit. Jika tidak, API mengembalikan status.code 422. Ini tidak diperlukan untuk penelusuran katalog biasa. |
pid | string | Tidak | Pemilih persediaan lanjutan yang disediakan oleh MultiTEL. Bentuk numerik dan bentuk heksadesimal 32 karakter yang didukung diterima; nilai yang tidak dikenali diabaikan tanpa pemberitahuan. Jangan sertakan untuk penggunaan biasa. Jangan membuat pemilih dari ID harga atau menganggap sembarang pemilih sebagai batasan eksklusif atas persediaan. |
Respons
Satu objek JSON yang berisi status dan response. Jika berhasil, status.code bernilai 200 dan response berupa larik entri nomor. status.results adalah jumlah entri dalam larik yang dikembalikan; status.msg dapat bernilai Results: N atau OK untuk respons streaming. Tanpa compact=1, sebagian pencarian menulis larik response secara bertahap dan diakhiri dengan status, jadi tunggu hingga seluruh badan JSON diterima. Ini bukan JSON yang dipisahkan oleh baris baru. Periksa status.code meskipun pengiriman melalui HTTP berhasil. Kolom yang umum ditampilkan di bawah; metadata khusus sumber dan kolom opsional bervariasi. Perlakukan setiap pengenal sebagai nilai opak yang tidak boleh ditafsirkan strukturnya, dan simpan nomor bersama price[].uuid yang dipilih untuknya.
Ilustrasi struktur respons; bukan data akun langsung atau penawaran harga terkini.
{
"status": {
"code": 200,
"msg": "Results: 1",
"results": 1
},
"response": [
{
"number": "12125550123",
"info": {
"uuid": "NUMBER_ID_FROM_RESPONSE",
"prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
"area_uuid": "AREA_ID_FROM_RESPONSE",
"country_uuid": "COUNTRY_ID_FROM_RESPONSE",
"country_iso": "US",
"prefix": "+1212",
"name": "Example area",
"state": "US"
},
"price": [
{
"uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
"per_minute": "0.01",
"per_sms": "0",
"per_mms": "0",
"free_minutes": "0",
"setup_price": "1.00",
"monthly_price": "2.00",
"yearly_price": "0",
"channels": "2"
}
],
"contract": {
"term": "1 month",
"renewal": "monthly",
"notice": "none"
},
"restrictions": {
"needs_registration": "0",
"restrictions": ""
},
"features": [
"voice"
],
"overflow": "0"
}
]
}Kesalahan
- 401: Autentikasi gagal. Kredensial yang tidak valid atau tidak disertakan serta akses akun API yang ditolak tidak menghasilkan hasil pencarian.
- 404: Invalid prefix ID, Invalid country, Invalid area, atau No numbers found. Baca status.msg; respons kesalahan bukan larik nomor.
- 400: NUMBER_FILTER_INVALID dalam response.code: mode tidak valid, nilai yang bukan terdiri atas 1–15 digit, atau filter_required tanpa menyertakan mode dan nilai sekaligus.
- 422: NUMBER_FILTER_UNSUPPORTED dalam response.code: prefiks menetapkan nomor saat pemesanan (reason=order_only_prefix dan next_function menunjukkan rute pemesanan), atau sumber yang dipilih secara eksplisit tidak dapat mendukung filter yang diwajibkan.
Ketersediaan dan efek samping
- Penangan ini melakukan pencarian dan menyiapkan penawaran harga; penangan ini tidak mengajukan pesanan nomor atau mendebit biaya pembelian nomor. Penangan ini dapat memperbarui cache katalog, menghapus persediaan kedaluwarsa dari cache, menyimpan paket harga dalam lingkup akun, dan menulis log pencarian.
- Ketersediaan merupakan hasil pada saat tertentu, bukan pencadangan. Pesanan berikutnya dapat gagal atau menunjukkan ketersediaan yang berbeda. Cocokkan dan pastikan hasil pesanan sebelum mencoba melakukan pembelian lagi.
- Harga berlaku khusus untuk masing-masing akun. Simpan ID paket yang dipilih untuk akun yang sama dan tinjau ketentuan serta biaya pemesanan secara terpisah; endpoint ini saja tidak membuktikan bahwa suatu harga akan tetap berlaku hingga pemesanan di kemudian hari.
- Nomor dan harga dalam contoh merupakan contoh fiktif untuk menunjukkan struktur respons, bukan penawaran harga langsung. Informasi kemampuan, jumlah kanal, masa kontrak, dan pendaftaran harus dibaca dari hasil sebenarnya yang dipilih.
- Sebagian deskripsi pendaftaran berisi teks berformat atau tautan. Perlakukan string yang dikembalikan sebagai data yang tidak tepercaya saat menampilkannya dalam aplikasi Anda sendiri.
- Ketersediaan nomor seluler dan penandanya bergantung pada kelayakan akun dan persediaan. Prefiks katalog atau penanda is_mobile saja tidak memastikan kemampuan seluler suatu nomor tertentu.