اتصال سفارش‌های ووکامرس به نرم‌افزار حسابداری؛ مسیر داده و خطاها
اتصال موفق فقط «ارسال سفارش» نیست. پیش از توسعه باید معلوم باشد کدام وضعیت سفارش مجوز صدور سند است، هر فیلد به چه چیزی نگاشت می‌شود، لغو و مرجوعی چگونه ثبت می‌شوند و در صورت قطع سرویس چه کسی خطا را می‌بیند و اصلاح می‌کند. این تصمیم‌ها از ثبت دوباره و مغایرت‌های پنهان جلوگیری می‌کنند.
برای مراحل دریافت کالا و تصمیم مالی، راهنمای مرجوعی و بازپرداخت جزئی را ببینید.
برای تشخیص اختلاف پرداخت و سفارش پیش از ثبت سند، راهنمای تأیید پرداخت ووکامرس را ببینید.
اول مشخص کنید چه رویدادی سند می‌سازد
«ثبت سفارش» می‌تواند قبل از پرداخت، پس از پرداخت یا حتی برای سفارش ناموفق رخ دهد. بنابراین یک عبارت کلی مثل «هر سفارش را به حسابداری بفرست» کافی نیست. باید تعیین کنید آیا سند هنگام وضعیت پردازش ساخته می‌شود، هنگام تکمیل، یا پس از تأیید دستی. سفارش در انتظار، ناموفق و پرداخت در محل نیز قاعدهٔ جدا می‌خواهند. وضعیت‌های ووکامرس را با وضعیت‌های نرم‌افزار مقصد در یک جدول تصمیم نگاشت کنید.
مسیر داده را فیلد به فیلد بنویسید
شناسهٔ سفارش، تاریخ، ارز، مبلغ کالا، تخفیف، مالیات، حمل، روش پرداخت و اقلام سفارش معمولاً بخشی از انتقال‌اند؛ اما نام و ساختار آن‌ها در هر نرم‌افزار یکسان نیست. برای هر فیلد، منبع، تبدیل لازم، اجباری یا اختیاری بودن و رفتار در صورت نبود مقدار را ثبت کنید. اگر کد کالا در دو سامانه متفاوت است، پیش از همگام‌سازی جدول نگاشت و صاحب مسئول اصلاح آن را مشخص کنید.
اطلاعات مشتری هم باید به حداقل لازم محدود شود. روشن کنید مشتری با چه کلیدی پیدا یا ساخته می‌شود و اگر شماره تلفن، شناسه اقتصادی یا نشانی ناقص بود، سفارش متوقف می‌شود یا در صف بررسی می‌ماند.
مبلغ را از همان سفارش بگیرید، نه قیمت امروز کالا
برای سند فروش، مبالغ ثبت‌شدهٔ سفارش مبنا باشند؛ محاسبهٔ دوباره با قیمت فعلی محصول می‌تواند تخفیف یا مالیات زمان خرید را تغییر دهد. در Orders API، جمع کل، تخفیف، مالیات، حمل و اقلام جدا هستند. واحد مبلغ، تبدیل احتمالی ریال و تومان و روش گردکردن را با مقصد مشخص کنید؛ عنوان واحد در صفحهٔ فروشگاه به‌تنهایی معیار انتقال نیست. جمع اجزای نگاشت‌شده باید با جمع مورد انتظار سند تطبیق داشته باشد. برای شناسهٔ محصول و تنوع نیز راهنمای نگاشت کالا و SKU را ببینید.
ثبت سند باید تکرار امن داشته باشد
یک سفارش ممکن است با اعلان‌های مختلف یا اجرای مجدد دوباره پردازش شود. کلید صدور فروش، مثلاً ترکیب شناسهٔ فروشگاه، شناسهٔ سفارش و نوع عملیات، باید در همهٔ تلاش‌ها ثابت بماند؛ شناسهٔ هر تلاش جای آن را نمی‌گیرد. شناسهٔ سند مقصد را هم ذخیره کنید. برای دو اجرای هم‌زمان، بررسی سادهٔ «قبلاً ثبت شده؟» کافی نیست؛ قفل یا محدودیت یکتا و پشتیبانی مقصد از جلوگیری از ایجاد تکراری باید با هم بررسی شوند.
اگر حسابداری سند را ساخت اما پاسخ نرسید چه؟
قطع ارتباط پس از ارسال، نتیجه را نامشخص می‌کند: شاید سند ثبت شده باشد. در این حالت ایجاد دوبارهٔ بدون بررسی مناسب نیست. اگر مقصد کلید تکرار امن می‌پذیرد، همان کلید را نگه دارید؛ اگر امکان جست‌وجوی سند با شناسهٔ مرجع دارد، ابتدا نتیجهٔ قبلی را پیدا و تطبیق دهید. وقتی هیچ‌کدام وجود ندارد، مورد باید برای بررسی مسئول متوقف شود و این محدودیت در برآورد ثبت شود. برای انتخاب روش دریافت تغییرها، وبهوک یا API دوره‌ای را بخوانید.
لغو، مرجوعی و ویرایش را از سفارش اولیه جدا کنید
لغو سفارش الزاماً به معنی حذف سند نیست. بسته به قواعد مالی، ممکن است ابطال یا سند برگشت لازم باشد. همین موضوع برای بازپرداخت کامل و جزئی، کم‌شدن یک قلم و تغییر هزینهٔ ارسال صدق می‌کند. برای هر رویداد مشخص کنید چه رکوردی در مقصد ساخته یا اصلاح می‌شود، چه کسی آن را تأیید می‌کند و ارتباطش با سند اولیه چگونه حفظ می‌شود.
بازپرداخت جزئی را فقط از وضعیت سفارش تشخیص ندهید
طبق راهنمای بازپرداخت ووکامرس، بازپرداخت جزئی الزاماً وضعیت سفارش را به «بازپرداخت‌شده» تغییر نمی‌دهد؛ تغییر مستقیم وضعیت به «لغوشده» یا «بازپرداخت‌شده» نیز به‌تنهایی پول مشتری را برنمی‌گرداند. بازپرداخت دستی، ثبت در فروشگاه است و بازگرداندن وجه باید جدا انجام شود. اتصال حسابداری باید رکورد بازپرداخت، مبلغ و اقلام آن را کنترل کند، نه فقط آخرین وضعیت سفارش.
Order Refunds API برای هر بازپرداخت شناسهٔ مستقل دارد. کلید عملیات برگشت را با شناسهٔ فروشگاه، سفارش و بازپرداخت تعریف کنید تا دو برگشت متفاوت به اشتباه یکی نشوند. ارتباط سند برگشت با فروش اولیه، اثر بر مالیات و حمل، و تأیید مسئول مالی را جدا مشخص کنید. ثبت سند مالی، برگشت وجه و بازگشت فیزیکی کالا سه نتیجهٔ جدا هستند؛ موفقیت یکی دلیل انجام دو مورد دیگر نیست.
| رویداد | تصمیم لازم | کنترل نتیجه |
|---|---|---|
| سفارش واجد صدور | زمان ایجاد فروش و فیلدهای لازم | شناسهٔ سند مقصد و تطبیق مبلغ |
| لغو پس از صدور | مسیر ابطال یا اصلاح مورد تأیید مسئول مالی | ارتباط با سند اولیه و نتیجهٔ ثبت‌شده |
| بازپرداخت جزئی | مبلغ، اقلام و اثر بر مالیات و حمل | شناسهٔ مستقل برگشت و عدم تکرار |
| پاسخ نامشخص مقصد | استعلام نتیجه یا توقف برای بررسی | پیداکردن سند قبلی پیش از ایجاد دوباره |
خطا باید قابل مشاهده و قابل اصلاح باشد
- در هر تلاش، زمان، شناسهٔ سفارش، نوع عملیات، پاسخ مقصد و نتیجهٔ قابل فهم ثبت شود؛ کلید و دادهٔ حساس وارد گزارش نشود.
- خطای موقت با فاصله و تعداد محدود پیگیری شود؛ در timeout پس از ارسال ابتدا نتیجهٔ نامشخص تعیین تکلیف شود. خطای اعتبارسنجی تا اصلاح داده تکرار نشود.
- برای تلاش‌های ناموفق صف جدا، اعلان مسئول و امکان اجرای مجدد کنترل‌شده وجود داشته باشد.
- پس از چند شکست متوالی، توقف یا هشدار روشن تعریف شود؛ موفقیت سفارش‌های بعدی نباید خطای قبلی را پنهان کند.
تطبیق دوره‌ای، خطاهای ساکت را پیدا می‌کند
حتی اگر API پاسخ موفق بدهد، کنترل دوره‌ای لازم است. برای یک بازهٔ مشخص، تعداد و مبلغ سفارش‌های واجد انتقال را با اسناد مقصد مقایسه کنید؛ سفارش بدون سند، سند تکراری، مبلغ متفاوت و برگشت ثبت‌نشده باید در گزارش استثنا دیده شوند. این کنترل جای گزارش فنی را نمی‌گیرد، اما مغایرتی را پیدا می‌کند که ممکن است در اجرای روزانه دیده نشود.
مثال فرضی یک جریان قابل آزمون
فرض کنید فروشگاه پس از پرداخت، سفارش را در وضعیت «در حال انجام» قرار می‌دهد. اتصال، سفارش را با کلید یکتا در صف می‌گذارد، اقلام را با کد مقصد نگاشت می‌کند و سند فروش می‌سازد. شناسهٔ سند کنار سفارش ذخیره می‌شود. اگر مقصد موقتاً پاسخ ندهد، تلاش بعدی همان عملیات را ادامه می‌دهد و سند دوم نمی‌سازد. بازپرداخت جزئی نیز به‌عنوان عملیات وابسته به سند اولیه ثبت و در گزارش تطبیق کنترل می‌شود. این سناریو نمونهٔ طراحی است، نه گزارش یک اتصال آماده یا پروژهٔ واقعی.
چهار آزمون پذیرش قبل از انتقال سفارش واقعی
این آزمون‌ها را در محیط آزمایشی با سفارش و سند ساختگی اجرا کنید. نتیجهٔ مورد انتظار را پیش از توسعه در شرح نیاز پروژه ثبت کنید و شواهد آن را هنگام تحویل افزونه بگیرید.
- تکرار و هم‌زمانی: همان عملیات صدور را دوباره و هم‌زمان اجرا کنید؛ باید یک فروش معتبر با یک شناسهٔ مقصد باقی بماند.
- قطع پاسخ پس از ثبت: پاسخ مقصد را پس از ساخت سند قطع کنید؛ اتصال باید سند قبلی را پیدا کند یا برای بررسی متوقف شود، بدون ساخت خودکار سند دوم.
- دو بازپرداخت جزئی: برای یک سفارش دو رکورد برگشت متفاوت بسازید و هرکدام را دوباره پردازش کنید؛ هر برگشت باید یک بار ثبت و جدا قابل پیگیری باشد.
- اختلاف مبلغ: نمونه‌ای با تخفیف، حمل و مالیات و یک مغایرت عمدی آماده کنید؛ گزارش تطبیق باید اختلاف را نشان دهد و مسئول اصلاح مشخص باشد.
چک‌لیست قبل از برآورد توسعه
- نرم‌افزار حسابداری در نسخهٔ مورد استفاده API مستند، محیط آزمایشی و روش استعلام سند با شناسهٔ مرجع دارد؟
- کدام وضعیت سفارش آغاز انتقال است و وضعیت‌های استثنا کدام‌اند؟
- مرجع مشتری، کالا، قیمت، مالیات و تخفیف کدام سامانه است؟
- لغو، ویرایش و بازپرداخت کامل یا جزئی چه اثر مالی دارند؟
- شناسهٔ یکتا و روش جلوگیری از ثبت دوباره چیست؟
- چه کسی خطاها و گزارش تطبیق را بررسی و اصلاح می‌کند؟
منابع فنی
مستندات رسمی در ۲۰۲۶/۱۰/۰۴ بازبینی شدند؛ قابلیت‌های API را با نسخهٔ نصب‌شدهٔ فروشگاه و نرم‌افزار مقصد تطبیق دهید.
- مستندات رسمی Orders API ووکامرس
- راهنمای رسمی وبهوک‌های ووکامرس
- مستندات رسمی بازپرداخت سفارش
- راهنمای بازپرداخت کامل، جزئی و دستی
اگر موضوع شما علاوه بر سند مالی، موجودی کالا را هم درگیر می‌کند، راهنمای اتصال ووکامرس به انبار را بخوانید. برای تعریف دقیق خروجی و معیار پذیرش نیز چک‌لیست شرح نیاز افزونه مفید است. مسیر ساخت افزونه اختصاصی وردپرس و ووکامرس توضیح می‌دهد بررسی و تحویل پروژه چگونه انجام می‌شود.