Pencarian Nomor Telepon Batch: Permintaan Multi Sinkron vs Tugas File Bulk

Perbandingan dua jalur batch CarrierLookup, yaitu permintaan multi sinkron dan tugas file bulk asinkron, beserta panduan keputusan berdasarkan ukuran daftar dan alur kerja.

Pencarian nomor telepon batch dengan CarrierLookup dapat dilakukan melalui salah satu dari dua jalur berbeda. Permintaan multi sinkron memproses hingga 100 nomor melalui API, atau hingga 500 nomor di dasbor, dan mengembalikan hasil yang berurutan dalam respons yang sama. Tugas file bulk mengambil file TXT atau CSV untuk satu negara yang dipilih, berjalan secara asinkron, dan diakhiri dengan satu file CSV yang dapat diunduh. Pilih permintaan multi untuk grup kecil dan alur kerja langsung, serta tugas file untuk daftar besar secara keseluruhan. Keduanya mengembalikan operator asli dan konteks alokasi nomor, bukan operator saat ini setelah porting dan bukan sinyal keterjangkauan.

Dua jalur batch, dua pekerjaan berbeda

Tim yang mencari pencarian nomor telepon batch sering kali berasumsi bahwa setiap alat batch bekerja dengan cara yang sama. CarrierLookup sengaja menawarkan dua bentuk, dan mencampurnya adalah kesalahan perencanaan yang paling umum.

Permintaan multi sinkron adalah panggilan interaktif. Anda mengirimkan sekelompok nomor E.164, menunggu, dan menerima satu jawaban yang berurutan. Nomor dalam grup tersebut dapat berasal dari negara yang berbeda, dan tidak diperlukan pemilihan negara secara terpisah.

Tugas file bulk adalah sebuah pekerjaan. Anda menyiapkan file TXT atau CSV satu kolom, memilih satu negara, mengirimkannya, dan kembali lagi nanti untuk melihat hasilnya. Pekerjaan berlangsung di latar belakang, dan outputnya berupa file, bukan badan respons.

Batasan per produk berlaku untuk kedua jalur tersebut, jadi periksa dokumentasi API saat ini sebelum menentukan ukuran pekerjaan.

Cara kerja permintaan multi sinkron

Gunakan POST /api/v1/batch-check dari server tepercaya, dengan kunci API dikirim dalam header X-API-Key. Dasbor menawarkan konsep yang sama di browser untuk grup yang lebih besar, hingga 500 nomor.

Setiap nomor harus ditulis dalam bentuk E.164: tanda plus di depan, kode negara, dan nomor pelanggan, tanpa spasi atau pemisah. Nomor yang diformat dengan buruk akan ditolak karena formatnya. Itu adalah masalah pemformatan yang harus diperbaiki, bukan temuan bahwa nomor tersebut tidak memiliki operator.

Respons melaporkan berapa banyak nomor yang dikirimkan, berapa banyak yang berhasil, dan berapa banyak yang gagal, diikuti dengan hasil dalam urutan yang sama seperti saat Anda mengirimkan nomor tersebut. Urutan sangat penting karena memungkinkan Anda memetakan setiap jawaban kembali ke baris dalam tabel Anda sendiri tanpa kunci gabungan (join key).

Dua perilaku yang perlu diperhatikan:

• Hasil yang ditandai sebagai tidak ada berarti tidak ada hasil normal yang kembali untuk nomor tersebut. Ini bukan pernyataan bahwa nomor tersebut tidak valid atau tidak tersambung.
• Jika seluruh permintaan mengalami timeout, permintaan tersebut gagal sebagai satu kesatuan. Tidak ada hasil parsial yang dikembalikan, dan jumlah penuh dikembalikan ke saldo Anda.

Karena panggilan bersifat sinkron, jauhkan dari jalur apa pun di mana pengguna menunggu pemuatan halaman kecuali Anda telah menangani timeout.

Cara kerja tugas file bulk

Gunakan POST /api/v1/bulk-tasks dengan badan multipart. Letakkan kolom negara sebelum kolom file, karena urutan penting dalam pengiriman multipart. Kemudian baca progres dengan GET /api/v1/bulk-tasks/{id}.

Tugas berada dalam salah satu dari tiga status: processing, success, atau failed. Lakukan polling tidak lebih sering dari setiap 30 detik. Loop yang lebih ketat menambah beban tanpa membuat tugas selesai lebih cepat, dan tidak ada waktu penyelesaian yang didokumentasikan, jadi rencanakan berdasarkan status, bukan jam.

Sebelum proses utama, file akan diproses sebelumnya. Baris yang tidak valid, duplikat, nomor tanpa kode negara, dan nomor di luar negara yang dipilih akan dikecualikan, dan baris yang dikecualikan tidak akan dikenakan biaya. Tugas juga dapat gagal selama persiapan jika file tidak memenuhi ketentuan penerimaan, dalam hal ini jumlah yang dicadangkan akan kembali ke dompet Anda secara penuh.

Jika berhasil, Anda mengunduh satu CSV, bukan ZIP. Kolomnya adalah pengenal, operator, operator dasar, jenis nomor, kode negara, wilayah, dan kota. Dalam CSV, pengenal berupa angka biasa dengan kode negara dan tanpa tanda plus, jadi normalisasikan kunci Anda sendiri sebelum menggabungkan file kembali ke database. Sel kosong berarti nilai tidak tersedia.

Memilih berdasarkan ukuran daftar, campuran negara, dan alur kerja

Mulailah dengan bentuk data Anda, bukan jumlah mentah.

