API İstekleri

Bu sayfa, API ile sağlıklı ve güvenli iletişim kurmak için gerekli olan temel yapı taşlarını ve parametreleri 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.

İstek Nesnesi Kuralları

• Zorunlu Alanlar: Zorunlu alanları eksiksiz içermelidir.
• Veri Tipleri: Veri tipleri (string, number, boolean vb.) doğru formatta olmalıdır.
• Şema Uyumu: API dokümantasyonunda belirtilen şema ve kurallara uygun hazırlanmalıdır.

400 Bad Request Hatası

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

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/alınan 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 İmzalama: 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

1. Eksiksiz Gönderim: Her API çağrısında gerekli tüm header parametreleri eksiksiz gönderilmelidir.
2. Hata Yönetimi: Parametreler yanlış ya da eksik gönderilirse, API isteği 401 Unauthorized veya 400 Bad Request hatalarıyla reddedilir.
3. Güvenli Saklama: Header değerleri güvenli ortamlarda saklanmalı, log dosyalarında veya üçüncü kişilerle paylaşılmamalıdır.
4. Sunucu Tarafında Kullanım: API anahtarları ve gizli anahtarlar (secret key) sadece sunucu tarafında (backend) 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.

Header Parametreleri Tablosu

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=

Not

* işaretli alanlar doldurulması zorunlu parametrelerdir.