معرفی کامل پلاگین
راهنمای دقیق اتصال نرمافزار حسابداری هلو به ووکامرس
برای اتصال فروشگاه ووکامرسی به نرمافزار حسابداری هلو، باید ابتدا روش ارتباطی مورد استفاده در نسخه نصبشده هلو مشخص شود.
افزونه ووکامرس نمیتواند بهصورت مستقیم و بدون داشتن یک مسیر ارتباطی معتبر، اطلاعات کالا، موجودی، قیمت یا سفارشات را از نرمافزار هلو دریافت یا به آن ارسال کند. بنابراین قبل از تنظیم افزونه، باید اطلاعات ارتباطی موردنیاز را از پشتیبانی نرمافزار هلو، شرکت ارائهدهنده وبسرویس، مسئول نصب یا مدیر شبکه و سیستم حسابداری دریافت کنید.
نکته مهم: اطلاعات موردنیاز دقیق برای اتصال، به نسخه هلو و نوع سرویس ارتباطی نصبشده بستگی دارد. ممکن است در یک سیستم از Web Service استفاده شود و در سیستم دیگر از API، سرویس واسط یا روش اختصاصی دیگری استفاده شده باشد.
قبل از شروع اتصال، چه اطلاعاتی باید آماده باشد؟
برای اتصال صحیح ووکامرس به هلو، ابتدا باید مشخص شود که سیستم هلو شما از چه روشی برای ارتباط با نرمافزارهای دیگر پشتیبانی میکند.
اطلاعات زیر را از مسئول سیستم یا پشتیبانی مربوطه دریافت کنید.
۱. آدرس دقیق سرویس ارتباطی
مهمترین اطلاعات، آدرس کامل سرویس ارتباطی هلو است.
این آدرس ممکن است شامل موارد زیر باشد:
- نام دامنه
- IP سرور
- شماره پورت
- مسیر Web Service یا API
- نسخه یا مسیر اختصاصی سرویس
نمونه ساختار آدرس:
https://example.com/api/...
یا:
http://SERVER-IP:PORT/...
آدرس واردشده در افزونه باید دقیقاً همان آدرسی باشد که سرویس هلو برای ارتباط خارجی ارائه کرده است.
۲. نوع روش اتصال و احراز هویت
باید مشخص شود سرویس هلو برای اتصال از چه روشی استفاده میکند.
برای مثال ممکن است سرویس از یکی از روشهای زیر استفاده کند:
- نام کاربری و رمز عبور
- API Key
- Token
- Bearer Token
- اطلاعات اختصاصی Web Service
- شناسه شرکت یا شناسه پایگاه داده
بنابراین نباید تمام فیلدهای اتصال را برای همه نسخههای هلو اجباری در نظر گرفت.
اطلاعاتی که باید دریافت کنید:
- نوع احراز هویت
- نام کاربری در صورت نیاز
- رمز عبور در صورت نیاز
- API Key یا Token در صورت استفاده
- نحوه دریافت یا تمدید Token
- اطلاعات اضافی موردنیاز سرویس
۳. نام شرکت، شناسه شرکت یا پایگاه داده
برخی سرویسهای ارتباطی ممکن است برای تشخیص شرکت یا مجموعه موردنظر به اطلاعاتی مانند موارد زیر نیاز داشته باشند:
- نام پایگاه داده
- نام شرکت
- شناسه شرکت
- شناسه شعبه
- شناسه فروشگاه
این اطلاعات فقط در صورتی باید در افزونه وارد شوند که سرویس ارتباطی هلو واقعاً به آنها نیاز داشته باشد.
بنابراین از پشتیبانی هلو سؤال کنید:
برای اتصال به اطلاعات شرکت موردنظر، چه شناسه یا اطلاعاتی باید همراه درخواست API ارسال شود؟
۴. دسترسی سرور ووکامرس به سرویس هلو
اگر وبسایت شما روی یک هاست یا سرور اینترنتی قرار دارد و نرمافزار هلو روی یک کامپیوتر یا سرور داخل شرکت نصب شده است، باید مسیر ارتباطی بین این دو سیستم برقرار باشد.
برای مثال آدرس زیر:
192.168.1.100
یک IP داخلی است و معمولاً فقط از داخل همان شبکه قابل دسترسی خواهد بود. سرور سایت نمیتواند مستقیماً به چنین آدرسی متصل شود، مگر اینکه زیرساخت ارتباطی مناسب ایجاد شده باشد.
برای اتصال سایت به سیستم هلو باید توسط مسئول شبکه یکی از روشهای امن و مناسب پیادهسازی شود، مانند:
- Web Service قابل دسترس از سرور سایت
- سرور یا API واسط
- VPN بین سرور سایت و شبکه محل نصب هلو
- Tunnel یا ارتباط امن شبکه
- محدودسازی دسترسی از طریق Firewall و IP مجاز
نکته امنیتی مهم: دیتابیس یا SQL Server نرمافزار حسابداری نباید بدون لایه امنیتی مناسب مستقیماً روی اینترنت باز شود. ارتباط افزونه بهتر است از طریق API یا Web Service کنترلشده انجام شود.
۵. اطلاعات موردنیاز برای دریافت گروهها و دستهبندیها
برای دریافت گروهها و ساخت یا اتصال دستهبندیهای ووکامرس، باید مشخص شود سرویس هلو چگونه اطلاعات گروهبندی کالاها را ارائه میکند.
اطلاعات موردنیاز:
- آدرس یا Endpoint دریافت گروهها
- آدرس یا Endpoint دریافت زیرگروهها، در صورت وجود
- روش ارسال درخواست
- روش احراز هویت
- ساختار پاسخ
حداقل اطلاعاتی که بهتر است از هر گروه دریافت شود:
- شناسه گروه
- کد گروه
- نام گروه
- شناسه یا کد گروه والد، در صورت وجود
نمونه ساختار منطقی:
[
{
"id": "10",
"code": "1001",
"name": "لوازم خانگی",
"parent_id": null
}
]
ساختار واقعی JSON ممکن است کاملاً متفاوت باشد و افزونه باید بر اساس پاسخ واقعی سرویس هلو آن را پردازش کند.
پس از دریافت گروهها، افزونه باید بتواند:
- گروههای هلو را نمایش دهد.
- برای هر گروه دستهبندی ووکامرس ایجاد کند.
- گروه هلو را به یک دستهبندی موجود متصل کند.
- شناسه ارتباط بین گروه هلو و دستهبندی ووکامرس را ذخیره کند.
- از ایجاد دستهبندی تکراری جلوگیری کند.
۶. اطلاعات موردنیاز برای دریافت کالاهای هلو
برای فراخوانی کالاها باید اطلاعات Endpoint یا متد مربوط به دریافت محصولات از هلو در اختیار افزونه قرار گیرد.
از پشتیبانی سرویس درخواست کنید موارد زیر را مشخص کند:
- آدرس دریافت لیست کالاها
- روش درخواست، مانند GET یا POST
- پارامترهای موردنیاز
- روش احراز هویت
- ساختار JSON پاسخ
- محدودیت تعداد کالا در هر درخواست
- روش صفحهبندی، در صورت وجود
- روش دریافت اطلاعات یک کالای خاص
- شناسه یکتای هر کالا
اطلاعات هر کالا، در صورت پشتیبانی سرویس، میتواند شامل موارد زیر باشد:
| اطلاعات هلو | محل ذخیره یا استفاده در ووکامرس |
|---|---|
| کد یا شناسه کالا | متای اختصاصی اتصال به هلو |
| SKU | SKU محصول ووکامرس |
| عنوان کالا | نام محصول |
| موجودی | Stock Quantity |
| قیمت اصلی | Regular Price |
| قیمت ویژه | Sale Price |
| تصویر | تصویر شاخص یا گالری |
| توضیحات | توضیحات محصول |
| رنگ | ویژگی محصول |
| سایز | ویژگی محصول |
| ابعاد | ویژگی محصول |
| اندازه | ویژگی محصول |
| جنس | ویژگی محصول |
فقط اطلاعاتی که واقعاً توسط سرویس هلو ارائه میشوند باید همگامسازی شوند. اگر برای مثال API هلو تصویر یا ویژگیهایی مانند رنگ و سایز را ارائه ندهد، افزونه نباید انتظار دریافت خودکار آنها را داشته باشد.
۷. شناسه اتصال کالا بین هلو و ووکامرس
یکی از مهمترین بخشهای اتصال، تعیین یک شناسه یکتا و پایدار برای ارتباط هر محصول ووکامرس با کالای متناظر در هلو است.
این شناسه میتواند یکی از موارد زیر باشد:
- کد کالا
- شناسه داخلی کالا
- SKU
- شناسه اختصاصی ارائهشده توسط API
در افزونه بهتر است یک مقدار اختصاصی مانند ErpCode یا Holoo Product ID برای هر محصول ذخیره شود.
ساختار پیشنهادی:
- شناسه محصول ووکامرس
- کد یکتای کالا در هلو
- SKU
- زمان آخرین همگامسازی
این کار باعث میشود افزونه هنگام بروزرسانی، دقیقاً همان محصول را پیدا کند و از ایجاد محصول تکراری جلوگیری شود.
توصیه مهم: اگر کد کالا یا SKU در هلو قابل تغییر است، بهتر است برای ارتباط اصلی از یک شناسه داخلی و ثابت استفاده شود.
۸. اطلاعات موردنیاز برای همگامسازی قیمت
برای بروزرسانی قیمت باید مشخص شود که API هلو چه فیلدهایی را ارائه میدهد.
برای مثال:
- قیمت فروش
- قیمت مصرفکننده
- قیمت همکار
- قیمت ویژه
- قیمت با تخفیف
قبل از اتصال باید مشخص شود:
- کدام قیمت هلو باید به «قیمت عادی» ووکامرس منتقل شود؟
- کدام قیمت باید به «قیمت فروش ویژه» منتقل شود؟
- واحد پول یا واحد مبلغ چیست؟
- آیا قیمت شامل مالیات است؟
- آیا قیمت صفر باید در ووکامرس ثبت شود یا نادیده گرفته شود؟
این Mapping باید در تنظیمات افزونه قابل کنترل باشد.
۹. اطلاعات موردنیاز برای همگامسازی موجودی
برای همگامسازی موجودی باید مشخص شود:
- موجودی از کدام فیلد دریافت میشود؟
- موجودی مربوط به کدام انبار است؟
- آیا چند انبار وجود دارد؟
- آیا موجودی چند انبار باید با یکدیگر جمع شود؟
- آیا فقط یک انبار مشخص مبنای فروش اینترنتی است؟
- آیا موجودی منفی مجاز است؟
پیشنهاد میشود در افزونه امکان انتخاب منبع موجودی فراهم شود.
برای مثال:
انبار انتخابی: انبار فروش اینترنتی
در این حالت فقط موجودی همان انبار در ووکامرس نمایش داده و همگامسازی میشود.
۱۰. اطلاعات موردنیاز برای ارسال سفارش ووکامرس به هلو
برای ارسال سفارش به هلو باید مشخص شود سرویس هلو چگونه یک فروش یا فاکتور جدید را ثبت میکند.
از پشتیبانی سرویس اطلاعات زیر را دریافت کنید:
- Endpoint ثبت فروش یا فاکتور
- روش ارسال درخواست
- ساختار JSON یا XML درخواست
- فیلدهای اجباری
- فیلدهای اختیاری
- نحوه ارسال اطلاعات مشتری
- نحوه ارسال کالاهای سفارش
- شناسه کالای موردنیاز
- تعداد
- قیمت واحد
- تخفیف
- مالیات
- هزینه ارسال
- توضیحات سفارش
- شماره سفارش
- نحوه دریافت شماره یا شناسه فاکتور ثبتشده در هلو
یک ساختار منطقی ممکن است به شکل زیر باشد:
{
"order_id": 1258,
"customer": {
"name": "نام مشتری",
"mobile": "شماره موبایل"
},
"items": [
{
"product_code": "12345",
"quantity": 2,
"price": 1500000
}
],
"shipping": 100000,
"discount": 50000
}
این فقط یک نمونه مفهومی است. ساختار واقعی درخواست باید دقیقاً مطابق مستندات API یا Web Service نصبشده برای هلو باشد.
۱۱. وضعیت سفارش و جلوگیری از ارسال تکراری
افزونه باید برای هر سفارش ووکامرس، وضعیت ارتباط با هلو را ذخیره کند.
برای مثال:
- ارسال نشده
- در حال ارسال
- ارسال موفق
- ارسال ناموفق
- نیازمند بررسی
پس از ارسال موفق، اطلاعات زیر باید ذخیره شود:
- شناسه سفارش ووکامرس
- زمان ارسال
- پاسخ سرویس
- شناسه یا شماره فاکتور هلو، در صورت دریافت
- وضعیت نهایی عملیات
به این ترتیب اگر مدیر سایت چند بار روی «ارسال دستی» کلیک کند، افزونه میتواند تشخیص دهد که سفارش قبلاً با موفقیت ارسال شده است.
۱۲. ارسال دستی سفارشات ارسالنشده
در بخش سفارشات افزونه باید امکان مدیریت سفارشهایی که به هلو ارسال نشدهاند وجود داشته باشد.
مدیر سایت باید بتواند:
- سفارشات ارسالشده را مشاهده کند.
- سفارشات ارسالنشده را مشاهده کند.
- سفارشات ناموفق را بررسی کند.
- براساس شماره سفارش جستجو کند.
- براساس وضعیت فیلتر کند.
- یک سفارش مشخص را بهصورت دستی دوباره ارسال کند.
ارسال دستی باید بدون رفرش کامل صفحه و با AJAX انجام شود.
پس از پایان عملیات، نتیجه باید شامل یکی از وضعیتهای زیر باشد:
- ارسال موفق
- ارسال ناموفق
- سفارش قبلاً ارسال شده است
- خطای ارتباط با هلو
- اطلاعات کالا ناقص است
- پاسخ نامعتبر از سرویس دریافت شد
۱۳. منطق کاهش موجودی پس از ثبت سفارش
منطق موجودی باید بهگونهای طراحی شود که یک عملیات فروش فقط یکبار در سیستم حسابداری ثبت شود.
برای مثال:
موجودی کالا در هلو:
۱۰ عدد
مشتری در ووکامرس:
۲ عدد
سفارش به وضعیت موردنظر، برای مثال «در حال انجام»، میرسد.
در صورتی که سفارش با موفقیت در هلو ثبت شود، موجودی طبق منطق سیستم حسابداری کاهش پیدا میکند.
افزونه باید ثبت کند:
- این سفارش به هلو ارسال شده است.
- عملیات کاهش موجودی برای آن ثبت شده است.
- شناسه فاکتور یا عملیات هلو چیست.
این اطلاعات برای جلوگیری از ثبت مجدد عملیات ضروری است.
۱۴. بازگشت موجودی در صورت لغو یا استرداد سفارش
اگر سفارشی که قبلاً در هلو ثبت شده است به وضعیت:
- لغو شده
- مسترد شده
تغییر کند، افزونه نباید صرفاً موجودی را بدون بررسی افزایش دهد.
ابتدا باید بررسی شود:
- آیا سفارش قبلاً با موفقیت به هلو ارسال شده است؟
- آیا عملیات بازگشت برای این سفارش قبلاً انجام شده است؟
- آیا API هلو از لغو، برگشت یا اصلاح فاکتور پشتیبانی میکند؟
اگر پاسخ مثبت باشد، عملیات مناسب باید از طریق API هلو انجام شود.
برای جلوگیری از خطای تکراری، باید یک وضعیت مستقل ذخیره شود:
- موجودی بازگشت داده نشده
- در حال بازگشت
- موجودی بازگشت داده شده
- خطا در بازگشت
بسیار مهم: بازگرداندن موجودی نباید با تغییرات مکرر وضعیت سفارش چند بار انجام شود.
۱۵. اطلاعاتی که باید از پشتیبانی هلو دریافت کنید
برای اتصال دقیق، این چکلیست را در اختیار پشتیبانی یا مسئول نصب سرویس هلو قرار دهید.
اطلاعات اصلی اتصال
- آدرس کامل Web Service یا API
- شماره Port، در صورت وجود
- نوع احراز هویت
- نام کاربری و رمز عبور، در صورت نیاز
- API Key یا Token، در صورت نیاز
- نام شرکت یا شناسه شرکت، در صورت نیاز
- نام دیتابیس، فقط در صورتی که سرویس به آن نیاز دارد
مستندات فنی
- مستندات API
- فایل PDF راهنما
- لینک مستندات آنلاین
- Swagger یا OpenAPI، در صورت وجود
- نمونه درخواست
- نمونه پاسخ موفق
- نمونه پاسخ خطا
عملیات موردنیاز
- دریافت گروههای کالا
- دریافت زیرگروهها
- دریافت لیست کالاها
- دریافت اطلاعات یک کالا
- دریافت موجودی
- دریافت قیمت
- ثبت یا شناسایی مشتری
- ثبت فروش یا فاکتور
- دریافت شماره فاکتور
- لغو، اصلاح یا برگشت فاکتور، در صورت پشتیبانی
- بررسی وضعیت فاکتور، در صورت پشتیبانی
۱۶. قبل از کلیک روی «تست اتصال»
قبل از تست اتصال، موارد زیر را بررسی کنید:
☐ آدرس سرویس صحیح است.
☐ سرویس هلو فعال و در حال اجرا است.
☐ سرور وردپرس به آدرس سرویس دسترسی دارد.
☐ Port موردنیاز مسدود نیست.
☐ اطلاعات احراز هویت صحیح است.
☐ SSL و گواهی HTTPS در صورت استفاده بهدرستی تنظیم شده است.
☐ شرکت یا پایگاه داده صحیح انتخاب شده است، در صورتی که سرویس به آن نیاز دارد.
☐ Endpoint موردنظر فعال است.
نکته نهایی و بسیار مهم
برای ایجاد یک اتصال واقعی، پایدار و بدون خطا بین ووکامرس و هلو، نباید Endpointها، نام فیلدها یا ساختار JSON را حدس زد.
افزونه باید بر اساس مستندات واقعی سرویس ارتباطی نصبشده روی سیستم هلو توسعه داده شود.
بنابراین بهترین اطلاعاتی که کاربر باید از پشتیبانی هلو دریافت کند، این سه مورد است:
۱. آدرس و روش دقیق اتصال به Web Service یا API
۲. مستندات Endpointهای دریافت کالا، قیمت، موجودی و گروهها
۳. ساختار دقیق ثبت فاکتور یا سفارش در هلو به همراه نمونه درخواست و پاسخ واقعی
پس از دریافت این اطلاعات، اتصال ووکامرس و هلو میتواند با Mapping دقیق فیلدها پیادهسازی شود و امکاناتی مانند دریافت کالا، ساخت دستهبندی، همگامسازی قیمت و موجودی، ارسال خودکار سفارش، ارسال دستی سفارش و مدیریت بازگشت موجودی با منطق واقعی همان سیستم انجام شود.