بهروزرسانی ۸ آبان ۱۴۰۵: خلاصه پاسخ به ابتدای صفحه آمد، راهنماهای تازه مرتبط و سؤالهای جدید اضافه شد و راه گرفتن مشاوره کوتاهتر شد.
یکپارچه سازی API یعنی نرمافزارهای کسبوکارتان را طوری به هم وصل کنید که داده خودش بین آنها جابهجا شود و کسی مجبور نباشد اطلاعات را دستی از یک جا به جای دیگر کپی کند. مثلاً سفارشی که در سایت ثبت میشود، بعد از پرداخت خودکار در حسابداری فاکتور شود، موجودی را کم کند و برای مشتری پیامک برود. بیشتر کسبوکارهای ایرانی امروز سایت، درگاه پرداخت، سامانه پیامک، حسابداری و گاهی CRM و انبار را جدا از هم دارند. وقتی اینها به هم وصل نیستند، یک یا چند نفر از تیم هر روز ساعتها وقت میگذارند تا عددها را یکی کنند و آخر هم جایی اشتباه میشود.
در این راهنما ساده توضیح میدهیم API و وبهوک چیست، کدام اتصالها اول ارزش انجام دارند، هر سرویس ایرانی (درگاه، پیامک، حسابداری، ارسال، ترب و دیجیکالا) چه نکتهای دارد، یک پروژه اتصال چطور جلو میرود و قبل از سفارش چه چیزهایی را باید روشن کنید تا اتصال «ظاهراً کار کند» ولی داده را خراب نکند.
بهروزرسانی ۲۰ مهر ۱۴۰۵: بخشهای تازهای درباره آماده بودن نرمافزار حسابداری برای اتصال، فرق اتصال قابل اعتماد با اتصال نمایشی، اینکه کدام خطا باید دوباره امتحان شود و کدام نه، گزارش تطبیق روزانه، برنامه رفتار در زمان قطعی سرویسها و بسته تحویل اتصال اضافه کردیم.
جواب کوتاه
- اول کارهای دستی تکراری را فهرست کنید و ببینید هر کدام در ماه چند ساعت وقت میگیرد و چقدر خطا میسازد. اتصالهایی را اول انجام دهید که بیشترین وقت و خطا را حذف میکنند.
- برای هر داده (کالا، قیمت، موجودی، مشتری، سفارش) فقط یک «سیستم مرجع» تعیین کنید. اگر قیمت هم در سایت عوض شود هم در حسابداری، دیر یا زود دو عدد متفاوت دارید.
- پرداخت را هیچوقت فقط با برگشت کاربر از درگاه تأیید نکنید؛ تأیید نهایی باید از سمت سرور و با استعلام از خود درگاه انجام شود.
- هر اتصال باید برای قطعی، تکرار درخواست و داده ناقص برنامه داشته باشد: صف، تلاش مجدد محدود و جلوگیری از ثبت تکراری.
- اتصال بدون پایش، روزی بیصدا از کار میافتد. داشبورد وضعیت، هشدار و گزارش مغایرت جزو خود کار است، نه اضافه.
- برای هزینه، اتصال ساده به یک سرویس معمولاً در حد دهها میلیون تومان است و همگامسازی دوطرفه سازمانی چند صد میلیون؛ جزئیات را در هزینه طراحی API در ۱۴۰۵ نوشتهایم.
API و وبهوک به زبان ساده
API (رابط برنامهنویسی) راه مشخصی است که یک نرمافزار از طریق آن از نرمافزار دیگر چیزی میخواهد یا به آن چیزی میفرستد. مثلاً سایت شما از سامانه پیامک میخواهد «این کد را به این شماره بفرست»، یا از حسابداری میپرسد «موجودی این کالا چند تاست؟». API تعیین میکند چه چیزی را میشود خواست، با چه فیلدهایی و جواب به چه شکلی برمیگردد. رایجترین نوعش در وب REST است که داده را معمولاً به شکل JSON جابهجا میکند.
وبهوک برعکس کار میکند: بهجای اینکه سیستم شما هر چند دقیقه بپرسد «خبر جدیدی هست؟»، سیستم طرف مقابل هر وقت اتفاقی افتاد خودش به آدرسی که شما دادهاید خبر میدهد. مثلاً ووکامرس هر سفارش جدید را به حسابداری اطلاع میدهد یا درگاه نتیجه تراکنش را میفرستد. وبهوک سریع و کمهزینه است، ولی باید امضا یا کلیدش بررسی شود تا کسی نتواند درخواست جعلی بفرستد.
چرا اتصال مستقیم به دیتابیس سیستم دیگر ایده خوبی نیست؟
گاهی پیشنهاد میشود برای سرعت، سایت مستقیم به دیتابیس حسابداری وصل شود. این کار اولش ساده به نظر میرسد، اما با اولین بهروزرسانی نرمافزار حسابداری ممکن است ساختار جدولها عوض شود و اتصال بشکند. قانونها و اعتبارسنجیهای خود نرمافزار هم دور زده میشوند و کنترل دسترسی سخت میشود. اگر نرمافزار وبسرویس رسمی دارد، از همان استفاده کنید. اتصال مستقیم به دیتابیس فقط وقتی منطقی است که راه دیگری نباشد، آن هم فقطخواندنی و با هماهنگی پشتیبانی همان نرمافزار.
آیا الان به یکپارچهسازی نیاز دارید؟ یک تست ۸ سؤالی
به هر سؤال که جوابش «بله» است یک امتیاز بدهید. این تست جای بررسی فنی را نمیگیرد، اما نشان میدهد اتصال برای شما چقدر فوری است.
| سؤال | اگر «بله» است یعنی |
|---|---|
| سفارشهای سایت را کسی دستی در حسابداری وارد میکند؟ | اتصال سفارش به حسابداری احتمالاً اولین اولویت است |
| هفتهای حداقل یک بار کالایی در سایت موجود است ولی در انبار تمام شده؟ | همگامسازی موجودی لازم است |
| قیمتها را در بیش از یک جا عوض میکنید؟ | باید سیستم مرجع قیمت تعیین شود |
| پیامک وضعیت سفارش یا نوبت را کسی دستی میفرستد؟ | اتصال پیامک خدماتی سریع جواب میدهد |
| لیدهای فرم سایت گاهی گم میشوند یا دیر پیگیری میشوند؟ | اتصال فرم به CRM یا پنل فروش |
| در ترب، دیجیکالا یا بازارگاه دیگری هم میفروشید؟ | همگامسازی قیمت و موجودی چندکاناله |
| آخر ماه برای تطبیق تراکنشهای درگاه با فاکتورها وقت زیادی میگذارید؟ | گزارش تطبیق خودکار لازم است |
| اپ موبایل یا نمایندگانی دارید که باید داده سایت را ببینند؟ | به API اختصاصی خودتان نیاز دارید |
۰ تا ۲ امتیاز: فعلاً با چند اتصال آماده و ساده (مثل افزونه رسمی درگاه و پیامک) کارتان راه میافتد. ۳ تا ۵ امتیاز: یک پروژه اتصال مرحلهای با دو یا سه اتصال اصلی منطقی است. ۶ تا ۸ امتیاز: بهتر است قبل از هر کدنویسی، نقشه کامل جریان داده و سیستم مرجع هر داده را بکشید؛ شاید حتی بازنگری در خود نرمافزارها لازم باشد.
حساب ساده: کار دستی امروز چقدر میارزد؟
قبل از اینکه درباره بودجه تصمیم بگیرید، کار دستی فعلی را با عدد ببینید. جدول زیر یک مثال فرضی است، نه آمار واقعی یک مشتری؛ عددهای خودتان را جایگزین کنید.
| کار دستی (مثال فرضی) | زمان در روز | زمان در ماه (۲۶ روز کاری) | خطای رایج |
|---|---|---|---|
| ورود سفارشهای سایت در حسابداری | ۴۵ دقیقه | حدود ۲۰ ساعت | اشتباه در کد کالا یا مبلغ |
| بهروز کردن موجودی سایت از روی انبار | ۳۰ دقیقه | حدود ۱۳ ساعت | فروش کالای ناموجود |
| ارسال پیامک کد رهگیری | ۲۰ دقیقه | حدود ۹ ساعت | جا افتادن مشتری |
| تطبیق تراکنشهای درگاه | — | حدود ۸ ساعت آخر ماه | پرداخت بدون سفارش یا برعکس |
| جمع | حدود ۵۰ ساعت |
در این مثال، تقریباً یکچهارم وقت یک نیروی تماموقت صرف جابهجایی داده میشود؛ بدون اینکه هزینه سفارشهای لغوشده به خاطر موجودی اشتباه را حساب کرده باشیم. اگر هزینه ماهانه این ساعتها و خطاها را در دوازده ماه ضرب کنید، معمولاً روشن میشود کدام اتصال ارزش انجام فوری دارد و کدام میتواند صبر کند.
اتصالهای رایج در ایران و نکته مخصوص هر کدام
بیشتر مقالهها فقط میگویند «سایت را به پیامک و حسابداری وصل کنید». اما هر سرویس ایرانی جزئیاتی دارد که اگر از اول دیده نشود، پروژه را عقب میاندازد:
| اتصال | چه کاری انجام میدهد | نکتهای که معمولاً جا میافتد |
|---|---|---|
| درگاه پرداخت (شاپرک، پرداختیارها) | ساخت تراکنش، برگشت کاربر، تأیید پرداخت | تأیید نهایی باید سمت سرور انجام شود؛ تراکنشهای «پرداختشده ولی تأییدنشده» برنامه پیگیری میخواهند. جزئیات در اتصال درگاه پرداخت به سایت |
| سامانه پیامک | کد تأیید، وضعیت سفارش، یادآوری نوبت | پیامک خدماتی معمولاً با قالب از پیش تأییدشده (پترن) ارسال میشود و تأیید قالب زمان میبرد؛ متنها را زود آماده کنید. پیامک تبلیغاتی قوانین جدا دارد |
| نرمافزار حسابداری | انتقال سفارش، مشتری، فاکتور؛ گرفتن قیمت و موجودی | بعضی نرمافزارها (مثل سپیدار و هلو) وبسرویس فروشگاهی دارند، ولی معمولاً به نسخه و ماژول خاص وابسته است. قبل از برآورد با پشتیبانی همان شرکت چک کنید |
| شرکتهای ارسال و پست | ثبت مرسوله، کد رهگیری، محاسبه هزینه ارسال | همه شرکتها API عمومی ندارند؛ بعضی فقط پنل یا فایل اکسل میدهند. شکل اتصال را قبل از قول دادن به مشتری روشن کنید |
| ترب و مقایسهگرهای قیمت | ارسال قیمت و موجودی محصولات | فیلدها و نسخه API ترب مشخص است و خطای رایج، ناهماهنگی موجودی است. راهنمای کامل در اتصال سایت به ترب |
| دیجیکالا و بازارگاهها | همگامسازی موجودی و قیمت بین سایت و بازارگاه | کد کالا در دو طرف یکی نیست و جدول نگاشت میخواهد. توضیح بیشتر در اتصال فروشگاه به دیجی کالا |
| CRM یا پنل فروش | ثبت خودکار لید از فرم، منبع ورود، پیگیری | شماره موبایل باید یک شکل ذخیره شود (۰۹ یا ۹۸+) تا مشتری تکراری ساخته نشود. ببینید: اتصال فرم سایت به CRM |
| ربات تلگرام یا بله | اعلان سفارش به تیم، پاسخ به مشتری | برای اعلان داخلی تیم ساده و کمهزینه است. ببینید: ساخت ربات تلگرام برای کسبوکار |
نرمافزار حسابداری شما برای اتصال آماده است؟
بیشترین تأخیر پروژههای اتصال به حسابداری از همینجا میآید: کارفرما فکر میکند نرمافزارش «API دارد»، ولی بعد معلوم میشود نسخهاش ماژول وبسرویس ندارد یا آن ماژول جداگانه فروخته میشود. قبل از گرفتن برآورد، این سؤالها را از فروشنده یا پشتیبانی نرمافزار حسابداری بپرسید:
| سؤال | چرا مهم است | اگر جواب منفی بود |
|---|---|---|
| نسخه فعلی ما ماژول وبسرویس یا API دارد؟ | خیلی از نرمافزارهای داخلی وبسرویس را بهصورت ماژول جدا یا فقط در نسخههای بالاتر میدهند | ارتقای نسخه، خرید ماژول یا تبادل فایل زمانبندیشده |
| ماژول وبسرویس چقدر هزینه دارد و تمدید سالانه دارد یا نه؟ | این هزینه جدا از دستمزد برنامهنویس است. مثلاً صفحه فروش وبسرویس وبکام هلو در زمان نوشتن این مطلب بازه حدود ۱۶٫۵ تا ۲۷٫۵ میلیون تومان را نشان میداد | هزینه را در بودجه جدا بنویسید تا بعداً غافلگیر نشوید |
| مستندات و نمونه درخواست دارد؟ | بدون مستندات، برنامهنویس باید با آزمون و خطا کار کند و زمان پروژه بالا میرود | یک جلسه فنی با پشتیبانی سازنده قبل از قرارداد بگذارید |
| نرمافزار روی سرور شبکه داخلی نصب است یا ابری؟ | نسخه نصبی باید از بیرون در دسترس باشد؛ معمولاً یعنی IP ثابت، VPN یا یک برنامه واسط روی همان سیستم | هماهنگی با مسئول شبکه را زودتر شروع کنید |
| کد کالا، انبار و گروه مشتری چطور تعریف شدهاند؟ | اگر کدها نامنظم یا تکراری باشند، اتصال همان بینظمی را به سایت میبرد | اول کدینگ کالا را مرتب کنید، بعد اتصال را روشن کنید |
| محیط یا شرکت آزمایشی برای تست داریم؟ | تست روی دفاتر واقعی یعنی سندهای آزمایشی وسط حسابهای سال مالی | یک شرکت یا سال مالی آزمایشی کپی بگیرید |
جزئیات اتصال به سپیدار، هلو و نرمافزارهای مشابه را در اتصال سایت به نرمافزار حسابداری نوشتهایم.
چند سناریوی واقعی از یکپارچهسازی
فروشگاه اینترنتی با حسابداری و ارسال
مشتری خرید میکند و پرداخت از سمت سرور تأیید میشود. همان لحظه سفارش با کد کالای حسابداری به نرمافزار حسابداری میرود و فاکتور صادر میشود، موجودی کم میشود، مرسوله در سامانه ارسال ثبت میشود و کد رهگیری با پیامک برای مشتری میرود. اگر حسابداری آن لحظه در دسترس نباشد، سفارش در صف میماند و چند دقیقه بعد دوباره ارسال میشود؛ نه اینکه گم شود.
شرکت خدماتی با سایت و CRM
بازدیدکننده فرم مشاوره را پر میکند. لید با صفحه ورود و منبع تبلیغ در CRM ثبت میشود، به کارشناس مسئول میرسد و یک کار پیگیری برای همان روز ساخته میشود. مشتری پیامک «درخواست شما رسید» میگیرد و مدیر فروش آخر هفته گزارش تبدیل لید به تفکیک کانال را دارد.
کلینیک با نوبتدهی، بیعانه و یادآوری
بیمار آنلاین نوبت میگیرد، بیعانه را از درگاه میپردازد، پیامک تأیید با آدرس و آمادگیها میگیرد و یک روز قبل یادآوری دریافت میکند. این زنجیره ساده کنسلی را کم میکند؛ روشهایش را در کاهش کنسلی نوبتها نوشتهایم.
شرکت پخش با نمایندگان
نمایندگان بهجای گرفتن فایل اکسل قیمت، از طریق API یا پنل اختصاصی قیمت و موجودی روز را میبینند و سفارش ثبت میکنند. هر نماینده کلید جدا دارد تا اگر همکاری تمام شد، فقط دسترسی همان نماینده قطع شود.

