نانوپ
مستندات n8n
74+ نود

مستندات n8n

74+ نود مستند شده · ۰ بازدید

🛍️

ووکامرس

WooCommerce

اتوماسیون فروشگاه ووکامرس: مدیریت سفارش، محصول، مشتری، کوپن، موجودی و ارسال

فروشگاهی
متوسط
۰ بازدید
n8n 1.0+

نمای کلی

نود WooCommerce یکی از مهم‌ترین و پرکاربردترین نودهای n8n برای اتوماسیون تجارت الکترونیک است. WooCommerce یک افزونه رایگان و متن‌باز برای WordPress است که آن را به یک فروشگاه آنلاین کامل تبدیل می‌کند. با بیش از ۵ میلیون نصب فعال، WooCommerce محبوب‌ترین پلتفرم فروشگاه‌ساز جهان و بدون شک انتخاب اول فروشگاه‌های اینترنتی ایرانی است.

چرا WooCommerce محبوب‌ترین در ایران است؟

  • رایگان و متن‌باز: بدون هزینه لایسنس ماهانه
  • پشتیبانی کامل فارسی: RTL، تقویم شمسی و زبان فارسی
  • درگاه‌های پرداخت ایرانی: ZarinPal، IDPay، ملت، سامان، پارسیان و ده‌ها درگاه دیگر
  • افزونه‌های فارسی: پست پیشتاز، تیپاکس، پیامک، فاکتور فارسی
  • هاست ارزان: روی هر هاست وردپرسی قابل نصب
  • سفارشی‌سازی نامحدود: هزاران افزونه و قالب رایگان و حرفه‌ای
  • جامعه بزرگ ایرانی: آموزش، پشتیبانی و توسعه‌دهندگان فراوان

قابلیت‌های کلیدی نود:

  • مدیریت سفارشات: دریافت، ایجاد، به‌روزرسانی و تغییر وضعیت
  • مدیریت محصولات: CRUD کامل محصولات ساده و متغیر
  • تنوع‌های محصول (Variations): سایز، رنگ، مدل و قیمت‌های مختلف
  • مدیریت مشتریان: ایجاد، ویرایش و جستجوی مشتریان
  • دسته‌بندی‌ها (Categories): ساختار درختی دسته‌بندی محصولات
  • تگ‌ها (Tags): برچسب‌گذاری محصولات
  • کوپن تخفیف (Coupons): ایجاد و مدیریت کدهای تخفیف
  • تنظیمات ارسال (Shipping): مناطق و روش‌های ارسال
  • مالیات (Tax): نرخ‌ها و کلاس‌های مالیاتی
  • نظرات محصول (Reviews): مدیریت بازخوردهای مشتریان
  • گزارش‌ها (Reports): آمار فروش، محصولات پرفروش و مشتریان

WooCommerce Trigger (Webhook):

  • سفارش جدید (order.created)
  • تغییر وضعیت سفارش (order.updated)
  • سفارش تکمیل شده (order.completed)
  • محصول جدید (product.created)
  • به‌روزرسانی محصول (product.updated)
  • مشتری جدید (customer.created)
  • کوپن جدید (coupon.created)
  • بازپرداخت (order.refunded)

مزیت WooCommerce نسبت به Shopify برای بازار ایران:

  • درگاه پرداخت ایرانی: پشتیبانی مستقیم از ZarinPal، IDPay، ملت و ده‌ها درگاه
  • هزینه کمتر: بدون کمیسیون ماهانه (Shopify از ۲۹ دلار/ماه شروع می‌شود)
  • کنترل کامل: سرور و داده‌ها کاملاً در اختیار شماست
  • زبان فارسی: پشتیبانی بومی از فارسی و تقویم شمسی
  • بدون تحریم: نیاز به VPN یا واسطه ندارید

احراز هویت

احراز هویت WooCommerce

روش اصلی: REST API Keys (توصیه شده)

WooCommerce از Consumer Key و Consumer Secret برای احراز هویت API استفاده می‌کند. این روش امن‌ترین و استانداردترین راه اتصال به n8n است.

#### مرحله ۱: فعال‌سازی REST API

  1. 1به پیشخوان وردپرس بروید
  2. 2مسیر: WooCommerce > تنظیمات > پیشرفته > REST API
  3. 3روی افزودن کلید (Add Key) کلیک کنید

#### مرحله ۲: ایجاد API Key

  1. 1توضیحات (Description): یک نام توصیفی وارد کنید، مثلاً "n8n Automation"
  2. 2کاربر (User): کاربر ادمین خود را انتخاب کنید
  3. 3سطح دسترسی (Permissions): بسته به نیاز:
  • Read: فقط خواندن (برای گزارش‌ها و مانیتورینگ)
  • Write: فقط نوشتن
  • Read/Write: خواندن و نوشتن (توصیه شده برای اتوماسیون کامل)
  1. 1روی ایجاد API Key کلیک کنید

