Phone Carrier Bulk Lookup API: Toplu kontrol

Gönderilen her mobil numara için operatörü, altta yatan operatörü, hat türünü, ülke kodunu, bölgeyi ve şehri sorgular. Operatör tabanlı gruplamayı ve sanal numara taramasını basitleştirir. Görev, standart asenkron toplu iş akışını kullanır.

Girdi biçimi

Her satırda bir telefon numarası bulunan bir metin dosyası yükleyin. Yüklemeden önce değerleri normalleştirin; telefonlar için E.164 biçimi önerilir.

+14155552671
+13105551234

Görev başına tek ülke gönderin. Numaralar görevin ülkesine göre normalize edilir (aşağıdaki country_code); aynı dosyadaki başka ülkeye ait numaralar bu ülkeye yeniden yazılır ve doğru sonuç vermez.

Görev oluşturma

POST https://api.numberchecker.ai/v1/tasks

curl --location 'https://api.numberchecker.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="globalCarrier"' \
--form 'country_code="US"'

İstek parametreleri

Alan	Zorunlu	Açıklama
file	evet	Metin dosyası, satır başına bir telefon numarası.
task_type	evet	globalCarrier. Önceki ülkeye özel görev türleri (usaCarrier, deCarrier, gbCarrier, …) hâlâ kabul edilir ve aynı ürüne yönlenir.
country_code	hayır	Dosyadaki numaraların ISO-3166 alpha-2 ülke kodu (US, DE, OM, …). Ülke kodu olmadan yazılmış numaraları normalize etmek için kullanılır. Belirtilmezse dosyadan çıkarılır.

API bir görev kimliği döndürür. Bu kimliği saklayın ve görev durumunu sorgulamak için kullanın.

Yükleme yanıtı

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Görev durumunu kontrol etme

POST https://api.numberchecker.ai/v1/gettasks

curl --location 'https://api.numberchecker.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

status değeri exported olana kadar sorgulayın. pending ve processing tamamlanmış sonuç değildir.

İşleme yanıtı

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Dışa aktarılan yanıt

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

Sonuç alanları

Alan	Açıklama	Örnek
number	Gönderilen dosyadaki giriş telefon numarası.	+14155552671
number_type	Numara için döndürülen hat türü.	mobile
country_code	country_code value returned for the input.	örnek değer
carrier	Carrier value returned for the number.	Örnek Carrier
underlying_carrier	Carrier value returned for the number.	Örnek Carrier
region	region value returned for the input.	örnek değer
city	Girdi için döndürülen şehir değeri.	örnek değer

Sonuç dosyası işlemleri

Dosyayı result_url üzerinden yalnızca görev dışa aktarıldıktan sonra indirin. Dosyayı işlerken döndürülen sütun adlarını koruyun.

Yanıt alanları

Alan	Açıklama
created_at	Görevin oluşturulduğu zaman.
updated_at	Son görev durumu güncellemesinin zamanı.
task_id	Benzersiz görev tanımlayıcısı.
status	pending, processing, exported veya failed.
total	İşlenen toplam giriş değeri.
success	Başarıyla işlenen değerler.
failure	İşlenemeyen değerler.
result_url	Görev dışa aktarıldığında indirme URL’si.
actual_amount	Varsa kesinleşen tutar.
estimated_amount	Görev oluşturulurken döndürülen tahmini tutar.

Durum kodları

Status	Açıklama
200	İstek başarılı.
202	Görev başarıyla oluşturuldu ve tahmini ücret uygulandı.
400	Geçersiz dosya, desteklenmeyen görev türü veya çok az geçerli giriş.
401	API anahtarı eksik veya geçersiz.
402	Yetersiz hesap bakiyesi.
403	Ürün hesabınız için kullanılamıyor (kaldırıldı veya yalnızca beyaz listedeki müşterilere açık); destekle iletişime geçin.
404	Görev bulunamadı.
413	Yüklenen dosya çok büyük.
500	Dahili sunucu hatası; daha sonra tekrar deneyin.
503	Ürün geçici olarak kullanılamıyor (bakım için duraklatıldı); ücret alınmaz, daha sonra tekrar deneyin.

Operasyon notları

• Görev eşzamansızdır; durumu sorgulamak için görev kimliğini kullanın.
• Yüklemeden önce ürüne özel giriş sınırlarını kontrol edin.
• Başarısız satırlar dışa aktarılan sonuçta raporlanır ve görev sayaçlarına yansıtılır.
• Yukarıdaki alanlar mevcut canlı sample temelindedir ve dışa aktarma şeması değişirse değişebilir.