سیستم مرجع هر داده؛ مهمترین تصمیم قبل از کدنویسی
بیشتر مشکلات اتصالها از فنی بودن نیست؛ از این است که معلوم نیست هر داده «مال» کدام سیستم است. جدول زیر حالت رایج برای یک فروشگاه با حسابداری است؛ ممکن است در کسبوکار شما فرق کند، اما مهم این است که روی کاغذ نوشته شود.
| داده | سیستم مرجع معمول | جهت | زمان انتقال |
|---|---|---|---|
| تعریف کالا و کد کالا | حسابداری | حسابداری به سایت | هنگام تعریف یا تغییر |
| موجودی | حسابداری یا انبار | به سایت و بازارگاهها | تا حد ممکن نزدیک به لحظه، بهخصوص اگر حضوری هم میفروشید |
| قیمت | فقط یک جا، به انتخاب شما | یکطرفه | هنگام تغییر |
| سفارش آنلاین | سایت | سایت به حسابداری | بلافاصله بعد از تأیید پرداخت |
| مشتری آنلاین | سایت | سایت به حسابداری و CRM | همراه اولین سفارش یا فرم |
| وضعیت ارسال | سامانه ارسال یا انبار | به سایت و پیامک مشتری | هنگام تغییر وضعیت |
| مرجوعی و لغو | سایت یا پنل پشتیبانی | به حسابداری و موجودی | هنگام ثبت، با تأیید کارشناس |
نمونه جدول نگاشت فیلدها
بعد از تعیین سیستم مرجع، باید معلوم شود هر فیلد در سیستم مبدأ به کدام فیلد در مقصد تبدیل میشود و اگر خالی بود چه اتفاقی بیفتد. یک تکه از جدول نگاشت سفارش به حسابداری معمولاً این شکلی است:
| فیلد در سایت | فیلد در حسابداری | تبدیل لازم | اگر خالی یا نامعتبر بود |
|---|---|---|---|
| شناسه سفارش | شماره مرجع فاکتور | بدون تغییر؛ برای جلوگیری از ثبت تکراری | ارسال متوقف و خطا ثبت شود |
| کد محصول سایت | کد کالا | از جدول نگاشت کد | سفارش در صف بررسی دستی برود |
| مبلغ (تومان) | مبلغ (ریال یا تومان) | تبدیل واحد پول در صورت نیاز | ارسال متوقف شود |
| تاریخ سفارش | تاریخ فاکتور | تبدیل میلادی و شمسی و منطقه زمانی تهران | تاریخ تأیید پرداخت جایگزین شود |
| موبایل مشتری | تلفن طرف حساب | یکسانسازی شکل شماره و ارقام فارسی و انگلیسی | مشتری بدون تلفن ثبت و علامتگذاری شود |
| هزینه ارسال و تخفیف | ردیف جدا در فاکتور | طبق روش حسابداری شما | با حسابدار هماهنگ شود |
ریال و تومان، تاریخ شمسی، ارقام فارسی و «ی» و «ک» عربی در اتصالهای ایرانی زیاد دردسر میسازند. اگر اینها از اول در جدول نگاشت دیده شوند، بخش بزرگی از مغایرتهای بعدی اصلاً پیش نمیآید.
روشهای اتصال؛ کدام برای شما مناسب است؟
| روش | کی مناسب است | محدودیت |
|---|---|---|
| افزونه یا اتصال آماده رسمی | سایت وردپرسی با درگاه، پیامک یا حسابداری رایج که افزونه رسمی دارد | فقط همان کارهایی که افزونه پشتیبانی میکند؛ وابسته به بهروزرسانی سازنده |
| ابزار اتوماسیون بدون کد | اتصالهای ساده بین سرویسهای خارجی محبوب | برای سرویسهای ایرانی، حجم بالا یا منطق پیچیده معمولاً کافی نیست |
| اتصال مستقیم نقطهبهنقطه | دو یا سه اتصال مشخص | با زیاد شدن سیستمها، شبکه درهمی میسازد که نگهداریاش سخت است |
| هاب مرکزی (بکاند اصلی) | چند سیستم و نیاز به گزارش و پایش یکجا | طراحی اولیه بیشتری میخواهد |
| تبادل فایل زمانبندیشده | نرمافزار قدیمی که API ندارد | لحظهای نیست؛ برای موجودی پرنوسان مناسب نیست |
برای بیشتر کسبوکارهای کوچک و متوسط، ترکیب «افزونه رسمی برای کارهای ساده + اتصال اختصاصی برای یکی دو جریان مهم» بهترین نسبت هزینه به نتیجه را دارد. اگر اتوماسیون فراتر از اتصال دو نرمافزار است، نگاهی به اتوماسیون فرایند کسبوکار بیندازید.
لحظهای یا دورهای؟
- لحظهای: بلافاصله بعد از رویداد، معمولاً با وبهوک. برای تأیید پرداخت، موجودی کالاهای پرفروش و پیامک به مشتری لازم است.
- دورهای: هر ساعت یا هر شب. برای انتقال فاکتورها به حسابداری یا گزارشها اغلب کافی و سادهتر است.
- ترکیبی: رویدادهای مهم لحظهای، بقیه دورهای، و یک تطبیق کامل شبانه که هر ناهماهنگی جاافتاده را پیدا کند. این حالت در عمل از همه مطمئنتر است.
مراحل یک پروژه یکپارچهسازی
| مرحله | چه کاری انجام میشود | خروجی که باید تحویل بگیرید |
|---|---|---|
| ۱. نقشه سیستمها و جریان داده | فهرست نرمافزارها، کارهای دستی و اینکه چه دادهای از کجا به کجا میرود | نمودار ساده جریان داده و فهرست اولویتها |
| ۲. بررسی APIهای موجود | مستندات، محیط آزمایشی، روش احراز هویت و محدودیت تعداد درخواست | گزارش امکانسنجی هر اتصال |
| ۳. سیستم مرجع و جدول نگاشت | تعیین مالک هر داده و تبدیل فیلدها | جدول نگاشت تأییدشده توسط شما و حسابدار |
| ۴. طراحی رفتار در خطا | اگر سرویسی قطع بود یا داده ناقص بود چه شود | سناریوهای خطا و مسئول رسیدگی |
| ۵. پیادهسازی و تست آزمایشی | ساخت اتصال روی محیط آزمایشی با داده نمونه | نتیجه تستهای پذیرش (جدول پایین) |
| ۶. همگامسازی اولیه | یکی کردن دادههای موجود قبل از روشن کردن اتصال | گزارش رکوردهای مغایر و اصلاحشده |
| ۷. راهاندازی و پایش | روشن کردن اتصال، داشبورد وضعیت و هشدار | دسترسی شما به داشبورد و گزارش مغایرت |
| ۸. مستندسازی و تحویل | توضیح هر اتصال، کلیدها و روش رسیدگی به خطا | مستندات، دسترسیها و سورس کد به نام شما |

