PyKAP - Python KAP API Kütüphanesi

PyKAP, Türkiye'nin Kamuyu Aydınlatma Platformu (KAP) API'si için kapsamlı bir Python istemci kütüphanesidir.

Özellikler

PyKAP, KAP API'sinin tüm servislerini destekler:

• Token Yönetimi: Otomatik token oluşturma ve yenileme
• Bildirim Servisleri: Bildirimleri listeleme, detay görüntüleme, ek dosya indirme
• Şirket Bilgileri: Şirket listesi, detayları ve menkul kıymet bilgileri
• Fon Bilgileri: Fon listesi ve detaylı fon bilgileri
• Bloklanmış Bildirimler: Erişime kapatılmış bildirimleri görüntüleme
• Hak Kullanım: Kurumsal işlem süreç durumları
• Gelişmiş Arama: Şirket koduna göre arama ve filtreleme

Kurulum

pip install -r requirements.txt

Geliştirme kurulumu için:

pip install -e .

Hızlı Başlangıç

Temel Kullanım

from pykap import KAPClient

# Test ortamı için istemci oluşturma (varsayılan API key ile)
client = KAPClient(test_mode=True)

# Şirket listesini alma
companies = client.get_members()
print(f"Toplam {len(companies)} şirket bulundu")

# Son bildirim indeksini öğrenme
last_index = client.get_last_disclosure_index()
print(f"Son bildirim indeksi: {last_index}")

# Bildirimleri listeleme
disclosures = client.get_disclosures(
    disclosure_index=last_index - 50,
    disclosure_type="ODA"  # Özel Durum Açıklamaları
)

for disclosure in disclosures:
    print(f"{disclosure.title} - {disclosure.disclosure_index}")

Kendi API Anahtarlarınızı Kullanma

Kendi API key ve secret bilgilerinizle:

from pykap import KAPClient

# Özel API anahtarları ile
client = KAPClient(
    test_mode=True,
    api_key="your-api-key-here",
    api_secret="your-api-secret-here"
)

# Ya da config dosyasından
from config import API_KEY, API_SECRET

client = KAPClient(
    test_mode=True,
    api_key=API_KEY,
    api_secret=API_SECRET
)

Üretim Ortamı Kullanımı

Üretim ortamında token gereklidir:

# Üretim ortamı için istemci
client = KAPClient(
    test_mode=False,
    api_key="your-api-key",
    api_secret="your-api-secret",
    auto_refresh_token=True
)

# Token otomatik olarak oluşturulur ve yenilenir
# Manuel token oluşturmak için:
token = client.generate_token()
print(f"Token: {token}")

Bildirim Detayı ve Ek İndirme

# Bildirim detayını alma
detail = client.get_disclosure_detail(
    disclosure_index=1211180,
    file_type="data"  # 'html' veya 'data'
)

print(f"Konu: {detail.subject.tr}")
print(f"Özet: {detail.summary.tr}")
print(f"Yayın Zamanı: {detail.time}")

# Ek dosyaları indirme
if detail.attachment_urls:
    for attachment in detail.attachment_urls:
        print(f"İndiriliyor: {attachment.file_name}")
        
        # URL'den attachment ID'yi çıkar
        attachment_id = attachment.url.split('/')[-1]
        file_content = client.download_attachment(attachment_id)
        
        # Dosyayı kaydet
        with open(attachment.file_name, 'wb') as f:
            f.write(file_content)

Şirket Bilgileri

# Hisse koduna göre şirket bulma
company = client.get_company_by_stock_code("THYAO")
if company:
    print(f"Şirket: {company.title}")
    print(f"ID: {company.id}")
    print(f"Tip: {company.member_type}")

# Şirket detaylarını alma
detail = client.get_member_detail(company.id)
print(detail)

# Şirketlerin menkul kıymet bilgileri
securities = client.get_member_securities()
for item in securities[:5]:
    print(f"{item.member.sirket_unvan}:")
    for security in item.securities:
        print(f"  - {security.isin_desc} ({security.borsa_kodu})")

Belirli Bir Şirkete Ait Bildirimleri Arama

# Şirket bildirimlerini arama
company = client.get_company_by_stock_code("THYAO")
if company:
    disclosures = client.search_disclosures_by_company(
        company_id=company.id,
        disclosure_type="ODA"
    )
    
    for disclosure in disclosures[:10]:
        print(f"{disclosure.title}")

Fon Bilgileri

# Aktif fonları listeleme
funds = client.get_funds(fund_state=["Y"])  # Y=Aktif

