API Dokümantasyonu

BinVerify REST API başvuru kılavuzu: kimlik doğrulama, her aracın istek alanları, yanıt zarfı, hata kodları, limitler ve sandbox anahtarları.

Genel Bakış

Planınızdaki her araç, HTTPS üzerinden tek bir POST uç noktası olarak kullanılabilir. İstekler ve yanıtlar JSON biçimindedir; tüm zaman damgaları UTC'dir.

Temel URL https://binverify.com/api/v1
Metot POST
Content-Type application/json
Uç nokta POST /api/v1/tool/{slug}

{slug}, aşağıdaki araç başvurusunda listelenen araç tanımlayıcısıdır; örneğin bin-lookup.

Kimlik Doğrulama

API anahtarınızı her isteğin Authorization başlığında Bearer token olarak gönderin. API rotalarında oturum çerezleri kabul edilmez.

Authorization: Bearer bv_pk_live_0123456789abcdef0123456789abcdef

Anahtarlar yalnızca oluşturulurken bir kez gösterilir. bv_pk_live_ (canlı) veya bv_pk_test_ (sandbox) ön ekinin ardından 32 karakter gelir. Yalnızca özet (hash) saklandığından kaybolan bir anahtarın yenisiyle değiştirilmesi gerekir.

Anahtarlarınızı panelinizdeki API Anahtarları sayfasından oluşturabilir, yetkilendirebilir, kısıtlayabilir ve iptal edebilirsiniz. Bir anahtar yalnızca yetki olarak seçilen araçlarda çalışır.

Her istekte yapılan kontroller

Kontroller bu sırayla çalışır; ilk başarısız kontrol isteği gösterilen durum koduyla sonlandırır.

  1. Bearer token içeren Authorization başlığı mevcut — aksi halde 401.
  2. Anahtar ön eki bv_pk_live_ veya bv_pk_test_ — aksi halde 401.
  3. Anahtar mevcut, aktif ve süresi dolmamış — aksi halde 401.
  4. Anahtarda IP izin listesi tanımlıysa istek IP'si listede — aksi halde 403.
  5. Araç, anahtarın yetkileri arasında — aksi halde 403.
  6. Planınız API erişimi içeriyor — aksi halde 403.
  7. Planınızın hız limiti — aksi halde 429 rate_limit_exceeded.
  8. Araç için aylık kota veya kredi (yalnızca canlı anahtarlar) — aksi halde 429 quota_exceeded veya 403.
İstek Biçimi

Aracın alanlarını, Content-Type: application/json başlığıyla istek gövdesinde bir JSON nesnesi olarak gönderin. Form kodlamalı gövdeler (application/x-www-form-urlencoded) de kabul edilir.

POST /api/v1/tool/bin-lookup HTTP/1.1
Host: binverify.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
    "bin": "411111"
}
  • Boolean alanlar: JSON true/false (veya 1/0) gönderin. “true” ve “false” dizeleri çoğu araçta true olarak değerlendirilir.
  • Aralık dışındaki sayısal seçenekler en yakın sınıra çekilir, listede bulunmayan seçenek değerleri varsayılana döner; istek reddedilmez.
  • Eksik veya hatalı biçimli bir zorunlu alan, alanı meta.validation_errors içinde belirten 400 yanıtı döndürür.
Araç Başvurusu

Her araç için bir bölüm: uç nokta, istek alanları ve bir istek örneği. Alan kuralları, API'nin yaptığı doğrulamayı birebir yansıtır.