#### مرحله ۳: ذخیره کلیدها پس از ایجاد، دو کلید نمایش داده می‌شود:

code
Consumer Key:    ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Consumer Secret: cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

مهم: Consumer Secret فقط یکبار نمایش داده می‌شود! آن را فوراً ذخیره کنید.

#### مرحله ۴: تنظیم در n8n

  1. 1در n8n به Credentials > WooCommerce API بروید
  2. 2اطلاعات را وارد کنید:
code
WooCommerce URL: https://your-store.com (بدون /wp-json)
   Consumer Key:    ck_xxxxxxxx
   Consumer Secret: cs_xxxxxxxx
  1. 1Include Credentials in Query: اگر از HTTP استفاده می‌کنید فعال کنید
  2. 2Test Connection بزنید

الزامات SSL:

  • WooCommerce API روی HTTP فقط با Basic Auth بدون رمزنگاری کار می‌کند
  • برای امنیت، حتماً از HTTPS استفاده کنید
  • اگر SSL ندارید، گزینه "Include Credentials in Query" را فعال کنید
  • SSL رایگان Let's Encrypt را فعال کنید

تنظیم Webhook برای WooCommerce Trigger:

#### روش ۱: خودکار از طریق n8n

  1. 1در n8n یک WooCommerce Trigger node اضافه کنید
  2. 2Event مورد نظر را انتخاب کنید (مثل Order Created)
  3. 3Workflow را Activate کنید
  4. 4n8n به صورت خودکار webhook را در WooCommerce ثبت می‌کند

#### روش ۲: دستی از پیشخوان وردپرس

  1. 1مسیر: WooCommerce > تنظیمات > پیشرفته > Webhooks
  2. 2افزودن Webhook کلیک کنید:
code
نام:       n8n Order Notification
   وضعیت:     فعال
   موضوع:     سفارش ایجاد شده (Order created)
   URL تحویل: https://your-n8n.com/webhook/woocommerce-orders
   Secret:    یک کلید امن تصادفی
   نسخه API:  نسخه ۳ WP REST API (v3)
  1. 1ذخیره Webhook کلیک کنید

Topics پرکاربرد Webhook:

code
order.created       → سفارش جدید ثبت شد
order.updated       → وضعیت سفارش تغییر کرد
order.deleted       → سفارش حذف شد
order.restored      → سفارش بازیابی شد
product.created     → محصول جدید اضافه شد
product.updated     → محصول ویرایش شد
product.deleted     → محصول حذف شد
customer.created    → مشتری جدید ثبت‌نام کرد
customer.updated    → اطلاعات مشتری تغییر کرد
coupon.created      → کوپن جدید ایجاد شد
coupon.updated      → کوپن ویرایش شد

نکات امنیتی:

  • Consumer Key و Secret را به اشتراک نگذارید
  • برای هر سرویس (n8n, اپ موبایل و غیره) API Key جداگانه بسازید
  • از HTTPS اجباری استفاده کنید
  • دسترسی‌ها را به حداقل مورد نیاز محدود کنید
  • API Keyهای استفاده نشده را حذف کنید
  • Webhook Secret را قوی و تصادفی انتخاب کنید
  • لاگ‌های REST API را دوره‌ای بررسی کنید

تنظیمات ویژه برای فروشگاه‌های ایرانی:

  • Permalink: حتماً از Pretty Permalinks استفاده کنید (نه Plain)
  • REST API: مطمئن شوید REST API توسط افزونه امنیتی بلاک نشده
  • فایروال: IP سرور n8n را در وایت‌لیست قرار دهید
  • Rate Limiting: اگر افزونه محدودکننده دارید، API calls را مستثنا کنید

عملیات‌های موجود

1

order-create

ایجاد سفارش جدید در فروشگاه با اطلاعات مشتری و محصولات

2

order-get

دریافت اطلاعات کامل یک سفارش با شناسه

3

order-list

دریافت لیست سفارشات با فیلترهای مختلف

4

order-update

ویرایش اطلاعات سفارش موجود مانند وضعیت، یادداشت و متادیتا

5

order-delete

حذف سفارش (انتقال به زباله‌دان یا حذف دائم)

6

product-create

ایجاد محصول جدید با عنوان، توضیحات، قیمت، تصاویر و موجودی

7

product-get

دریافت اطلاعات کامل یک محصول با شناسه

8

product-update

