API Pencarian Operator Asli Massal: Mengirim Tugas Berkas dan Melakukan Polling untuk CSV

Panduan pengembang untuk tugas berkas massal CarrierLookup: mengirimkan TXT atau CSV dengan negara, status polling, dan membaca hasil CSV tunggal.

API Pencarian Operator Asli massal CarrierLookup adalah tugas berkas asinkron. Kirim permintaan multipart ke POST /api/v1/bulk-tasks dengan kolom negara ditempatkan sebelum berkas, lalu baca status dari GET /api/v1/bulk-tasks/{id} tidak lebih sering dari setiap 30 detik hingga statusnya success atau failed. Tugas yang berhasil akan mengembalikan satu CSV yang dapat diunduh dengan operator asli, operator dasar, jenis nomor, dan kolom alokasi. Rute ini cocok untuk daftar besar untuk satu negara. Batas per produk berlaku, jadi konfirmasikan terlebih dahulu dalam dokumentasi API.

Siapkan berkas sebelum Anda memanggil API

Berkas yang bersih menghemat lebih banyak waktu daripada logika percobaan ulang apa pun. Rute massal menerima berkas TXT atau CSV satu kolom dengan satu nomor berkode negara per baris. XLSX tidak diterima, jadi ekspor lembar kerja ke teks biasa atau CSV terlebih dahulu.

Tulis setiap baris sebagai digit dengan kode negara. Pastikan daftar tersebut pada dasarnya hanya satu negara, karena satu negara dipilih untuk tugas tersebut dan nomor di luar negara tersebut akan dikecualikan.

Rutinitas persiapan singkat:

1. Ekspor satu kolom dan hapus header atau catatan.
2. Normalisasikan setiap baris ke bentuk digit berkode negara.
3. Bagi daftar utama berdasarkan negara dan buat satu berkas per negara.
4. Periksa berkas terhadap batas saat ini dalam dokumentasi API. Batas ukuran berkas default yang didokumentasikan di sana dapat digantikan oleh batas yang dikembalikan oleh layanan langsung, jadi nilai langsunglah yang berlaku.

Pra-pemrosesan akan mengecualikan baris yang tidak valid, duplikat, nomor tanpa kode negara, dan nomor di luar negara yang dipilih, dan tidak ada satu pun dari hal tersebut yang dikenakan biaya. Menghapusnya sendiri terlebih dahulu memberi Anda gambaran yang lebih jelas tentang berapa banyak baris yang sebenarnya Anda kirimkan. Simpan salinan berkas yang tepat yang Anda kirimkan, beserta jumlah barisnya, sehingga Anda dapat mencocokkan CSV akhir dengan daftar sumber Anda nanti dan melihat baris mana yang terbuang.

Kirim tugas dengan permintaan multipart

Kirim dengan POST /api/v1/bulk-tasks dari server tepercaya. Lakukan autentikasi dengan header X-API-Key, dan jangan pernah mengekspos kunci tersebut dalam kode peramban.

Isinya adalah data formulir multipart dengan dua bagian: negara yang dipilih dan berkas. Urutan itu penting, jadi letakkan bagian negara sebelum bagian berkas. Banyak klien HTTP membangun isi dari kamus, dan urutannya mungkin mengikuti urutan penyisipan, jadi periksa bagaimana klien Anda membuat serialisasinya.

Sketsa panggilan dengan curl:

curl -X POST https://carrierlookup.online/api/v1/bulk-tasks \
  -H "X-API-Key: $CARRIERLOOKUP_API_KEY" \
  -F "country=GB" \
  -F "file=@uk_numbers.csv"

Gunakan kode negara ISO yang sesuai dengan daftar. Respons memberi Anda cara untuk merujuk tugas untuk polling, jadi simpan referensi tersebut dengan catatan pekerjaan Anda sendiri. Jangan membuat kolom tambahan, array JSON nomor, webhook, atau panggilan pembatalan. Hanya pengiriman berkas dan pembacaan status yang didokumentasikan.

Lakukan polling tugas tanpa membebani API

Baca status 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 sekali setiap 30 detik. Perulangan yang lebih rapat tidak mempercepat pekerjaan. Tidak ada waktu penyelesaian normal yang didokumentasikan, dan tidak ada progres per nomor, jadi bangun perulangan di sekitar status alih-alih menebak durasi.

import time, requests

def wait_for_task(task_ref, headers):
    while True:
        r = requests.get(f"https://carrierlookup.online/api/v1/bulk-tasks/{task_ref}", headers=headers, timeout=30)
        state = r.json()["data"]["status"]
        if state in ("success", "failed"):
            return state
        time.sleep(30)