Araç Uç nokta
BIN Sorgulama POST /api/v1/tool/bin-lookup
IP Adresi Sorgulama POST /api/v1/tool/ip-info
VPN ve Proxy Tespiti POST /api/v1/tool/ip-probe
IP Kara Liste Kontrolü POST /api/v1/tool/ip-blocklist
Telefon Numarası Doğrulama POST /api/v1/tool/phone-validate
E-posta Doğrulama POST /api/v1/tool/email-verify
E-posta Adresi Kontrolü POST /api/v1/tool/email-validate
Alan Adı Sorgulama POST /api/v1/tool/domain-lookup
QR Kod Oluşturucu POST /api/v1/tool/qr-code
HTTP Durum Kontrolü POST /api/v1/tool/url-info
User Agent Çözümleme POST /api/v1/tool/ua-lookup
Görsel Filigran POST /api/v1/tool/image-watermark
Görsel Boyutlandırma POST /api/v1/tool/image-resize
HTML'den PDF'ye Dönüştürme POST /api/v1/tool/html-render
HTML Temizleme POST /api/v1/tool/html-clean
Adresten Koordinat Bulma POST /api/v1/tool/geocode-address
Koordinattan Adres Bulma POST /api/v1/tool/geocode-reverse
Sayfa İçeriği Çıkarma POST /api/v1/tool/browser-bot
DNSBL Kontrolü POST /api/v1/tool/host-reputation
Küfür Filtresi POST /api/v1/tool/bad-word-filter
Döviz ve Birim Çevirici POST /api/v1/tool/convert
BIN Sorgulama bin-lookup

Uç nokta: POST https://binverify.com/api/v1/tool/bin-lookup

Alan Tip Zorunlu Açıklama Örnek
bin string Evet Kart numarasının ilk 6–8 hanesi (yalnızca rakam). 411111

İstek örneği

{
    "bin": "411111"
}
IP Adresi Sorgulama ip-info

Uç nokta: POST https://binverify.com/api/v1/tool/ip-info

Alan Tip Zorunlu Açıklama Örnek
ip string Evet IPv4 veya IPv6 adresi ya da 192.0.2.0/24 gibi bir CIDR bloğu. 8.8.8.8
reverse_lookup boolean Hayır Ana bilgisayar adını da çözümle. Varsayılan false. true

İstek örneği

{
    "ip": "8.8.8.8",
    "reverse_lookup": true
}
VPN ve Proxy Tespiti ip-probe

Uç nokta: POST https://binverify.com/api/v1/tool/ip-probe

Alan Tip Zorunlu Açıklama Örnek
ip string Evet IPv4 veya IPv6 adresi ya da bir CIDR bloğu. 8.8.8.8

İstek örneği

{
    "ip": "8.8.8.8"
}
IP Kara Liste Kontrolü ip-blocklist

Uç nokta: POST https://binverify.com/api/v1/tool/ip-blocklist

Alan Tip Zorunlu Açıklama Örnek
ip string Evet IPv4 veya IPv6 adresi, CIDR bloğu ya da IP:port; birden çok giriş virgülle ayrılabilir. 198.51.100.1
vpn_lookup boolean Hayır VPN ve proxy verilerini de denetle. Varsayılan false; false iken is_vpn null döner. true

İstek örneği

{
    "ip": "198.51.100.1",
    "vpn_lookup": true
}
Telefon Numarası Doğrulama phone-validate

Uç nokta: POST https://binverify.com/api/v1/tool/phone-validate

Alan Tip Zorunlu Açıklama Örnek
number string Evet Uluslararası (+90…) veya yerel biçimde telefon numarası; rakam, boşluk ve + - ( ) . / karakterlerine izin verilir. +442079460018
country_code string Hayır Yerel biçimdeki numaralar için iki harfli ISO ülke kodu (otomatik olarak büyük harfe çevrilir). GB
ip string Hayır Yerel biçimdeki numaralarda ülkeyi belirlemek için kullanılan IP adresi. 8.8.8.8

İstek örneği

{
    "number": "+442079460018"
}
E-posta Doğrulama email-verify

Uç nokta: POST https://binverify.com/api/v1/tool/email-verify

Alan Tip Zorunlu Açıklama Örnek
email string Evet Doğrulanacak e-posta adresi (SMTP posta kutusu denetimi dahil). user@example.com
fix_typos boolean Hayır Doğrulamadan önce yaygın alan adı yazım hatalarını düzelt. Varsayılan false. true

İstek örneği

{
    "email": "user@example.com",
    "fix_typos": true
}
E-posta Adresi Kontrolü email-validate

Uç nokta: POST https://binverify.com/api/v1/tool/email-validate

