API Deteksi Operator: Menambahkan Konteks Operator dan Jenis Saluran ke Backend Pendaftaran

Panduan integrasi backend untuk memanggil API deteksi operator setelah pendaftaran telepon, menyimpan operator asli dan jenis nomor sebagai konteks tinjauan, serta menangani kegagalan dengan aman.

API deteksi operator, dalam alur pendaftaran telepon, adalah panggilan sisi server yang mengambil nomor yang dikirimkan dan mengembalikan operator tempat rentang nomor tersebut awalnya dialokasikan, jenis nomor, dan geografi alokasi. Dengan CarrierLookup, backend menormalisasi nomor ke format E.164, mengirimkannya ke POST /api/v1/check dengan kunci API yang disimpan di server, dan menyimpan hasilnya di samping akun sebagai konteks tinjauan. Penempatan terbaik adalah setelah formulir diterima dan sebelum keputusan perutean atau tinjauan manual apa pun, sehingga pencarian yang lambat atau Tidak dapat ditentukan tidak akan pernah menghalangi pengguna untuk menyelesaikan pendaftaran.

Pencarian nomor telepon vs deteksi operator berbasis IP

Pencarian untuk API deteksi operator akan menghasilkan dua jenis layanan yang berbeda, dan memilih layanan yang salah akan membuang-buang waktu sprint integrasi Anda.

Backend pendaftaran yang ingin memahami nomor telepon yang diketik seseorang memerlukan jenis yang kedua. Pencarian IP tidak memberikan informasi apa pun tentang nomor tersebut, dan pencarian nomor tidak memberikan informasi apa pun tentang sesi penelusuran. Beberapa tim menyimpan keduanya, tetapi keduanya menjawab pertanyaan yang berbeda dan harus ditempatkan di kolom terpisah dengan nama yang terpisah.

Di mana panggilan API deteksi operator ditempatkan dalam pendaftaran

Tempatkan pencarian di backend, setelah validasi formulir Anda sendiri dan sebelum keputusan apa pun yang menggunakan outputnya. Urutan yang berhasil untuk sebagian besar produk:

1. Terima formulir. Periksa apakah kolom telepon ada dan diformat dengan benar.
2. Normalisasi ke E.164. Konversi input menjadi tanda plus, kode negara, dan digit pelanggan tanpa spasi, sebagaimana didefinisikan dalam ITU-T E.164. Pemeriksaan sinkron tidak memerlukan pemilihan negara terpisah, sehingga kode negara di dalam nomor tersebut membawa informasi tersebut.
3. Buat akun dalam status konteks tertunda. Jangan biarkan respons HTTP terbuka saat menunggu pencarian jika halaman pendaftaran Anda memiliki anggaran latensi yang ketat.
4. Panggil POST /api/v1/check dari pekerjaan atau pekerja dengan satu nomor.
5. Simpan hasilnya dengan waktu pencarian dan status seperti selesai, kosong, atau Tidak dapat ditentukan.
6. Terapkan aturan Anda sendiri. Rute akun, tambahkan ke antrean tinjauan manual, atau jangan lakukan apa pun.

Menjalankan panggilan dalam antrean menjaga pendaftaran tetap responsif dan memberikan tempat alami untuk percobaan ulang.

Apa yang harus disimpan dari setiap pencarian

Pemeriksaan yang selesai menjelaskan alokasi nomor dalam istilah sederhana: operator asli, operator dasar ketika sebuah merek berjalan di jaringan lain, jenis nomor seperti seluler atau saluran tetap, kode negara, serta wilayah dan kota yang terlampir pada rentang tersebut. Simpan ini dalam kolom yang namanya menjelaskan isinya, misalnya original_carrier alih-alih carrier, dan allocation_region alih-alih location. Wilayah dan kota menjelaskan di mana rentang tersebut dialokasikan, yang bukan merupakan lokasi orang yang mendaftar.

Simpan tiga nilai lagi di sampingnya:

• Stempel waktu pencarian, agar peninjau mengetahui seberapa lama konteks tersebut.
• Hasil: selesai dengan nilai, selesai dengan nilai kosong, atau Tidak dapat ditentukan.
• Input yang dikirim, string E.164 yang tepat, yang membuat audit dan pemeriksaan ulang di kemudian hari menjadi mudah.

Hasil yang selesai dapat kembali dengan setiap kolom operator kosong. Simpan sebagai selesai-kosong, bukan sebagai kegagalan dan bukan sebagai bukti apa pun tentang akun tersebut. Perbedaan itu penting nantinya ketika seseorang membuat dasbor di atas kolom-kolom ini.

Menangani waktu tunggu, hasil Tidak dapat ditentukan, dan input yang ditolak

Tiga bentuk kegagalan memerlukan jalur kode yang berbeda, dan menggabungkannya adalah bug integrasi yang paling umum.

