چطور برای ووکامرس سیستم حسابداری خودکار بسازیم؟ ثبت سفارش، پرداخت و موجودی

اگر فروشگاه ووکامرسی دارید و هنوز سفارش‌ها، پرداخت‌ها، مشتری‌ها و موجودی کالا را دستی وارد نرم‌افزار حسابداری می‌کنید، این آموزش دقیقاً برای حذف همین کار تکراری است. در این مقاله یک معماری عملی می‌سازیم که اطلاعات فروشگاه WooCommerce را دریافت کند، آن‌ها را به اسناد قابل استفاده در سیستم حسابداری تبدیل کند و در عین حال جلوی ثبت دوباره سفارش، مغایرت پرداخت و به‌هم‌ریختن موجودی را بگیرد.

هدف این نیست که کل یک نرم‌افزار حسابداری حرفه‌ای را از صفر در چند خط کد بسازیم. هدف این است که «هسته اتصال» را درست طراحی کنیم؛ یعنی بدانیم چه اطلاعاتی از ووکامرس بگیریم، چه زمانی سند فروش یا پرداخت بسازیم، چگونه تغییر وضعیت سفارش را مدیریت کنیم و چطور ارتباط را طوری بنویسیم که با ساختار جدید WooCommerce و قابلیت HPOS نیز سازگار بماند.

سیستم حسابداری متصل به ووکامرس دقیقاً چه کاری انجام می‌دهد؟

ووکامرس خودش سیستم فروشگاهی است؛ یعنی سفارش، محصول، مشتری، تخفیف، مالیات، هزینه ارسال و روش پرداخت را نگهداری می‌کند. اما اطلاعات فروشگاهی با اطلاعات حسابداری یکی نیست. برای نمونه، وجود یک سفارش با وضعیت «در انتظار پرداخت» الزاماً به معنی ثبت درآمد نیست و تغییر وضعیت یک سفارش به «مرجوع‌شده» باید در سیستم مالی نیز اثر مناسبی داشته باشد.

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

معماری پیشنهادی؛ حسابداری را داخل دیتابیس وردپرس نسازید

یک اشتباه رایج این است که توسعه‌دهنده مستقیماً سراغ جدول‌های دیتابیس وردپرس برود و سفارش‌ها را از wp_posts و wp_postmeta بخواند. این روش برای اتصال جدید انتخاب خوبی نیست. WooCommerce قابلیت High-Performance Order Storage یا HPOS را برای نگهداری سفارش‌ها در جدول‌های اختصاصی ارائه کرده و در فروشگاه‌های جدید این ساختار به مسیر اصلی تبدیل شده است.

راه مطمئن‌تر این است که سیستم حسابداری یک برنامه مستقل باشد و از API رسمی ووکامرس استفاده کند. در این معماری، فروشگاه فقط داده فروش را ارسال می‌کند و برنامه حسابداری منطق مالی خودش را نگه می‌دارد.

پیش‌نیازهای ساخت اتصال

برای مسیر اصلی این آموزش، یک فروشگاه WooCommerce فعال، دسترسی مدیر وردپرس و یک برنامه سمت سرور نیاز دارید. نمونه کد را با PHP می‌نویسیم چون هم با اکوسیستم وردپرس هم‌خوان است و هم روی بیشتر سرورهای لینوکسی قابل اجراست. اگر پروژه شما Laravel است، همین منطق را می‌توانید داخل Route، Controller، Queue و Job پیاده کنید.

مرحله ۱: ساخت کلید REST API در ووکامرس

REST API رابط رسمی برنامه‌نویسی WooCommerce است. از طریق آن می‌توان سفارش‌ها، محصولات و مشتری‌ها را با فرمت JSON خواند یا در صورت داشتن مجوز مناسب تغییر داد.

در پیشخوان وردپرس به مسیر WooCommerce → Settings → Advanced → REST API بروید و یک کلید جدید بسازید. اگر سیستم حسابداری فقط اطلاعات را می‌خواند، دسترسی Read کافی است. دسترسی Read/Write را فقط وقتی بدهید که واقعاً قرار است موجودی، وضعیت یا داده دیگری به WooCommerce برگردانده شود.

آدرس پایه API در ساختار فعلی WooCommerce به شکل زیر است. به‌جای shop.example.com دامنه واقعی فروشگاه خود را قرار دهید:

https://shop.example.com/wp-json/wc/v3/

