Telefon Operatörü Sorgulama API'si: Tek İstek, Tek Orijinal Operatör Sonucu

Tekil bir telefon numarası operatör sorgulama API çağrısı için geliştirici kılavuzu: istek, sonuç okuma, hata yönetimi ve çoklu isteklere ne zaman geçileceği.

Bir telefon operatörü sorgulama API'si, sunucunuzdan bir telefon numarası alır ve o numara aralığının orijinal olarak tahsis edildiği operatörü ve ilgili bağlamı döndürür. CarrierLookup ile güvenilir bir arka uç, bir E.164 numarayı X-API-Key başlığı ile POST /api/v1/check adresine gönderir ve eşzamanlı bir sonuç alır: orijinal operatör, temel operatör, numara türü, ülke kodu ile tahsis bölgesi ve şehri. Operatör, numara taşıma işleminden sonraki ağ değil, orijinal tahsis bilgisidir. Boş alanlara sahip tamamlanmış bir sonuç yine de tamamlanmış bir sorgulamadır; belirlenemedi durumu ise sıfır olmayan bir iş kodu döndürür. Tek bir çağrıda 100 numaraya kadar işlem yapmak için POST /api/v1/batch-check yöntemine geçin.

Bir telefon operatörü sorgulama API'si ne döndürür?

Birçok operatör sorgulama sayfası iki farklı soruyu birbirine karıştırır: bu numara aralığı kime verildi ve numaraya bugün kim hizmet veriyor. CarrierLookup ilk soruyu yanıtlar. Operatör sonucu, numara bloğunun ulusal numaralandırma planı kapsamında orijinal olarak tahsis edildiği operatörü belirtir. FCC numara taşıma kılavuzunda açıklandığı üzere, numara taşıma özelliğinin bulunduğu ülkelerde abone, numarasını koruyarak başka bir sağlayıcıya geçebilir; bu nedenle orijinal operatör ile mevcut sağlayıcı farklı olabilir.

Basit bir dille açıklanan tamamlanmış tekil bir sonuç şunları içerir:

• Orijinal operatör: aralığın tahsis edildiği operatör.
• Temel operatör: bir değer mevcut olduğunda, o operatörün arkasındaki ağ.
• Numara türü: mobil veya sabit hat gibi aralık türü.
• Ülke kodu, bölge ve şehir: bir kişinin veya cihazın bulunduğu yer değil, aralığın tahsis edildiği yer.

Bunları gruplandırma, yönlendirme testleri ve inceleme için tahsis bağlamı olarak değerlendirin. Bir operatör sonucu, bir numaranın kullanımda olduğunu, arama veya SMS alabildiğini ya da belirli bir kişiye ait olduğunu göstermez.

Operatör sorgulama API'sine tek bir numara gönderme

Tekil numara rotası, kısa ve eşzamanlı bir istektir. Tipik bir entegrasyon beş adımı izler:

1. Anahtarı güvenilir bir sunucuda tutun. REST API, bir X-API-Key başlığı ile kimlik doğrulaması yapar. Bu çağrıyı arka ucunuzdan veya bir iş çalıştırıcısından yapın; anahtarın kopyalanabileceği tarayıcı veya mobil uygulama kodundan asla yapmayın.
2. Girdiyi E.164 formatına normalleştirin. ITU-T E.164 planı, uluslararası formatı tanımlar. CarrierLookup; başında artı işareti, ülke kodu ve abone numarası olan, boşluk, tire veya parantez içermeyen bir format bekler. 020 7946 0000 olarak yazılan bir Birleşik Krallık numarası +442079460000 haline gelir. libphonenumber gibi kütüphaneler, kaydın ülkesi bilindiğinde yerel formatları ayrıştırabilir.
3. POST /api/v1/check adresine gönderin. İstek başına bir numara. Ülke kodu numaranın bir parçası olduğundan, ayrı bir ülke seçimine gerek yoktur.
4. Eşzamanlı yanıtı bekleyin. Sonuç aynı yanıt içinde geri döner; sorgulanacak bir şey yoktur.
5. Sonucu sorgulama tarihiyle saklayın. Tahsis verileri bir aralık için sabittir, ancak her sorgulamanın ne zaman yapıldığını kaydetmek denetimleri kolaylaştırır.

Girdi formatı nedeniyle reddedilirse, numarayı düzeltin ve tekrar gönderin. Bir format reddi, operatör hakkında hiçbir şey ifade etmez.

Tamamlanmış, boş ve belirlenemedi sonuçlarını okuma

En yaygın entegrasyon hatası, üç farklı sonucu tek bir sonuç gibi ele almaktır. Önce iş koduna, ardından değerlere göre dallanma yapın.

Tablodan iki kural çıkar. İkincisi, belirlenemedi durumu başarılı bir boş sonuç değildir, bu nedenle ondan gelen boş alanları asla CRM'inize yazmayın. Başarısız veya belirlenemedi sorgulamalar ücret kesmezken, alanları boş olsa bile tamamlanmış sorgulamalar ücret keser.

Temel operatör, bölge veya şehir gibi isteğe bağlı alanlar, aksi takdirde tamamlanmış sonuçlarda boş olabilir. Şemanızı, her alanın bağımsız olarak boş (null) olabileceği şekilde tasarlayın.

Zaman aşımları, eşzamanlılık ve bakiye yönetimi