API publik mendokumentasikan batas waktu untuk permintaan tunggal dan multi, serta sejumlah slot sinkron dalam penerbangan bersama yang terbatas per akun. Jaga konkurensi pekerja Anda di bawah anggaran bersama tersebut daripada memicu satu permintaan per pendaftaran secara paralel selama lonjakan lalu lintas. Pencarian yang gagal atau Tidak dapat ditentukan tidak dikenakan biaya, sehingga kebijakan percobaan ulang tidak perlu khawatir tentang penagihan ganda, tetapi tetap harus membatasi upaya, misalnya tiga kali percobaan yang tersebar selama satu jam, lalu biarkan akun dengan status Tidak dapat ditentukan untuk peninjau.

Menyimpan kunci API di server

REST API melakukan autentikasi dengan header X-API-Key, yang hanya boleh dikirim dari server tepercaya. Jangan pernah memanggil pencarian dari JavaScript browser atau bundel aplikasi seluler; siapa pun dapat mengekstrak kunci yang dikirim ke klien dan menghabiskan saldo Anda dengannya.

Kontrol praktis, sejalan dengan OWASP Secrets Management Cheat Sheet:

• Muat kunci dari manajer rahasia atau penyimpanan rahasia platform penerapan, bukan dari kode sumber.
• Berikan akses baca hanya kepada pekerja pencarian.
• Rotasi kunci sesuai jadwal dan segera setelah dicurigai adanya kebocoran.
• Jangan pernah menulis kunci, atau header permintaan lengkap, ke dalam log aplikasi.
• Pantau saldo akun dengan GET /api/v1/balance, yang membaca saldo tanpa membebankan biaya, dan beri peringatan pada penurunan mendadak yang tidak sesuai dengan volume pendaftaran.

Lindungi juga pemicunya sendiri. Batasi kecepatan titik akhir pendaftaran Anda sendiri agar pengiriman formulir otomatis tidak berubah menjadi aliran pencarian berbayar.

Menggunakan hasil dalam perutean dan tinjauan

Perlakukan operator dan jenis nomor sebagai input untuk aturan yang dimiliki tim Anda, bukan sebagai vonis. Beberapa contoh yang digunakan tim:

• Pengujian perutean. Kelompokkan akun baru berdasarkan operator asli dan bandingkan kinerja penyedia pesan yang berbeda untuk setiap grup dalam metrik Anda sendiri.
• Antrean tinjauan. Kirim akun yang jenis nomornya di luar ekspektasi produk, seperti nomor saluran tetap pada aplikasi seluler, kepada peninjau dengan konteks yang terlampir.
• Kualitas data. Tandai pendaftaran di mana kode negara nomor dan negara yang dipilih dalam formulir tidak sesuai, sehingga dukungan dapat meminta koreksi.

Tuliskan aturannya dan pastikan aturan tersebut dapat dibalik. Peninjau yang melihat akun yang ditandai harus melihat nilai pencarian, waktu pencarian, dan aturan yang dipicu. Karena operator mencerminkan alokasi asli, hasil tidak pernah berdiri sendiri sebagai bukti bahwa telepon dapat menerima kode atau milik orang yang mendaftar; pasangkan dengan langkah verifikasi Anda yang ada.

FAQ

Bagaimana tim dapat memeriksa banyak akun yang sudah ada yang mendaftar sebelum integrasi?

Gunakan POST /api/v1/batch-check untuk katalog lama dalam grup hingga 100 nomor E.164 per permintaan. Hasil kembali dalam urutan input, dan setiap baris menyatakan apakah hasil normal ada. Baris tanpa hasil normal harus ditandai untuk percobaan ulang nanti alih-alih dicatat sebagai kosong. Daftar historis yang sangat besar lebih baik ditangani sebagai tugas file massal asinkron yang dikirim per negara.

Bagaimana backend dapat menghindari pembayaran untuk nomor yang sama dua kali?

Simpan cache yang dikunci pada string E.164 yang dinormalisasi dengan waktu pencarian. Ketika sebuah nomor sudah memiliki hasil yang selesai dari pemeriksaan baru-baru ini, gunakan kembali hasil tersebut alih-alih memanggil API lagi. Konteks alokasi berubah perlahan, sehingga banyak tim hanya menyegarkan ketika catatan diedit atau ketika hasil yang disimpan lebih lama dari periode yang mereka pilih, seperti beberapa bulan.

Bagaimana pengembang dapat menguji integrasi sebelum ditayangkan?

Arahkan pekerja ke konfigurasi pementasan dengan kunci API-nya sendiri dan saldo kecil, lalu jalankan serangkaian kasus yang dibuat skrip: nomor seluler yang valid, nomor saluran tetap, input yang gagal dalam normalisasi E.164, dan waktu tunggu yang dipaksakan. Konfirmasikan setiap jalur menulis status hasil yang diharapkan dan tidak ada kunci atau header yang muncul di log sebelum mengaktifkan lalu lintas produksi.

Pelajari Lebih Lanjut

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

• Lihat dokumentasi produk →
• Bicara dengan tim →