Hesaplar ve senkronizasyon

Bu rehberde Mavi Rota Teknoloji A.Ş. için production ortamında iki IBAN taşıyan bir Aktifbank bağlantısı kuracağız. Firma kimliği 66b0f09a8f10000000000001, örnek bağlantı kimliği 66b0f09a8f10000000000101 olarak kullanılacaktır.

Yetki ve güven sınırı

Bağlantı ve banka credential yönetimi bank:connections, manuel senkronizasyon bank:operate kapsamı ister. Her çağrıda x-api-key ile x-api-secret birlikte; yazma çağrılarında ayrıca credential firmasıyla eşleşen x-company-id gönderilir. Banka credential değerleri kaydedildikten sonra hiçbir API cevabında geri verilmez. Yalnız yapılandırma durumunu GET /banks/accounts/{id}/credentials ile izleyebilirsiniz.

1. Bağlantıyı oluşturun

curl --request POST \
  --url https://api.tahsil.dev/banks/accounts \
  --header "x-api-key: $TAHSIL_API_KEY" \
  --header "x-api-secret: $TAHSIL_API_SECRET" \
  --header "x-company-id: 66b0f09a8f10000000000001" \
  --header "content-type: application/json" \
  --data '{"bankCode":"aktifbank","title":"Mavi Rota tahsilat IBANları","environment":"production"}'

{
  "status": true,
  "result": {
    "id": "66b0f09a8f10000000000101",
    "status": true,
    "bankCode": "aktifbank",
    "environment": "production",
    "title": "Mavi Rota tahsilat IBANları",
    "subAccounts": [],
    "syncHealth": {
      "status": "never",
      "lastAttemptAt": null,
      "lastSuccessAt": null
    }
  }
}

2. Banka alanlarını okuyun

Banka kataloğundaki alanları GET /banks/provider/variables/{bankCode} ile okuyun. Çoklu hesap destekleyen hedef alanı aşağıdaki metadata ile döner:

Metadata	Değer	Anlam
`repeatable`	`true`	Alan bir dizi kabul eder
`label`	`IBAN'lar`	Arayüzde gösterilecek alan etiketi
`format`	`iban`	Her öğe IBAN olarak doğrulanır
`minItems`	`1`	En az bir hedef gerekir
`maxItems`	`10`	Bir bağlantıda en fazla 10 hedef bulunabilir

Alan adı bankaya göre değişir:

Banka kodu	Hedef alanı	Ortak credential alanları
`aktifbank`	`IBAN`	`USERNAME`, `PASSWORD`, isteğe bağlı `KURUM_KODU`
`vakif`	`HesapNo`	`MusteriNo`, `KurumKullanici`, `Sifre`
`turkiyefinans`	`HesapNo`	`KullaniciKod`, `password`

Metadata’yı sabit bir istemci listesi yerine bu endpointten okuyun. Hedef alan tek değerle gönderilse bile dizi olmalıdır.

3. Credential’ı ve iki IBAN’ı kaydedin

Değerleri yalnız backend ortamınızdan gönderin; loglamayın ve tarayıcı depolamasında tutmayın. Aktifbank örneği:

const accountId = '66b0f09a8f10000000000101';
const response = await fetch(
  `https://api.tahsil.dev/banks/accounts/${accountId}/credentials`,
  {
    method: 'PUT',
    headers: {
      'x-api-key': process.env.TAHSIL_API_KEY,
      'x-api-secret': process.env.TAHSIL_API_SECRET,
      'x-company-id': '66b0f09a8f10000000000001',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      credentials: {
        USERNAME: process.env.MAVI_ROTA_AKTIFBANK_USERNAME,
        PASSWORD: process.env.MAVI_ROTA_AKTIFBANK_PASSWORD,
        KURUM_KODU: process.env.MAVI_ROTA_AKTIFBANK_INSTITUTION_CODE,
        IBAN: [
          'TR330006100519786457841326',
          'TR100006200119000006672315',
        ],
      },
    }),
  },
);

const payload = await response.json();
if (!response.ok || payload.status !== true) {
  throw new Error(payload.code ?? `HTTP_${response.status}`);
}

Aynı iki hedefi VakıfBank veya Türkiye Finans bağlantısında kullanırken yalnız banka alanlarını değiştirin:

const targetIbans = [
  'TR330006100519786457841326',
  'TR100006200119000006672315',
];

const credentialsByBank = {
  vakif: {
    MusteriNo: process.env.MAVI_ROTA_VAKIF_CUSTOMER_NO,
    KurumKullanici: process.env.MAVI_ROTA_VAKIF_USERNAME,
    Sifre: process.env.MAVI_ROTA_VAKIF_PASSWORD,
    HesapNo: targetIbans,
  },
  turkiyefinans: {
    KullaniciKod: process.env.MAVI_ROTA_TF_USERNAME,
    password: process.env.MAVI_ROTA_TF_PASSWORD,
    HesapNo: targetIbans,
  },
};

Credential gövdesi en fazla 64 KiB olabilir. Aynı hedefi farklı yazımlarla tekrarlamayın; boşluklar temizlendikten ve harfler normalize edildikten sonra duplicate hedefler reddedilir.

4. Setup çalıştırın

POST /banks/accounts/{id}/setup bağlantıyı doğrular ve bankanın alt hesaplarını keşfeder. Aktifbank, VakıfBank ve Türkiye Finans için Tahsil hedef IBAN’ların her birini aynı ortak credential ile ayrı ayrı sorgular ve başarılı sonuçları tek bağlantı cevabında birleştirir.

