Idempotency

Yazma uçları her istekte bir Idempotency-Key header'ı bekler. Ağ hatası veya timeout sonrası aynı isteği aynı anahtarla tekrarlayabilirsiniz; işlem ikinci kez yürütülmez, ilk sonucun aynısı döner.

Header bekleyen uçlar: card/pay, transaction/capture, payment/link/create, recurring/create.

Zorunlu

Idempotency-Key header'ı gönderilmezse istek HTTP 400 ile reddedilir. Gövdedeki idempotencyKey alanı bu mekanizmanın parçası değildir — o alan sizin kendi referansınızdır ve yalnızca işlem kaydına yazılır.

Kullanım

curl -X POST https://<host>/partner/1.0/pos/card/pay \
  -H "X-Api-Key: ..." \
  -H "X-Timestamp: ..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: pay-ORD-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "ORD-1001",
    "paymentMethod": "CARD",
    "amount": 100.00,
    "currency": "TRY"
  }'

Idempotency-Key imzaya dahil değildir; ancak her tekrar denemesinde X-Timestamp ve X-Signature yeniden üretilmelidir — aynı imza 5 dakikalık pencerede ikinci kez kabul edilmez (bkz. Kimlik Doğrulama).

Davranış

Durum	Sonuç
Header yok	400 — istek işlenmez.
İlk istek	Normal işlenir; sonuç anahtara bağlanır.
Aynı anahtar + aynı gövde, ilk istek tamamlanmış	İlk isteğin sonucu döner; işlem tekrar yürütülmez.
Aynı anahtar + aynı gövde, ilk istek hâlâ sürüyor	406 — eşzamanlı tekrar reddedilir; ilk isteğin bitmesini bekleyip tekrar deneyin.
Aynı anahtar + farklı gövde	406 — anahtar başka bir istek için kullanılmış. Her mantıksal işleme kendi anahtarını verin.
İlk istek başarısız bitmiş	Aynı anahtar yeniden denenebilir.

Anahtarlar entegrasyonunuzun işletmesi kapsamında benzersizdir ve 24 saat saklanır. Farklı uçlar birbirinin anahtarını görmez.

Önerilen Pattern

{işlem}-{orderNumber}:

pay-ORD-1001
link-ORD-1001

Anahtarı isteği oluştururken üretip saklayın; tekrar denemede aynısını gönderin. Her denemede yeni anahtar üretmek korumayı devre dışı bırakır.