فاز اول چه باشد، چه چیزی بماند برای بعد؟
بزرگترین اشتباه این است که همه اتصالها با هم شروع شوند. با یک یا دو جریانی شروع کنید که بیشترین کار دستی را حذف میکند و بعد که پایدار شد، سراغ بقیه بروید.
| نوع کسبوکار | فاز اول پیشنهادی | بعداً |
|---|---|---|
| فروشگاه اینترنتی | تأیید پرداخت سمت سرور، سفارش به حسابداری، پیامک وضعیت | ترب و دیجیکالا، سامانه ارسال، گزارش سود هر کالا |
| شرکت خدماتی | فرم سایت به CRM، پیامک تأیید، اعلان به تیم | ردیابی منبع تبلیغ، اتصال تماس تلفنی، پیشفاکتور خودکار |
| کلینیک و سالن | نوبتدهی، بیعانه، یادآوری پیامکی | اتصال مالی به حسابداری، باشگاه مشتریان |
| پخش و B2B | قیمت و موجودی از حسابداری به پنل نمایندگان | API برای سیستم نمایندگان بزرگ، محاسبه پورسانت |
مشکلات رایج و راهحل هر کدام
| مشکل | راهحل |
|---|---|
| نرمافزار قدیمی API ندارد | تبادل فایل زمانبندیشده، وبسرویس جانبی سازنده، یا در آخر اتصال فقطخواندنی به دیتابیس با هماهنگی پشتیبانی |
| سرویس طرف مقابل قطع یا کند است | صف، تلاش مجدد محدود با فاصله افزایشی و ثبت درخواستهای ناموفق |
| یک سفارش دو بار در حسابداری ثبت شد | ارسال شناسه یکتای سفارش و رد کردن درخواست تکراری در مقصد |
| داده دو سیستم با هم نمیخواند | سیستم مرجع روشن و گزارش تطبیق شبانه |
| سرویس طرف مقابل API را تغییر داد | جدا بودن لایه اتصال از بقیه کد و پیگیری اطلاعیههای سرویس |
| هیچکس متوجه خطا نشد | لاگ متمرکز، داشبورد وضعیت و هشدار خودکار در پیامرسان تیم |
اتصال قابل اعتماد چه فرقی با اتصال نمایشی دارد؟
اتصالی که در جلسه دمو یک سفارش را درست به حسابداری میفرستد، لزوماً روز شلوغ حراج را تحمل نمیکند. فرق این دو در چند جزئیات فنی است که کارفرما معمولاً نمیبیند، ولی نبودشان بعداً به شکل فاکتور تکراری، سفارش گمشده یا مغایرت مالی خودش را نشان میدهد. این جدول را میتوانید عیناً از پیمانکار بپرسید:
| موضوع | اتصال نمایشی | اتصال قابل اعتماد | سؤالی که از پیمانکار بپرسید |
|---|---|---|---|
| درخواست تکراری | اگر درخواست دو بار برسد، دو فاکتور ثبت میشود | هر عملیات یک شناسه یکتا دارد و مقصد درخواست تکراری را نادیده میگیرد | اگر شبکه وسط ارسال قطع شود و دوباره بفرستیم، چه چیزی جلوی ثبت دوباره را میگیرد؟ |
| کندی سرویس مقابل | کاربر پشت صفحه پرداخت منتظر میماند | کارهای کند در صف و پشت صحنه انجام میشوند و کاربر فوراً جواب میگیرد | کدام کارها همزمان با درخواست کاربر انجام میشوند و کدام در صف؟ |
| محدودیت تعداد درخواست | در روزهای شلوغ سرویس مقابل درخواستها را رد میکند و داده جا میماند | سرعت ارسال کنترل میشود و بعد از پیام «درخواست زیاد» با فاصله دوباره تلاش میشود | سقف درخواست هر سرویس را میدانید و برایش برنامه دارید؟ |
| وبهوک دریافتی | هر درخواستی که به آدرس برسد قبول میشود | امضا یا کلید هر وبهوک قبل از پردازش بررسی و رویداد تکراری کنار گذاشته میشود | اگر کسی آدرس وبهوک را پیدا کند و درخواست جعلی بفرستد چه میشود؟ |
| ترتیب رویدادها | فرض میشود همه چیز به ترتیب میرسد | رویدادی که دیر برسد، داده جدیدتر را با داده قدیمی بازنویسی نمیکند | اگر «لغو سفارش» زودتر از «ثبت سفارش» برسد چه اتفاقی میافتد؟ |
| کامل بودن داده | فقط به وبهوکها تکیه میشود | کنار وبهوک، یک تطبیق دورهای هم جاافتادهها را پیدا میکند | اگر یک وبهوک اصلاً نرسد، کی و چطور متوجه میشویم؟ |
| ردیابی | وقتی خطا شد، کسی نمیداند کجا | هر درخواست شماره پیگیری دارد و در لاگ از سایت تا مقصد قابل دنبال کردن است | برای یک سفارش مشخص، میتوانید مسیرش را در لاگ نشانم بدهید؟ |
کدام خطا باید دوباره امتحان شود و کدام نه؟
«تلاش مجدد خودکار» خوب است، ولی نه برای همه خطاها. اگر درخواستی به خاطر داده غلط رد شده باشد، هزار بار تکرارش فقط لاگ را پر میکند و ممکن است سرویس مقابل حساب شما را موقتاً مسدود کند.
| نوع خطا | مثال | رفتار درست |
|---|---|---|
| قطعی یا کندی موقت | تمام شدن مهلت پاسخ، خطای ۵۰۰ یا ۵۰۳ سرور مقابل | چند بار تلاش مجدد با فاصله افزایشی، با همان شناسه یکتا تا ثبت تکراری پیش نیاید |
| درخواست زیاد | خطای ۴۲۹ | صبر به اندازهای که سرویس اعلام کرده، بعد ادامه با سرعت کمتر |
| داده نامعتبر | کد کالای ناموجود، شماره موبایل اشتباه، فیلد اجباری خالی | تکرار نشود؛ برود در صف بررسی دستی و به مسئول هشدار داده شود |
| دسترسی | کلید منقضی یا اشتباه، خطای ۴۰۱ یا ۴۰۳ | تکرار نشود؛ هشدار فوری چون احتمالاً همه درخواستها رد میشوند |
| نتیجه نامعلوم | درخواست ارسال شد ولی جوابی نیامد | قبل از ارسال دوباره، از مقصد استعلام شود که ثبت شده یا نه |
همین منطق در پرداخت هم مهم است؛ نمونههایش را در پرداخت ناموفق در فروشگاه اینترنتی آوردهایم.
امنیت در اتصالها
- کلیدها و توکنها در جای امن سرور نگه داشته شوند، نه داخل کد یا فایلهای عمومی.
- هر اتصال فقط به حداقل دسترسی لازم محدود شود؛ کلید پیامک لازم نیست به حسابداری دسترسی داشته باشد.
- همه ارتباطها روی HTTPS باشند و وبهوکهای دریافتی امضا یا کلیدشان بررسی شود.
- هر شریک یا نماینده کلید جدا داشته باشد تا بشود فقط دسترسی یک نفر را قطع کرد.
- داده حساس مشتری فقط در صورت ضرورت منتقل و ذخیره شود.
- با رفتن هر نیرو یا پیمانکار، کلیدهایی که به آنها دسترسی داشتهاند عوض شوند.
برای فهرست کاملتر، چکلیست امنیت سایت کسبوکار را ببینید.