for fund in funds[:10]:
    print(f"{fund.fund_name} ({fund.fund_code})")
    print(f"  Tip: {fund.fund_type}")
    print(f"  Durum: {fund.fund_state}")

# Fon detayı
fund_detail = client.get_fund_detail(fund_id=4282)
print(fund_detail)

Bloklanmış Bildirimler

# Erişime kapatılmış bildirimleri listeleme
blocked = client.get_blocked_disclosures()

for item in blocked:
    print(f"Bildirim ID: {item.disclosure_index}")
    print(f"Tip: {item.blocked_type}")
    print(f"Neden: {item.is_blocked_description_tr}")

Hak Kullanım Süreç Durumu

# Kurumsal işlem durumlarını sorgulama
statuses = client.get_ca_event_status(process_ref_ids=[12941, 13214])

for status in statuses:
    print(f"Süreç ID: {status.ref_id}")
    print(f"Durum: {status.status_text}")
    if status.complete_date:
        print(f"Tamamlanma: {status.complete_date}")

Context Manager Kullanımı

# Otomatik kaynak yönetimi
with KAPClient(test_mode=True) as client:
    companies = client.get_members()
    print(f"{len(companies)} şirket bulundu")
    # Client otomatik olarak kapatılır

Bildirim Tipleri ve Sınıfları

Bildirim Sınıfları (DisclosureClass)

from pykap.models import DisclosureClass

# FR - Finansal Rapor Bildirimi
# ODA - Özel Durum Açıklaması Bildirimi
# DG - Diğer Bildirim
# DUY - Düzenleyici Kurum Bildirimi

disclosures = client.get_disclosures(
    disclosure_index=1000000,
    disclosure_class=DisclosureClass.FR
)

Bildirim Tipleri (DisclosureType)

from pykap.models import DisclosureType

# FR - Finansal Rapor
# ODA - Özel Durum Açıklaması
# DG - Diğer
# DUY - Düzenleyici Kurum
# FON - Fon Bildirimi
# CA - Hak Kullanım Bildirimi

disclosures = client.get_disclosures(
    disclosure_index=1000000,
    disclosure_type=DisclosureType.ODA
)

Şirket Tipleri (MemberType)

from pykap.models import MemberType

# IGS - İşlem Gören Şirket
# IGMS - İşlem Görmeyen Şirket
# YK - Yatırım Kuruluşu
# PYS - Portföy Yönetim Şirketi
# FK - Fon Kurucu
# Ve daha fazlası...

Gelişmiş Kullanım

Özel Filtreleme

# Belirli bir dönem için bildirimleri alma
start_index = 1200000
end_index = 1200100

all_disclosures = []
current_index = start_index

while current_index < end_index:
    batch = client.get_disclosures(
        disclosure_index=current_index,
        disclosure_class="FR"
    )
    all_disclosures.extend(batch)
    
    if batch:
        # Sonraki batch için index güncelle
        current_index = int(batch[-1].disclosure_index) + 1
    else:
        break

print(f"Toplam {len(all_disclosures)} bildirim bulundu")

Hata Yönetimi

from pykap.exceptions import (
    KAPAuthenticationError,
    KAPAPIError,
    KAPValidationError
)

try:
    # Geçersiz index
    disclosures = client.get_disclosures(disclosure_index=100)
    
except KAPValidationError as e:
    print(f"Geçersiz parametre: {e}")
    
except KAPAuthenticationError as e:
    print(f"Kimlik doğrulama hatası: {e}")
    
except KAPAPIError as e:
    print(f"API Hatası: {e}")
    print(f"Hata Kodu: {e.error_code}")
    print(f"HTTP Durum: {e.status_code}")

API Referansı

KAPClient Metodları

Token Yönetimi

• generate_token() - Yeni token oluştur (üretim ortamı)

Bildirim Servisleri

• get_disclosures(disclosure_index, disclosure_type, disclosure_class, company_id) - Bildirim listesi
• get_disclosure_detail(disclosure_index, file_type, sub_report_list) - Bildirim detayı
• download_attachment(attachment_id) - Ek dosya indir
• get_last_disclosure_index() - Son bildirim indeksi

Şirket Servisleri

• get_members() - Tüm şirketler
• get_member_detail(member_id) - Şirket detayı
• get_member_securities() - Menkul kıymet bilgileri
• get_company_by_stock_code(stock_code) - Hisse koduna göre şirket bul

Fon Servisleri

• get_funds(fund_state, fund_class, fund_type) - Fon listesi
• get_fund_detail(fund_id) - Fon detayı

