SSS

Kimlik Doğrulama (AccessToken) ile İlgili Sorular

AccessToken nasıl alınır?

Tüm endpoint’ler yetkilendirme ister. Token almak için POST /auth/token servisine kullanıcı adı ve şifre gönderilir.

Bu token, tüm isteklerde Header’da kullanılmalıdır:

Authorization: Bearer {AccessToken}

Token ne kadar süre geçerlidir?

expiresIn alanı saniye cinsinden süredir (örneğin 3600 → 1 saat).
Süre dolduğunda sistem 401 Unauthorized döner.
Yeni token alınmalıdır.

Refresh token desteği var mı?

Varsa, refreshToken ile yeni accessToken alınabilir. Eğer sisteminizde refresh token desteği yoksa, kullanıcı oturumu yenilenmelidir.

“401 Unauthorized” hatası alıyorum, neden?

• Token süresi dolmuş olabilir.
• Token yanlış kullanıcıya/tenant’a ait olabilir.
• Header eksik ya da yanlış yazılmıştır (Bearer unutulmuş olabilir).

Çözüm: Token’ı yenileyin ve formatın doğru olduğundan emin olun.

İstek Formatı & Gönderim Kuralları

API isteklerinde Content-Type zorunlu mu?

Evet. Tüm POST ve PUT isteklerinde şu header yer almalıdır:

Content-Type: application/json

Aksi takdirde 400 Bad Request alınabilir.

Boş alanlar nasıl gönderilmeli?

Boş bırakılacak string alanlar için

"address": null

veya hiç gönderilmemelidir. Boş string ("") gönderilmesi önerilmez.

“Zorunlu alan eksik” hatası aldım, nasıl çözülür?

Yanıtta “details” kısmı hangi alanın eksik olduğunu belirtir

{
  "errorCode": "ERR_VALIDATION",
  "details": { "field": "email" }
}

İlgili alanın zorunlu olup olmadığını endpoint tanımından kontrol edin.

Boolean alanlar string olarak gönderilebilir mi?

Hayır.

"isActive": "true" yerine "isActive": true şeklinde boolean türünde olmalıdır.

Veri İşlemleri (Oluşturma, Güncelleme, Silme)

Aynı “erpCode” veya “code” neden hata veriyor?

Bu alanlar sistemde benzersiz (unique) olmalıdır.

Aynı değer mevcutsa

{
  "errorCode": "ERR_CONFLICT",
  "message": "Aynı erpCode başka bir kayıtla çakışıyor."
}

Yeni kayıt eklemeden önce ilgili kodun kullanımda olup olmadığını sorgulayın.

Güncelleme (PUT) işlemlerinde code değiştirilebilir mi?

Evet, updateCode mevcut kaydı bulmak için kullanılır; code alanı yeni değerle güncellenebilir.

Ancak yeni code başka kayıtla çakışırsa 409 Conflict döner.

Silinen kayıtlar geri alınabilir mi?

Hayır.

DELETE endpoint’leri kalıcıdır.

Örneğin /vendor/creditcard çağrısı ile silinen kartlar geri getirilemez.

Hangi alanlar isteğe bağlı, hangileri zorunlu?

Her endpoint’in “Zorunlu” sütunu altında belirtilmiştir.

Bazı alanlar şarta bağlı olarak zorunludur (ör. taxNumber sadece kurumsal hesaplarda zorunlu).

PUT ve POST farkı nedir?

• POST: Yeni kayıt oluşturur.
• PUT: Mevcut kaydı günceller.
  Yanlış metod kullanımı 400 veya 409 hatasına yol açabilir.

Sunucu “500 Internal Server Error” dönerse ne yapılmalı?

Bu hata beklenmeyen sistemsel durumlardan kaynaklanır. Yanıttaki traceId ile teknik destek ekibine bildirim yapılmalıdır

{
  "traceId": "5c1d7f2a-ec81-4e1b-b72c-11e2f8cb234f"
}

