اتصال ERP و CRM: قرارداد مالک فیلد، رخداد و retry

سه سیستم دارید: ERP که موجودی و قیمت را می‌داند، CRM که مشتری و فروش را می‌داند، و وب‌سایت که سفارش می‌گیرد. هر کدام از دیگری داده می‌خواهد. اگر اتصال را «هر وقت چیزی عوض شد، برای بقیه بفرست» بنویسید، ظرف چند ماه دو مشتری با دو شماره‌تلفن، قیمتی که در سایت و ERP فرق دارد و سفارشی که دو بار ثبت شده خواهید داشت. راه‌حل، یک قرارداد اتصال مکتوب است: مالک هر فیلد، رخدادها، قاعدهٔ تکرار، نسخه و تعارض.

مرز منابع: ایدمپوتنسی و خطاهای نامعین را از مستندات Stripe و تکرار با backoff را از مقالهٔ Amazon Builders' Library گرفته‌ایم؛ این‌ها الگوهای عمومی‌اند که Stripe و AWS مثال می‌زنند، نه مشخصهٔ ERP یا CRM شما. قالب‌ها و جدول‌ها توصیهٔ نویسنده‌اند. قوانین داده و مالیات ایران بررسی نشده است. برای مفهوم API API چیست و REST API چیست را ببینید.

اول: مالک هر فیلد

قاعدهٔ اصلی: هر فیلد فقط یک مالک دارد؛ بقیه فقط‌خواندنی یا کپی‌اند. مالک را بر اساس «چه کسی دانش معتبر دارد» انتخاب کنید، نه بر اساس سهولت اتصال.

نکتهٔ سفارش: مالکیت می‌تواند در طول چرخهٔ عمر دست‌به‌دست شود (وب‌سایت تا ثبت، بعد ERP)؛ این را با یک «وضعیت تحویل مالکیت» صریح ثبت کنید، نه ضمنی.

دوم: رخدادها، نه کپی دوره‌ای

برای هر تغییر معنادار یک رخداد با نام و شکل مشخص تعریف کنید: «سفارش ثبت شد»، «موجودی تغییر کرد»، «مشتری ادغام شد». حداقل فیلدهای هر رخداد (توصیهٔ نویسنده):

• شناسهٔ یکتای رخداد (برای حذف تکرار در مصرف‌کننده)؛
• نوع و نسخهٔ طرح (مثلاً order.created، نسخه ۱)؛
• زمان وقوع در مبدأ (نه زمان دریافت)؛
• شناسهٔ موجودیت و یک شمارندهٔ نسخه یا زمان آخرین تغییر برای تشخیص رخداد قدیمی؛
• داده کمینه؛ برای بقیه، مصرف‌کننده با شناسه داده را می‌خواند.

رخداد «لحظه‌ای» تغییر را می‌رساند؛ برای ترمیم خطا یک مسیر «همگام‌سازی کامل» هم داشته باشید که بازهٔ زمانی را دوباره بخواند.

سوم: تکرار بدون تکثیر

AWS می‌گوید API دارای عارضهٔ جانبی فقط وقتی برای تکرار امن است که ایدمپوتنت باشد؛ در غیر این صورت تکرار می‌تواند اثر را چند بار ایجاد کند. Stripe الگوی عملی می‌دهد: کلاینت کلیدی تا ۲۵۵ نویسه می‌سازد؛ سرور نتیجهٔ نخستین اجرا را نگه می‌دارد و در تکرار با همان کلید همان پاسخ را برمی‌گرداند؛ اگر همان کلید با پارامتر دیگر بیاید خطا می‌دهد. Stripe پیشنهاد می‌کند کلید را از یک شیء کاربر مثل شناسهٔ سبد خرید هم بتوان ساخت، که برای ما معادل «شناسهٔ سفارش وب‌سایت» است.

قواعد پیشنهادی برای اتصال شما:

