> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fatorly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# معرّف عدم التكرار

> لماذا يحتاج كل POST إلى ترويسة Idempotency-Key، وكيف تختار قيمتها، وماذا يحدث عند إعادة المحاولة.

الشبكات غير موثوقة. قد ينجح الطلب على الخادم لكن لا تصلك الاستجابة — فتبقى غير
متأكّد إن كان عليك إعادة المحاولة. يزيل **معرّف عدم التكرار** هذا الخطر: تُرفِق
مفتاحًا فريدًا بكل عملية كتابة، وتضمن الواجهة حدوث العملية مرة واحدة على الأكثر.

## ترويسة `Idempotency-Key`

كل عملية `POST` (الفواتير والعملاء والأصناف وغيرها) **تتطلّب** ترويسة
`Idempotency-Key`. وهي سلسلة فريدة يولّدها العميل وتُعرّف هذه العملية تحديدًا:

```bash theme={null}
curl https://integration.fatorly.com/v1/invoices \
  -H "X-Api-Key: fat_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-2026-00042" \
  -d @invoice.json
```

<Warning>
  إذا غابت ترويسة `Idempotency-Key`، يُرفَض الطلب برمز **HTTP 400**. لا توجد قيمة
  افتراضية ضمنية.
</Warning>

<Note>
  **استثناء واحد:** الطلب `POST /invoices/{id}/validate` (ونظيره لإشعارات الخصم)
  فحص للقراءة فقط لا يغيّر شيئًا، لذلك **لا** يتطلّب ترويسة `Idempotency-Key` —
  استدعِه بحرّية أثناء تصحيح المسودّة.
</Note>

## اختيار المفتاح

* اجعله **فريدًا لكل عملية منطقية** — مثلًا مفتاح واحد لكل فاتورة تنوي إنشاءها.
  يصلح كلٌّ من قيمة UUID أو معرّف عمل ثابت مثل `invoice-2026-00042`.
* **لا تُعِد استخدام** مفتاح لعملية مختلفة. فالمفتاح هو ما يعتمده الخادم للتعرّف
  على التكرار.
* ولّده على جهة **العميل** قبل المحاولة الأولى، وأعِد استخدام القيمة **نفسها** في
  كل إعادة محاولة للعملية ذاتها.

## ماذا يحدث عند إعادة المحاولة

عندما ترسل طلبًا بمفتاح `Idempotency-Key` سبق أن عالجه الخادم، فإنه **لا** يُنشئ
سجلًّا ثانيًا. بل يُعيد بأمان **النتيجة الأصلية** للطلب الأول:

<Steps>
  <Step title="الطلب الأول">
    ينشئ `POST /invoices` مع `Idempotency-Key: invoice-2026-00042` الفاتورة
    ويُعيدها.
  </Step>

  <Step title="ضياع الاستجابة">
    تعني المهلة المنتهية أو الاتصال المقطوع أنك لم ترَ الاستجابة، فلا تعرف إن نجح
    الطلب.
  </Step>

  <Step title="إعادة المحاولة بالمفتاح نفسه">
    تُعيد إرسال الطلب ذاته تمامًا بنفس `Idempotency-Key`. تتعرّف الواجهة على
    المفتاح وتُعيد الفاتورة الأصلية — **دون إنشاء أي نسخة مكرّرة**.
  </Step>
</Steps>

تحمل الاستجابة المُعادة الترويسة **`Idempotency-Replayed: true`** لتميّزها عن
تنفيذ جديد.

<Note>
  هذا يجعل إعادة المحاولة آمنة تمامًا. أعِد المحاولة دائمًا بالمفتاح نفسه بدلًا من
  توليد مفتاح جديد، وإلا اعتبره الخادم عملية جديدة كليًا وقد تُنشئ نسخة مكرّرة.
</Note>

<Warning>
  إعادة استخدام المفتاح مع **جسم طلب مختلف** تُرفَض برمز **HTTP 409 Conflict** —
  فالخادم يرفض التخمين أيّ نسخة قصدت. يجب أن تُعيد إعادةُ المحاولة إرسال الجسم
  نفسه تمامًا؛ أما العملية الجديدة فتحتاج مفتاحًا جديدًا. راجع
  [الأخطاء](/ar/developers/errors).
</Warning>