API Yanıtları

Bu sayfa, API tarafından dönen yanıtların yapısını, anlamını ve olası durum kodlarını açıklar.

Yanıt (Response) İmzası ve Doğrulama

İstek başarıyla işlendiğinde, tüm API'lerimiz yanıt başlığında (response header) bir imza döner. Bu imza, yanıtın gönderildiği andan itibaren değiştirilmediğini (veri bütünlüğü) ve yetkili kaynaktan geldiğini (kaynak doğruluğu) kanıtlar. Güvenlik açısından, her çağrıda bu alanların istemci tarafından doğrulanması kritik öneme sahiptir.

Yanıtta Görebileceğiniz Başlıklar

• x_signature – Yanıt imzası
• x_nonce – Sunucu tarafından üretilen, tek seferlik benzersiz değer
• x_timestamp – Yanıtın üretildiği zamanı temsil eden zaman damgası (format dokümantasyonda belirtilir; örn. ISO-8601 veya Unix epoch ms)

Neyi Doğrulamalısınız?

İmza Eşleşmesi: Sunucudan gelen x_signature ile sizin yeniden hesapladığınız imza birebir aynı olmalıdır.

Zaman Damgası Geçerliliği:x_timestamp, belirlediğiniz tolerans aralığı içinde olmalıdır (örn. ±5 dk). Büyük sapmalar replay saldırısı riski taşır.

Nonce Tekilliği:x_nonce, kısa süreli bir önbellekte saklanmalı ve tekrar kullanımı reddedilmelidir (replay önleme).

Yanıt İmzası Nasıl Hesaplanır?

İmza, istek tarafındaki mantığın yanıt için uygulanmış halidir. Tipik olarak şu bileşenler bu sırayla yan yana eklenir:

client_token_hash + secret_key + nonce + timestamp + response_body

Ardından:

1. Ortaya çıkan string SHA256 ile hash'lenir,
2. Hash sonucu Base64'e çevrilir,
3. Elde edilen değer x_signature ile karşılaştırılır.

Bileşen Detayları

• client_token_hash: clientToken → SHA256 → Base64
• secret_key: Üretildiği formatın aynısıyla, hiçbir dönüşüm yapılmadan kullanılır.
• response_body: Geldiği haliyle (boşluklar, yeni satırlar, karakter kaçışları dahil) imzaya dahil edilir. JSON'u yeniden biçimlendirmeyin; ham gövde baytlarını kullanın.

Özel Durumlar

Aktarım katmanı değişiklikleri:

• HTTP istemcinizin otomatik sıkıştırma, yeniden biçimlendirme veya karakter kodlaması gibi davranışları imzayı bozabilir.
• Tercihen imzayı ham (raw) gövde baytları üzerinden hesaplayın.
• Karakter kodlaması olarak UTF-8 kullanın ve iki tarafta da aynı olduğundan emin olun.

Günlükleme (logging):secret_key, clientToken veya türevlerini log'lamayın. Hata ayıklamada yalnızca imza doğrulama sonucu ve meta bilgileri (ör. timestamp, nonce) yeterlidir.

Hata Durumunda Önerilen Davranış

İmza eşleşmiyorsa veya timestamp/nonce kontrolleri başarısızsa:

• Yanıtı işleme almayın.
• Olayı güvenlik uyarısı olarak log'layın (gizli verileri maskeleyerek).
• Ağ geçici hatası olabileceğini düşünüyorsanız tek seferlik yeniden deneme yapın.
• Sorun sürerse entegrasyon anahtarlarınızın güvenliğini kontrol edin ve HalkÖde destek ekibiyle iletişime geçin.

Header Alanları

Ad	Tip	Açıklama
x_nonce	string	Cevaba özel rastgele oluşturulmuş benzersiz ID
x_timestamp	string	UTC zaman damgası, yyyyMMddHHmmss formatında.
x_signature	string	Mesaj imzası. (Client token hash'i + secret key + nonce + timestamp + yanıt gövdesi, SHA256 ile hash'lenip Base64 formatına dönüştürülerek header'a eklenir.)

API Yanıt (Response) Yapısı ve Kontrolleri

Tüm API çağrılarında, sistem tarafından döndürülen sonuç nesnesi belirli bir standart formatta iletilir. Bu yapı, geliştiricilerin çağrının başarılı olup olmadığını hızlı ve güvenilir bir şekilde anlamasına yardımcı olur.

1️⃣ Temel Alanlar

Her yanıt nesnesinde genellikle aşağıdaki ana alanlar bulunur:

Alan	Açıklama
state	Çağrının başarı durumunu gösterir. Örnek: "0" (Başarısız) veya "1" (Başarılı). Her çağrıda bu alanın kontrol edilmesi, veri bütünlüğünü ve işlem doğruluğunu sağlamak açısından kritik öneme sahiptir.
result	Gerçek yanıt verisinin yer aldığı alandır. Bu alan, API'den API'ye farklılık gösterebilir; yani her servis kendi özel veri yapısını bu alanda döndürür.
message / error	(Opsiyonel) Hata durumunda veya ek bilgi sağlamak için kullanılan açıklayıcı mesaj alanıdır.

2️⃣ state Alanının Önemi

• Her API çağrısı sonrası mutlaka state kontrol edilmelidir.
• Başarısız (0) durumlarda, yanıtın diğer alanları işlem için geçersiz olabilir.
• Bu kontrol, hem veri bütünlüğünü hem de işlem güvenliğini sağlamaya yardımcı olur.

3️⃣ result Alanı

• result, çağrıya özel asıl veriyi içerir.
• Örneğin bir ödeme sorgulama API'sinde, result içinde işlem detayları, tutar, ödeme durumu gibi bilgiler yer alabilir.
• Her API'nin döndürdüğü nesne yapısı farklıdır, bu yüzden ilgili API'nin "Yanıt (Response)" bölümüne bakarak yapıyı anlamak gerekir.

4️⃣ Örnek Yaklaşım (Pseudo JSON)

{
  "state": "1",
  "result": {
    "transactionId": "123456789",
    "amount": 100.50,
    "currency": "TRY",
    "status": "COMPLETED"
  },
  "message": "İşlem başarıyla tamamlandı."
}

Burada:

• state → çağrı sonucu,
• result → asıl işlem verisi,
• message → isteğe bağlı açıklama mesajıdır.

Önemli

result içindeki veri formatı API'den API'ye değişiklik gösterebilir. Her yeni entegrasyon veya API çağrısında dokümantasyondaki ilgili Response bölümünü mutlaka inceleyin.

Ad	Tip	Açıklama
state	enum	İşlemin başarı durumu. (1: Başarılı, 0: Hatalı)
result	object	Asıl sonuç nesnesi. Tüm uç noktaların (endpoint) yanıtları bu alanda yer alır.