Diğer Servisler

• get_blocked_disclosures() - Bloklanmış bildirimler
• get_ca_event_status(process_ref_ids) - Hak kullanım durumu
• search_disclosures_by_company(company_id, start_index, disclosure_type) - Şirket bildirimlerini ara

Proje Yapısı

pykap/
├── pykap/
│   ├── __init__.py          # Paket başlatma
│   ├── client.py            # Ana API istemcisi
│   ├── models.py            # Veri modelleri
│   └── exceptions.py        # Özel hatalar
├── examples/
│   └── basic_usage.py       # Kullanım örnekleri
├── setup.py                 # Kurulum dosyası
├── requirements.txt         # Bağımlılıklar
├── README.md               # Bu dosya
└── LICENSE                 # Lisans

Kimlik Doğrulama

API Anahtarları

Kendi API anahtarlarınızı kullanmak için:

1. config.py dosyasını düzenleyin:

API_KEY = "sizin-api-key-buraya"
API_SECRET = "sizin-api-secret-buraya"
TEST_MODE = True

2. Doğrudan kod içinde kullanın:

client = KAPClient(
    test_mode=True,
    api_key="your-api-key",
    api_secret="your-api-secret"
)

Test Ortamı

Test ortamında kimlik doğrulama gerekmez (API key ile):

client = KAPClient(
    test_mode=True,
    api_key="your-test-api-key"
)

Üretim Ortamı

Üretim ortamında API Key ile token alınmalıdır:

client = KAPClient(
    test_mode=False,
    api_key="your-production-api-key",
    auto_refresh_token=True
)
# Token otomatik olarak yönetilir (24 saat geçerli)

Varsayılan API Key

API Key belirtilmezse, kütüphane varsayılan değeri kullanır:

• Varsayılan: 29223dec-32bc-49fb-919f-51405d110ab2

Önemli Notlar

1. Bildirim İndeksi: disclosureIndex 538004'ten başlar. 84196-538004 arası KAP 4.0 öncesi verilerdir.

2. Token Süresi: Üretim ortamında token 24 saat geçerlidir. auto_refresh_token=True ile otomatik yenilenir.

3. Erişime Kapatılmış Bildirimler: KVKK nedeniyle bazı bildirimler erişime kapatılmıştır. get_blocked_disclosures() ile listelenebilir.

4. Rate Limiting: API'ye aşırı istek göndermekten kaçının.

5. Veri Güncelliği: API üzerinden alınan veriler geçmiş tarihli canlı ortam verileridir ve güncel durumdan farklılık gösterebilir.

Katkıda Bulunma

Katkılar memnuniyetle karşılanır! Lütfen:

1. Fork yapın
2. Feature branch oluşturun (git checkout -b feature/amazing-feature)
3. Değişikliklerinizi commit edin (git commit -m 'Add amazing feature')
4. Branch'inizi push edin (git push origin feature/amazing-feature)
5. Pull Request oluşturun

Lisans

Bu proje MIT lisansı altında lisanslanmıştır - detaylar için LICENSE dosyasına bakın.

İletişim

• KAP Destek: kapdestek@mkk.com.tr
• KAP İletişim: https://www.mkk.com.tr/iletisim-formu
• Sorumlu Kurum: Kamuyu Aydınlatma Hizmetleri Direktörlüğü

Faydalı Bağlantılar

• KAP Resmi Sitesi
• KAP API Dokümantasyonu
• MKK Resmi Sitesi

Hata Kodları

Kod	Açıklama
ER001	Servis erişim yetkiniz bulunmamaktadır
ER002	Unauthorized request
ER003	Tanımlı olmayan IP adresinden erişim
ER004	Token geçersiz
ER005	IP bilgisi doğrulanamadı
ER006	Geçersiz token
ER007	Token bilgisi doğrulanamadı
ER008	Authorization token is not valid

Örnekler

Daha fazla örnek için examples klasörüne bakın.

Performans İpuçları

1. Test ortamını geliştirme için kullanın
2. Toplu sorgularda sayfalama kullanın
3. Token'ı önbelleğe alın (üretimde)
4. Context manager kullanın
5. Gereksiz detay sorgularından kaçının

Sürüm Geçmişi

v1.0.0 (2026-01-22)

• İlk sürüm
• Tüm KAP API servisleri destekleniyor
• Test ve üretim ortamı desteği
• Otomatik token yönetimi
• Kapsamlı hata yönetimi

---

Not: Bu kütüphane resmi bir KAP/MKK ürünü değildir. Bağımsız bir açık kaynak projesidir.