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ı.
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} |
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.
- Bearer token içeren Authorization başlığı mevcut — aksi halde 401.
- Anahtar ön eki bv_pk_live_ veya bv_pk_test_ — aksi halde 401.
- Anahtar mevcut, aktif ve süresi dolmamış — aksi halde 401.
- Anahtarda IP izin listesi tanımlıysa istek IP'si listede — aksi halde 403.
- Araç, anahtarın yetkileri arasında — aksi halde 403.
- Planınız API erişimi içeriyor — aksi halde 403.
- Planınızın hız limiti — aksi halde 429 rate_limit_exceeded.
- Araç için aylık kota veya kredi (yalnızca canlı anahtarlar) — aksi halde 429 quota_exceeded veya 403.
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.
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-lookupUç 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-infoUç 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
}
ip-probeUç 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-blocklistUç 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
}
phone-validateUç 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"
}
email-verifyUç 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
}
email-validateUç 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
}
domain-lookupUç 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-codeUç nokta: POST https://binverify.com/api/v1/tool/qr-code
| 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"
}
url-infoUç 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
}
ua-lookupUç 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"
}
image-watermarkUç nokta: POST https://binverify.com/api/v1/tool/image-watermark
| 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"
}
image-resizeUç nokta: POST https://binverify.com/api/v1/tool/image-resize
| 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-renderUç nokta: POST https://binverify.com/api/v1/tool/html-render
| 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-cleanUç 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"
}
geocode-addressUç 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
}
geocode-reverseUç 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"
}
browser-botUç 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"
}
host-reputationUç 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
}
bad-word-filterUç 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"
}
convertUç 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"
}
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.
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. |
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 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.
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
}
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);
}