Listeleme, Sayfalama & Filtreleme

Tüm kayıtları tek seferde alabilir miyim?

Hayır, sistem sayfalama yapısını zorunlu kılar.

Her istek için maksimum pageSize=100 gönderilebilir.

Toplam kayıt sayısını nereden öğrenebilirim?

Tüm listeleme yanıtlarında totalCount alanı bulunur. Bu değer toplam kayıt sayısını belirtir.

Filtre parametresi vermezsem ne olur?

Tüm kayıtlar döner.

Ancak performans için sayfalama yapılır (örneğin ilk 10 kayıt).

Filtrelerde büyük/küçük harf duyarlılığı var mı?

Genellikle case-insensitive’dir (örneğin "tr", "TR" fark etmez).

Ancak code gibi bazı alanlar birebir eşleşme gerektirir.

Ödeme, Kart ve Cari Hesap İşlemleri

Kart numaraları neden maskeleniyor?

Güvenlik gereği.

Kart numarası sadece ilk 6 ve son 4 hane gösterilir:

858563******9966

Tam numara hiçbir API çağrısında dönmez.

“isVisibleOnPayment” ne işe yarar?

Bu alan cari hesapların ödeme ekranlarında listelenip listelenmeyeceğini belirler.

true → ödeme ekranlarında görünür,

false → sadece arka plan işlemlerinde kullanılır.

Cari hesap “code” değişirse eski ödemeler etkilenir mi?

Hayır.

Eski işlemler updateCode referansıyla saklandığı için geçmiş veriler bozulmaz.

Kayıtlı kartlar neden görünmüyor?

• Token farklı tenant’a ait olabilir.
• Üyeye ait kayıtlı kart bulunmuyorsa 404 döner.
• Silinmiş kartlar hiçbir zaman listelenmez.

Geliştirici İpuçları & En İyi Uygulamalar

Hata yönetimini nasıl en iyi şekilde yapabilirim?

Her isteğin sonucunda isSuccess alanını kontrol edin. Hatalı isteklerde errorCode ve traceId’yi loglayın. Bu, hata ayıklamayı kolaylaştırır.

Test ortamında nasıl çalışabilirim?

Test ortamına ait base URL şu şekilde olur

https://sandbox.catvendorapi.com/

Gerçek işlemler öncesi test ortamında entegrasyon tamamlanmalıdır.

API sürüm değişiklikleri nasıl takip edilir?

Dokümanın “Versiyon Notları (Change Log)” bölümünde son değişiklikler listelenir. Yeni versiyonlar genellikle v2, v3 endpoint prefix’iyle gelir.

Rate Limit (istek sınırı) var mı?

Varsa 429 Too Many Requests hatası döner. Kısa süreli bekleyip yeniden deneyin veya destek ekibiyle iletişime geçin.

UTC tarih farkı neden oluşuyor?

API tüm tarihleri UTC (Coordinated Universal Time) olarak döner. İstemcide yerel saate dönüştürülmesi gerekir.

Kullanıcıya kayıt maili ne zaman gider?

Bazı endpoint’lerde (sendRegisterMail: true) belirtilirse, kullanıcıya kayıt maili otomatik gönderilir. Bu işlem opsiyoneldir.

Mobil kullanımı nasıl etkinleştiririm?

canUseMobile alanını true göndererek ilgili kullanıcıya mobil erişim izni verilir. Mobil kullanıcılar sadece desteklenen mobil uygulamaya giriş yapabilir.

JSON formatı dışında veri gönderebilir miyim?

Hayır.

Tüm istekler ve yanıtlar application/json formatındadır.

XML veya form-data desteklenmez.

Özetle

SSS bölümü, geliştiricilerin en sık karşılaştığı hataları, teknik kuralları ve iş kurallarını örneklerle açıklar.

Bu bölüm, sistemdeki tüm modüller (Bayi, Alt Bayi, Kullanıcı, Cari Hesap, Kart vb.) için ortaktır.