Alan Tip Zorunlu Açıklama Örnek
email string Evet Geçerlenecek e-posta adresi (söz dizimi ve DNS/MX denetimi, SMTP yok). user@example.com
fix_typos boolean Hayır Geçerlemeden önce yaygın alan adı yazım hatalarını düzelt. Varsayılan false. true

İstek örneği

{
    "email": "user@example.com",
    "fix_typos": true
}
Alan Adı Sorgulama domain-lookup

Uç nokta: POST https://binverify.com/api/v1/tool/domain-lookup

Alan Tip Zorunlu Açıklama Örnek
host string Evet Alan adı, ana bilgisayar adı, FQDN, URL veya e-posta adresi. example.com
live boolean Hayır Canlı DNS denetimi yap. Varsayılan true. true

İstek örneği

{
    "host": "example.com",
    "live": true
}
QR Kod Oluşturucu qr-code

Uç nokta: POST https://binverify.com/api/v1/tool/qr-code

Bu araç için API yanıtı yalnızca istek parametrelerini (data nesnesi) içerir; üretilen dosya şu an API yanıtına dahil edilmemektedir. Dosyayı indirmek için paneli kullanın.

Alan Tip Zorunlu Açıklama Örnek
content string Evet Kodlanacak metin veya URL (en fazla 4096 karakter). https://example.com
width integer Hayır Görsel genişliği (piksel), 50–1000. Varsayılan 256. 256
height integer Hayır Görsel yüksekliği (piksel), 50–1000. Varsayılan 256. 256
fg_color string Hayır #RRGGBB biçiminde ön plan rengi. Varsayılan #000000. #000000
bg_color string Hayır #RRGGBB biçiminde arka plan rengi. Varsayılan #ffffff. #ffffff

İstek örneği

{
    "content": "https://example.com",
    "width": 256,
    "height": 256,
    "fg_color": "#000000",
    "bg_color": "#ffffff"
}
HTTP Durum Kontrolü url-info

Uç nokta: POST https://binverify.com/api/v1/tool/url-info

Alan Tip Zorunlu Açıklama Örnek
url string Evet Şema dahil mutlak URL. https://example.com/
fetch_content boolean Hayır Sayfa içeriğini getir ve çözümle. Varsayılan false. true
ignore_certificate_errors boolean Hayır TLS sertifika hatalarını yok say. Varsayılan false. false
timeout integer Hayır İstek zaman aşımı (saniye), 1–60. Varsayılan 60. 30
retry integer Hayır Hata durumunda yeniden deneme sayısı, 0–3. Varsayılan 0. 1

İstek örneği

{
    "url": "https://example.com/",
    "fetch_content": true
}
User Agent Çözümleme ua-lookup

Uç nokta: POST https://binverify.com/api/v1/tool/ua-lookup

Alan Tip Zorunlu Açıklama Örnek
ua string Evet Çözümlenecek User-Agent dizesi. Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.144 Mobile Safari/537.36
ua_version string Hayır İstemci ipucu: Sec-CH-UA tam sürüm. 120.0.6099.144
ua_platform string Hayır İstemci ipucu: Sec-CH-UA-Platform. Android
ua_platform_version string Hayır İstemci ipucu: Sec-CH-UA-Platform-Version. 13
ua_mobile string Hayır İstemci ipucu: Sec-CH-UA-Mobile (?1 veya ?0). ?1
ua_arch string Hayır İstemci ipucu: Sec-CH-UA-Arch. arm
ua_bitness string Hayır İstemci ipucu: Sec-CH-UA-Bitness. 64
ua_form_factors string Hayır İstemci ipucu: Sec-CH-UA-Form-Factors. Mobile
device_model string Hayır Biliniyorsa cihaz modeli. Pixel 7
device_brand string Hayır Biliniyorsa cihaz markası. Google

İstek örneği

{
    "ua": "Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.6099.144 Mobile Safari/537.36"
}
Görsel Filigran image-watermark

Uç nokta: POST https://binverify.com/api/v1/tool/image-watermark

Bu araç için API yanıtı yalnızca istek parametrelerini (data nesnesi) içerir; üretilen dosya şu an API yanıtına dahil edilmemektedir. Dosyayı indirmek için paneli kullanın.