ویرایش اطلاعات محصول موجود: قیمت، موجودی، توضیحات و تصاویر

9

product-delete

حذف محصول از فروشگاه

10

product-variation-create

ایجاد تنوع جدید برای محصول متغیر (سایز، رنگ، مدل)

11

customer-create

ایجاد مشتری (کاربر) جدید در فروشگاه

12

customer-get

دریافت اطلاعات کامل یک مشتری

13

customer-list

دریافت لیست مشتریان با فیلتر و صفحه‌بندی

14

customer-update

ویرایش اطلاعات مشتری شامل آدرس، تلفن و متادیتا

15

coupon-create

ایجاد کوپن تخفیف جدید با شرایط مختلف

16

category-create

ایجاد دسته‌بندی جدید برای محصولات با ساختار درختی

17

tag-create

ایجاد تگ (برچسب) جدید برای محصولات

18

shipping-zone-list

دریافت لیست مناطق ارسال و روش‌های حمل‌ونقل تعریف‌شده

19

tax-rate-list

دریافت لیست نرخ‌های مالیاتی تعریف‌شده در فروشگاه

20

review-list

دریافت نظرات و امتیازات مشتریان روی محصولات

21

report-sales

دریافت گزارش آماری فروش با فیلتر بازه زمانی

کاربردهای متداول

کاربردهای رایج

۱. اعلان سفارش جدید در تلگرام

هر بار که سفارش جدیدی ثبت شود، پیام فارسی کاملی با جزئیات سفارش به گروه تلگرام مدیران ارسال شود. ضروری‌ترین اتوماسیون برای هر فروشگاه ایرانی.

code
WooCommerce Trigger (order.created)
  → Code (فرمت فارسی پیام)
    const order = $input.first().json;
    const items = order.line_items.map(i =>
      '- ' + i.name + ' x' + i.quantity + ' | ' + i.total + ' تومان'
    ).join('\n');
    return {
      text: '🛒 سفارش جدید #' + order.number + '\n\n'
        + '👤 ' + order.billing.first_name + ' ' + order.billing.last_name + '\n'
        + '📱 ' + order.billing.phone + '\n'
        + '💰 ' + order.total + ' تومان\n'
        + '📦 ' + items + '\n'
        + '🏠 ' + order.shipping.address_1 + ', ' + order.shipping.city
    };
  → Telegram (sendMessage)
    ChatId: @my_shop_orders
    ParseMode: HTML

۲. همگام‌سازی موجودی با انبار فیزیکی

وقتی موجودی در سیستم انبارداری تغییر کند، موجودی محصول در WooCommerce هم به‌روز شود. جلوگیری از فروش محصول تمام‌شده.

code
Webhook (تغییر موجودی انبار)
  → WooCommerce (product-update)
    productId: از mapping table
    stock_quantity: موجودی جدید
    stock_status: instock / outofstock
  → IF (stock_quantity < 5)
    → Telegram (هشدار موجودی کم)
      Text: "هشدار! موجودی محصول X به Y عدد رسید"
  → IF (stock_quantity == 0)
    → Telegram (هشدار اتمام موجودی)
    → Google Sheets (ثبت در لیست سفارش مجدد)

۳. بازیابی سبد خرید رها شده (Abandoned Cart Recovery)

ارسال خودکار پیامک یا ایمیل یادآوری به مشتریانی که سبد خرید خود را تکمیل نکرده‌اند. یکی از موثرترین تکنیک‌های افزایش فروش.

code
Schedule (هر ساعت)
  → MySQL (خواندن سبدهای رها شده > 1 ساعت)
    SELECT * FROM wp_woocommerce_sessions
    WHERE session_expiry > NOW()
    AND cart_contents != ''
  → Loop (هر سبد رها شده)
    → Code (استخراج اطلاعات مشتری و محصولات)
    → IF (شماره تلفن دارد)
      → HTTP Request (ارسال پیامک)
        Text: "سلام! سبد خرید شما منتظر تکمیل است. برگردید و خرید کنید..."
        Link: https://shop.com/cart
    → IF (ایمیل دارد)
      → Email Send (یادآوری سبد خرید)
    → Wait (24 ساعت)
    → IF (هنوز خرید نکرده)
      → WooCommerce (coupon-create)
        code: "COMEBACK-{userId}"
        discount_type: percent
        amount: "10"
        usage_limit: 1
        date_expires: 3 روز بعد
      → پیامک/ایمیل (کد تخفیف ویژه)

۴. فروش چندکاناله (Multi-channel Selling)

همگام‌سازی محصولات و موجودی بین WooCommerce و سایر کانال‌های فروش (دیجیکالا، ترب، اینستاگرام).

