شناسه کالا و SKU در اتصال ووکامرس به انبار؛ چگونه نگاشت را درست تعریف کنیم؟
اگر سفارش به انبار برسد اما سایز یا رنگ اشتباه از موجودی کم شود، موفق‌بودن درخواست API کمکی نمی‌کند. پیش از اتصال ووکامرس به انبار یا حسابداری، باید مشخص کنید هر قلم قابل فروش دقیقاً به کدام رکورد مقصد مربوط است. SKU می‌تواند کلید این تطبیق باشد، به شرطی که کامل، یکتا و تحت قاعدهٔ تغییر مشخص باشد؛ در غیر این صورت به جدول نگاشت مستقل نیاز دارید.
تفاوت ID محصول، SKU و کد کالای انبار چیست؟
شناسهٔ داخلی محصول در ووکامرس، SKU و کد کالا در سامانهٔ انبار سه مقدار با نقش‌های متفاوت‌اند. یکسان‌بودن آن‌ها را بدون بررسی داده فرض نکنید. عنوان محصول هم برای تطبیق مناسب نیست: نام‌ها ممکن است تکراری باشند یا ویرایش شوند. جدول زیر یک الگوی پیشنهادی برای طراحی اتصال است.
| مقدار | کاربرد در نگاشت | پرسش قبل از اتصال |
|---|---|---|
| ID داخلی ووکامرس | ارجاع به رکورد محصول در همان سایت | در بازسازی یا انتقال کاتالوگ، شناسه‌ها حفظ می‌شوند؟ |
| ID تنوع | تشخیص گزینهٔ خریداری‌شده، مانند سایز و رنگ | هر تنوع در مقصد رکورد مستقل دارد؟ |
| SKU | کلید تجاریِ پیشنهادی برای تطبیق | همهٔ اقلام قابل فروش کد مستقل دارند و تغییر آن کنترل می‌شود؟ |
| کد کالای مقصد | ارجاع به کالا در انبار یا حسابداری | کد مقصد متن است یا عدد و چه کسی آن را تغییر می‌دهد؟ |
بارکد و SKU را هم بدون بررسی قرارداد داده جای یکدیگر نگذارید. ممکن است در کسب‌وکار شما برابر باشند، اما این برابری باید در نمونهٔ داده و مستندات سامانهٔ مقصد تأیید شود. اگر چند سایت به یک انبار وصل‌اند، شناسهٔ سایت نیز باید در کلید نگاشت لحاظ شود.
در محصول متغیر، تطبیق باید تا سطح تنوع پیش برود
در ووکامرس هر تنوع می‌تواند SKU و موجودی خودش را داشته باشد. مستندات محصولات متغیر همچنین توضیح می‌دهد که SKU خالیِ تنوع می‌تواند از SKU محصول والد استفاده کند. بنابراین مشاهدهٔ یک SKU روی محصول، به‌تنهایی نشان نمی‌دهد تمام تنوع‌های آن شناسهٔ مستقل دارند. اگر انبار سایزها و رنگ‌ها را جدا مدیریت می‌کند، تطبیق تنها با شناسه یا کد والد کافی نیست.
در API سفارش، اقلام دارای فیلدهای product_id و variation_id هستند؛ API تنوع‌ها نیز مسیر جداگانه‌ای زیر محصول والد دارد. اتصال باید نوع قلم را تشخیص دهد و برای تنوع، نگاشت همان تنوع را بررسی کند. قرارداد انتقال باید مشخص کند که مقصد شناسهٔ تنوع، SKU مستقل یا کلید دیگری را می‌پذیرد.
نمونهٔ فرضی: سه تنوع از یک پیراهن
فرض کنید محصول والد ID برابر ۴۱۰ دارد و سه گزینهٔ خرید به سه رکورد مستقل انبار متصل‌اند. همهٔ شناسه‌ها و کدهای جدول زیر فرضی‌اند؛ این جدول خروجی یک فروشگاه واقعی نیست.
| تنوع فرضی | ID تنوع | SKU | کد مقصد |
|---|---|---|---|
| سرمه‌ای، متوسط | ۴۱۱ | SH-NV-M | 001207 |
| سرمه‌ای، بزرگ | ۴۱۲ | SH-NV-L | 001208 |
| آبی، متوسط | ۴۱۳ | SH-BL-M | 001209 |
برای سفارش دو عدد «سرمه‌ای، بزرگ»، مقصد باید همان رکورد 001208 باشد. فرستادن ID والد بدون اطلاعات تنوع، انتخاب یکی از رکوردها بر اساس شباهت عنوان یا استفاده از اولین نتیجهٔ جست‌وجو، معیار پذیرش این اتصال را برآورده نمی‌کند.
چه زمانی SKU مشترک کافی است و چه زمانی جدول نگاشت لازم دارید؟
- کلید مشترک: اگر هر قلم قابل فروش در دو سامانه دقیقاً یک SKU مستقل دارد، کدها کامل‌اند و فرایند تغییر کنترل می‌شود، می‌توان این کلید را برای اتصال ارزیابی کرد.
- جدول نگاشت مستقل: اگر کدهای دو سامانه متفاوت‌اند، چند سایت دارید یا SKUهای قبلی باید حفظ شوند، نگاشت صریحِ رکورد مبدأ به رکورد مقصد مناسب‌تر است.
- اصلاح داده پیش از اتصال: اگر کدها خالی یا مبهم‌اند، ابتدا مسئول رفع ابهام و فهرست موارد حل‌نشده را تعیین کنید. ساخت افزونه، انتخاب تجاریِ نامشخص بین دو کالا را خودبه‌خود حل نمی‌کند.
در نگاشت مستقل، حداقل مبدأ، شناسهٔ محصول یا تنوع، کد مقصد، وضعیت تأیید و سابقهٔ تغییر را مشخص کنید. جزئیات ذخیره‌سازی به پروژه بستگی دارد. بهتر است بتوانید نشان دهید چه کسی نگاشت را عوض کرده و کدام عملیات با نسخهٔ قبلی آن اجرا شده است.
صفرهای ابتدا و تفاوت نوشتار کد را از دست ندهید
در مثال فرضی، تبدیل 001208 به عدد، کد را به 1208 تغییر می‌دهد. اگر مقصد این دو را متفاوت بداند، انتقال عددی خطاست. فایل CSV یا صفحه‌گسترده را با ستون متنی بررسی کنید و رفت‌وبرگشت فایل را هم تست کنید؛ ظاهر صحیح سلول، حفظ مقدار اصلی را تضمین نمی‌کند.
برای فاصلهٔ ابتدا و انتها، حروف بزرگ و کوچک، رقم فارسی و لاتین و خط تیره، قاعدهٔ صریح بنویسید. حذف یا تبدیل خودکار این موارد ممکن است دو کد متفاوت را یکی کند. پیش از هر پاک‌سازی، موارد برخورد را گزارش کنید و از مسئول کاتالوگ تأیید بگیرید. همین قاعده باید در ورود دستی، فایل و API اعمال شود.
برای شناسهٔ ناشناخته یا مبهم چه اتفاقی باید بیفتد؟
پیشنهاد طراحی این است که تطبیق نامشخص، به‌صورت خودکار به کالای حدسی تبدیل نشود. عملیات مربوط را با دلیل مشخص در وضعیت قابل پیگیری نگه دارید؛ رفتار کل سفارش، مانند توقف کامل یا اجازهٔ پردازش اقلام معتبر، باید پیشاپیش توافق شود. اپراتور باید تفاوت «کالا نگاشت ندارد»، «تنوع اشتباه است» و «ارتباط مقصد قطع شده» را ببیند.
پس از اصلاح نگاشت، پیش از اجرای مجدد بررسی کنید آیا عملیات قبلی در مقصد ثبت شده است. پاسخ خطا یا قطع ارتباط به‌تنهایی به معنای ثبت‌نشدن عملیات نیست. قواعد تکرار امن و تطبیق نتیجه را در راهنمای اتصال ووکامرس به انبار و انتخاب روش انتقال را در راهنمای وبهوک یا API دوره‌ای ببینید.
تغییر SKU و حذف کالا را چگونه مدیریت کنیم؟
اگر SKU تغییر کند، سفارش‌های قبلی نباید بدون بررسی با نگاشت جدید تفسیر شوند. در طراحی اتصال مشخص کنید عملیات در انتظار اجرا از کدام نسخهٔ نگاشت استفاده می‌کند و سابقهٔ عملیات انجام‌شده چگونه حفظ می‌شود. تغییر کد در یک سامانه باید در سامانهٔ دیگر و جدول نگاشت بررسی شود؛ تغییر خودکارِ بدون گزارش می‌تواند مرجع کالا را جابه‌جا کند.
برای کالای غیرفعال یا حذف‌شده نیز تکلیف سفارش قدیمی، مرجوعی و اصلاح سند را تعیین کنید. استفادهٔ مجدد از کد یک کالای قدیمی برای کالای دیگری باید از نظر اثر روی سابقه بررسی شود. اگر قرار است کاتالوگ یا افزونه جایگزین شود، راهنمای حفظ داده هنگام جایگزینی افزونه را هم در برنامه بگذارید.
چک‌لیست آزمون نگاشت پیش از انتشار
- یک محصول ساده و چند تنوع با رنگ و سایز نزدیک را انتخاب کنید؛ برای هرکدام رکورد مقصد و تعداد مورد انتظار را از قبل ثبت کنید.
- SKU خالی، کد ناشناخته و رکورد مبهم را آزمایش کنید؛ اتصال باید همان رفتار توافق‌شده را نشان دهد و علت قابل فهم ثبت کند.
- کد دارای صفر ابتدا و تفاوت رقم یا فاصله را از ورود فایل تا درخواست مقصد دنبال کنید.
- یک سفارش با دو تنوع از یک والد بفرستید؛ تطبیق هر قلم را مستقل بررسی کنید.
- تغییر SKU، غیرفعال‌شدن کالا و مرجوعی سفارش قبلی را تست کنید؛ سابقه باید قابل ردیابی بماند.
- قطع پاسخ مقصد و اجرای مجدد پس از اصلاح نگاشت را امتحان کنید؛ شمار و کالای عملیات ثبت‌شده در مقصد را کنترل کنید.
این آزمون‌ها پیشنهاد پذیرش پروژه‌اند و جای بررسی محیط واقعی را نمی‌گیرند. دادهٔ آزمایشی را جدا نگه دارید و آزمون تغییر موجودی را در محیط مناسب انجام دهید. خروجی کنترل باید شامل قلم مبدأ، نگاشت استفاده‌شده و نتیجهٔ مقصد باشد؛ صرفاً ثبت پاسخ موفق API کافی نیست.
برای سفارش اتصال چه چیزی آماده کنید؟
نمونهٔ بدون اطلاعات مشتری از محصول ساده، محصول متغیر و رکورد انبار، تعریف فیلدهای شناسه، جهت انتقال داده و مسئول تأیید نگاشت را آماده کنید. همچنین توضیح دهید آیا یک کالا در چند انبار موجود است یا واحد فروش با واحد انبار فرق دارد؛ این موارد قواعد اضافه می‌خواهند و از برابری SKU به‌تنهایی به دست نمی‌آیند.
برای نوشتن محدوده از قالب شرح نیاز افزونه کمک بگیرید. اگر راهکار موجود سناریوهای شما را پوشش نمی‌دهد، در خدمت ساخت افزونه اختصاصی وردپرس و ووکامرس مسیر بررسی پروژه آمده است. شرح کوتاه مسئله و نمونهٔ بی‌نام را در فرم تماس بفرستید؛ کلید API یا رمز لازم نیست.
اگر فهرست کالا برای اصلاح قیمت استفاده می‌شود، راهنمای ویرایش گروهی قیمت محصولات ووکامرس پیش‌نمایش، اجرای دوباره و برگشت تغییرات را پوشش می‌دهد.
منابع و محدودهٔ راهنما
مستندات در ۳ اکتبر ۲۰۲۶ بازبینی شدند. رفتار SKU و موجودی تنوع و فیلدهای API از منابع رسمی زیر بررسی شده‌اند؛ جدول نگاشت، مثال و چک‌لیست این مقاله پیشنهاد طراحی‌اند و باید با سامانهٔ مقصد و نسخه‌های نصب‌شده آزموده شوند.