Perlakukan nama kolom dalam sketsa ini sebagai placeholder, dan ambil bentuk respons yang tepat dari dokumentasi API. Dalam produksi, tambahkan waktu tunggu maksimum yang sesuai dengan jadwal pekerjaan Anda, simpan status yang terakhir diamati, dan biarkan peringatan operator muncul jika tugas tetap dalam status processing lebih lama dari toleransi Anda sendiri.

Unduh dan baca CSV

Ketika statusnya success, unduh hasilnya. Anda menerima satu CSV, bukan ZIP. Berkas tersebut berisi pengenal, operator, operator dasar, jenis nomor, kode negara, wilayah, dan kota untuk nomor yang mengembalikan hasil.

Tiga aturan membaca:

• Pengenal tidak memiliki tanda plus. Ini adalah digit biasa dengan kode negara dan tanpa spasi. Normalisasikan kunci Anda sendiri dengan cara yang sama sebelum menggabungkannya.
• Sel kosong berarti Tidak dapat ditentukan. Biarkan sebagai nilai yang tidak tersedia dan jangan mengubahnya menjadi kesimpulan negatif.
• Operator adalah alokasi asli. Ini bukan operator saat ini setelah porting. Wilayah dan kota menjelaskan geografi alokasi, bukan di mana orang atau perangkat berada.

Muat berkas ke dalam tabel staging terlebih dahulu, lalu gabungkan ke dalam catatan kontak Anda berdasarkan kunci. Simpan referensi tugas dan tanggal jalankan di tabel staging, sehingga audit nanti dapat mengetahui jalankan mana yang menghasilkan nilai mana. Ingatlah bahwa CSV tidak memiliki kolom yang menyatakan apakah suatu nomor dapat dihubungi, dan aturan Anda sendiri tidak boleh menyimpulkannya.

Kegagalan, reservasi, dan saldo

Tugas massal mencadangkan perkiraan biaya saat Anda mengirimkannya dan hanya mengenakan biaya pada nomor yang mengembalikan hasil. Bagian yang tidak terpakai dari cadangan akan kembali ke dompet yang sama saat tugas selesai, dan tugas yang gagal akan mengembalikan seluruh cadangannya. Ini adalah rekonsiliasi di dalam saldo Anda dan bukan pengembalian dana pembelian.

Tugas dapat gagal selama persiapan, misalnya ketika terlalu sedikit nomor seluler valid yang diperkirakan atau kondisi penerimaan lainnya tidak terpenuhi. Jika itu terjadi, tinjau berkas untuk pengecualian yang dijelaskan di atas, perbaiki daftar, dan kirim tugas baru alih-alih mencoba kembali berkas yang sama secara membabi buta.

Periksa GET /api/v1/balance sebelum mengirim. Ini membaca saldo tanpa mengenakan biaya apa pun. Dalam pekerjaan terjadwal, bandingkan saldo dengan ukuran daftar yang Anda harapkan dan berhenti lebih awal jika saldo kurang, karena cadangan yang tidak mencukupi akan menghentikan tugas. Untuk kelompok sisa kecil setelah pemisahan negara, permintaan multi sinkron melalui POST /api/v1/batch-check mungkin lebih sederhana daripada tugas berkas lainnya.

FAQ

Bagaimana pengembang dapat mengirim tugas massal tanpa kesalahan multipart?

Letakkan kolom negara sebelum kolom berkas dalam isi multipart, kirim berkas sebagai TXT atau CSV biasa dengan satu nomor berkode negara per baris, dan simpan kunci API di header X-API-Key dari server tepercaya. Periksa bagaimana klien HTTP Anda mengurutkan kolom formulir.

Bagaimana pengembang dapat memilih interval polling untuk status tugas?

Lakukan polling panggilan status tidak lebih sering dari sekali setiap 30 detik dan berhenti ketika statusnya success atau failed. Tidak ada waktu penyelesaian normal atau progres per nomor yang didokumentasikan, jadi tetapkan waktu tunggu maksimum Anda sendiri dan beri tahu operator ketika tugas melampauinya.

Bagaimana tim dapat menangani tugas massal yang gagal?

Baca kegagalan sebagai sinyal tentang berkas atau kondisi penerimaan. Reservasi dikembalikan sepenuhnya, jadi tinjau daftar untuk baris yang tidak valid, duplikat, kode negara yang hilang, dan nomor di luar negara yang dipilih, perbaiki, dan kirim tugas baru.

Pelajari Lebih Lanjut

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

• Lihat dokumentasi produk →
• Bicara dengan tim →