Ana içeriğe geç

Idempotency

Amaç

Idempotency-Key, ağ hatası, timeout veya geçici arıza nedeniyle ERP istemcisinin aynı işlemi tekrar göndermesi durumunda business işleminin birden fazla uygulanmasını önler.

Kapsam:

text POST /api/v1/inbound/work-orders

Test endpointi POST /api/v1/inbound/work-orders/test halka açık format doğrulama rotasıdır. Idempotency-Key istemez, acquire/replay yapmaz ve idempotency kaydı yazmaz. Bkz. Gelen İş Emirleri.

Tutarlılık garantisi

Bu servis normal çalışma koşullarında effectively-once istek işleme; kesinti sonrası güvenli retry ve natural-key uzlaştırma sağlar.

MongoDB standalone ortamında business yazımı ile idempotency tamamlaması multi-document transaction içinde olmadığı için mutlak exactly-once iddiası yoktur.

HTTP sözleşmesi

Zorunlu header (live)

http Idempotency-Key: ERP-WO-20260807-000001

Kurallar:

Kural Değer
Zorunluluk IDEMPOTENCY_ENABLED=true ve IDEMPOTENCY_REQUIRED=true iken zorunlu
Uzunluk 8–128 karakter
Karakterler A-Z a-z 0-9 . _ : -
Boşluk Baş/sondaki whitespace reddedilir
Büyük/küçük harf Case-sensitive
Çoklu header Reddedilir

Scope

Tekillik şu alanlarla kapsamlanır:

  • client_id (auth principal; auth kapalıysa anonymous)
  • company_id
  • organization_id
  • HTTP method
  • route
  • idempotency_key

Farklı tenant veya client altında aynı key bağımsızdır.

Response headerları

Header İlk istek Replay
X-Request-ID Mevcut attempt id Yeni attempt id
Idempotency-Key Key echo Key echo
Idempotency-Replayed false true
Idempotency-Original-Request-ID Mevcut ile aynı İlk işlenen request id

Envelope request_id her zaman mevcut HTTP attempt id değeridir.

Eşzamanlı işleme

Aktif processing lease varken:

  • HTTP 409
  • kod IDEMPOTENCY_REQUEST_IN_PROGRESS
  • header Retry-After: 2

Payload çakışması

Aynı scope/key, farklı canonical payload:

  • HTTP 409
  • kod IDEMPOTENCY_KEY_CONFLICT
  • mesaj: The Idempotency-Key has already been used with a different request payload.

Canonical request hash

Karşılaştırma canonical_request_sha256 ile yapılır (decode, normalize, validation, tenant resolve sonrası).

Dahil:

  • resolve edilmiş company_id / organization_id
  • normalize edilmiş projects contract
  • endpoint contract version

Hariç:

  • request_id, zaman damgaları, Authorization, token, remote IP, User-Agent, Accept

JSON/XML semantik eşdeğerlik aynı hash üretebilir. Accept hash’e dahil değildir.

Arşiv için ayrıca raw_body_sha256 tutulur.

Processing lease

IDEMPOTENCY_PROCESSING_LEASE_SECONDS (varsayılan 300, min 30, max 3600).

Lease dolmadan aynı key için diğer istekler in-progress alır. Lease dolunca aynı hash ile ownership alınabilir.

Retryable hatalar

MongoDB unavailable / beklenmeyen 5xx → failed_retryable. Sonraki aynı key/hash ownership alıp yeniden deneyebilir. Deterministik completed business yanıtları (ör. 409 NO_PROJECT_PROCESSED) saklanır ve replay edilir.

Retention

IDEMPOTENCY_RETENTION_HOURS (varsayılan 720 = 30 gün) expires_at değerini belirler. TTL index expireAfterSeconds: 0 kullanır.

ERP retry örneği

  1. Live isteği Idempotency-Key: ERP-WO-20260807-000001 ile gönderin.
  2. Timeout olursa aynı key ve aynı payload ile tekrarlayın.
  3. İlk istek tamamlandıysa replayed logical response alın (Idempotency-Replayed: true).
  4. Hâlâ processing ise Retry-After kadar bekleyip tekrarlayın.
  5. Aynı key’i farklı work-order payload için yeniden kullanmayın.

İlgili