code
WooCommerce Trigger (product.updated)
  → IF (تغییر قیمت یا موجودی)
    → HTTP Request (به‌روزرسانی در API دیجیکالا)
      PUT /api/products
      Body: {sku, price_new, stock}
    → HTTP Request (به‌روزرسانی در ترب)
    → Google Sheets (ثبت لاگ تغییرات)
  → IF (محصول جدید)
    → Telegram (ارسال محصول به کانال اینستاگرام)
    → HTTP Request (ایجاد در سایر پلتفرم‌ها)

۵. صدور خودکار فاکتور رسمی فارسی

پس از تکمیل سفارش، فاکتور رسمی فارسی تولید و به مشتری ایمیل شود.

code
WooCommerce Trigger (order.completed)
  → WooCommerce (order-get: اطلاعات کامل)
  → Code (تولید HTML فاکتور فارسی)
    const order = $input.first().json;
    // تبدیل تاریخ به شمسی
    // فرمت اعداد فارسی
    // ساخت جدول آیتم‌ها
    // محاسبه مالیات بر ارزش افزوده
  → HTTP Request (تبدیل HTML به PDF)
  → Email Send (ارسال فاکتور)
    To: order.billing.email
    Subject: "فاکتور سفارش #" + order.number
    Attachment: invoice.pdf

۶. سیستم امتیازدهی و وفاداری مشتریان

بر اساس خرید مشتری، امتیاز اختصاص داده شود و در خرید بعدی تخفیف بگیرد.

code
WooCommerce Trigger (order.completed)
  → Code (محاسبه امتیاز)
    const points = Math.floor(order.total / 10000); // هر 10,000 تومان = 1 امتیاز
  → MySQL (به‌روزرسانی امتیاز مشتری)
    UPDATE wp_usermeta SET meta_value = meta_value + points
    WHERE user_id = order.customer_id AND meta_key = 'loyalty_points'
  → IF (امتیاز > 100)
    → WooCommerce (coupon-create)
      code: "LOYAL-{customer_id}"
      discount_type: fixed_cart
      amount: "50000"
      usage_limit: 1
    → SMS/Telegram (اطلاع‌رسانی به مشتری)
      Text: "تبریک! شما 100 امتیاز جمع کردید. کد تخفیف 50,000 تومانی..."

۷. گزارش فروش روزانه و هفتگی

ارسال خودکار آمار فروش به مدیران در تلگرام و ذخیره در Google Sheets.

code
Schedule (هر شب ساعت ۲۳:۳۰)
  → WooCommerce (order-list)
    status: completed,processing
    after: امروز ۰۰:۰۰
  → Code (محاسبه آمار)
    const orders = $input.all().map(i => i.json);
    const totalSales = orders.reduce((s, o) => s + parseFloat(o.total), 0);
    const avgOrder = totalSales / orders.length;
    const topProducts = ...; // محصولات پرفروش
  → Telegram (sendMessage)
    Text:
      📊 گزارش فروش امروز:
      تعداد سفارش: {count}
      مجموع فروش: {totalSales} تومان
      میانگین سفارش: {avgOrder} تومان
      پرفروش‌ترین: {topProduct}
  → Google Sheets (ذخیره آمار روزانه)

۸. پردازش خودکار پرداخت و تغییر وضعیت سفارش

وقتی پرداخت از درگاه ایرانی تایید شود، وضعیت سفارش به صورت خودکار تغییر کند.

code
Webhook (callback درگاه زرین‌پال)
  → HTTP Request (verify payment)
    POST https://api.zarinpal.com/pg/v4/payment/verify.json
  → IF (Status == 100: تایید شده)
    → WooCommerce (order-update)
      status: processing
      meta_data: [{key: "zarinpal_ref", value: RefID}]
    → Telegram (تایید پرداخت به ادمین)
  → ELSE
    → WooCommerce (order-update)
      status: failed
    → Telegram (هشدار پرداخت ناموفق)

۹. ارسال خودکار کد رهگیری مرسوله

وقتی بسته در سیستم لجستیک ثبت شد، کد رهگیری به مشتری ارسال شود.

code
Webhook (ثبت بارنامه از پست/تیپاکس)
  → WooCommerce (order-update)
    orderId: order_id
    status: completed
    meta_data: [{key: "tracking_code", value: tracking}]
  → WooCommerce (order-get: اطلاعات مشتری)
  → HTTP Request (ارسال پیامک)
    Text: "سفارش #{order_number} ارسال شد.
           کد رهگیری: {tracking_code}
           پیگیری: https://tracking.post.ir/?id={tracking_code}"
  → Telegram (اعلان ارسال به ادمین)