برای آزمایش دسترسی به سفارش‌ها می‌توانید از یک درخواست سمت سرور استفاده کنید. فرمان زیر باید روی ترمینال رایانه یا VPS اجرا شود؛ کلیدهای واقعی خودتان را جایگزین مقدارهای نمونه کنید:

curl -u "ck_REPLACE_ME:cs_REPLACE_ME" \
"https://shop.example.com/wp-json/wc/v3/orders?per_page=1"

اگر پاسخ JSON سفارش دریافت کردید، اتصال درست است. خطای 401 معمولاً به کلید اشتباه یا سطح دسترسی مربوط است و خطای 404 می‌تواند از آدرس، پیوندهای یکتا یا تنظیمات وب‌سرور ناشی شود.

مرحله ۲: ساخت Webhook برای دریافت تغییرات لحظه‌ای

اگر فقط REST API را هر چند دقیقه یک‌بار بررسی کنیم، هم درخواست اضافه به فروشگاه می‌زنیم و هم ممکن است ثبت یک پرداخت با تأخیر انجام شود. Webhook روش بهتری برای اعلان رویداد است؛ یعنی WooCommerce هنگام تغییر سفارش خودش یک درخواست HTTP به سیستم حسابداری می‌فرستد.

از مسیر WooCommerce → Settings → Advanced → Webhooks یک Webhook ایجاد کنید. برای شروع، رویداد Order updated کاربردی است، چون تغییر وضعیت سفارش و بسیاری از تغییرات مهم را پوشش می‌دهد. آدرس تحویل می‌تواند چیزی شبیه این باشد:

https://accounting.example.com/webhooks/woocommerce

برای Webhook یک Secret قوی تعیین کنید. WooCommerce بر اساس بدنه درخواست و این Secret یک امضای HMAC-SHA256 می‌سازد و آن را در هدر X-WC-Webhook-Signature می‌فرستد. سیستم حسابداری باید قبل از قبول داده، امضا را دوباره محاسبه و مقایسه کند.

نمونه دریافت امن Webhook با PHP

کد زیر یک نمونه ساده برای فهم منطق است. آن را در فایلی مثل public/webhooks/woocommerce.php قرار دهید یا همین منطق را داخل Controller پروژه اجرا کنید. مقدار Secret باید از متغیر محیطی خوانده شود.

<?php

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$secret    = getenv('WC_WEBHOOK_SECRET');

if (!$secret) {
    http_response_code(500);
    exit('Webhook secret is not configured');
}

$expected = base64_encode(
    hash_hmac('sha256', $payload, $secret, true)
);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid webhook signature');
}

$data = json_decode($payload, true);

if (!is_array($data) || empty($data['id'])) {
    http_response_code(400);
    exit('Invalid payload');
}

$orderId   = (int) $data['id'];
$topic     = $_SERVER['HTTP_X_WC_WEBHOOK_TOPIC'] ?? 'unknown';
$delivery  = $_SERVER['HTTP_X_WC_WEBHOOK_DELIVERY_ID'] ?? null;

// در این نقطه فقط رویداد را ذخیره یا وارد صف کنید.
// پردازش سنگین حسابداری بهتر است بعد از ارسال پاسخ 2xx انجام شود.

http_response_code(200);
echo 'accepted';

نتیجه درست این مرحله دریافت پاسخ 200 در لاگ Webhook ووکامرس است. اگر امضا اشتباه باشد باید 401 دریافت کنید؛ این رفتار نشان می‌دهد Endpoint درخواست جعلی را قبول نمی‌کند.

مرحله ۳: قبل از ساخت فاکتور، رویداد را ثبت کنید

Webhook ممکن است دوباره ارسال شود، سفارش ممکن است چند بار Update شود و حتی یک تغییر کوچک در آدرس مشتری نیز همان Order ID را دوباره به سیستم شما بفرستد. اگر هر Webhook مستقیماً یک فاکتور جدید بسازد، خیلی زود با فاکتورهای تکراری روبه‌رو می‌شوید.

راه‌حل، طراحی Idempotent است؛ یعنی پردازش دوباره یک رویداد نباید نتیجه مالی را چند بار ثبت کند. برای این کار، حداقل Order ID ووکامرس و Delivery ID را ذخیره کنید.