Genel API, dakika başına bir kota yerine küçük bir kullanım kontrolü seti belgeler. Bir hesabın eşzamanlı istekler için paylaşılan beş uçuşta (in-flight) yuvası vardır ve aynı anda yalnızca bir çoklu istek çalışabilir. Tekil isteklerin 60 saniyelik belgelenmiş bir zaman aşımı sınırı vardır, bu nedenle HTTP istemcisi zaman aşımınızı birkaç saniye yerine bunun biraz üzerine ayarlayın.

Pratik yönetim:

• Flood yapmak yerine kuyruğa alın. Kayıt veya içe aktarma işiniz ani artışlar yaratıyorsa, uçuşta beşten fazla sorgulama olmaması için küçük bir işçi havuzu tutun.
• Belirlenemedi sonuçlarını aralıklarla tekrar deneyin. Bir gecikme ve tekrar deneme sınırı kullanın; sürekli ve anında tekrar denemeler nadiren yardımcı olur.
• İş kodunu ve mesajı günlüğe kaydedin. Bunlar, hataları yalnızca bir HTTP durumundan çok daha iyi açıklar.
• Bakiyeyi harcamadan okuyun. GET /api/v1/balance, büyük bir işten önce ön kontrol için uygun olan kalan bakiyeyi ücretsiz olarak döndürür.

Hesabınızdaki mevcut sınırlar için varsayımları kodlamak yerine API belgelerini kontrol edin; API sabit bir günlük istek sınırı yayınlamaz.

POST /api/v1/batch-check veya dosya görevine ne zaman geçilmeli?

Tekil numara rotası, olay odaklı işlere uygundur: bir form gönderimi, yeni bir CRM kaydı, bir destek temsilcisinin bir kişiyi kontrol etmesi. Bir iş düzenli olarak aynı anda birkaç numarayı işlediğinde, numara başına bir çağrı ek yük getirir.

• POST /api/v1/batch-check, tek bir eşzamanlı istekte 1 ila 100 E.164 numarayı kabul eder ve numaralar farklı ülkelerden gelebilir. Sonuçlar, girdiyle aynı sırada döner, böylece her satırı konumuna göre eşleyebilirsiniz. Her satır bir exists bayrağı taşır; false, o satır için normal bir sonuç olmadığı anlamına gelir, numaranın geçersiz veya bağlantısının kesik olduğu anlamına gelmez. Bir çoklu istek zaman aşımına uğrarsa, tüm istek kısmi sonuçlar olmadan başarısız olur ve ayrılan miktar tamamen iade edilir, bu nedenle grupları makul tutun ve grubu tekrar deneyin.
• Kontrol paneli, kod olmadan eşzamanlı çoklu sorgulama için 500 numaraya kadar kabul eder.
• Toplu dosya görevleri, tüm listeler için uygundur: tek bir CSV hazır olana kadar sorgulanan, seçili bir ülke için TXT veya CSV dosyasının eşzamansız yüklemesi. Ürün başına sınırlar geçerlidir; API belgelerine bakın.

Aynı sorgulamalar, tekil ve çoklu kontrolleri kapsayan ancak dosya görevlerini kapsamayan resmi MCP uç noktası aracılığıyla yapay zeka asistanları için de mevcuttur.

SSS

Ekipler boş bir operatör sonucunu başarısız bir sorgulamadan nasıl ayırt edebilir?

Herhangi bir değeri okumadan önce iş kodunu kontrol edin. Boş operatör alanlarına sahip bir başarı kodu, tamamlanmış bir sorgulamadır ve mevcut değil olarak saklanmalıdır. Sıfır olmayan bir kod, kontrolün belirlenemediği veya başarısız olduğu anlamına gelir; sonuç olarak hiçbir şey yazılmamalı ve kayıt daha sonra tekrar denenmeli veya incelemeye gönderilmelidir. Bu iki yolu ayrı tutmak, iyi kayıtların eksik veri olarak işaretlenmesini önler.

Operatör sorgulama API'si bir numaranın bugün kullandığı ağı gösterir mi?

Hayır. Operatör değeri, numara aralığının orijinal olarak tahsis edildiği operatördür. Bir abone numarayı taşıdıktan sonra, hizmet başka bir yere taşınsa bile o orijinal operatör sonuçta aynı kalır. Gruplandırma, yönlendirme testleri veya inceleme için tahsis bağlamına ihtiyaç duyan ekipler bunu doğrudan kullanabilir; mevcut hizmet ağı veya ulaşılabilirlik olarak değerlendirilmemelidir.

Bir ön uç (frontend), operatör sorgulama API'sini doğrudan çağırmalı mı?

Çağırmamalıdır. X-API-Key başlığı hesap bakiyesine erişim sağlar, bu nedenle çağrılar güvenilir bir sunucuda yapılmalıdır. Yaygın bir model, ön ucun telefon numarasını kendi arka ucunuza göndermesi, arka ucun bunu E.164'e normalleştirmesi, POST /api/v1/check çağrısını yapması, sonucu saklaması ve arayüzün görüntülemesi gerekenleri döndürmesidir.

Daha Fazla Bilgi

İş akışınızdaki bir sonraki adıma uygun ürün bilgisini seçin.

• Ürün belgelerini görüntüleyin →
• Ekiple görüşün →