۱۰. یکپارچه‌سازی با نرم‌افزار حسابداری

همگام‌سازی سفارشات و فاکتورها با نرم‌افزارهای حسابداری ایرانی (هلو، سپیدار، راهکاران).

code
WooCommerce Trigger (order.completed)
  → Code (تبدیل فرمت سفارش به فرمت حسابداری)
    // تبدیل تاریخ میلادی به شمسی
    // محاسبه مالیات بر ارزش افزوده (۹٪)
    // تفکیک آیتم‌ها بر اساس کد حسابداری
    // استخراج اطلاعات مشتری
  → HTTP Request (ارسال به API نرم‌افزار حسابداری)
    POST /api/invoices
    Body: {customer, items, tax, date_shamsi}
  → MySQL (ذخیره mapping سفارش-فاکتور)
  → IF (خطا)
    → Telegram (هشدار خطای همگام‌سازی حسابداری)

۱۱. مدیریت خودکار نظرات و امتیازات محصول

بررسی نظرات جدید، فیلتر اسپم و اعلان نظرات مثبت/منفی.

code
Schedule (هر ۳۰ دقیقه)
  → WooCommerce (review-list) status: hold
  → Loop (هر نظر)
    → Code (بررسی اسپم و محتوای نامناسب)
    → IF (امتیاز >= 4)
      → WooCommerce API (approve review)
      → Telegram (نظر مثبت جدید!)
    → IF (امتیاز <= 2)
      → Telegram (هشدار نظر منفی به تیم پشتیبانی)
      → Email (ارسال ایمیل عذرخواهی + کد تخفیف به مشتری)
    → IF (اسپم)
      → WooCommerce API (trash review)

۱۲. ایجاد خودکار محصول از Google Sheets

مدیران محصولات را در اسپردشیت وارد کنند و به صورت خودکار در فروشگاه ایجاد شوند.

code
Google Sheets Trigger (ردیف جدید)
  → WooCommerce (product-create)
    name: نام محصول
    regular_price: قیمت
    description: توضیحات
    sku: کد محصول
    categories: [{id: mapping[category_name]}]
    images: [{src: image_url}]
    manage_stock: true
    stock_quantity: موجودی
    status: publish
  → Google Sheets (به‌روزرسانی ستون woo_product_id)
  → Telegram (محصول جدید اضافه شد)

۱۳. سیستم هشدار قیمت رقبا

مانیتورینگ قیمت رقبا و به‌روزرسانی خودکار قیمت‌ها.

code
Schedule (هر ۶ ساعت)
  → WooCommerce (product-list: محصولات فعال)
  → Loop (هر محصول)
    → HTTP Request (scrape قیمت رقیب از ترب/دیجیکالا)
    → Code (مقایسه قیمت)
    → IF (قیمت ما > قیمت رقیب + 5%)
      → WooCommerce (product-update)
        sale_price: قیمت رقابتی
      → Telegram (هشدار تغییر قیمت)
    → Google Sheets (ثبت لاگ مقایسه قیمت)

نکات حرفه‌ای

نکات حرفه‌ای

۱. از WooCommerce Trigger (Webhook) بجای Polling استفاده کنید

Webhook بلافاصله پس از رویداد اجرا می‌شود در حالی که Polling (Schedule + API) تاخیر دارد و منابع بیشتری مصرف می‌کند. برای سفارش جدید، همیشه از Webhook استفاده کنید.

۲. Batch Operations برای عملیات انبوه

برای به‌روزرسانی چندین محصول یا سفارش، از Batch API استفاده کنید تا بجای N درخواست جداگانه، همه را در یک درخواست ارسال کنید:

code
POST /wp-json/wc/v3/products/batch
Body: {
  update: [
    {id: 1, regular_price: "50000"},
    {id: 2, regular_price: "75000"},
    {id: 3, stock_quantity: 0}
  ]
}

حداکثر ۱۰۰ آیتم در هر batch.

۳. استفاده از meta_data برای داده‌های سفارشی

WooCommerce از meta_data برای ذخیره هر نوع اطلاعات اضافی پشتیبانی می‌کند. از آن برای ذخیره اطلاعات خاص فروشگاه ایرانی استفاده کنید:

code
meta_data: [
  {key: "_billing_national_code", value: "0012345678"},
  {key: "_billing_postal_code", value: "1234567890"},
  {key: "_tracking_code", value: "123456789012"},
  {key: "_payment_gateway_ref", value: "A00000000000000000000"},
  {key: "_shamsi_date", value: "1403/05/15"}
]

۴. وضعیت‌های سفارش WooCommerce