CREATE TABLE woo_sync_events (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    delivery_id VARCHAR(100) NULL,
    topic VARCHAR(100) NOT NULL,
    woo_order_id BIGINT UNSIGNED NOT NULL,
    payload JSON NOT NULL,
    status VARCHAR(30) NOT NULL DEFAULT 'pending',
    attempts INT UNSIGNED NOT NULL DEFAULT 0,
    last_error TEXT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    processed_at TIMESTAMP NULL,
    UNIQUE KEY uniq_delivery_id (delivery_id),
    KEY idx_woo_order_id (woo_order_id),
    KEY idx_status (status)
);

اگر دیتابیس شما PostgreSQL است، نوع JSON و تعریف شناسه خودکار را با ساختار PostgreSQL تطبیق دهید. هدف این جدول نگهداری صف حسابداری نیست؛ هدف این است که بدانیم چه رویدادی رسیده، آیا پردازش شده و در صورت خطا چرا شکست خورده است.

مرحله ۴: جزئیات تازه سفارش را از REST API بگیرید

برای تصمیم مالی مهم بهتر است فقط به Payload ذخیره‌شده Webhook متکی نباشید. Worker می‌تواند Order ID را بردارد و نسخه تازه سفارش را از REST API دریافت کند. این کار مخصوصاً زمانی مفید است که چند تغییر پشت‌سرهم روی یک سفارش رخ داده باشد.

<?php

function getWooOrder(int $orderId): array
{
    $baseUrl = rtrim(getenv('WC_STORE_URL'), '/');
    $key     = getenv('WC_CONSUMER_KEY');
    $secret  = getenv('WC_CONSUMER_SECRET');

    $url = $baseUrl . '/wp-json/wc/v3/orders/' . $orderId;

    $ch = curl_init($url);

    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_USERPWD        => $key . ':' . $secret,
        CURLOPT_HTTPAUTH       => CURLAUTH_BASIC,
        CURLOPT_TIMEOUT        => 20,
        CURLOPT_CONNECTTIMEOUT => 5,
    ]);

    $body = curl_exec($ch);

    if ($body === false) {
        throw new RuntimeException(curl_error($ch));
    }

    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status !== 200) {
        throw new RuntimeException('WooCommerce returned HTTP ' . $status);
    }

    $data = json_decode($body, true);

    if (!is_array($data)) {
        throw new RuntimeException('Invalid JSON response');
    }

    return $data;
}

بعد از دریافت سفارش، فیلدهایی مثل شناسه، شماره سفارش، وضعیت، مبلغ کل، تخفیف، هزینه ارسال، مالیات، اطلاعات مشتری، اقلام، شناسه تراکنش و اطلاعات پرداخت را به مدل داخلی خودتان تبدیل کنید.

مرحله ۵: وضعیت سفارش را مستقیم به سند حسابداری تبدیل نکنید

یکی از مهم‌ترین بخش‌های پروژه همین‌جاست. وضعیت‌های ووکامرس برای مدیریت جریان سفارش ساخته شده‌اند، نه برای تعیین خودکار ماهیت حسابداری. برای مثال، در بعضی درگاه‌ها وضعیت processing بعد از پرداخت موفق ثبت می‌شود، اما نمی‌توان این رفتار را برای همه روش‌های پرداخت و همه فروشگاه‌ها یک قانون قطعی دانست.

بهتر است «قانون مالی» جدا داشته باشید. این قانون می‌تواند علاوه بر status، وجود تاریخ پرداخت، شناسه تراکنش، روش پرداخت، مبلغ دریافت‌شده و وضعیت Refund را بررسی کند.

مرحله ۶: ساخت مدل داده حسابداری

حتی اگر نسخه اول پروژه ساده باشد، بهتر است همه چیز را داخل یک جدول Orders ذخیره نکنید. از همان ابتدا موجودیت‌های اصلی را جدا کنید تا بعداً گزارش فروش، مانده مشتری، برگشت از فروش و موجودی قابل اعتماد باشند.

وجود شناسه خارجی در هر بخش حیاتی است. مثلاً اگر woo_order_id = 8124 قبلاً فاکتور ساخته، Webhook بعدی باید همان فاکتور را Update کند، نه اینکه فاکتور شماره دوم بسازد.

مرحله ۷: سند حسابداری فروش چگونه ساخته می‌شود؟

ساخت سند مالی باید بر اساس سیاست حسابداری کسب‌وکار شما باشد. مثال زیر فقط برای درک ساختار دوبل حسابداری است و جایگزین نظر حسابدار، الزامات مالیاتی یا قوانین محل فعالیت شما نیست.