Alan Tip Zorunlu Açıklama Örnek
image_url string Evet Filigran eklenecek görselin mutlak URL'si. https://example.com/photo.jpg
watermark_url string Evet Filigran görselinin mutlak URL'si. https://example.com/logo.png
opacity integer Hayır Filigran saydamlığı, 0–100. Varsayılan 50. 50
format string Hayır Çıktı biçimi: png veya jpg. Varsayılan png. png
position string Hayır center, top-left, top-center, top-right, bottom-left, bottom-center veya bottom-right. Varsayılan center. bottom-right
width integer Hayır Çıktı genişliği (piksel), 50–4000. 800
height integer Hayır Çıktı yüksekliği (piksel), 50–4000. 600
resize_mode string Hayır scale, pad veya crop. Varsayılan scale. scale
bg_color string Hayır transparent veya #RRGGBB. Varsayılan transparent. transparent

İstek örneği

{
    "image_url": "https://example.com/photo.jpg",
    "watermark_url": "https://example.com/logo.png",
    "opacity": 50,
    "position": "bottom-right"
}
Görsel Boyutlandırma image-resize

Uç nokta: POST https://binverify.com/api/v1/tool/image-resize

Bu araç için API yanıtı yalnızca istek parametrelerini (data nesnesi) içerir; üretilen dosya şu an API yanıtına dahil edilmemektedir. Dosyayı indirmek için paneli kullanın.

Alan Tip Zorunlu Açıklama Örnek
image_url string Evet Boyutlandırılacak görselin mutlak URL'si. https://example.com/photo.jpg
width integer Evet Çıktı genişliği (piksel), 50–4000. 800
height integer Hayır Çıktı yüksekliği (piksel), 50–4000. 600
format string Hayır Çıktı biçimi: png veya jpg. Varsayılan png. png
resize_mode string Hayır scale, pad veya crop. Varsayılan scale. scale
bg_color string Hayır transparent veya #RRGGBB. Varsayılan transparent. transparent

İstek örneği

{
    "image_url": "https://example.com/photo.jpg",
    "width": 800,
    "height": 600,
    "resize_mode": "scale"
}
HTML'den PDF'ye Dönüştürme html-render

Uç nokta: POST https://binverify.com/api/v1/tool/html-render

Bu araç için API yanıtı yalnızca istek parametrelerini (data nesnesi) içerir; üretilen dosya şu an API yanıtına dahil edilmemektedir. Dosyayı indirmek için paneli kullanın.

