> ## Documentation Index
> Fetch the complete documentation index at: https://docs.banka.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Yazılım firmaları için

> Tek entegratör anahtarıyla müşterilerinizin firmalarını (VKN) ve banka bağlantılarını yönetin; kredi kuralları.

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](https://app.banka.pro/api-anahtarlari) | 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.

> [!WARNING]
>
> 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ış

**1. 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.

```bash theme={null}
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`.

**2. Bankanın istediği bilgileri öğrenin**

[Banka kataloğu](https://docs.banka.pro/api-reference/entegrator/banka-baglantilari/katalog.md) bağlanabilecek bankaları, bağlantı türlerini ve her bankanın istediği alanları kredi durumunuzla birlikte döndürür.

**3. 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.

```bash theme={null}
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": "..."}}}'
```

**4. 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.

```bash theme={null}
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.

**5. Veriyi okuyun**

Hesap ve hareketleri firma adresiyle okuyun. Değişenleri almak için [artımlı eşitleme](https://docs.banka.pro/artimli-esitleme.md) kurallarını kullanın.

```bash theme={null}
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](https://docs.banka.pro/api-reference/entegrator/banka-sorgusu/baslat.md) 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](https://docs.banka.pro/api-reference/entegrator/krediler/ozet.md) 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.

```json Kredi özeti theme={null}
{
  "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](https://docs.banka.pro/api-reference/entegrator/banka-baglantilari/guncelle.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.