فرض کنید سفارش پرداخت‌شده شامل ۱٬۰۰۰٬۰۰۰ تومان فروش کالا و ۱۰۰٬۰۰۰ تومان هزینه ارسال است. یک الگوی ساده ممکن است دریافت را در بدهکار و درآمد فروش/ارسال را در بستانکار ثبت کند. اگر مالیات نیز وجود دارد، حساب مالیات پرداختنی باید جدا شود. بهای تمام‌شده و کاهش موجودی نیز سند مستقل یا خطوط جداگانه خود را می‌خواهد.

مرحله ۸: موجودی را یک‌طرفه یا دوطرفه همگام کنیم؟

اگر هم WooCommerce و هم سیستم حسابداری اجازه ویرایش موجودی داشته باشند، بدون تعیین «مرجع اصلی» خیلی زود با حلقه همگام‌سازی روبه‌رو می‌شوید. مثلاً حسابداری موجودی را به ۸ تغییر می‌دهد، ووکامرس Webhook می‌فرستد، حسابداری دوباره همان تغییر را پردازش می‌کند و زنجیره ادامه پیدا می‌کند.

برای شروع، یک مرجع اصلی انتخاب کنید. اگر WooCommerce مرجع موجودی است، حسابداری فقط مقدار را دریافت کند. اگر انبار و حسابداری مرجع اصلی‌اند، تغییر موجودی از سیستم حسابداری با REST API به WooCommerce ارسال شود و هر تغییر خروجی با یک شناسه منبع ثبت شود تا دوباره وارد چرخه نشود.

برای تطبیق کالا استفاده از SKU بسیار مفید است، اما SKU خالی یا تکراری می‌تواند اتصال را خراب کند. بهتر است کنار SKU، شناسه عددی محصول و Variation ID ووکامرس نیز ذخیره شود.

مرحله ۹: سفارش‌های قدیمی را چگونه وارد کنیم؟

Webhook فقط از لحظه فعال‌شدن اتصال به بعد کاربرد دارد. برای سفارش‌های قبلی باید یک Import اولیه انجام دهید. این کار بهتر است صفحه‌به‌صفحه از REST API انجام شود تا حافظه سرور و زمان اجرای درخواست کنترل شود.

GET /wp-json/wc/v3/orders?per_page=100&page=1
GET /wp-json/wc/v3/orders?per_page=100&page=2
GET /wp-json/wc/v3/orders?per_page=100&page=3

در Import تاریخی نیز همان قانون جلوگیری از تکرار اعمال می‌شود. اگر سفارش قبلاً با Webhook وارد شده، Import نباید نمونه دوم ایجاد کند.

مرحله ۱۰: صف پردازش و Retry را جدی بگیرید

Webhook باید سریع پاسخ بدهد. دریافت سفارش، محاسبه فاکتور، ساخت سند، تغییر موجودی و تماس با APIهای دیگر را داخل همان درخواست انجام ندهید. بهتر است ابتدا Payload ذخیره شود، پاسخ موفق به WooCommerce برگردد و Worker جدا پردازش را ادامه دهد.

اگر REST API برای چند ثانیه در دسترس نبود، رویداد نباید از بین برود. ستون‌هایی مثل attempts و last_error برای همین هستند. برای Retry می‌توانید فاصله‌ها را به‌تدریج بیشتر کنید؛ مثلاً یک دقیقه، پنج دقیقه و پانزده دقیقه. بعد از چند شکست، وضعیت را به failed تغییر دهید تا اپراتور آن را بررسی کند.

برای کنترل در دسترس‌بودن Endpoint نیز می‌توانید از یک ابزار مانیتورینگ استفاده کنید. مقاله نصب Uptime Kuma روی VPS مسیر مناسبی برای ساخت مانیتور ساده وضعیت سرویس است.

امنیت اتصال حسابداری و ووکامرس

این اتصال به داده مشتری و اطلاعات مالی دسترسی دارد؛ بنابراین امنیت آن فقط یک گزینه اضافی نیست. چند کنترل باید از روز اول در معماری وجود داشته باشد.

آزمایش اتصال قبل از استفاده واقعی

قبل از اتصال فروشگاه اصلی، یک محیط آزمایشی یا Staging بسازید. فقط ثبت یک سفارش موفق کافی نیست؛ تغییر وضعیت‌ها و سناریوهای برگشت را نیز بررسی کنید.