گزارش تطبیق روزانه؛ چه چیزی را با چه چیزی مقایسه کنیم؟
حتی بهترین اتصال هم گاهی یک رویداد را جا میاندازد. گزارش تطبیق یعنی هر روز، خودکار، اعداد دو سیستم کنار هم گذاشته شوند و اختلافها به یک نفر مشخص اعلام شود. این گزارش لازم نیست پیچیده باشد؛ یک جدول ساده در پنل یا یک پیام صبحگاهی کافی است.
| مقایسه | دو طرف | زمان | اختلاف معمولاً یعنی |
|---|---|---|---|
| تعداد و جمع مبلغ سفارشهای پرداختشده | سایت و حسابداری | هر شب | سفارشی در صف مانده یا کد کالایش نگاشت ندارد |
| تراکنشهای موفق | گزارش درگاه و سفارشهای سایت | هر شب | پرداخت انجام شده ولی سفارش تأیید نشده؛ باید با کد پیگیری بررسی شود |
| موجودی کالاهای پرفروش | انبار یا حسابداری و سایت | چند بار در روز | همگامسازی موجودی عقب افتاده؛ خطر فروش کالای ناموجود |
| قیمت | سیستم مرجع قیمت و سایت و بازارگاهها | بعد از هر تغییر قیمت گروهی | یکی از کانالها بهروز نشده |
| پیامکهای ارسالی | رویدادهای سایت و گزارش سامانه پیامک | هفتگی | قالب رد شده یا اعتبار پنل تمام شده |
| صف خطا | صف بررسی دستی | هر روز صبح | اگر صف خالی نمیشود، یک مشکل تکرارشونده هست که باید ریشهای حل شود |
وقتی یک سرویس قطع شد چه کنیم؟
بهتر است این برنامه قبل از اولین قطعی نوشته و به تیم داده شود، نه وسط بحران:
| سرویس قطعشده | اثر روی مشتری | کاری که سیستم خودکار انجام میدهد | کاری که تیم انجام میدهد |
|---|---|---|---|
| حسابداری | معمولاً هیچ؛ سفارش در سایت ثبت میشود | سفارشها در صف میمانند و بعد از وصل شدن ارسال میشوند | بعد از وصل شدن، گزارش تطبیق همان روز را چک میکند |
| درگاه پرداخت | پرداخت انجام نمیشود | اگر درگاه دوم دارید، خودکار یا دستی به آن سوئیچ میشود | تراکنشهای نیمهکاره را با گزارش درگاه تطبیق میدهد |
| سامانه پیامک | کد ورود یا اطلاعرسانی نمیرسد | پیامها در صف میمانند؛ در صورت امکان سرویس پشتیبان استفاده میشود | برای ورود، راه جایگزین موقت فعال میکند |
| ترب یا بازارگاه | قیمت و موجودی آنجا قدیمی میماند | تغییرات جمع میشوند و بعد یکجا ارسال میشوند | کالاهای ناموجود را دستی غیرفعال میکند |
برای ورود با پیامک و سرویس پشتیبان، ورود با پیامک در سایت را ببینید.
تست تحویل: قبل از پرداخت آخر اینها را امتحان کنید
| تست | نتیجه درست |
|---|---|
| یک سفارش آزمایشی کامل از سایت | فاکتور با مبلغ و کد کالای درست در حسابداری، موجودی کم شده، پیامک رسیده |
| کاربر پرداخت کند و قبل از برگشت به سایت صفحه را ببندد | پرداخت از سمت سرور تأیید و سفارش ثبت شود |
| همان سفارش دو بار ارسال شود | فقط یک فاکتور ثبت شود |
| حسابداری چند دقیقه خاموش باشد | سفارش در صف بماند و بعد از روشن شدن خودکار ثبت شود |
| کالایی که کد نگاشت ندارد سفارش داده شود | سفارش در صف بررسی دستی برود و هشدار بیاید |
| قیمت در سیستم مرجع عوض شود | در سایت و بازارگاهها در زمان توافقشده عوض شود |
| مرجوعی ثبت شود | موجودی برگردد و سند برگشت در حسابداری ثبت شود |
| گزارش تطبیق آخر روز | تعداد و جمع مبلغ سفارشهای دو طرف یکی باشد یا مغایرتها فهرست شوند |
| یک وبهوک بدون امضای درست به آدرس اتصال فرستاده شود | درخواست رد شود و هیچ دادهای تغییر نکند |
| صد سفارش آزمایشی پشت سر هم ثبت شود | همه بدون خطای محدودیت درخواست و بدون ثبت تکراری به مقصد برسند |
از پیمانکار چه بپرسید؟
| سؤال | جواب قابل اعتماد | جوابی که باید مکث کنید |
|---|---|---|
| قبل از برآورد، مستندات API طرف مقابل را دیدهاید؟ | بله، یا مرحله بررسی کوتاه جدا پیشنهاد میدهد | «همه APIها مثل هماند، مشکلی نیست» |
| اگر حسابداری قطع باشد، سفارش چه میشود؟ | صف و تلاش مجدد را توضیح میدهد | «قطع نمیشود» |
| جلوی ثبت تکراری را چطور میگیرید؟ | شناسه یکتا و رد درخواست تکراری | جواب روشنی ندارد |
| من از کجا بفهمم اتصال از کار افتاده؟ | داشبورد، هشدار و گزارش مغایرت | «خودتان اگر دیدید خبر بدهید» |
| سورس کد و کلیدها به نام چه کسی است؟ | به نام شما، با مستندات | روی سرور یا حساب پیمانکار |
| بعد از تحویل، تغییر API سرویسها را چه کسی پیگیری میکند؟ | قرارداد پشتیبانی روشن یا تحویل به تیم شما | موضوع اصلاً مطرح نمیشود |
درباره مالکیت سورس و تحویل کد، مالکیت سورس کد سایت را هم بخوانید.
هزینه یکپارچهسازی به چه چیزهایی بستگی دارد؟
- تعداد اتصالها و یکطرفه یا دوطرفه بودن آنها
- کیفیت مستندات و وجود محیط آزمایشی در سیستم طرف مقابل
- پیچیدگی جدول نگاشت و قانونهای همگامسازی
- حجم سفارشها و رویدادها
- نیاز به داشبورد پایش، هشدار و گزارش مغایرت
- یکی کردن دادههای قبلی پیش از روشن کردن اتصال
طبق بازههای منتشرشده در بازار ایران برای ۱۴۰۵، اتصال ساده به یک درگاه یا سامانه پیامک معمولاً حدود ۳۰ تا ۷۰ میلیون تومان است و یکپارچهسازی سازمانی با همگامسازی دوطرفه (مثلاً با ERP) حدود ۲۰۰ تا ۵۰۰ میلیون تومان. اینها بازهاند، نه قیمت قطعی؛ برآورد دقیق بدون دیدن مستندات و نمونه داده ممکن نیست. توضیح کامل و نفر-ساعت هر سطح در هزینه طراحی API در ۱۴۰۵ و تصویر کلیتر در هزینه ساخت نرمافزار اختصاصی آمده است.
ساختن API برای کسبوکار خودتان
یکپارچهسازی فقط وصل شدن به API دیگران نیست. گاهی کسبوکار شما باید API خودش را داشته باشد:
- اپ موبایل یا PWA: اپ از طریق API به همان داده و منطق سایت دسترسی میگیرد.
- نمایندگان و همکاران: قیمت و موجودی را مستقیم از سیستم شما میگیرند.
- مشتریان سازمانی: میخواهند سیستم خودشان را به سیستم شما وصل کنند.
- محصول SaaS: API مستند برای مشتریان B2B تقریباً یک انتظار عادی است.
یک API قابل اتکا مستندات بهروز (معمولاً با استاندارد OpenAPI)، احراز هویت با کلید یا توکن و دسترسی محدود، محدودیت تعداد درخواست، نسخهبندی، پیام خطای روشن، اعتبارسنجی ورودی و لاگ دارد. اگر دنبال برنامهنویس برای این کار هستید، برنامهنویس بکاند پروژهای نکات سنجش و قرارداد را توضیح میدهد.
بسته تحویل اتصال؛ بعد از پروژه چه چیزهایی باید دست شما باشد؟
اتصالها بیشتر از خود سایت به آدم وابستهاند: اگر فقط برنامهنویس اصلی بداند کلید کدام سرویس کجاست، رفتن او یعنی توقف کار. اینها را جزو تحویل در قرارداد بنویسید:
| مورد تحویل | شامل چه چیزی | چرا |
|---|---|---|
| فهرست اتصالها | هر اتصال، دو طرفش، جهت داده، زمانبندی و مسئول | تصویر کلی برای هر برنامهنویس بعدی |
| حسابها و کلیدها | حساب هر سرویس به نام خود شرکت، با فهرست کلیدها و محل نگهداریشان | اگر حساب به نام پیمانکار باشد، با رفتنش دسترسی هم میرود |
| مستندات API | مستندات OpenAPI یا مشابه، با نمونه درخواست و پاسخ | تغییر و توسعه بعدی بدون حدس و گمان |
| جدول نگاشت نهایی | نسخه تأییدشده جدول نگاشت فیلدها و کدها | اضافه کردن کالا یا انبار جدید بدون خراب شدن اتصال |
| راهنمای خطا | معنی هشدارهای رایج و کاری که برای هر کدام باید کرد | تیم داخلی خطاهای ساده را خودش رفع میکند |
| سورس و دسترسی سرور | مخزن کد، تنظیمات صف و زمانبندیها | امکان جابهجایی پیمانکار یا سرور |
برای بندهای قرارداد، مالکیت سورس کد سایت و برای هزینه نگهداری بعد از تحویل، پشتیبانی ماهانه سایت را بخوانید.
چکلیست شروع پروژه یکپارچهسازی
- فهرست همه نرمافزارها و سرویسها، با نسخه و ماژول
- فهرست کارهای دستی که امروز داده را جابهجا میکنند و زمان هر کدام
- مستندات API یا راه تماس با پشتیبانی فنی هر نرمافزار
- دسترسی به محیط آزمایشی یا حداقل حساب آزمایشی هر سرویس
- سیستم مرجع برای کالا، قیمت، موجودی، مشتری و سفارش
- جدول نگاشت فیلدها که حسابدار هم تأییدش کرده باشد
- متن قالبهای پیامک خدماتی برای ارسال به سامانه پیامک
- اولویتبندی اتصالها و تعریف فاز اول
- سناریوهای خطا و اینکه چه کسی به هشدارها رسیدگی میکند
- فهرست تستهای تحویل (جدول بالا)
- بند مالکیت سورس، کلیدها و مستندات در قرارداد
- تکلیف پشتیبانی بعد از تحویل و پیگیری تغییرات API سرویسها
- پاسخ پشتیبانی نرمافزار حسابداری درباره ماژول وبسرویس، هزینه و تمدیدش
- تعریف گزارش تطبیق روزانه و اینکه چه کسی آن را میخواند
- برنامه رفتار در زمان قطعی هر سرویس
اشتباهات رایج
- همه اتصالها با هم: با پرارزشترین جریان شروع کنید.
- تأیید پرداخت فقط با برگشت کاربر: پرداختهایی که کاربر صفحه را بسته گم میشوند یا بدتر، درخواست جعلی پذیرفته میشود.
- سیستم مرجع نامعلوم: دو سیستم که هر دو قیمت را عوض میکنند یعنی ناهماهنگی دائمی.
- برنامه نداشتن برای خطا: اتصالی که فقط در شرایط عالی کار کند، دیر یا زود داده را خراب میکند.
- یکی نکردن دادههای قبلی: روشن کردن اتصال روی دادههای ناهماهنگ، مغایرتها را چند برابر میکند.
- نبود پایش: اتصالی که بیصدا از کار افتاده ممکن است هفتهها دیده نشود.
- نبود مستندات: وقتی برنامهنویس اصلی در دسترس نباشد، کسی نمیداند اتصالها چطور کار میکنند.
مطالب مرتبط
- هزینه طراحی API در ۱۴۰۵
- اتصال سایت به نرمافزار حسابداری
- نرمافزار انبارداری اختصاصی یا آماده
- اتوماسیون پیامک فروش؛ از فرم سایت تا پیگیری
- سیستم استعلام قیمت و پیشفاکتور آنلاین B2B
- هزینه ساخت پنل مدیریت اختصاصی
یکپارچهسازی API با پونوکد
در پونوکد طراحی API و اتصال نرمافزارها از کارهای اصلی ماست: API با Django REST Framework، مستندات OpenAPI، اتصال به درگاه پرداخت، سامانه پیامک، حسابداری، ترب و سرویسهای دیگر، همراه با صف، پایش و گزارش مغایرت. چون سایت، پنل و API را در یک تیم میسازیم، اتصالها از اول جزو معماری سیستماند، نه وصلهای که بعداً اضافه شود. قبل از برآورد، مستندات سیستمهای شما را بررسی میکنیم و اگر اتصالی با یک افزونه آماده حل میشود، همان را پیشنهاد میدهیم.
جزئیات این خدمت در صفحه طراحی و توسعه API است. برای طراحی سایت، پنل مدیریت و داشبورد و بقیه کارها به خدمات پونوکد سر بزنید و بازه قیمتها را در صفحه قیمتها ببینید.
تماس برای بررسی اتصالهای شما
فهرست نرمافزارهایتان و کارهای دستی فعلی را بفرستید تا بگوییم کدام اتصال اول ارزش دارد و از چه راهی انجام میشود.
- تلفن و واتساپ: ۰۹۹۱۵۶۱۵۹۴۶
- تلگرام: t.me/resonea
- فرم تماس: تماس با پونوکد
راهنماهای تازه مرتبط؛ آبان ۱۴۰۵
- اتصال سایت به نقشه نشان؛ برای فرم آدرس و هزینه ارسال بر اساس فاصله، اتصال به سرویسهای نقشه نشان را ببینید.
- اتصال CRM به تلفن VoIP؛ اتصال CRM به مرکز تلفن تحت شبکه؛ ثبت خودکار تماس و تبدیل تماس بیپاسخ به کار پیگیری.
- اتصال کارتخوان به نرم افزار ۱۴۰۵؛ اتصال نرمافزار فروش به کارتخوان (پیسیپوز) و تطبیق تراکنشها با شماره مرجع.
- API قیمت طلا برای سایت؛ برای سایت طلا: گرفتن نرخ روز از سرویس قیمتدهی و محاسبه قیمت محصول روی سرور.
- استعلام قیمت ساخت نرم افزار ۱۴۰۵؛ قبل از سفارش اتصالها، سند نیازمندی و استعلام قیمت قابل مقایسه بگیرید.
نکتههای تازه ۱۴۰۵ درباره اتصالها
- حساب پرداخت سرویسهای گوگل کلود (از جمله نقشه گوگل) از ایران فعال نمیشود؛ برای نقشه، جستوجوی آدرس و مسیریابی، سرویسهای داخلی مثل نشان با کلید API جداگانه برای نمایش و برای سرویسها گزینه عملیترند. کلید سرویس نباید در کد صفحه دیده شود.
- اتصال به کارتخوان استاندارد واحدی ندارد: هر شرکت پرداخت پروتکل و روش فعالسازی خودش را دارد و اتصال به یکی به معنای اتصال به همه نیست.
- برای اتصال CRM به تلفن، مرکز تلفن باید رویداد تماس یا رابط برنامهنویسی بدهد؛ ایزابل/استریسک روی سرور خودتان یا سانترال ابری دارای API این امکان را دارند.
- در اتصال قیمت لحظهای (مثل نرخ طلا)، قیمت نهایی را روی سرور حساب کنید، منبع پشتیبان داشته باشید و زمان آخرین بهروزرسانی را کنار قیمت نشان دهید.
مشاوره پیش از تصمیم: اگر میخواهید همین موضوع را روی پروژه خودتان بسنجید، بازه هزینه را در صفحه قیمتها ببینید و برای یک گفتوگوی کوتاه با ۰۹۹۱۵۶۱۵۹۴۶ تماس بگیرید، در تلگرام پیام بدهید یا فرم تماس را پر کنید.
سؤالات متداول درباره یکپارچه سازی API
نرمافزار حسابداری ما API ندارد؛ اتصال ممکن است؟
در بیشتر موارد بله؛ از راه تبادل فایل زمانبندیشده، وبسرویس جانبی خود سازنده، یا در آخر اتصال فقطخواندنی با هماهنگی پشتیبانی. قبل از تصمیم، نسخه و امکانات نرمافزار شما بررسی میشود.
یکپارچهسازی چقدر زمان میبرد؟
اتصال ساده مثل پیامک خدماتی یا درگاه معمولاً چند روز تا دو هفته کار دارد، به شرط آماده بودن قالبها و دسترسیها. همگامسازی دوطرفه با حسابداری یا انبار معمولاً چند هفته طول میکشد و بیشترش صرف نگاشت، یکی کردن دادههای قبلی و تست میشود.
با افزونه آماده کارمان راه نمیافتد؟
اگر سایت وردپرسی است و افزونه رسمی همان سرویس کار شما را پوشش میدهد، اغلب همان کافی است. اتصال اختصاصی وقتی لازم میشود که منطق خاصی دارید، چند سیستم درگیرند یا افزونه بهروز و قابل اعتماد نیست.
اگر یکی از سرویسها قطع شود، داده از دست میرود؟
در طراحی درست نه. درخواست در صف میماند، بعد از برقراری ارتباط دوباره ارسال میشود و اگر چند بار ناموفق بود هشدار میدهد تا کسی بررسی کند.
اگر قیمت در سایت و حسابداری فرق کند کدام معتبر است؟
همان که از اول سیستم مرجع تعیین کردهاید. بهتر است قیمت فقط در یک جا ویرایش شود و طرف دیگر فقط بخواند.
برای اپ موبایل API جدا لازم است؟
اگر سایت از اول روی API ساخته شده باشد، اپ از همان استفاده میکند. در غیر این صورت باید یک لایه API برای اپ طراحی شود.
مستندات و سورس اتصالها تحویل داده میشود؟
باید بشود و این را در قرارداد بنویسید. در پروژههای ما مستندات OpenAPI، توضیح هر اتصال و سورس کد جزو تحویل است.
ماژول وبسرویس حسابداری را باید جدا بخریم؟
در خیلی از نرمافزارهای حسابداری داخلی بله؛ وبسرویس بهصورت ماژول جدا یا در نسخههای بالاتر عرضه میشود و هزینهاش جدا از دستمزد برنامهنویسی است. قبل از برآورد، از فروشنده بپرسید نسخه شما چه دارد و تمدید سالانه هست یا نه.
از کجا بفهمیم اتصال بیصدا از کار افتاده؟
با گزارش تطبیق روزانه و هشدار خودکار. اگر هر صبح تعداد سفارشهای سایت با حسابداری و تراکنشهای درگاه مقایسه شود، اختلاف همان روز دیده میشود، نه آخر ماه موقع بستن حسابها.
برای نقشه و آدرس در سایت ایرانی، API گوگل مپ مناسب است یا نشان؟
سرویسهای اصلی گوگل مپ حساب پرداخت گوگل کلود میخواهند که از ایران فعال نمیشود. برای همین بیشتر سایتهای ایرانی برای انتخاب آدرس، تبدیل آدرس به مختصات و محاسبه فاصله از سرویسهای داخلی مثل نشان استفاده میکنند. سقف درخواست و تعرفه را از پنل توسعهدهندگان همان سرویس بگیرید.
اتصال نرمافزار به کارتخوان هم نوعی یکپارچهسازی API است؟
بله، ولی با سرویسهای وب فرق دارد: ارتباط معمولاً از طریق شبکه محلی یا کابل با دستگاه و با پروتکل شرکت پرداخت انجام میشود. اول از شرکت ارائهدهنده کارتخوان بپرسید پیسیپوز را برای دستگاه شما فعال میکند یا نه.
اگر به وبلاگهای حوزه تکنولوژی روز دنیا علاقهمندید، میتوانید به وبسایت شخصی من هم سر بزنید: ramineslami.ir/blogs