1. Grup campuran negara yang membutuhkan jawaban sekarang. Gunakan permintaan multi sinkron. Tugas satu file akan memaksa Anda untuk membagi daftar berdasarkan negara terlebih dahulu.
2. Daftar besar yang pada dasarnya satu negara. Gunakan tugas file. Pilih negara, kirim file, dan biarkan pra-pemrosesan menghapus duplikat dan nomor yang tidak sesuai.
3. Daftar campuran negara yang besar. Bagi berdasarkan kode negara, lalu kirim satu tugas file per negara. Apa pun yang tidak sesuai dengan file negara dapat melalui permintaan multi dalam potongan hingga 100 nomor.
4. Pemeriksaan per catatan di dalam pendaftaran atau entri CRM. Gunakan pemeriksaan nomor tunggal, POST /api/v1/check. Nomor dari Tiongkok daratan, Hong Kong, dan Makau hanya didukung melalui pemeriksaan nomor tunggal waktu nyata dalam volume kecil, jadi arahkan ke sana, bukan ke permintaan multi atau file.

Pekerjaan bulk juga cocok untuk tugas batch yang berjalan semalaman atau di antara kampanye, karena Anda mengirim, melakukan polling, dan mengumpulkan. Permintaan multi cocok untuk loop yang sudah memproses data dalam potongan kecil dan dapat menulis hasil langsung kembali ke database atau CRM.

Penagihan dan pemeriksaan saldo untuk kedua jalur

Kedua jalur menggunakan satu saldo bersama, dan setiap nomor yang selesai dikenakan biaya dengan tarif yang dipublikasikan sama. Pencarian yang gagal atau tidak dapat ditentukan tidak dikenakan biaya. Pencarian yang selesai yang kolom operatornya kosong tetap merupakan pencarian yang selesai dan tetap dapat dikenakan biaya, jadi jangan membaca baris kosong sebagai gratis atau sebagai bukti bahwa tidak ada operator.

Tugas file mencadangkan jumlah estimasi saat pengiriman dan kemudian hanya mengenakan biaya pada nomor yang mengembalikan hasil. Bagian cadangan yang tidak terpakai, atau seluruh cadangan dari tugas yang gagal, kembali ke dompet yang sama. Ini adalah rekonsiliasi di dalam saldo Anda, bukan pengembalian dana pembelian.

Sebelum pengiriman besar apa pun, baca saldo dengan GET /api/v1/balance. Panggilan tersebut tidak membebankan biaya apa pun, dan memberi tahu Anda apakah cadangan akan mencukupi. Tambahkan pemeriksaan yang sama ke tugas terjadwal agar saldo rendah menghentikan proses sebelum dimulai, alih-alih gagal di tengah alur kerja.

Membaca hasil dengan benar

Jalur mana pun yang Anda pilih, data tersebut memiliki arti yang sama. Operator adalah operator tempat rentang nomor tersebut awalnya dialokasikan. Ini bukan jaringan yang melayani nomor tersebut saat ini, karena porting dapat memindahkan nomor tanpa mengubah alokasi asli. Operator dasar dan jenis nomor menambahkan konteks, serta wilayah dan kota menjelaskan geografi alokasi, bukan di mana orang atau perangkat berada.

Hal itu membuat output berguna untuk pengelompokan, pengujian perutean, dan antrean peninjauan. Ini bukan bukti bahwa nomor dapat menerima panggilan atau pesan, bahwa nomor tersebut aktif, atau siapa pemiliknya.

Simpan setiap bidang sebagai atribut alokasi asli, biarkan nilai kosong diberi label sebagai tidak tersedia, dan hindari menimpa bidang apa pun yang telah dikonfirmasi oleh sistem Anda sendiri dengan cara lain. Tim yang memperlakukan bidang ini sebagai konteks alokasi menghindari sebagian besar perselisihan di kemudian hari tentang apa yang dijanjikan oleh data tersebut.

FAQ

Bagaimana tim dapat memutuskan antara permintaan multi dan tugas file?

Lihat bentuk daftar terlebih dahulu. Sekelompok nomor campuran negara yang membutuhkan jawaban berurutan segera cocok dengan permintaan multi. Daftar besar yang pada dasarnya satu negara cocok dengan tugas file, yang berjalan di latar belakang dan berakhir dalam satu CSV. Batasan per produk berlaku, jadi konfirmasikan dokumentasi API saat ini sebelum menentukan ukuran jalur mana pun.

Bagaimana tim dapat menangani urutan hasil dalam permintaan multi?

Hasil kembali dalam urutan yang sama seperti saat nomor dikirim, jadi simpan daftar Anda sendiri dalam urutan yang stabil dan cocokkan berdasarkan posisi. Perlakukan hasil tidak ada sebagai tidak ada hasil normal, bukan sebagai nomor tidak valid, dan coba lagi hanya baris yang Anda perlukan setelah memperbaiki masalah format apa pun.

Bagaimana tim dapat menghindari polling yang sia-sia pada tugas bulk?

Lakukan polling status tugas tidak lebih sering dari setiap 30 detik dan berhenti saat statusnya success atau failed. Tidak ada waktu penyelesaian yang didokumentasikan, jadi bangun pekerjaan berdasarkan status. Jika berhasil, unduh CSV tunggal dan normalisasikan pengenal sebelum menggabungkannya ke catatan yang ada.

Pelajari Lebih Lanjut

Pilih informasi produk yang sesuai dengan langkah selanjutnya dalam alur kerja Anda.

• Lihat dokumentasi produk →
• Hubungi tim →