درک صحیح وضعیت‌ها برای اتوماسیون حیاتی است:

code
pending      → در انتظار پرداخت (سفارش ثبت شده ولی پرداخت نشده)
processing   → در حال پردازش (پرداخت شده، آماده ارسال)
on-hold      → در انتظار (نیاز به بررسی دستی)
completed    → تکمیل شده (ارسال شده و تحویل داده شده)
cancelled    → لغو شده (توسط مشتری یا ادمین)
refunded     → مسترد شده (وجه برگردانده شده)
failed       → ناموفق (پرداخت ناموفق)
trash        → زباله‌دان

سفارش معمولی: pending → processing → completed

۵. Pagination برای دریافت همه داده‌ها

WooCommerce حداکثر ۱۰۰ آیتم در هر صفحه برمی‌گرداند. Header پاسخ شامل اطلاعات صفحه‌بندی است:

code
X-WP-Total: 250          → تعداد کل آیتم‌ها
X-WP-TotalPages: 3       → تعداد کل صفحات

برای دریافت همه: حلقه‌ای بنویسید که page را افزایش دهد تا X-WP-TotalPages.

۶. تنظیمات ویژه درگاه‌های پرداخت ایرانی

الگوی اتوماسیون WooCommerce + درگاه‌های ایرانی:

code
WooCommerce + ZarinPal:
  → سفارش جدید (status: pending)
  → پرداخت موفق → order-update (status: processing)
  → پرداخت ناموفق → order-update (status: failed)
  → ذخیره شماره تراکنش در meta_data

WooCommerce + IDPay:
  → مشابه ZarinPal با API متفاوت
  → callback URL: /wc-api/idpay_gateway

افزونه‌های محبوب درگاه:
  → WooCommerce ZarinPal Gateway
  → IDPay for WooCommerce
  → WooCommerce Mellat Bank Gateway
  → WooCommerce Saman Bank Gateway

۷. ساختار صحیح محصول متغیر (Variable Product)

برای ایجاد محصول با تنوع (سایز، رنگ) سه مرحله لازم است:

code
مرحله ۱: ایجاد محصول Variable
  WooCommerce (product-create)
    type: variable
    attributes: [{name: "رنگ", options: ["قرمز", "آبی", "سبز"], variation: true}]

مرحله ۲: ایجاد Variation برای هر گزینه
  WooCommerce (product-variation-create)
    productId: شناسه محصول والد
    regular_price: "150000"
    attributes: [{name: "رنگ", option: "قرمز"}]
    stock_quantity: 10

مرحله ۳: تکرار برای سایر گزینه‌ها
  → Loop → Variation Create

۸. Rate Limit و بهینه‌سازی درخواست‌ها

WooCommerce محدودیت rate limit پیش‌فرض ندارد، ولی سرور شما دارد:

code
نکات بهینه‌سازی:
  → بین درخواست‌ها 300ms Wait اضافه کنید
  → از per_page: 100 بجای مقدار پیش‌فرض ۱۰ استفاده کنید
  → فقط فیلدهای مورد نیاز را درخواست کنید: ?_fields=id,name,price
  → از Batch API برای عملیات انبوه استفاده کنید
  → WP Object Cache (Redis) فعال کنید

۹. Webhook Topics پرکاربرد و ترتیب رویدادها

code
order.created       → ثبت سفارش جدید (اولین رویداد)
order.updated       → هر تغییر در سفارش (وضعیت، آدرس و غیره)
order.deleted       → حذف سفارش
order.restored      → بازیابی سفارش از زباله‌دان
product.created     → محصول جدید از پیشخوان
product.updated     → هر تغییر در محصول
product.deleted     → حذف محصول
customer.created    → ثبت‌نام مشتری جدید
customer.updated    → تغییر اطلاعات مشتری
coupon.created      → کوپن جدید ایجاد شد
coupon.updated      → کوپن ویرایش شد

ترتیب سفارش معمولی: order.created → order.updated (pending) → order.updated (processing) → order.updated (completed)

۱۰. یکپارچه‌سازی با پلاگین‌های فارسی محبوب

code
پیامک:
  → WP SMS, Melipayamak, Kavenegar
  → می‌توانید از n8n بجای افزونه SMS استفاده کنید (ارزان‌تر)

حمل‌ونقل:
  → WooCommerce Post Pishtaz (پست پیشتاز)
  → Tipax Shipping
  → Peyk, SnapExpress (ارسال فوری)
  → n8n می‌تواند کد رهگیری را خودکار وارد کند

فاکتور:
  → Persian WooCommerce Invoice
  → n8n می‌تواند فاکتور PDF فارسی تولید کند