1. هر درخواست نوشتن (ایجاد سفارش در ERP) یک کلید ایدمپوتنسی دارد که از شناسهٔ سفارش مبدأ ساخته می‌شود.
2. ERP در تکرار با همان کلید، همان نتیجه را بدهد و در تکرار با پارامتر متفاوت خطا بدهد.
3. مصرف‌کنندهٔ رخداد، شناسهٔ رخدادهای پردازش‌شده را ذخیره کند و تکراری را نادیده بگیرد.
4. پیامد پاسخ 500 یا timeout را «نامعین» بدانید: Stripe هم می‌گوید پیامد 500 نامعین است و پیش از تکرار با کلید جدید باید نتیجه را تطبیق داد.

فاصلهٔ تکرار و محدودیت

AWS هشدار می‌دهد تکرار می‌تواند بار سیستم وابسته را تقویت کند و برای کاهش آن backoff نمایی با jitter و محدودکردن تعداد تکرار را توصیه می‌کند؛ همچنین محدودکردن تکرار با token bucket را معرفی می‌کند. معنای عملی (توصیهٔ نویسنده): تعداد تلاش را محدود کنید (مثلاً ۵ بار)، فاصله را افزایش دهید و تصادفی کنید، و بعد از آن پیام را به یک «صف خطا» (dead-letter) بفرستید با هشدار به مالک. عدد دقیق را با ظرفیت سیستم‌هایتان تنظیم کنید؛ ما عدد مرجع نداریم.

چهارم: نسخه و تغییر طرح

• تغییر سازگار (افزودن فیلد اختیاری) بدون نسخهٔ جدید؛ مصرف‌کننده فیلد ناشناخته را نادیده بگیرد.
• تغییر ناسازگار (حذف، تغییر معنا) نسخهٔ جدید رخداد؛ مدت هم‌زمانی مشخص برای نسخهٔ قدیم.
• یک پروندهٔ «تعریف رخدادها» در مخزن، با مالک و تاریخچه.
• آزمون قرارداد: نمونهٔ رخداد هر نسخه در تست خودکار هر دو طرف.

پنجم: حل تعارض

ششم: تطبیق و پایش

هر شب برای هر موجودیت مشترک شمار و مجموع کنترلی (مثلاً تعداد سفارش‌های روز و جمع مبلغ) را بین سیستم‌ها مقایسه کنید و اختلاف را هشدار دهید. متریک‌های اتصال (تعداد رخداد، تأخیر، خطا، صف خطا) را با اصول پایش سیستم بسنجید. برای تصمیم‌های معماری کلی‌تر، انتخاب معماری اپلیکیشن وب را ببینید.

قالب یک‌صفحه‌ای قرارداد

اشتباهات رایج

• دو مالک برای یک فیلد، با همگام‌سازی دوطرفه.
• تکرار بدون کلید ایدمپوتنسی و بدون حذف تکرار در مصرف‌کننده.
• تکرار بی‌پایان و هم‌زمان که سیستم مقصد را بیشتر می‌اندازد.
• رخداد بدون نسخه و بدون شناسه.
• نبودن مسیر ترمیم (همگام‌سازی کامل) و تطبیق شبانه.

چک‌لیست

1. مالک هر فیلد مشترک مکتوب و یکتاست.
2. رخدادها شناسه، نسخه، زمان وقوع و شمارندهٔ ترتیب دارند.
3. عملیات نوشتن با کلید ایدمپوتنسی انجام می‌شود و مصرف‌کننده تکرار را نادیده می‌گیرد.
4. تکرار محدود، با backoff و jitter و صف خطا است.
5. قاعدهٔ تغییر طرح و نسخه‌بندی مکتوب است.
6. قاعدهٔ حل تعارض و تطبیق شبانه تعریف و پایش می‌شود.
7. الزامات داده و مالیات ایران از منبع رسمی روز و حسابدار بررسی شده است.

منابع و مراجع

• Idempotent requests — Stripe.
• Advanced error handling — Stripe.
• Timeouts, retries, and backoff with jitter — Amazon Builders' Library (Marc Brooker)، 2019-12-05.
• How to use objects for business processes — HubSpot، 2026-10-02.