Yanıtlar ve hatalar - BankaPro API

Başarı zarfı

{
  "success": true,
  "data": {},
  "meta": {
    "requestId": "9cc0d3d1-1e63-4c90-b08f-90b6332e70ca",
    "timestamp": "2026-09-08T20:00:00.000Z"
  }
}

Alan	Açıklama
`data`	Uca göre nesne veya dizi
`meta.requestId`	İsteğin izleme kimliği; `x-request-id` başlığıyla aynıdır
`meta.timestamp`	Yanıtın üretildiği an (UTC)
`meta.page`, `meta.pageSize`, `meta.total`, `meta.totalPages`	Yalnız liste uçlarında. Bkz. Sayfalama ve filtreler
`meta.partial`	`true` ise yanıt eksik veri içerir
`meta.warnings`	Eksikliğin nedenini anlatan uyarılar

Kısmi yanıtlar ve uyarılar

Bakiye her hesap için bilinmeyebilir. Bu durumda istek yine başarılı döner ve meta.warnings durumu açıklar; veri eksikse meta.partial ayrıca true olur. Uyarı taşıyan yanıtı eksiksiz veri gibi işlemeyin.

"meta": {
  "partial": true,
  "warnings": [
    { "code": "BALANCE_VALUE_UNKNOWN", "message": "…", "accountCount": 2 }
  ]
}

Uyarı kodu	Anlamı
`BALANCE_VALUE_UNKNOWN`	Doğrulanmış bakiyesi bulunmayan hesaplar toplamlara dahil edilmedi
`BALANCE_VALUE_STALE`	Son hareket bakiye bilgisi taşımadığı için önceki doğrulanmış bakiye kullanıldı
`BALANCE_CURRENCY_MISMATCH`	Hesabın para birimiyle eşleşen bir hareket bakiyesi bulunamadı
`INVALID_ACCOUNT_CURRENCY`	Para birimi kodu geçersiz olan hesaplar bakiye toplamlarına dahil edilmedi

Tanımadığınız bir uyarı kodu gelirse onu da bir veri eksikliği işareti olarak ele alın.

Hata zarfı

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "pageSize 1-100 araliginda olmalidir.",
    "details": [{ "field": "pageSize", "rule": "min:1,max:100" }]
  },
  "traceId": "9cc0d3d1-1e63-4c90-b08f-90b6332e70ca"
}

Programınızın karar verirken error.code değerini kullanın; error.message insan için yazılmıştır ve değişebilir.
error.details doğrulama hatalarında hangi alanın hangi kuralı ihlal ettiğini listeler; diğer hatalarda boş dizidir.
traceId, destek talebinde paylaşmanız gereken kimliktir.

Hata kodları

HTTP	Kod	Ne zaman
400	`VALIDATION_FAILED`	Parametre veya gövde kurallara uymuyor; ayrıntı `details` içinde
400	`INVALID_JSON`	Gövde geçerli JSON değil
400	`TENANT_SELECTOR_FORBIDDEN`	İstekte firma seçmeye çalışan başlık veya parametre var. Bkz. Firma bağlamı
401	`UNAUTHORIZED`	Kimlik bilgisi yok, yanlış, anahtar pasif veya süresi dolmuş
403	`FORBIDDEN`	Anahtarın bu uç için yetkisi yok
403	`API_IP_FORBIDDEN`	İstek, anahtarın IP kısıtı dışındaki bir adresten geldi
403	`API_PRODUCT_FORBIDDEN`	Anahtarın BankaPro erişimi yok
403	`API_COMPANY_FORBIDDEN`	Firmanın BankaPro erişimi yok veya etkin değil
403	`CORS_FORBIDDEN`	İstek tarayıcıdan (`Origin` başlığıyla) geldi
404	`RESOURCE_NOT_FOUND`	Kaynak yok ya da firmanıza ait değil
413	`PAYLOAD_TOO_LARGE`	Gövde izin verilen boyutu aşıyor
429	`RATE_LIMITED`	İstek limiti aşıldı. Bkz. Limitler
500	`INTERNAL_ERROR`	Beklenmeyen sunucu hatası

Başka bir firmaya ait hesap veya hareket kimliğiyle yapılan istek 404 döner; kaydın var olup olmadığı açıklanmaz.

İzleme kimliği (`x-request-id`)

Her yanıtta x-request-id başlığı bulunur. İsteğinizde kendi kimliğinizi gönderebilirsiniz: değer 1–100 karakterse ve yalnız harf, rakam, nokta, alt çizgi, iki nokta veya tire içeriyorsa korunur, aksi halde sunucu yeni bir UUID üretir. Kendi log kayıtlarınızla eşleştirmek için bu kimliği saklayın.

curl https://api.banka.pro/v1/bank-transactions \
  -u "$BANKAPRO_API_KEY_ID:$BANKAPRO_API_SECRET" \
  -H "x-request-id: erp-sync-2026-09-08-001"

Önbellek

Bütün yanıtlar Cache-Control: no-store taşır. Banka verisini ara katmanlarda (CDN, proxy) önbelleğe almayın.