تقویم شمسی:
  → WP Jalali (Shamsi Calendar)
  → تاریخ سفارش در API به میلادی است، در n8n تبدیل کنید

۱۱. فیلتر کردن سفارشات با پارامترهای پیشرفته

code
سفارشات امروز:
  /orders?after=2024-01-15T00:00:00&status=processing

سفارشات یک مشتری خاص:
  /orders?customer=123&per_page=100

سفارشات حاوی محصول خاص:
  /orders?product=456

جستجو بر اساس شماره سفارش:
  /orders?search=1234

مرتب‌سازی بر اساس تاریخ (جدیدترین):
  /orders?orderby=date&order=desc

۱۲. Error Handling حرفه‌ای

همیشه Error Workflow داشته باشید:

code
WooCommerce Node → On Error:
  → Code (استخراج جزئیات خطا)
    const error = $input.first().json;
    const errorCode = error.data?.status || 'unknown';
    const errorMsg = error.message || 'خطای ناشناخته';
  → IF (errorCode == 429 || errorCode >= 500)
    → Wait (5 ثانیه) → Retry
  → ELSE
    → MySQL (ذخیره لاگ خطا)
    → Telegram (هشدار به ادمین)
      Text: "خطای WooCommerce API: {errorCode} - {errorMsg}"

۱۳. تست API بدون n8n

برای عیب‌یابی، ابتدا API را مستقیماً تست کنید:

code
curl https://your-store.com/wp-json/wc/v3/orders \
  -u ck_xxxxx:cs_xxxxx

curl https://your-store.com/wp-json/wc/v3/products \
  -u ck_xxxxx:cs_xxxxx \
  -H "Content-Type: application/json"

اگر curl کار کرد ولی n8n نه، مشکل از تنظیمات credential n8n است.

۱۴. Multi-vendor Setup (فروشگاه چندفروشنده‌ای)

برای فروشگاه‌های چندفروشنده‌ای (Dokan, WCFM, WC Vendors):

code
WooCommerce Trigger (order.created)
  → Code (تفکیک آیتم‌ها بر اساس فروشنده)
  → Loop (هر فروشنده)
    → Telegram (اعلان سفارش به فروشنده)
    → Email (جزئیات سفارش)
    → MySQL (ثبت کمیسیون)
  → Code (محاسبه کمیسیون فروشگاه)

۱۵. استفاده از WooCommerce REST API v3

همیشه از آخرین نسخه API (v3) استفاده کنید:

code
Base URL: https://your-store.com/wp-json/wc/v3/
Endpoints:
  /orders            → سفارشات
  /products          → محصولات
  /products/{id}/variations → تنوع‌ها
  /customers         → مشتریان
  /coupons           → کوپن‌ها
  /shipping/zones    → مناطق ارسال
  /taxes             → مالیات
  /reports/sales     → گزارش فروش
  /products/categories → دسته‌بندی‌ها
  /products/tags     → تگ‌ها
  /products/reviews  → نظرات

۱۶. بهینه‌سازی عملکرد برای فروشگاه‌های بزرگ

code
اگر فروشگاه شما بیش از ۱۰۰۰ محصول یا ۵۰۰ سفارش روزانه دارد:
  → از Redis Object Cache استفاده کنید
  → WP-Cron را با سرور cron جایگزین کنید
  → REST API Caching فعال کنید
  → از _fields پارامتر برای محدود کردن فیلدها استفاده کنید
  → HPOS (High-Performance Order Storage) را فعال کنید
  → از CDN برای تصاویر محصول استفاده کنید
  → دیتابیس را بهینه و index کنید

رفع مشکلات

رفع مشکلات رایج

خطای 401 - Consumer Key/Secret نامعتبر

علت: کلیدهای API اشتباه یا نامعتبر هستند

راه‌حل

  • مطمئن شوید Consumer Key با ck_ و Consumer Secret با cs_ شروع می‌شود
  • کلیدها را از WooCommerce > تنظیمات > پیشرفته > REST API مجدداً بررسی کنید
  • کلید جدید بسازید اگر Secret را گم کرده‌اید (فقط یکبار نمایش داده می‌شود)
  • URL فروشگاه را بدون اسلش انتهایی و بدون /wp-json وارد کنید
  • مطمئن شوید Permalinks روی Plain نباشد (Pretty Permalinks فعال باشد)

خطای 403 - دسترسی کافی نیست

علت: سطح دسترسی API Key پایین‌تر از عملیات درخواستی است