<?php
$accountId = '66b0f09a8f10000000000101';
$curl = curl_init("https://api.tahsil.dev/banks/accounts/$accountId/setup");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: ' . getenv('TAHSIL_API_KEY'),
        'x-api-secret: ' . getenv('TAHSIL_API_SECRET'),
        'x-company-id: 66b0f09a8f10000000000001',
        'content-type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{}',
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
$payload = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

if ($status >= 400 || ($payload['status'] ?? false) !== true) {
    throw new RuntimeException($payload['code'] ?? "HTTP_$status");
}

Başarılı setup iki hesabı accounts içinde döndürür. Her alt hesap için kararlı bir subAccountKey bulunur:

{
  "status": true,
  "result": {
    "accountId": "66b0f09a8f10000000000101",
    "bankCode": "aktifbank",
    "accountCount": 2,
    "accounts": [
      {
        "accountNo": "10000001",
        "iban": "TR330006100519786457841326",
        "currency": "TRY",
        "subAccountKey": "sub_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      {
        "accountNo": "10000002",
        "iban": "TR100006200119000006672315",
        "currency": "TRY",
        "subAccountKey": "sub_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      }
    ]
  }
}

Filtre ve schedule tanımlarında subAccountKey değerini saklayın; IBAN maskelense veya sunum biçimi değişse bile bu anahtar alt hesap kimliğini korur.

5. İlk senkronizasyonu başlatın

Tarih vermediğinizde bağlantının olağan senkronizasyon kapsamı kullanılır. Kontrollü ilk alım için YYYY-MM-DD biçiminde aralık gönderebilirsiniz:

curl --request POST \
  --url https://api.tahsil.dev/banks/accounts/66b0f09a8f10000000000101/sync \
  --header "x-api-key: $TAHSIL_API_KEY" \
  --header "x-api-secret: $TAHSIL_API_SECRET" \
  --header "x-company-id: 66b0f09a8f10000000000001" \
  --header "content-type: application/json" \
  --data '{"startDate":"2026-07-01","endDate":"2026-07-15"}'

{
  "status": true,
  "result": {
    "accountId": "66b0f09a8f10000000000101",
    "bankCode": "aktifbank",
    "fetched": 148,
    "inserted": 147,
    "duplicates": 1,
    "accountCount": 2,
    "accountUpdated": true,
    "fetchedAt": "2026-07-15T10:25:02.000Z"
  }
}

Tahsil her hedefin hesap ve hareket sonucunu birleştirir. Hareketin subAccountKey alanı kaynak alt hesaba bağlanır. Aynı banka hareketi yeniden gelirse providerStamp kimliği üzerinden tekrar oluşturulmaz. Farklı hesaplardan aynı stamp gelirse veri sessizce birleştirilmez; 502 PROVIDER_STAMP_COLLISION döner. Sync isteğini zaman aşımı sonrası güvenle yeniden gönderebilirsiniz; sonucu bağlantı sağlığından doğrulayın.

6. Sağlığı izleyin

GET /banks/accounts/{id}/health; son setup ve sync denemesini, son başarılı çalışmayı, hata kodunu, süreyi ve schedule durumunu tek cevapta verir.

Çoklu hedef hataları

HTTP	Kod	Yapılacak işlem
`422`	`BANK_ACCOUNT_TARGET_REQUIRED`	En az bir IBAN gönderin
`422`	`BANK_ACCOUNT_TARGET_INVALID`	Geçersiz IBAN’ı düzeltin
`422`	`BANK_ACCOUNT_TARGET_DUPLICATE`	Normalize edildiğinde tekrar eden hedefi kaldırın
`422`	`BANK_ACCOUNT_TARGET_LIMIT_EXCEEDED`	Hedef sayısını en fazla 10’a indirin
`502`	`BANK_ACCOUNT_TARGET_QUERY_FAILED`	`meta.targetIndex` ile hedef sırasını ve bağlantı sağlığını inceleyin
`502`	`PROVIDER_STAMP_COLLISION`	Senkronizasyonu durdurup correlation kimliğiyle destek kaydı oluşturun

BANK_SYNC_INVALID_DATE_FORMAT için tarih biçimini, BANK_SYNC_INVALID_DATE_RANGE için başlangıç ve bitiş sırasını düzeltin. Bağlantı hatalarında API secret veya banka credential değerini cevap, uygulama logu ya da destek kaydına yazdırmayın.

Hoş geldiniz

Başlangıç

Firma ve erişim

Banka bağlantıları

Banka hareketleri

Otomasyon

Operasyon

Kaynaklar

Yetki ve güven sınırı

1. Bağlantıyı oluşturun

2. Banka alanlarını okuyun

3. Credential’ı ve iki IBAN’ı kaydedin

4. Setup çalıştırın

5. İlk senkronizasyonu başlatın

6. Sağlığı izleyin

Çoklu hedef hataları

​Yetki ve güven sınırı

​1. Bağlantıyı oluşturun

​2. Banka alanlarını okuyun

​3. Credential’ı ve iki IBAN’ı kaydedin

​4. Setup çalıştırın

​5. İlk senkronizasyonu başlatın

​6. Sağlığı izleyin

​Çoklu hedef hataları

Yetki ve güven sınırı

1. Bağlantıyı oluşturun

2. Banka alanlarını okuyun

3. Credential’ı ve iki IBAN’ı kaydedin

4. Setup çalıştırın

5. İlk senkronizasyonu başlatın

6. Sağlığı izleyin

Çoklu hedef hataları