IBAN Çözümleme ve Doğrulama API Dokümantasyonu
Tek bir HTTP GET veya POST isteği ile IBAN numarasını ISO 7064 Mod-97 algoritmasıyla doğrulayın; banka adı, şube kodu, hesap numarası ve kurum logosunu 1 milisaniyenin altında elde edin.
1. Hızlı Başlangıç & Canlı İstek
Aşağıdaki hazır kod bloklarını projenize doğrudan kopyalayabilir, cURL, JavaScript, Python veya PHP ile anında test edebilirsiniz.
curl -X GET "https://ibancozumle.com/api/query-iban?iban=TR920082900009491605176612" \ -H "x-api-key: SIZIN_API_ANAHTARINIZ"
{
"success": true,
"valid": true,
"iban": "TR920082900009491605176612",
"formatted": "TR92 0082 9000 0949 1605 1766 12",
"bank_code": "0829",
"bank_name": "Papara Elektronik Para A.Ş.",
"bank_type": "elektronik_para",
"bank_type_display": "Elektronik Para Kuruluşu",
"bank_logo": "/logos/Papara.svg",
"branch_code": "00829",
"branch_info": "00829 Nolu Şube",
"account_number": "0009491605176612",
"branch_count": "1",
"swift_code": "",
"website": "https://www.papara.com/"
}2. Kimlik Doğrulama (Authentication)
Harici yazılımlarınız, e-ticaret altyapınız veya ERP sistemlerinizden gönderilen tüm API istekleri kimlik doğrulamasına tabidir. API anahtarınızı aşağıdaki 3 alternatif yöntemden herhangi biriyle gönderebilirsiniz.
x-api-key Başlığı
HTTP Header içerisinde gönderilir. Sunucu erişim loglarına düşmez, en güvenli ve endüstri standardı entegrasyon yöntemidir.
Bearer Token
Standart Authorization başlığı ile Bearer token formatında iletilir. OAuth2 veya microservice mimarileriyle tam uyumludur.
api_key Parametresi
Özel HTTP başlığı eklemenin zor olduğu web kancaları (webhooks) veya hızlı testler için doğrudan URL sorgusu olarak iletilebilir.
3. Kullanılabilir Endpoint'ler
/api/query-ibanURL query parametresi üzerinden hızlıca IBAN doğrulamak için kullanılır. Tarayıcıdan ve basit HTTP istemcilerinden doğrudan çağrılabilir.
/api/query-ibanJSON gövdesi (body) veya form verisi ile güvenli sunucudan sunucuya (backend-to-backend) entegrasyonlar için önerilir.
4. İstek Parametreleri
| Parametre | Tip | Konum | Zorunlu mu? | Açıklama |
|---|---|---|---|---|
| iban | string | Query / JSON Body / Form | Evet | Doğrulanacak Türkiye IBAN numarası. "TR" ile başlamalı ve toplam 26 karakter olmalıdır. Boşluklar sistem tarafından otomatik temizlenir. |
| api_key | string | Query Parametresi | Alternatif | API anahtarınızı HTTP Header (x-api-key) yerine URL parametresi olarak geçmek isterseniz kullanılır. |
5. Başarılı Yanıt Modeli (200 OK)
| Alan Adı | Tip | Örnek Değer | Açıklama |
|---|---|---|---|
| success | boolean | true | İşlemin başarı durumunu belirtir. |
| valid | boolean | true | IBAN'ın ISO 7064 Mod-97 kuralına göre matematiksel olarak doğruluğu. |
| bank_name | string | "Papara Elektronik Para A.Ş." | Hesabın ait olduğu banka veya ödeme kuruluşunun resmi adı. |
| bank_code | string | "0829" | Kurumun 4 veya 5 haneli resmi TCMB kurum kodu. |
| bank_type | string | "elektronik_para" | Kurum türü: "banka", "odeme_kurulusu", "elektronik_para". |
| bank_logo | string | "/logos/Papara.svg" | Kurumun yüksek çözünürlüklü vektörel SVG veya WebP logo bağlantısı. |
| branch_code | string | "00829" | IBAN içerisinden ayrıştırılan 5 haneli şube kodu. |
| account_number | string | "0009491605176612" | IBAN'dan ayrıştırılan 16 haneli müşteri hesap numarası. |
| swift_code | string | "TCZBTR2AXXX" | Bankaya ait uluslararası BIC / SWIFT kodu (varsa). |
6. Hata Kodları ve HTTP Durumları
API standart HTTP durum kodları ile yanıt verir. Hatalı durumlarda JSON formatında açıklayıcı bir error mesajı döndürülür.
Gönderilen IBAN eksik, hatalı karakter içeriyor veya ISO 7064 Mod-97 algoritmasından geçemediğinde döner.
{
"success": false,
"error": "IBAN kontrol toplamı geçersiz."
}API anahtarı hiç gönderilmediğinde veya geçersiz / tanımsız bir anahtar girildiğinde döner.
{
"success": false,
"error": "API anahtarı eksik. Sorgu göndermek için 'x-api-key' başlığı zorunludur."
}API anahtarınız yönetici tarafından durdurulmuş (pasif) veya lisans süresi sona ermişse döner.
{
"success": false,
"error": "Bu API anahtarının süresi 28.10.2026 tarihinde dolmuştur."
}Paketinize ait dakika, saat, gün veya aylık sorgu kotası dolduğunda döner.
{
"success": false,
"error": "Dakikalık sorgu limitiniz doldu (5 sorgu/dk). Lütfen 1 dakika sonra tekrar deneyin."
}Sorgulama esnasında beklenmeyen bir sunucu hatası oluştuğunda döner.
{
"success": false,
"error": "IBAN sorgulanırken bir sunucu hatası oluştu."
}Saniyede Yüzlerce İstek mi Göndermek İstiyorsunuz?
Kurumsal projeleriniz, ERP veya muhasebe sistemleriniz için özel SLA garantili, dedicated altyapı ve webhook destekli kurumsal paketlerimizi keşfedin.