راه‌حل

  • سطح دسترسی API Key را بررسی کنید (Read/Write/Read-Write)
  • برای ایجاد و ویرایش، حتماً دسترسی Write لازم است
  • کاربر مرتبط با API Key باید نقش Administrator داشته باشد
  • بررسی کنید افزونه امنیتی (Wordfence, iThemes) REST API را بلاک نکرده باشد
  • اگر از CDN مثل Cloudflare استفاده می‌کنید، IP سرور n8n را وایت‌لیست کنید

خطای 404 - Endpoint پیدا نشد

علت: REST API غیرفعال یا URL نادرست

راه‌حل

  • Permalink Settings را به Post name یا Custom Structure تغییر دهید
  • آدرس فروشگاه را بررسی کنید: https://your-store.com (بدون /shop یا /wp-json)
  • REST API URL را تست کنید: https://your-store.com/wp-json/wc/v3/
  • افزونه WooCommerce نصب و فعال باشد
  • فایل .htaccess دسترسی به wp-json را بلاک نکرده باشد
  • اگر ۴۰۴ می‌گیرید، از پیشخوان وردپرس Permalinks را یکبار Save کنید

خطای 400 - پارامتر نامعتبر

علت: داده‌های ارسالی فرمت صحیح ندارند

راه‌حل

  • regular_price و sale_price باید string باشند، نه number: "50000" نه 50000
  • categories باید آرایه از object باشد: [{id: 15}] نه [15]
  • images باید URL کامل و قابل دسترس داشته باشند
  • stock_quantity باید عدد صحیح (integer) باشد
  • sku نباید تکراری باشد
  • status فقط مقادیر مجاز: draft, pending, private, publish
  • برای سفارش: line_items باید حداقل یک آیتم داشته باشد

خطای 500 - Internal Server Error

علت: مشکل در سرور وردپرس

راه‌حل

  • لاگ خطاهای PHP را بررسی کنید: wp-content/debug.log
  • WP_DEBUG را در wp-config.php فعال کنید
  • حافظه PHP را افزایش دهید: define('WP_MEMORY_LIMIT', '256M')
  • تداخل افزونه‌ها را بررسی کنید (غیرفعال کردن یک‌به‌یک)
  • نسخه PHP سرور حداقل ۷.۴ باشد (۸.۱+ توصیه می‌شود)

Webhook Events دریافت نمی‌شوند

علت: تنظیمات Webhook نادرست یا مشکل شبکه

راه‌حل

  • مطمئن شوید n8n از اینترنت قابل دسترس است (Public URL، نه localhost)
  • SSL معتبر روی n8n فعال باشد (HTTPS)
  • وضعیت Webhook در WooCommerce > تنظیمات > پیشرفته > Webhooks "فعال" باشد
  • Delivery URL را بررسی کنید
  • لاگ Webhook را ببینید: هر webhook تاریخچه ارسال دارد
  • Webhook Secret را در n8n تنظیم کنید
  • WooCommerce Action Scheduler فعال باشد (WP Cron باید کار کند)
  • اگر از افزونه کش استفاده می‌کنید، REST API را از کش مستثنا کنید

مشکل محصولات متغیر (Variable Products)

علت: Attributes یا Variations نادرست تنظیم شده

راه‌حل

  • ابتدا محصول را با type: variable ایجاد کنید
  • Attributes را با variation: true تعریف کنید
  • سپس Variations را جداگانه ایجاد کنید
  • هر Variation باید attributes با مقدار دقیق option داشته باشد
  • regular_price برای Variation اجباری است (نه محصول والد)
  • حداکثر تعداد Variations: بستگی به سرور دارد (معمولاً ۵۰-۱۰۰)

کندی API و Timeout

علت: حجم زیاد داده یا سرور ضعیف

راه‌حل

  • از per_page برای محدود کردن نتایج استفاده کنید
  • از pagination استفاده کنید (page=1, page=2, ...)
  • بین درخواست‌ها Wait node اضافه کنید (300-500ms)
  • از فیلترهای date و status برای محدود کردن نتایج استفاده کنید
  • Object Cache (Redis/Memcached) روی سرور وردپرس نصب کنید
  • max_execution_time PHP را افزایش دهید
  • از WooCommerce REST API Caching افزونه استفاده کنید

مشکل Encoding فارسی

علت: مشکل در UTF-8 یا JSON encoding

راه‌حل

  • مطمئن شوید سرور از UTF-8 پشتیبانی می‌کند
  • در header درخواست: Content-Type: application/json; charset=utf-8
  • از JSON.stringify() برای ارسال داده‌های فارسی استفاده کنید
  • Collation دیتابیس: utf8mb4_unicode_ci باشد
  • در WordPress: DB_CHARSET باید utf8mb4 باشد
اشتراک‌گذاری:

آیا این مستندات مفید بود؟