خطاهای رایج و روش پیدا کردن مشکل

Webhook ارسال می‌شود ولی در حسابداری چیزی ثبت نمی‌شود

اول لاگ Webhook را در WooCommerce بررسی کنید. اگر پاسخ Endpoint غیر از 2xx است، قبل از بررسی منطق حسابداری مشکل ارتباط یا احراز اصالت را حل کنید. اگر پاسخ 200 است ولی جدول رویداد خالی مانده، مسیر ذخیره Payload و اتصال دیتابیس را بررسی کنید.

برای یک سفارش چند فاکتور ساخته می‌شود

مشکل معمولاً نبود Unique Constraint یا Idempotency است. روی woo_order_id در جدول فاکتور محدودیت یکتا بگذارید و هنگام دریافت رویداد ابتدا رکورد موجود را پیدا کنید.

بعد از فعال‌کردن HPOS اتصال قدیمی خراب شده است

اگر کد قدیمی مستقیم از جدول‌های وردپرس سفارش می‌خواند، احتمال ناسازگاری وجود دارد. مسیر صحیح، استفاده از APIهای WooCommerce یا CRUD رسمی است. اتصال مستقل مبتنی بر REST API عملاً نباید به محل فیزیکی ذخیره Order وابسته باشد.

موجودی بین دو سیستم دائم عقب و جلو می‌شود

مرجع اصلی موجودی مشخص نشده یا تغییرهای خود سیستم دوباره به‌عنوان ورودی تازه پردازش می‌شوند. یک سیستم را Source of Truth قرار دهید و برای تغییرهای خروجی شناسه منبع ذخیره کنید.

پرسش‌های متداول

آیا برای اتصال حسابداری به ووکامرس حتماً باید افزونه نصب کنیم؟

خیر. WooCommerce REST API و Webhook داخلی دارد و می‌توان بدون افزونه واسط یک اتصال اختصاصی ساخت. افزونه فقط زمانی لازم است که قابلیت مشخصی فراتر از APIهای موجود نیاز داشته باشید.

بهتر است حسابداری داخل وردپرس باشد یا جدا؟

برای پروژه جدی، جدا بودن سیستم حسابداری معمولاً معماری تمیزتر و قابل توسعه‌تری ایجاد می‌کند؛ چون دیتابیس مالی، سطوح دسترسی، صف و منطق حسابداری از چرخه به‌روزرسانی وردپرس مستقل می‌مانند.

برای دریافت اطلاعات سفارش REST API بهتر است یا Webhook؟

این دو مکمل هم هستند. Webhook تغییر را سریع اعلام می‌کند و REST API برای گرفتن نسخه تازه و کامل داده مناسب است.

اگر Webhook دوبار ارسال شود چه می‌شود؟

اگر سیستم درست طراحی شده باشد، هیچ سند تکراری نباید ساخته شود. Order ID و Delivery ID باید برای جلوگیری از پردازش دوباره کنترل شوند.

آیا می‌توان موجودی حسابداری را به ووکامرس برگرداند؟

بله، با REST API و کلید دارای مجوز Write می‌توان موجودی را تغییر داد. قبل از این کار باید مرجع اصلی موجودی و روش جلوگیری از حلقه Sync مشخص باشد.

آیا این روش با HPOS سازگار است؟

معماری مبتنی بر REST API به جدول فیزیکی ذخیره سفارش وابسته نیست و برای اتصال خارجی انتخاب مناسب‌تری از خواندن مستقیم دیتابیس است. اگر افزونه اختصاصی داخل وردپرس می‌نویسید، باید از APIهای رسمی WooCommerce استفاده و سازگاری HPOS را نیز بررسی کنید.

منابع رسمی این آموزش

🔹 مستندات رسمی WooCommerce REST API — مرجع Endpointها، ساختار API و نسخه wc/v3.

🔹 راهنمای Authentication ووکامرس — مرجع ساخت REST API Key و سطح دسترسی کلیدها.

🔹 راهنمای رسمی Webhookهای WooCommerce — توضیح ساخت Webhook و رویدادهای سفارش، محصول و مشتری.

🔹 مرجع فنی Webhook — شامل هدرهای تحویل و امضای X-WC-Webhook-Signature.

🔹 مستندات HPOS ووکامرس — توضیح ساختار جدید ذخیره سفارش و دلیل استفاده از APIهای رسمی به‌جای دسترسی مستقیم به جدول‌های قدیمی.