پاسخ کوتاه
پیش از سفارش اتصال API، مستندات و محیط آزمایش، روش احراز هویت، موجودیتها و فیلدها، جهت و زمان تبادل، شناسه یکتای رکورد، رفتار Retry، جلوگیری از ثبت تکراری، مدیریت خطا، گزارش مغایرت و مالک پشتیبانی هر دو سامانه را مشخص کنید. برآورد معتبر بدون دسترسی به مستندات و نمونه داده معمولاً ممکن نیست.
اول مسئله کسبوکار و مرز اتصال را بنویسید
عبارت «اتصال CRM به حسابداری» برای تخمین کافی نیست. باید رویداد آغازکننده، اطلاعات ورودی، نتیجه مورد انتظار و مالک تصمیم مشخص شوند. برای مثال: «پس از قطعیشدن فاکتور در CRM، مشتری و سند فروش در حسابداری ایجاد و شماره سند به CRM بازگردانده شود.»
دامنه
- پرسش کلیدی
- کدام جریانها متصل میشوند؟
- نمونه پاسخ
- ایجاد مشتری و فاکتور؛ نه دریافت و پرداخت
منبع حقیقت
- پرسش کلیدی
- نسخه معتبر هر داده کجاست؟
- نمونه پاسخ
- اطلاعات مشتری در CRM، مانده در حسابداری
جهت
- پرسش کلیدی
- تبادل یکطرفه است یا دوطرفه؟
- نمونه پاسخ
- فاکتور رفت و شماره سند برگشت
زمان
- پرسش کلیدی
- لحظهای، دورهای یا دستی؟
- نمونه پاسخ
- صف لحظهای با امکان ارسال مجدد دستی
مالک خطا
- پرسش کلیدی
- چه کسی مغایرت را پیگیری میکند؟
- نمونه پاسخ
- کارشناس مالی با داشبورد خطا
آمادگی API هر دو سامانه را ارزیابی کنید
نسخه مستندات، URL محیط Sandbox، نمونه Request و Response، روش دریافت دسترسی و محدودیت Rate باید پیش از برآورد بررسی شوند. اگر فقط یک فایل ناقص یا دسترسی Production وجود دارد، برای مرحله کشف فنی و نمونهسازی زمان جدا در نظر بگیرید.
- مستندات نسخهدار ترجیحاً در قالب OpenAPI یا نمونه معادل
- محیط Sandbox و حساب آزمایشی با داده غیرحساس
- روش Authentication، عمر Token و فرایند تمدید یا چرخش کلید
- محدودیت تعداد درخواست، Timeout و اندازه Payload
- Webhooks، ترتیب رویدادها و روش تأیید دریافت
- سیاست تغییر نسخه و زمان اعلام Deprecation
نگاشت داده و شناسهها را قبل از کدنویسی ببندید
دو سامانه معمولاً نام، نوع و قواعد اعتبارسنجی یکسانی ندارند. جدول نگاشت باید فیلد مبدأ، مقصد، تبدیل، اجباریبودن، مقدار پیشفرض و رفتار در داده نامعتبر را نشان دهد. کد مشتری یا شماره ملی نیز همیشه بهتنهایی شناسه مناسب یکپارچهسازی نیست.
customerId
- فیلد مقصد
- external_reference
- قاعده تبدیل
- ذخیره شناسه پایدار سامانه مبدأ
- رفتار خطا
- توقف همان رکورد و ثبت خطا
mobile
- فیلد مقصد
- phone
- قاعده تبدیل
- یکسانسازی کد کشور و ارقام
- رفتار خطا
- رد مقدار نامعتبر
status
- فیلد مقصد
- document_state
- قاعده تبدیل
- نگاشت جدول وضعیت مصوب
- رفتار خطا
- ارسال به صف بررسی دستی
updatedAt
- فیلد مقصد
- last_sync_at
- قاعده تبدیل
- ذخیره UTC و نمایش محلی
- رفتار خطا
- هشدار ترتیب زمانی ناسازگار
Retry، Idempotency و بازیابی خطا را طراحی کنید
قطعی شبکه و پاسخهای موقت بخشی طبیعی از سیستم توزیعشدهاند. Retry محدود با فاصله افزایشی میتواند خطای موقت را پوشش دهد، اما برای عملیات تغییردهنده مانند ثبت پرداخت باید Idempotency Key یا شناسه یکتا وجود داشته باشد تا تکرار درخواست، عملیات را دوباره انجام ندهد.
پس از پایان تلاشها، رکورد نباید ناپدید شود. وضعیت، دلیل خطا، زمان تلاش بعدی و امکان ارسال مجدد کنترلشده باید در صف خطا یا داشبورد عملیاتی ثبت شود.
- تفکیک خطای موقت از خطای دائمی یا اعتبارسنجی
- حداکثر تعداد Retry و Backoff مشخص
- Idempotency Key برای عملیات دارای اثر جانبی
- Correlation ID مشترک در لاگ دو سامانه
- Dead-letter یا صف بررسی برای خطاهای تکرارشونده
- عملیات Reconcile برای کشف رکوردهای جاافتاده یا متفاوت
امنیت اتصال API فقط نگهداری یک کلید نیست
مجوز باید برای هر شیء و عملیات کنترل شود، نه صرفاً در لحظه ورود. داده خروجی نیز باید به حداقل موردنیاز محدود باشد. مصرف منابع، ورودی سامانه ثالث، نسخههای فراموششده API و لاگنشدن رخدادها از ریسکهای شناختهشده یکپارچهسازیاند.
- HTTPS و اعتبارسنجی گواهی در تمام مسیر
- دسترسی حداقلی، Token کوتاهعمر و چرخش Secret
- کنترل سطح دسترسی شیء و عملیات در هر Endpoint
- اعتبارسنجی Schema و محدودکردن Payload و نرخ درخواست
- حذف داده حساس از Log و پیام خطا
- ثبت Audit برای تغییرات مهم و فراخوانیهای مدیریتی
معیار پذیرش و مسئولیت پشتیبانی اتصال
آزمون موفقیت فقط دریافت کد ۲۰۰ نیست. مسیرهای تکرار، Timeout، Token منقضی، داده نامعتبر، پاسخ ناقص و قطعی هر سامانه را بررسی کنید. معیار پذیرش باید تعداد و صحت رکورد، زمان همگامسازی و روش گزارش خطا را پوشش دهد.
- آزمون قرارداد داده و فیلدهای اجباری
- آزمون ثبت تکراری و ارسال رویداد با ترتیب متفاوت
- آزمون قطعی، Timeout، Rate Limit و انقضای Token
- مقایسه تعداد و مبلغ رکوردها در گزارش Reconciliation
- Alert برای توقف جریان یا افزایش خطا
- تعیین مسئول هر سامانه، ساعات پاسخ و مسیر Escalation
پرسشهای متداول
آیا وجود API یعنی اتصال ساده و کمهزینه است؟
خیر. کیفیت مستندات، Sandbox، قواعد داده، امنیت، جهت همگامسازی و سناریوهای خطا روی زمان و هزینه اثر مستقیم دارند.
Webhook بهتر است یا دریافت دورهای اطلاعات؟
Webhook برای رویداد نزدیک به لحظه مناسب است، اما باید اعتبارسنجی، Retry و کشف رویداد ازدسترفته داشته باشد. دریافت دورهای سادهتر است ولی تأخیر و بار بیشتری ایجاد میکند. انتخاب به نیاز کسبوکار بستگی دارد.
اگر نرمافزار فعلی API نداشته باشد چه میشود؟
ابتدا امکان Export استاندارد، افزونه رسمی یا لایه واسط بررسی میشود. اتصال مستقیم به دیتابیس یا RPA ممکن است در بعضی شرایط ممکن باشد، اما ریسک امنیت و نگهداری آن باید جدا ارزیابی شود.
چه کسی باید خطاهای اتصال را پشتیبانی کند؟
در قرارداد باید برای هر سمت مالک فنی، مسئول کسبوکار و مسیر Escalation مشخص باشد. بدون این توافق، هر اختلال ممکن است بین دو تأمینکننده معطل بماند.
خدمت و راهنماهای مرتبط
برای ادامه مسیر، صفحه خدمت مرتبط، نمونهکار و راهنماهای مکمل را ببینید.
منابع و مبنای تدوین
این راهنما با استفاده از مستندات فنی و منابع تخصصی زیر تدوین شده است. تصمیم نهایی هر پروژه باید با دادهها، قرارداد و شرایط واقعی همان سازمان تطبیق داده شود.