Yazılım firmaları için

Kendi müşterilerinize banka verisi sunan bir yazılım firmasıysanız BankaPro size entegratör anahtarı verir. Bu anahtarla müşterilerinizin firmalarını (VKN veya TCKN) ekler, her firmaya banka bağlar ve o firmanın hesap ve hareketlerini okursunuz. Bütün işlemler API üzerinden yapılır; müşterilerinizin BankaPro’ya giriş yapması gerekmez.

İki anahtar türü

	Firma anahtarı	Entegratör anahtarı
Kim oluşturur	Firma yöneticisi, app.banka.pro	BankaPro, sözleşmeyle birlikte
Kapsam	Tek firma	Size bağlı bütün müşteri firmaları
Veri uçlarının adresi	`/v1/bank-accounts`, `/v1/bank-transactions` …	`/v1/companies/{companyId}/bank-accounts` …
Firma ve banka yönetimi	Yok	`/v1/companies`, `/v1/companies/{companyId}/bank-connections`

Entegratör anahtarı da HTTP Basic ile gönderilir: kullanıcı adı anahtar kimliği, parola secret key değeridir. Secret key size bir kez iletilir; kaybederseniz BankaPro’dan yenilenmesini isteyin, eski değer o anda geçersiz olur.

Entegratör anahtarı bütün müşterilerinizin banka verisine erişir. Yalnız sunucunuzda saklayın, mümkünse IP kısıtı tanımlatın ve her ortam (canlı, test) için ayrı anahtar kullanın.

Firma adresi

Müşteri firmasının verisine her zaman adresteki companyId ile erişilir. Firma başlık veya sorgu parametresiyle seçilemez; companies, companyIds gibi alanlar 400 TENANT_SELECTOR_FORBIDDEN döner.

Entegratör anahtarıyla firma adresi olmadan bir veri ucunu (ör. GET /v1/bank-accounts) çağırırsanız 400 COMPANY_REQUIRED alırsınız.
Size ait olmayan bir firma 404 RESOURCE_NOT_FOUND, pasif bir firma 403 COMPANY_PASSIVE döner.
Firma adresli veri uçları firma anahtarındaki uçlarla aynı parametre, yanıt ve kurallara sahiptir.

Akış

Müşteri firmasını ekleyin

VKN (10 hane) veya şahıs işletmeleri için TCKN (11 hane) ve unvanla firma oluşturun. Kontrol hanesi doğrulanır; aynı VKN ikinci kez eklenirse 409 COMPANY_EXISTS döner. Firma eklemek kredi kullanmaz.

curl https://api.banka.pro/v1/companies \
  -u "$BANKAPRO_API_KEY_ID:$BANKAPRO_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"data": {"taxId": "1234567890", "title": "Örnek Ticaret A.Ş."}}'

Yanıttaki id, sonraki isteklerde kullanacağınız companyId değeridir. Kayıtlı bir VKN’yi bulmak için GET /v1/companies?taxId=1234567890.

Bankanın istediği bilgileri öğrenin

Banka kataloğu bağlanabilecek bankaları, bağlantı türlerini ve her bankanın istediği alanları kredi durumunuzla birlikte döndürür.

Bilgileri doğrulayın

Müşterinin banka web servis bilgilerini kaydetmeden bankada doğrulayın. Yanıt, bankanın döndürdüğü hesapları listeler; kredi kullanmaz.

curl https://api.banka.pro/v1/companies/$COMPANY_ID/bank-connections/verify \
  -u "$BANKAPRO_API_KEY_ID:$BANKAPRO_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"data": {"bankCode": "akbank", "fields": {"username": "...", "pass": "..."}}}'

Bağlantıyı ekleyin

Aynı bilgilerle, bağlanacak hesapların kimliklerini (accountIds) seçerek bağlantıyı oluşturun. Bilgiler bankada yeniden doğrulanır; her para birimi ayrı bağlantı olarak döner ve ilk banka sorgusu arka planda başlar.

curl https://api.banka.pro/v1/companies/$COMPANY_ID/bank-connections \
  -u "$BANKAPRO_API_KEY_ID:$BANKAPRO_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"data": {"bankCode": "akbank", "fields": {"username": "...", "pass": "..."}, "accountIds": ["..."]}}'