Alan Tip Zorunlu Açıklama Örnek
content string Evet URL (http:// veya https://) ya da ham HTML, en fazla 100000 karakter. https://example.com/
format string Hayır pdf, png veya jpg. Varsayılan pdf. pdf
title string Hayır Belge başlığı (en fazla 255 karakter). Example
page_size string Hayır A3, A4, A5, Letter, Legal veya Ledger. Varsayılan A4. A4
image_width integer Hayır png/jpg için görünüm alanı genişliği (piksel), 50–4000. Varsayılan 1024. 1024
image_height integer Hayır png/jpg için görsel yüksekliği (piksel), 50–4000. 768
margin number Hayır Sayfa kenar boşluğu, 0 veya daha büyük. Varsayılan 0. 10
landscape boolean Hayır Yatay yönlendirme. Varsayılan false. false
grayscale boolean Hayır Gri tonlamalı oluştur. Varsayılan false. false
zoom number Hayır Yakınlaştırma çarpanı, 0.1–5.0. Varsayılan 1.0. 1
bg_color string Hayır transparent veya #RRGGBB. #ffffff
css string Hayır Sayfaya eklenecek ek CSS. body { font-family: sans-serif; }
delay integer Hayır Oluşturmadan önce beklenecek saniye, 0–30. Varsayılan 0. 2
ignore_certificate_errors boolean Hayır TLS sertifika hatalarını yok say. Varsayılan false. false

İstek örneği

{
    "content": "https://example.com/",
    "format": "pdf",
    "page_size": "A4"
}
HTML Temizleme html-clean

Uç nokta: POST https://binverify.com/api/v1/tool/html-clean

Alan Tip Zorunlu Açıklama Örnek
content string Evet URL veya ham HTML, en fazla 100000 karakter. <p>Hello <b>world</b></p>
output_type string Evet plain-text, simple-text, basic-html, basic-html-with-images veya advanced-html. plain-text

İstek örneği

{
    "content": "<p>Hello <b>world</b></p>",
    "output_type": "plain-text"
}
Adresten Koordinat Bulma geocode-address

Uç nokta: POST https://binverify.com/api/v1/tool/geocode-address

Alan Tip Zorunlu Açıklama Örnek
address string Evet Serbest biçimli adres, en fazla 500 karakter. 1600 Pennsylvania Ave NW, Washington, DC
country_code string Hayır Aramayı daraltmak için iki harfli ISO ülke kodu. US
language_code string Hayır ar, de, en, es, fr, it, ja, nl, pt, ru veya zh. Varsayılan en. en
fuzzy_search boolean Hayır Yaklaşık eşleşmelere izin ver. Varsayılan false. false
limit integer Hayır En fazla sonuç sayısı, 1–32. Varsayılan 8. 5

İstek örneği

{
    "address": "1600 Pennsylvania Ave NW, Washington, DC",
    "country_code": "US",
    "limit": 5
}
Koordinattan Adres Bulma geocode-reverse

Uç nokta: POST https://binverify.com/api/v1/tool/geocode-reverse

Alan Tip Zorunlu Açıklama Örnek
latitude number Koşullu Enlem, -90 ile 90 arası. geohash gönderilmiyorsa longitude ile birlikte zorunludur. 38.8977
longitude number Koşullu Boylam, -180 ile 180 arası. geohash gönderilmiyorsa latitude ile birlikte zorunludur. -77.0365
geohash string Koşullu Koordinatlara alternatif olarak geohash (1–12 karakter); koordinat gönderildiğinde yok sayılır. dqcjqcp84c6e
language_code string Hayır ar, de, en, es, fr, it, ja, nl, pt, ru veya zh. Varsayılan en. en
zoom string Hayır Sonuç ayrıntısı: address, street, city, state veya country. Varsayılan address. address

İstek örneği

{
    "latitude": 38.8977,
    "longitude": -77.0365,
    "zoom": "address"
}
Sayfa İçeriği Çıkarma browser-bot

Uç nokta: POST https://binverify.com/api/v1/tool/browser-bot

Alan Tip Zorunlu Açıklama Örnek
url string Evet Yüklenecek sayfanın mutlak URL'si. https://www.example.com/
selector string Hayır Çıkarılacak öğelerin CSS seçicisi (en fazla 500 karakter). a
timeout integer Hayır Sayfa yükleme zaman aşımı (saniye), 1–30. Varsayılan 30. 30
delay integer Hayır Yüklemeden sonra beklenecek saniye, 0–10. Varsayılan 3. 3
user_agent string Hayır Özel User-Agent dizesi (en fazla 500 karakter). Mozilla/5.0
ignore_certificate_errors boolean Hayır TLS sertifika hatalarını yok say. Varsayılan false. false

İstek örneği

{
    "url": "https://www.example.com/",
    "selector": "a"
}
DNSBL Kontrolü host-reputation

Uç nokta: POST https://binverify.com/api/v1/tool/host-reputation

Alan Tip Zorunlu Açıklama Örnek
host string Evet IP adresi, alan adı, FQDN veya URL (en fazla 2048 karakter). 8.8.8.8
list_rating integer Hayır Kontrol edilecek kara listeler: 1 = yalnız derecesi 1 olan listeler, 2 = derecesi 1 ve 2 olanlar, 3 = bütün listeler (1–3). Varsayılan 3. 3

İstek örneği

{
    "host": "8.8.8.8",
    "list_rating": 3
}
Küfür Filtresi bad-word-filter

Uç nokta: POST https://binverify.com/api/v1/tool/bad-word-filter

Alan Tip Zorunlu Açıklama Örnek
content string Evet Metin, HTML veya URL, en fazla 100000 karakter. This damn printer is crap
censor_character string Hayır Eşleşmeleri maskelemek için kullanılan tek karakter (daha uzun değerler tek karaktere kısaltılır). *
catalog string Hayır Kelime kataloğu: strict veya obscene. Varsayılan strict. strict

İstek örneği

{
    "content": "This damn printer is crap",
    "censor_character": "*",
    "catalog": "strict"
}
Döviz ve Birim Çevirici convert

Uç nokta: POST https://binverify.com/api/v1/tool/convert

Alan Tip Zorunlu Açıklama Örnek
from_value string Evet Dönüştürülecek miktar, sayısal dize olarak (en fazla 50 karakter). 100
from_type string Evet Kaynak para birimi, kripto para veya birim kodu; örneğin USD (en fazla 30 karakter). USD
to_type string Evet Hedef para birimi, kripto para veya birim kodu; örneğin EUR. EUR
historical_date string Hayır Geçmiş bir tarihin kurunu kullan: YYYY-MM-DD, YYYY-MM veya YYYY. 2026-01-15

İstek örneği

{
    "from_value": "100",
    "from_type": "USD",
    "to_type": "EUR"
}
Yanıt Biçimi

Başarılı ya da hatalı her yanıt, aynı dört anahtarı taşıyan bir JSON nesnesidir: success, data, error ve meta.

Başarılı yanıt — bin-lookup

{
    "success": true,
    "data": {
        "bin": "411111",
        "brand": "VISA",
        "type": "CREDIT",
        "category": "CLASSIC",
        "country": "United States",
        "country_iso": "US",
        "country_iso3": "USA",
        "currency": "USD",
        "bank": "EXAMPLE BANK N.A.",
        "bank_phone": "+1 800 555 0100",
        "bank_website": "https://www.example-bank.com",
        "prepaid": false,
        "commercial": false,
        "reloadable": null
    },
    "error": null,
    "meta": {
        "request_id": "3f9c2a1b7d4e5f60",
        "tool": "bin-lookup",
        "cache_hit": false,
        "duration_ms": 142
    }
}

data, araç sonucunu taşır. bin-lookup için anahtarlar tam olarak gösterildiği gibidir; kart verisinde bulunmayan değerler null döner. reloadable yalnız ön ödemeli kartlarda verilir; diğer kartlarda null döner.

Başarılı yanıtta meta anahtarları

Anahtar Açıklama
request_id Bu isteğin benzersiz kimliği (16 onaltılık karakter). Destek talebinde bu değeri belirtin.
tool Çalıştırılan aracın kod adı.
cache_hit Yanıt, canlı sağlayıcı çağrısı yerine BinVerify'ın saklı sonuçlarından verildiyse true.
duration_ms Sunucu tarafındaki işlem süresi (milisaniye).
sandbox Yalnızca sandbox (test anahtarı) yanıtlarında bulunur ve true'dur.

Hata yanıtı

Hatalarda success false, data null olur; error ya sabit bir kod (örneğin quota_exceeded) ya da kısa bir mesaj taşır. meta, kimlik doğrulama hatalarında null'dır; çalıştırma sırasında oluşan hatalarda request_id ve tool içerir; doğrulama ve kota hatalarında ek ayrıntılar taşır.

{
    "success": false,
    "data": null,
    "error": "Validation failed.",
    "meta": {
        "request_id": "3f9c2a1b7d4e5f60",
        "tool": "bin-lookup",
        "validation_errors": {
            "bin": "BIN must be 6–8 digits."
        }
    }
}

Kota tükendi — 429 quota_exceeded

HTTP/1.1 429 Too Many Requests
Retry-After: 1296000

{
    "success": false,
    "data": null,
    "error": "quota_exceeded",
    "meta": {
        "tool_slug": "bin-lookup",
        "monthly_limit": 1000,
        "used": 1000,
        "remaining": 0,
        "period_end": "2026-11-01T00:00:00Z",
        "retry_after": 1296000
    }
}

monthly_limit, used ve remaining aracın bu dönemdeki kotasını açıklar. period_end (UTC) ve retry_after (saniye) abonelerde bulunur ve kotanın ne zaman yenileneceğini söyler; aynı sayı Retry-After başlığında da gönderilir.

Hata Kodları

error alanının alabileceği tüm değerler, HTTP durum koduna göre gruplanmıştır.

HTTP error değeri Anlamı
400 Validation failed.
Zorunlu bir alan eksik ya da bir değer hatalı biçimli; meta.validation_errors her alanı bir mesajla eşler.
400 Invalid Idempotency-Key (1-255 visible ASCII characters).
Idempotency-Key başlığı 1–255 görünür ASCII karakterden oluşmalıdır.
401 Missing or invalid Authorization header.
Empty bearer token.
Authorization: Bearer başlığı eksik ya da boş.
401 Invalid key format.
Invalid key environment prefix.
Token bv_pk_live_ veya bv_pk_test_ ile başlamıyor.
401 Invalid API key.
Token ile eşleşen aktif bir anahtar yok.
401 API key is revoked.
API key is expired.
API key has expired.
Anahtar API Anahtarları sayfasından iptal edilmiş ya da son kullanma tarihi geçmiş.
401 User account not found.
Anahtarın sahibi olan hesap artık mevcut değil.
403 Request IP not in allowed list.
İstek IP'si anahtarın IP izin listesinde değil.
403 API key does not have scope for this tool.
Araç, anahtarın yetkileri arasında değil.
403 Your plan does not include API access.
Planınız API erişimi içermiyor; API erişimi olan bir plana yükseltin.
403 no_api_access
İstek işlenirken planınızın API erişimi sona erdi (örneğin abonelik bitti).
403 tool_not_in_plan
Araç planınızda engelli ya da planınıza dahil değil; krediler bu aracı açmaz.
403 entitlement_check_failed
Kota doğrulanamadı; istek güvenli tarafta kalınarak reddedildi. Kısa süre sonra yeniden deneyin.
403 No entitlement left for this tool.
Kalan son birim, bu istek ücretlendirilemeden eş zamanlı başka bir istek tarafından kullanıldı.
404 Tool not found.
Bu kod adıyla bir araç yok.
409 A request with this Idempotency-Key is still in progress.
Aynı Idempotency-Key ile bir istek hâlâ çalışıyor; bitince yeniden deneyin.
422 Idempotency-Key was already used for a different request.
Idempotency-Key son 24 saat içinde farklı bir araç ya da gövdeyle kullanılmış.
429 rate_limit_exceeded
Bu dakika içinde çok fazla istek; Retry-After saniye kadar bekleyin (meta.retry_after içinde de bulunur).
429 quota_exceeded
Aracın aylık kotası ve kredileriniz tükendi; meta kota durumunu ve period_end değerini taşır.
500 Internal error.
Beklenmeyen sunucu hatası; ayrıntılar kaydedilir ve ücret alınmaz.
502 Tool execution failed.
Veri sağlayıcısı başarısız oldu ya da zaman aşımına uğradı; ücret alınmaz. Daha sonra yeniden deneyin.
503 maintenance
BinVerify bakımda; meta.retry_after saniye sonra yeniden deneyin.
Idempotency-Key

Bir isteği (örneğin ağ zaman aşımından sonra) güvenle yinelenebilir kılmak için isteğe bağlı Idempotency-Key başlığı (1–255 görünür ASCII karakter, API anahtarı başına benzersiz) gönderin.

Idempotency-Key: order-7781
  • 24 saat içinde aynı anahtar, aynı araç ve aynı gövde: saklanan yanıt Idempotent-Replayed: true başlığıyla yeniden döndürülür ve ikinci kez ücret alınmaz.
  • Aynı anahtar, farklı araç ya da gövde: 422.
  • İlk istek hâlâ çalışırken aynı anahtar: 409 (hiç tamamlanmayan bir istek 10 dakika sonra serbest bırakılır).
  • Hata yanıtı (4xx veya 5xx) anahtarı ayırmaz; istek aynı anahtarla yeniden denenebilir.
  • Sandbox anahtarları Idempotency-Key başlığını yok sayar.
Hız Limitleri ve Kotalar

Hız limitleri araç başına, sabit bir dakikalık pencerelerde sayılır ve API ile web araçları arasında paylaşılır. Plan başına varsayılanlar:

Plan Dakikadaki istek (araç başına)
Ücretsiz 15
Başlangıç 30
Pro 60
Pro Rollover 60
Kurumsal Sınırsız

Limitin üzerinde API, Retry-After başlığıyla (pencerenin sıfırlanmasına kalan saniye) 429 rate_limit_exceeded döndürür. Retry-After tek hız limiti başlığıdır; X-RateLimit-* başlıkları gönderilmez.

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{
    "success": false,
    "data": null,
    "error": "rate_limit_exceeded",
    "meta": {
        "retry_after": 37
    }
}

Canlı anahtarlar web araçlarıyla aynı aylık kotayı tüketir: başarılı her yanıt için bir birim (saklı yanıtlar dahil); önce devir, sonra dönemin kotası, sonra satın alınan krediler kullanılır. Birim, sağlayıcı çağrılmadan önce ayrılır ve çağrı başarısız olursa serbest bırakılır; başarısız istekler hiçbir zaman ücretlendirilmez.

Kota ve krediler tükendiğinde API 429 quota_exceeded döndürür. Araç başına kalan kotanızı panel ana sayfasında görebilirsiniz.

Sandbox (test anahtarları)

Test ortamıyla oluşturulan anahtarlar (bv_pk_test_…) sandbox modunda çalışır:

  • Hiçbir sağlayıcı çağrılmaz; her araç canlı yanıt biçiminde sabit, gerçekçi örnek veri döndürür.
  • Kota veya kredi tüketilmez ve ücret alınmaz.
  • Yanıtlar deterministiktir: aynı girdi her zaman aynı veriyi döndürür; bin, ip veya email gibi girdi değerleri yanıtta aynen yansıtılır.
  • Girdi doğrulanmaz ve Idempotency-Key başlığı yok sayılır.
  • Kimlik doğrulama, IP izin listesi, yetkiler, planın API erişimi ve hız limitleri canlı anahtarlarla tamamen aynı şekilde uygulanır.
  • meta.sandbox true olur ve çağrılar geçmişinizde sandbox durumuyla listelenir.

Sandbox yanıtları şu meta nesnesini taşır:

"meta": {
    "request_id": "3f9c2a1b7d4e5f60",
    "tool": "bin-lookup",
    "sandbox": true,
    "cache_hit": false,
    "duration_ms": 1
}
Kod Örnekleri

YOUR_API_KEY yerine API Anahtarları sayfasından aldığınız bir anahtarı yazın. İsteklerinizde uygulamanızı tanıtan kendi User-Agent başlığınızı gönderin (örneğin MyShop/1.0): bazı HTTP kütüphanelerinin varsayılan değeri, örneğin Python'daki urllib'inki, otomatik trafik sayılıp engelleniyor (hata 1010).

cURL

curl -X POST https://binverify.com/api/v1/tool/bin-lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-7781" \
  -d '{"bin": "411111"}'

PHP

$ch = curl_init('https://binverify.com/api/v1/tool/bin-lookup');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode(['bin' => '411111']),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($body['success']) {
    echo $body['data']['brand'], ' / ', $body['data']['bank'];
} elseif ($status === 429) {
    echo 'Wait: ', $body['error'], ' (retry_after ', $body['meta']['retry_after'] ?? '?', ')';
} else {
    echo 'Error: ', $body['error'];
}

Python (requests)

import requests

response = requests.post(
    'https://binverify.com/api/v1/tool/bin-lookup',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'bin': '411111'},
    timeout=10,
)
result = response.json()

if result['success']:
    print(result['data']['brand'], '/', result['data']['bank'])
elif response.status_code == 429:
    print('wait', result['error'], response.headers.get('Retry-After'))
else:
    print('error', result['error'])

JavaScript (fetch)

const response = await fetch('https://binverify.com/api/v1/tool/bin-lookup', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ bin: '411111' }),
});

const result = await response.json();
if (result.success) {
  console.log(result.data.brand, result.data.bank);
} else if (response.status === 429) {
  console.log('wait', result.error, response.headers.get('Retry-After'));
} else {
  console.log('error', result.error);
}