API İstekleri

Bu sayfa, bir API ile sağlıklı ve güvenli iletişim kurmak için gerekli olan temel yapı taşlarını açıklar.

İstek (Request) Yapısı ve Geçerlilik Kontrolü

API ile sağlıklı bir iletişim kurulabilmesi için, istemcilerin gönderecekleri istek (request) nesnelerinin belirlenen kurallara ve yapıya uygun şekilde oluşturulması gerekmektedir.

Her bir istek nesnesi;

• Zorunlu alanları eksiksiz içermeli,

• Veri tipleri (string, number, boolean vb.) doğru formatta olmalı,

• API dokümantasyonunda belirtilen şema ve kurallara uygun hazırlanmalıdır.

⚠️ Eğer gönderilen istek nesnesi doğru biçimde oluşturulmamışsa, API çağrısı işleme alınmaz ve sistem tarafından 400: Bad Request hatası döndürülür.

Bu hata durumunda:

• Yanıt (response) nesnesi içerisinde, hatanın nedeni açıklayıcı bir şekilde iletilir.

• Hangi alanın eksik, hatalı veya yanlış formatta olduğu belirtilir.

• Böylece istemci, hatayı kolayca tespit edip düzeltebilir.

Önemli: İstek nesnesinin doğru şekilde oluşturulması, entegrasyon sürecinin sorunsuz ilerlemesi için kritik öneme sahiptir. Yanlış yapılandırılmış istekler yalnızca hata alınmasına değil, aynı zamanda işlem sürelerinin uzamasına ve sistem kaynaklarının gereksiz kullanımına da yol açabilir.

Başlık (Header) Parametreleri ve Güvenlik Önemi

Her API çağrısında, istemcinin kimliğini doğrulamak ve gönderilen mesajın güvenilirliğini sağlamak için belirli başlık (header) parametreleri eklenmelidir. Bu parametreler, kimlik doğrulama (authentication) ve mesaj imzalama (message signing) süreçlerinin temelini oluşturur.

Bu alanların her çağrıda doğru şekilde ayarlanması, yalnızca yetkili istemcilerin API’ye erişebilmesini sağlar ve gönderilen/verilen verilerin üçüncü kişiler tarafından değiştirilmeden iletilmesini garanti altına alır.

🔹 Başlık parametrelerinin önemi:

• Kimlik doğrulama: API’ye hangi istemcinin bağlandığını doğrular. Böylece yalnızca yetkili uygulamalar işlem yapabilir.

• Mesaj imzalama: Gönderilen isteğin içeriğinin değiştirilip değiştirilmediğini kontrol eder. Bu sayede veri bütünlüğü korunur.

• Zaman damgası (timestamp) kullanımı: Her isteğin geçerlilik süresini sınırlandırır, böylece olası tekrar saldırılarının (replay attack) önüne geçilir.

• Şifreleme ve hashleme: Özel anahtar (secret key) ile imzalanan istekler, sadece doğru anahtara sahip taraflarca doğrulanabilir.

🔹 Uygulama sırasında dikkat edilmesi gerekenler:

• Her API çağrısında gerekli tüm header parametreleri eksiksiz gönderilmelidir.

• Parametreler yanlış ya da eksik gönderilirse, API isteği 401 Unauthorized veya 400 Bad Request hatalarıyla reddedilir.

• Header değerleri güvenli ortamlarda saklanmalı, log dosyalarında veya üçüncü kişilerle paylaşılmamalıdır.

• API anahtarları ve gizli anahtarlar (secret key) sadece sunucu tarafında kullanılmalı, istemci tarafında (browser, mobil uygulama vb.) asla açık şekilde tutulmamalıdır.

---

Özetle: Header parametreleri, API çağrılarında yalnızca bir “zorunlu alan” değil; aynı zamanda sistemin güvenliğini, veri bütünlüğünü ve kimlik doğrulama sürecini garanti eden en kritik bileşenlerdir.

Ad	Tip	Açıklama
x_client_token*	string	Üye işyerine özel tanımlı (client) token. Header’da iletilirken doğrudan kullanılır, imza hesaplamasında ise SHA256 ile hash’lenip Base64 formatına dönüştürülmelidir. Örnek : 5383126a-5710-48fa-8a38-c5157b45e03a
x_nonce*	string	İsteğe özel rastgele oluşturulmuş benzersiz ID. Örnek : 1fd953f3-48bf-41ad-8526-6d2d4bb360ab
x_timestamp*	string	UTC zaman damgası, yyyyMMddHHmmss formatında. Örnek: 20250707152223
x_signature*	string	Mesaj imzası. (Client token hash'i + secret key + nonce + timestamp + istek gövdesi, SHA256 ile hash'lenip Base64 formatına dönüştürülerek header'a eklenmelidir.) Örnek : iYq5tAzHM1sG1sDP0NmPD64gBZ8VlPEZPYxEprBLnTM=