Banka bilgileri şifreli saklanır ve hiçbir yanıtta geri dönmez.

Veriyi okuyun

Hesap ve hareketleri firma adresiyle okuyun. Değişenleri almak için artımlı eşitleme kurallarını kullanın.

curl "https://api.banka.pro/v1/companies/$COMPANY_ID/bank-transactions?updatedSince=2026-10-17T00:00:00.000Z" \
  -u "$BANKAPRO_API_KEY_ID:$BANKAPRO_API_SECRET"

Bağlantılar BankaPro tarafından gün içinde düzenli olarak otomatik sorgulanır. Hemen güncel veri gerektiğinde firma adresli manuel banka sorgusu kullanılır.

Kredi

Krediler sözleşmenizde tanımlı kota ve dönem (aylık veya yıllık) üzerinden sayılır.

Bir müşteri firmasında bağlı her banka bir kredidir. Aynı bankanın başka hesabı, para birimi veya alt hesabı ek kredi kullanmaz; pasif bağlantılar sayılmaz.
Firma eklemek, bilgileri doğrulamak ve bağlantının bilgilerini güncellemek kredi kullanmaz.
Dönemin herhangi bir anında aktif olan her firma–banka ikilisi o dönem için sayılır. Pasife aldığınız bir ikilinin kredisi dönem sonuna kadar kullanılmış kalır; aynı ikiliyi aynı dönemde yeniden açmak yeni kredi kullanmaz.
Dönem, sözleşmenizin başlangıç gününde başlar ve aylık sözleşmede her ay, yıllık sözleşmede her yıl aynı gün yenilenir (Türkiye saati).
Bu dönemde sayılan ikili sayısı kotaya ulaştığında yeni bir firma–banka ikilisi 403 CREDIT_LIMIT_REACHED ile reddedilir. Kota artışı için BankaPro ile iletişime geçin.

Kredi özeti kotayı, bu dönemde kullanılanı, şu an aktif olanı ve açılabilecek kredi sayısını döndürür. Firma listesindeki creditCount her firmanın o an kullandığı krediyi gösterir.

Kredi özeti

{
  "success": true,
  "data": {
    "contract": {
      "period": "yearly",
      "startDate": "2026-10-16T21:00:00.000Z",
      "endDate": "2027-10-16T20:59:59.999Z",
      "state": "active",
      "endsAt": "2027-10-16T20:59:59.999Z",
      "accessUntil": "2027-10-23T20:59:59.999Z",
      "daysLeft": 364,
      "accessDaysLeft": 371
    },
    "currentPeriod": { "index": 0, "start": "2026-10-16T21:00:00.000Z", "end": "2027-10-16T21:00:00.000Z" },
    "creditLimit": 50,
    "used": 12,
    "active": 11,
    "available": 38
  },
  "meta": { "requestId": "9cc0d3d1-1e63-4c90-b08f-90b6332e70ca", "timestamp": "2026-10-17T09:00:00.000Z" }
}

Firmayı pasife alma

PATCH /v1/companies/{companyId} ile status: "passive" gönderdiğinizde firmanın aktif banka bağlantıları da pasife alınır ve kredisi sonraki dönemden itibaren sayılmaz. Firmayı yeniden aktifleştirdiğinizde bağlantılar pasif kalır; her birini bağlantı güncelleme ucuyla ayrıca açarsınız. Firma ve bağlantı silinmez.

Sözleşme süresi

Sözleşmenin bitiş tarihi varsa bitiş gününden sonra 7 gün ek süre tanınır. Sözleşme pasifse, başlangıç günü gelmemişse veya ek süre dolmuşsa entegratör anahtarıyla yapılan her istek 403 API_COMPANY_FORBIDDEN döner. Güncel durum kredi özetindeki contract.state alanındadır.

Yetkiler

Entegratör anahtarına veri yetkilerine (baAccounts, baTransactions, baOperations, baSync, baPii) ek olarak iki yetki verilir:

Yetki	Açtığı uçlar
`baCompanies`	Müşteri firmalarını listeleme, ekleme, güncelleme ve pasife alma
`baConnections`	Banka kataloğu, bilgileri doğrulama, bağlantı ekleme, güncelleme ve bilgilerini yenileme

Kredi özeti her entegratör anahtarına açıktır.

Başlarken

Temel kavramlar