Ana içeriğe geç

SSS(Sık Sorulan Sorular)

Kimlik Doğrulama & Güvenlik​

AccessToken neden 24 saat sonra geçersiz oluyor?

  • Açıklama: Güvenlik politikası gereği token’lar süreli üretilir (default 24 saat).
  • Çözüm: expiry değerini yerelde saklayın; istek öncesi kontrol edip dolmuşsa yeniden alın.
  • İpucu: Sunucu saat farklarından etkilenmemek için her zaman UTC bazlı karşılaştırma yapın.

“401 Unauthorized” alıyorum; tipik nedenler neler?

  • Nedenler
    • Authorization header eksik/yanlış format: Bearer <token> değil
    • Token süresi dolmuş
    • Yanlış ortam token’ı (Demo token → Prod istek)
  • Çözüm
    • Header örneği
      Authorization: Bearer eyJhbGciOi… Content-Type: application/json
    • Token’ı yenileyip isteği tekrar gönderin.

Token otomatik yenileme akışını nasıl kurarım?

  • Önerilen Akış
    • Token + expiry lokalde saklanır
    • Her istekten önce nowUtc < expiry - skew kontrol edilir (skew ~5 dk)
    • Gerekirse /auth/api/token/connect ile yenilenir, ardından orijinal istek tekrarlanır
      Not: 401 döndüğünde tek seferlik otomatik refresh-retry yapmak iyi pratiktir.

“403 Forbidden” ne anlama gelir, nasıl çözülür?

  • Anlamı: Lisans/servis yetkisi yok veya kapalı.
  • Kontrol Listesi
    • CAT API lisansı aktif mi?
    • “Servis Yetkileri” kısmında endpoint açık mı?
    • Dakika/istek limitleri sebebiyle engel var mı? (0 = limitsiz)

TLS ve güvenli başlıklar için gereksinimler neler?

  • Gereksinimler: TLS 1.2+; tüm istekler HTTPS.
  • Başlıklar
  • Authorization: Bearer ...Content-Type: application/json
  • Gerekirse X-Request-Id ile idempotency/izlenebilirlik sağlayın.

Listeleme, Sayfalama ve Filtreleme​

“GET /CurrentAccountTransaction” ile tüm veriyi tek seferde çekebilir miyim?

  • Yanıt: Hayır. Performans için sayfalama zorunlu.
  • Varsayılanlar: page=1, pageSize=10 (maks. genellikle 100 önerilir).
  • Örnek: GET /cat/cat/list?page=1&pageSize=98

Tekil sorgu mu, sayfalı liste mi? Nasıl karar verilir?

Kural

  • Tekil: Id veya ErpCode verilirse sadece o kayıt döner.
  • Liste: Id/ErpCode yoksa page/pageSize ile sayfalı sonuç döner.
  • Hata: Her ikisi de boş ve sayfalama yoksa 400 dönebilir.

Neden boş liste dönüyor?

Muhtemel Nedenler

  • Parametre isimleri case-sensitive (örn. ErpCode ≠ erpcode).
  • Filtre değeri yanlış veya kayıt yok.
    Öneri: Parametre adlarını dokümandaki ile birebir kullanın.

Performansı nasıl artırırım?

İpuçları

  • Gereksiz filtre ve büyük pageSize göndermeyin.
  • Mümkünse ErpCode/currentAccountErpCode gibi indeksli alanları kullanın.
  • Büyük sorguları tarih aralığıyla parçalayın.

Agent (Bayi/Müşteri) ve Veri Doğruluğu​

AgentErpCode neden önemli ve nasıl doğrulanır?

  • Önemi: İşlemin ilişkilendirildiği ajan (bayi/müşteri) tekil anahtarıdır.
  • Doğrulama: Portalda kayıtlı kodla birebir (büyük/küçük harf, noktalama) eşleşmelidir.

currentAccountErpCode ile AgentErpCode farkı nedir?

Fark

  • AgentErpCode: işlemi yapan/ilişkili ajan
  • currentAccountErpCode: borcun bağlı olduğu cari hesap
    Not: Çok şubeli yapılarda farklı olabilir; dizi şeklinde gönderilebilir.

“404 Not Found” ama cari hesap var; neden?

Olası Sebepler

  • Hesap pasif/silinmiş
  • Ortam farkı (Demo’da var, Prod’da yok)
  • Yazım/biçim hatası
    Çözüm: Aktiflik durumunu ve doğru ortamı doğrulayın; parametre adlarını kontrol edin.

Çakışmalar (duplicate) neden olur?

  • Neden: Aynı erpCode ile ikinci kez kayıt oluşturma girişimi.
  • Davranış: 409 Conflict.
  • Çözüm: Güncelleme için PUT kullanın veya benzersiz erpCode üretin.

Para birimi (currencyId) uyuşmazlıklarında ne yapmalı?

  • Kural: ISO kodları (TRY, USD, EUR) ve sistemde tanımlı olmalı.
  • Hata Örneği
  { 
    "status": "error", 
    "message": "Geçersiz currencyId", 
    "messageCode": "404" 
  }

Çözüm: Portal/konfigde tanımlı para birimlerine uygun değer gönderin.

Ödemeler, İadeler ve Borç Bildirimi​

Vadesi geçen borçlar için bildirim nasıl tetiklenir?

  • Endpoint: POST cat/cat/SendCATDebtInfoMail
  • Koşullar
    • PaidAmount ≤ Amount
    • DueDate < now
    • Cari hesap ve borç sahibi aktif/silinmemiş

Yanıt Örneği

  {  
      "status": "success",  
      "message": "Borç bilgilendirme içierikleri gönderildi"  
  }

Bildirim gitmiyorsa ne kontrol etmeliyim?

  • Bildirim şablonu (Hareket Borç Bildirim) aktif mi?
  • E-posta/telefon bilgisi mevcut mu?
  • Kullanıcı yetkileri uygun mu?
  • Kayıt koşulları (vade, ödeme oranı) sağlanıyor mu?

Mail/SMS önceliği nerede belirlenir?

  • Yanıt: Portal tarafındaki şablon kurallarında. API, kuralları uygulayarak çalışır; body boş gönderilir.

Borç görünmedi; neden?

  • Muhtemel Nedenler
    • Kayıt soft-deleted/pasif
    • Filtreleme hatası
    • Farklı ortamda sorgu
  • Çözüm: Durum alanlarını ve sorgu parametrelerini doğrulayın.

Bildirim yükünü azaltmak için öneri var mı?

Öneriler

  • Zamanlanmış tetikleme (cron) ve koşul ön kontrolü
  • Loglama + hata/başarı raporlama
  • Rate limitlere dikkat (429 almamak için aralıklı gönderim)