---
title: "کلید یکتاسازی (Idempotency Key)"
description: "کلید یکتاسازی چیست، چرا API حسابداری برای جلوگیری از ثبت سند تکراری هنگام تلاش دوباره به آن نیاز دارد، چه مقداری مناسب است و سرور در تکرار چه پاسخی می‌دهد."
canonical: https://hesabdar.my/glossary/idempotency-key
language: fa
publisher: "حسابدار من"
updated: 2026-11-06
---

# کلید یکتاسازی (Idempotency Key)

> کلید یکتاسازی چیست، چرا API حسابداری برای جلوگیری از ثبت سند تکراری هنگام تلاش دوباره به آن نیاز دارد، چه مقداری مناسب است و سرور در تکرار چه پاسخی می‌دهد.

کلید یکتاسازی مقداری یکتاست که برنامه همراه درخواستی که چیزی می‌سازد ارسال می‌کند تا فرستادن دوباره همان درخواست اثر اضافه‌ای نداشته باشد. اگر خطای شبکه معلوم نکند درخواست اول موفق بوده یا نه، برنامه با همان کلید دوباره تلاش می‌کند و سرور به‌جای ساخت سند تکراری، نتیجه اول را برمی‌گرداند.

تلاش دوباره اجتناب‌ناپذیر است: قطع ارتباط، پایان مهلت پاسخ و راه‌اندازی دوباره سرویس‌ها برنامه را درباره نتیجه درخواست مردد می‌گذارد. بدون این کلید، تکرار «ثبت سند» فروش را دو بار ثبت می‌کند و دفتر تا وقتی کسی متوجه شود اشتباه می‌ماند.

راه‌حل این است که کلید را از سابقه خودتان بسازید، مثلاً `shop-order-1045` یا شماره فاکتور در سیستم فروش، و در سرآیند `Idempotency-Key` بفرستید. در [حسابدار من](https://hesabdar.my/guides/accounting-api) درخواست تکراری با کلیدی که قبلاً استفاده شده، همان سند موجود را با وضعیت ۲۰۰ به‌جای ۲۰۱ برمی‌گرداند و چیز جدیدی ثبت نمی‌کند.

در هر تلاش کلید تصادفی تازه نسازید؛ این کار هدف را از بین می‌برد. کلید را یک بار برای هر رویداد بسازید و کنار همان رویداد ذخیره کنید تا همه تلاش‌ها یک مقدار داشته باشند.

## مثال: تلاش دوباره پس از قطع ارتباط

سرویس پرداخت درخواست ثبت سند را با `Idempotency-Key: payout-1405-08-15-001` می‌فرستد. سند شماره ۴۸۲ ساخته می‌شود اما پاسخ در قطع ارتباط گم می‌شود. سرویس با همان کلید دوباره تلاش می‌کند و سند ۴۸۲ را با وضعیت ۲۰۰ دریافت می‌کند. در دفتر یک سند هست، نه دو سند.

### کدام درخواست‌ها به کلید یکتاسازی نیاز دارند؟

عمدتاً درخواست‌های POST که رکورد می‌سازند. درخواست‌های GET، PUT و DELETE اگر درست پیاده‌سازی شوند ذاتاً تکرارپذیرند.

### کلید یکتاسازی همان شماره عطف سند است؟

می‌تواند همان مقدار را داشته باشد، اما کاربردش فرق دارد: شماره عطف برای انسان روی سند ذخیره می‌شود و کلید یکتاسازی به سرور می‌گوید دو درخواست، یک تلاش واحدند.

راهنما: https://hesabdar.my/guides/accounting-api