چگونه یک REST API سفارشی در ووکامرس بسازیم تا کسب‌وکارمان را به سطح بعدی ببریم؟ 🚀

چگونه یک REST API سفارشی در ووکامرس بسازیم تا کسب_وکارمان را به سطح بعدی ببریم؟ 🚀
محصولات زیر برای شماست...
جدیدترین مقالات
دسترسی سریع
فهرست محتوا

تا به حال به این فکر کرده‌اید که فروشگاه ووکامرسی شما بتواند با یک اپلیکیشن موبایل اختصاصی، یک نرم‌افزار حسابداری پیشرفته یا حتی یک سیستم مدیریت مشتریان (CRM) به صورت یکپارچه صحبت کند؟ این رویای شیرین، با مفهومی به نام API به واقعیت تبدیل می‌شود.

API یا “رابط برنامه‌نویسی کاربردی”، مانند یک مترجم و پیام‌رسان حرفه‌ای بین نرم‌افزارهای مختلف عمل می‌کند و به آن‌ها اجازه می‌دهد داده‌ها را به شکلی امن و استاندارد با یکدیگر رد و بدل کنند.

این مقاله از دسته بندی آموزش فروشگاه اینترنتی در وردپرس نیاز، قدم‌به‌قدم و کاملاً عملی برای توسعه‌دهندگان و صاحبان فروشگاه‌های اینترنتی است که می‌خواهند از مرزهای یک سایت ساده فراتر بروند. ما به شما نشان می‌دهیم چطور می‌توانید با ساخت یک API سفارشی، امکانات فروشگاه ووکامرسی خود را گسترش دهید، فرآیندهایتان را خودکار کنید و تجربه‌ای بی‌نظیر برای مشتریان خود خلق کنید. صبرب کنید! اگر هنوز آنلاین شاپ ندارید، میتوانید با مطالعه مقاله ساخت فروشگاه آنلاین با وردپرس، ابتدا یک آنلاین شاپ بسازید سپس به ادامه آموزش بپردازید. پس اگر آماده‌اید قدرت واقعی ووکامرس را در وبسایت خود ببینید، با ما همراه باشید!

چرا API پیش‌فرض ووکامرس همیشه کافی نیست و چه زمانی به یک API سفارشی نیاز پیدا می‌کنیم؟ 🤔

شاید با خودتان فکر کنید: “خب، ووکامرس که خودش یک REST API قدرتمند دارد! چرا باید خودم را به دردسر بیندازم و یکی دیگر بسازم؟” این سوال کاملاً به‌جاست. API داخلی ووکامرس برای انجام کارهای استاندارد مانند خواندن لیست محصولات یا ثبت سفارش فوق‌العاده است، اما کسب‌وکارهای در حال رشد، نیازهای منحصربه‌فردی دارند که در قالب‌های استاندارد نمی‌گنجد.

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

آیا می‌خواهید اطلاعات خاصی را به اپلیکیشن موبایل خود ارسال کنید؟ 📱

فرض کنید در حال ساخت اپلیکیشن موبایل برای فروشگاهتان هستید. API پیش‌فرض ووکامرس می‌تواند لیست محصولات را با تمام جزئیات (قیمت، توضیحات کامل، SKU، وزن و…) برای شما ارسال کند. اما اپلیکیشن شما در صفحه اصلی فقط به “نام محصول”، “تصویر شاخص” و “قیمت” نیاز دارد. ارسال این حجم از اطلاعات اضافی، سرعت بارگذاری اپلیکیشن را به شدت کاهش می‌دهد و تجربه کاربری را خراب می‌کند.

با ساخت Endpoint سفارشی، شما یک نقطه پایانی (Endpoint) جدید ایجاد می‌کنید که دقیقاً و فقط همین سه فیلد را برمی‌گرداند. این کار باعث افزایش سرعت API و بهینه‌سازی عملکرد اپلیکیشن شما می‌شود. علاوه بر این، شاید بخواهید داده‌های ترکیبی ارسال کنید؛ مثلاً لیستی از محصولات پرفروش به همراه آخرین دیدگاه‌های تایید شده برای هر کدام. چنین منطق پیچیده‌ای تنها از طریق یک API سفارشی قابل پیاده‌سازی است.

چگونه می‌توانید فرآیندهای داخلی کسب‌وکارتان را با API خودکار کنید؟ ⚙️

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

برای مثال:

  • اتصال به نرم‌افزار حسابداری: می‌توانید یک API سفارشی بنویسید که به محض ثبت یک سفارش موفق، به صورت خودکار یک فاکتور در نرم‌افزار حسابداری شما ایجاد کند.
  • هماهنگی با انبار: یک Endpoint می‌تواند پس از تغییر وضعیت سفارش به “در حال انجام”، مستقیماً به سیستم انبارداری شما دستور بسته‌بندی کالا را ارسال کند.
  • یکپارچه‌سازی با CRM: می‌توانید اطلاعات مشتریان جدید را به صورت خودکار در نرم‌افزار CRM خود ثبت کرده و برای آن‌ها کمپین‌های بازاریابی هدفمند تعریف کنید.

این خودکارسازی‌ها خطای انسانی را به صفر نزدیک کرده و زمان تیم شما را برای تمرکز بر رشد کسب‌وکار آزاد می‌کند.

آیا امنیت و بهینه‌سازی سرعت برای شما اولویت دارد؟ 🛡️

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

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

“آیا برای تشخیص نیازهای دقیق کسب‌وکارتان و طراحی یک نقشه راه فنی برای API به کمک نیاز دارید؟ همین حالا برای یک جلسه مشاوره رایگان با کارشناسان وردپرس نیاز، تیکت ثبت کنید!“

حالا که به اهمیت و ضرورت یک API سفارشی پی بردیم، شاید این سوال برایتان پیش بیاید که آیا برای این کار حتماً باید یک برنامه‌نویس حرفه‌ای باشم؟ خبر خوب این است که برای شروع، نه! بیایید ببینیم چطور می‌توان اولین قدم را بدون نوشتن حتی یک خط کد برداشت.

چگونه بدون یک خط کدنویسی و با استفاده از افزونه، یک Endpoint ساده بسازیم؟ 🧩

ورود به دنیای API نباید ترسناک باشد! وردپرس به لطف اکوسیستم قدرتمند افزونه‌هایش، به شما اجازه می‌دهد بسیاری از کارهای فنی را بدون نیاز به دانش برنامه‌نویسی انجام دهید. اگر هدف شما ایجاد یک Endpoint ساده برای خواندن اطلاعات از دیتابیس (مثلاً نمایش پست‌های یک دسته‌بندی خاص یا محصولات یک برند) است، استفاده از افزونه یک راهکار سریع، آسان و کارآمد است.

در جدول زیر، یک مقایسه سریع بین روش استفاده از افزونه و کدنویسی سفارشی برای شما نوشتیم تا به شما در انتخاب مسیر درست کمک کند:

ویژگیاستفاده از افزونه (مانند WP REST API Controller)کدنویسی سفارشی (PHP)
سرعت راه‌اندازی🚀 بسیار سریع (چند دقیقه)🕒 متوسط تا طولانی (بسته به پیچیدگی)
نیاز به دانش فنی👩‍💻 پایین (آشنایی با وردپرس کافیست)👨‍💻 بالا (نیازمند تسلط به PHP و API وردپرس)
انعطاف‌پذیری🟠 محدود به امکانات افزونه🟢 نامحدود (هر منطقی قابل پیاده‌سازی است)
عملکرد و بهینه‌سازی🟠 خوب (برای کارهای ساده)🟢 عالی (کنترل کامل روی کوئری‌ها و خروجی)
امنیت🟠 وابسته به کیفیت افزونه🟢 عالی (کنترل کامل روی مجوزهای دسترسی)

همانطور که می‌بینید، افزونه‌ها برای شروع و پروژه‌های کوچک گزینه‌ای عالی هستند. بیایید یکی از بهترین ابزارها در این زمینه را با هم بررسی کنیم.

افزونه WP REST API Controller چیست و چه کمکی به ما می‌کند؟

افزونه WP REST API Controller یک ابزار فوق‌العاده کاربردی است که به شما یک رابط کاربری گرافیکی (UI) برای مدیریت Endpointهای REST API وردپرس می‌دهد. به زبان ساده، این افزونه به شما اجازه می‌دهد بدون نوشتن کد، مشخص کنید که کدام نوع از محتوای سایتتان (نوشته‌ها، برگه‌ها، محصولات و…) از طریق API قابل دسترسی باشند و کدام فیلدها در خروجی JSON نمایش داده شوند. این کار برای ساخت Endpoint سفارشی جهت خواندن داده‌ها ایده‌آل است.

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

راهنمای گام‌به‌گام نصب و راه‌اندازی افزونه WP REST API Controller چگونه است؟

بیایید در کمتر از ۱۰ دقیقه اولین Endpoint خود را بسازیم. این مراحل را دنبال کنید:

  1. نصب و فعال‌سازی افزونه:
    • از پیشخوان وردپرس به بخش افزونه‌ها > افزودن بروید.
    • نام WP REST API Controller را جستجو کرده، آن را نصب و سپس فعال کنید.
  2. پیکربندی اولیه:
    • پس از فعال‌سازی، یک منوی جدید به نام API Controller به پیشخوان شما اضافه می‌شود. روی آن کلیک کنید.
    • شما لیستی از تمام پست‌تایپ‌های موجود در سایتتان (مانند Posts, Pages, Products) را مشاهده خواهید کرد.
  3. ساخت اولین Endpoint برای محصولات:
    • در لیست، تیک گزینه Products را بزنید تا API برای محصولات فعال شود.
    • با زدن این تیک، بلافاصله Endpointهای استاندارد برای خواندن لیست محصولات (GET) و مشاهده یک محصول خاص (GET /<id>) فعال می‌شوند.
  4. سفارشی‌سازی فیلدهای خروجی:
    • روی دکمه Edit در مقابل Products کلیک کنید.
    • در صفحه جدید، شما می‌توانید مشخص کنید کدام فیلدها (مانند title, content, price, featured_image) در خروجی نمایش داده شوند. تیک فیلدهای غیرضروری را بردارید تا خروجی سبک‌تر و سریع‌تر شود.
  5. تست Endpoint:
    • آدرس https://yourdomain.com/wp-json/wp/v2/products را در مرورگر خود باز کنید.
    • شما باید لیستی از محصولات خود را در قالب یک خروجی JSON تمیز و مرتب مشاهده کنید. تبریک می‌گوییم! 🎉

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

چگونه با کدنویسی PHP یک REST API کاملاً سفارشی و حرفه‌ای در ووکامرس ایجاد کنیم؟ 💻

اینجا بخش هیجان‌انگیز ماجراست! جایی که کنترل کامل را به دست می‌گیریم و دقیقاً همان چیزی را می‌سازیم که کسب‌وکارمان به آن نیاز دارد. ساخت REST API سفارشی در ووکامرس با کدنویسی به شما این قدرت را می‌دهد که هر منطقی را پیاده‌سازی کنید؛ از محاسبات پیچیده گرفته تا اتصال به سرویس‌های دیگر.

برای شروع، کافی است قطعه کد زیر را به فایل functions.php قالب فرزند (Child Theme) خود یا یک افزونه سفارشی اضافه کنید. این بهترین روش برای جلوگیری از پاک شدن کدهایتان پس از به‌روزرسانی قالب است.

PHP
وردپرس نیاز 
add_action( 'rest_api_init', function () {
  // کدهای ثبت Endpoint در اینجا قرار می‌گیرند
} );

این هوک (rest_api_init) نقطه شروع کار ماست. وردپرس به ما اطمینان می‌دهد که تمام کدهای داخل این تابع، در زمان صحیح و پس از بارگذاری کامل هسته REST API اجرا می‌شوند. حالا بیایید با پیش‌نیازها و مفاهیم اصلی آشنا شویم.

پیش‌نیازهای کدنویسی یک API سفارشی در وردپرس چیست؟

قبل از نوشتن اولین خط کد، بهتر است با چند مفهوم کلیدی آشنا شوید. نگران نباشید، آن‌ها را به زبان ساده توضیح می‌دهم:

  • هوک (Hook): قلاب‌هایی در وردپرس هستند که به شما اجازه می‌دهند کدهای خود را در نقاط مشخصی از اجرای وردپرس “آویزان” کنید. rest_api_init یک نمونه از این هوک‌هاست.
  • تابع register_rest_route: این مهم‌ترین تابع در آموزش rest api وردپرس است. با استفاده از این تابع، شما یک مسیر (URL)، متدهای قابل قبول (GET, POST, etc.) و تابع پاسخگو را برای Endpoint جدید خود ثبت می‌کنید.
  • فضای نام (Namespace): یک پیشوند برای URL شماست که از تداخل Endpoint شما با Endpointهای دیگر وردپرس یا افزونه‌ها جلوگیری می‌کند. مثلاً my-app/v1.
  • پاسخ JSON: فرمت استاندارد تبادل داده در وب است. خروجی API شما باید به صورت JSON باشد تا اپلیکیشن‌ها و نرم‌افزارها بتوانند به راحتی آن را بخوانند. وردپرس این کار را به صورت خودکار برای شما مدیریت می‌کند.

با دانستن این مفاهیم، شما برای برداشتن قدم بعدی و ساخت اولین Endpoint کاملاً آماده‌اید.

چگونه اولین Endpoint سفارشی خود را با تابع register_rest_route ثبت کنیم؟

بیایید یک مثال کاربردی را با هم پیاده‌سازی کنیم: ایجاد یک Endpoint برای نمایش لیست محصولات ویژه (Featured Products) ووکامرس. این قابلیتی است که در اپلیکیشن‌های موبایل بسیار پرکاربرد است.

کد زیر را در هوک rest_api_init که بالاتر معرفی کردیم، قرار دهید:

PHP
وردپرس نیاز 
// فایل functions.php
add_action( 'rest_api_init', 'register_featured_products_route' );

function register_featured_products_route() {
    register_rest_route( 'my-store/v1', '/featured-products', array(
        'methods'  => 'GET', // متد درخواست (فقط خواندن)
        'callback' => 'get_featured_products_callback', // تابعی که پاسخ را تولید می‌کند
        'permission_callback' => '__return_true', // موقتاً دسترسی برای همه باز است
    ) );
}

function get_featured_products_callback( $request ) {
    // اجرای کوئری برای دریافت محصولات ویژه
    $args = array(
        'post_type'      => 'product',
        'posts_per_page' => 10,
        'tax_query'      => array(
            array(
                'taxonomy' => 'product_visibility',
                'field'    => 'name',
                'terms'    => 'featured',
            ),
        ),
    );

    $query = new WP_Query( $args );

    if ( !$query->have_posts() ) {
        return new WP_Error( 'no_products_found', 'هیچ محصول ویژه‌ای یافت نشد.', array( 'status' => 404 ) );
    }

    $products_data = array();
    foreach ( $query->get_posts() as $post ) {
        $product = wc_get_product( $post->ID );
        $products_data[] = array(
            'id'    => $product->get_id(),
            'name'  => $product->get_name(),
            'price' => $product->get_price(),
            'image' => wp_get_attachment_url( $product->get_image_id() ),
        );
    }

    // بازگرداندن پاسخ موفقیت آمیز
    return new WP_REST_Response( $products_data, 200 );
}

تحلیل کد:

  1. register_rest_route: ما یک مسیر جدید با آدرس /my-store/v1/featured-products ثبت کردیم که فقط به درخواست‌های GET پاسخ می‌دهد.
  2. get_featured_products_callback: این تابع قلب تپنده Endpoint ماست. ما با استفاده از WP_Query، محصولاتی که به عنوان “ویژه” علامت‌گذاری شده‌اند را پیدا می‌کنیم.
  3. فرمت‌بندی خروجی: به جای ارسال تمام اطلاعات محصول، ما فقط فیلدهای ضروری (ID, نام, قیمت و تصویر) را در یک آرایه تمیز و بهینه قرار می‌دهیم.
  4. WP_REST_Response: در نهایت، داده‌های آماده شده را به همراه کد وضعیت HTTP 200 (موفقیت‌آمیز) برمی‌گردانیم. این بهترین روش برای ارسال پاسخ در REST API وردپرس است.

حالا با فراخوانی آدرس https://yourdomain.com/wp-json/my-store/v1/featured-products می‌توانید خروجی را مشاهده کنید.

H3: چطور می‌توانیم پارامترهای ورودی را دریافت و اعتبارسنجی (Validation) کنیم؟

یک API قدرتمند باید بتواند ورودی دریافت کند. برای مثال، شاید بخواهیم به کاربر اجازه دهیم تعداد محصولات ویژه را خودش تعیین کند. برای این کار، می‌توانیم پارامتر count را به Endpoint خود اضافه کنیم.

ابتدا register_rest_route را به شکل زیر تغییر می‌دهیم:

PHP
وردپرس نیاز 
register_rest_route( 'my-store/v1', '/featured-products', array(
    'methods'  => 'GET',
    'callback' => 'get_featured_products_callback',
    'args'     => array(
        'count' => array(
            'validate_callback' => function($param, $request, $key) {
                return is_numeric( $param ) && $param > 0; // باید یک عدد مثبت باشد
            },
            'sanitize_callback' => 'absint', // تبدیل به عدد صحیح مثبت
            'default'           => 5, // مقدار پیش‌فرض
        ),
    ),
    'permission_callback' => '__return_true',
) );

و سپس در تابع get_featured_products_callback، این پارامتر را دریافت و استفاده می‌کنیم:

PHP
وردپرس نیاز 
function get_featured_products_callback( $request ) {
    $count = $request->get_param('count'); // دریافت پارامتر count

    $args = array(
        'post_type'      => 'product',
        'posts_per_page' => $count, // استفاده از پارامتر در کوئری
        // ... بقیه کوئری
    );
    // ...
}

validate_callback تضمین می‌کند که ورودی کاربر معتبر است (در اینجا یک عدد مثبت) و از اجرای کوئری با مقادیر مخرب جلوگیری می‌کند. این یک لایه امنیتی حیاتی است. حالا کاربر می‌تواند با آدرس .../featured-products?count=3 تعداد محصولات را مشخص کند.

بهترین روش برای احراز هویت (Authentication) در API سفارشی چیست؟

تا اینجا، Endpoint ما عمومی بود (permission_callback => '__return_true'). اما اکثر APIها نیاز به احراز هویت دارند تا فقط کاربران مجاز به داده‌ها دسترسی داشته باشند. در اینجا دو روش رایج را بررسی می‌کنیم:

  1. کلیدهای API ووکامرس (API Keys):
    • روش کار: ووکامرس به شما اجازه می‌دهد در پیشخوان کلیدهای Consumer Key و Consumer Secret بسازید. این کلیدها باید در هدر هر درخواست ارسال شوند.
    • مزایا: امن، استاندارد و به راحتی با سیستم ووکامرس یکپارچه می‌شود.
    • معایب: برای احراز هویت هر کاربر به صورت مجزا مناسب نیست و بیشتر برای ارتباط سرور-به-سرور کاربرد دارد.
    • پیاده‌سازی: برای استفاده از این روش، کافی است permission_callback را به function() { return current_user_can('read_private_products'); } تغییر دهید. ووکامرس به طور خودکار کلیدهای ارسالی را بررسی و کاربر مربوطه را شناسایی می‌کند.
  2. توکن JWT (JSON Web Tokens):
    • روش کار: این روش مدرن‌تر است و برای اپلیکیشن‌های موبایل ایده‌آل است. کاربر با نام کاربری و رمز عبور خود یک توکن دریافت می‌کند و سپس آن توکن را در هدر درخواست‌های بعدی ارسال می‌کند.
    • مزایا: بدون حالت (Stateless)، امن و مناسب برای احراز هویت کاربران نهایی.
    • معایب: نیاز به نصب یک افزونه جانبی مانند JWT Authentication for WP REST API دارد.
    • پیاده‌سازی: پس از نصب افزونه JWT، یک Endpoint برای لاگین و دریافت توکن خواهید داشت. سپس در permission_callback می‌توانید اعتبار توکن را بررسی کنید.

انتخاب روش احراز هویت به کاربرد API شما بستگی دارد، اما برای توسعه API برای اپلیکیشن موبایل، روش JWT به شدت توصیه می‌شود.

“کدنویسی API پیچیده به نظر می‌رسد؟ نگران نباشید! تیم متخصص وردپرس نیاز می‌تواند توسعه API سفارشی ووکامرس شما را از صفر تا صد، با رعایت بالاترین استانداردهای امنیتی و عملکردی، بر عهده بگیرد.“

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

چطور خطاهای رایج REST API در وردپرس و ووکامرس را شناسایی و رفع کنیم؟ 🛠️

هیچ توسعه‌ای بدون مواجهه با خطا کامل نمی‌شود. در دنیای REST API وردپرس نیز با پیام‌ها و مشکلات گیج‌کننده‌ای روبرو خواهید شد. مهم این است که بدانید از کجا شروع به عیب‌یابی کنید. در این بخش، ما یک جعبه ابزار عملی برای رفع خطای rest api در وردپرس در اختیار شما قرار می‌دهیم تا بتوانید مانند یک کارآگاه حرفه‌ای، ریشه مشکل را پیدا و آن را حل کنید.

چرا با خطای “REST API encountered an error” مواجه می‌شویم؟

این خطا یکی از عمومی‌ترین و در عین حال آزاردهنده‌ترین خطاهای وردپرس است. این پیام مانند چراغ “چک موتور” ماشین است؛ به شما می‌گوید مشکلی وجود دارد، اما نمی‌گوید مشکل دقیقاً چیست! این خطا می‌تواند به دلایل مختلفی رخ دهد. برای عیب‌یابی، این چک‌لیست را قدم به قدم دنبال کنید:

  1. ابزار سلامت سایت (Site Health Tool):
    • به بخش ابزارها > سلامت سایت در پیشخوان وردپرس بروید.
    • در تب “وضعیت”، به دنبال هرگونه خطای بحرانی (Critical issue) بگردید. وردپرس اغلب در این بخش اطلاعات دقیق‌تری درباره منشأ خطا (مثلاً یک خطای PHP در یک افزونه خاص) به شما می‌دهد.
  2. بررسی تداخل افزونه‌ها:
    • این شایع‌ترین دلیل است. یک افزونه با کدنویسی ضعیف می‌تواند کل REST API را از کار بیندازد.
    • راه‌حل: تمام افزونه‌ها را غیرفعال کنید و سپس API خود را تست کنید. اگر مشکل حل شد، افزونه‌ها را یکی‌یکی فعال کنید و پس از فعال‌سازی هرکدام، API را مجدداً تست کنید تا افزونه مخرب را پیدا کنید.
  3. بررسی فایل .htaccess:
    • گاهی اوقات تنظیمات نادرست در این فایل می‌تواند جلوی مسیرهای API (/wp-json/) را بگیرد.
    • راه‌حل: از طریق FTP یا مدیریت فایل هاست، نام فایل .htaccess را موقتاً به .htaccess_old تغییر دهید. سپس به تنظیمات > پیوندهای یکتا در پیشخوان وردپرس بروید و بدون هیچ تغییری، روی دکمه “ذخیره تغییرات” کلیک کنید تا وردپرس یک فایل .htaccess جدید و سالم بسازد.
  4. فعال کردن حالت اشکال‌زدایی (Debug Mode):
    • اگر مراحل بالا جواب نداد، حالت دیباگ وردپرس را فعال کنید. فایل wp-config.php را باز کرده و مقدار WP_DEBUG را به true تغییر دهید: define( 'WP_DEBUG', true );
    • حالا دوباره API را فراخوانی کنید. این بار به جای پیام خطای عمومی، پیام دقیق‌تری از خطای PHP دریافت خواهید کرد که به شما در یافتن مشکل کمک می‌کند.

افزونه WooCommerce Legacy REST API چیست و آیا هنوز به آن نیاز داریم؟

شاید در حین جستجو، با نام افزونه legacy rest api برخورد کرده باشید. این افزونه برای حفظ سازگاری با نسخه‌های بسیار قدیمی ووکامرس (قبل از نسخه ۲.۶) که از یک ساختار API متفاوت استفاده می‌کردند، طراحی شده بود. آدرس‌های این API قدیمی با /wc-api/v3/ شروع می‌شد.

آیا امروز به آن نیاز دارید؟ در ۹۹.۹ درصد موارد، خیر. REST API مدرن ووکامرس که با /wp-json/wc/v3/ شروع می‌شود، بسیار قدرتمندتر، امن‌تر و استانداردتر است. نصب افزونه Legacy فقط در صورتی منطقی است که شما از یک نرم‌افزار یا سرویس بسیار قدیمی استفاده می‌کنید که هنوز برای اتصال به ووکامرس، به آن API منسوخ شده وابسته است. برای تمام پروژه‌های جدید، باید به طور کامل از این افزونه دوری کنید.

چگونه مشکلات مربوط به CORS و دسترسی از دامنه‌های دیگر را حل کنیم؟

این یک مشکل بسیار رایج برای توسعه‌دهندگان فرانت‌اند است. فرض کنید شما یک وب‌اپلیکیشن با React یا Vue روی دامنه app.mydomain.com ساخته‌اید و می‌خواهید به API وردپرس خود در mydomain.com متصل شوید. مرورگر به دلایل امنیتی (تحت سیاستی به نام Cross-Origin Resource Sharing یا CORS)، این درخواست را مسدود می‌کند.

برای حل این مشکل، باید به وردپرس بگویید که دریافت درخواست از دامنه اپلیکیشن شما مجاز است. این کار با افزودن هدرهای HTTP خاصی به پاسخ API انجام می‌شود. کد زیر را به فایل functions.php خود اضافه کنید:

PHP
وردپرس نیاز 
function add_cors_headers() {
    // فقط به دامنه اپلیکیشن خود اجازه دهید
    header("Access-Control-Allow-Origin: https://app.mydomain.com"); 
    header("Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE");
    header("Access-Control-Allow-Headers: Content-Type, Authorization");
}

add_action('rest_api_init', function() {
    // این هدرها را به تمام پاسخ های API اضافه کن
    add_action('rest_pre_serve_request', 'add_cors_headers');
});

نکته مهم: هرگز از * به جای آدرس دامنه (Access-Control-Allow-Origin: *) استفاده نکنید، مگر اینکه API شما کاملاً عمومی باشد. این کار درب سایت شما را به روی هر دامنه‌ای باز می‌کند و یک حفره امنیتی بزرگ ایجاد می‌کند.

با حل این چالش‌های رایج، شما برای ساخت APIهای پایدار و قابل اعتماد آماده‌اید. اما تئوری کافیست! بیایید با دو مثال کاملاً واقعی، تمام این مفاهیم را در عمل ببینیم.

دو مثال پروژه محور واقعی از ساخت API سفارشی در وردپرس و ووکامرس 💡

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

مثال اول: ساخت Endpoint برای “محصولات مرتبط هوشمند” در اپلیکیشن موبایل

صورت مسئله: قابلیت “محصولات مرتبط” پیش‌فرض ووکامرس، گاهی نتایج خوبی ارائه نمی‌دهد. ما می‌خواهیم یک Endpoint بسازیم که وقتی ID یک محصول را دریافت می‌کند، لیستی از محصولاتی را برگرداند که در همان دسته بندی اصلی قرار دارند، اما خود محصول ورودی را شامل نشود. این قابلیت برای بخش “شاید این‌ها را هم بپسندید” در اپلیکیشن عالی است.

کد کامل:

PHP
وردپرس نیاز 
// فایل functions.php
add_action( 'rest_api_init', 'register_smart_related_products_route' );

function register_smart_related_products_route() {
    register_rest_route( 'my-store/v1', '/products/(?P<id>\d+)/related-smart', array(
        'methods'  => 'GET',
        'callback' => 'get_smart_related_products',
        'args'     => array(
            'id' => array(
                'validate_callback' => function($param, $request, $key) {
                    return is_numeric($param);
                },
                'required' => true,
            ),
        ),
        'permission_callback' => '__return_true', // برای نمایش عمومی
    ) );
}

function get_smart_related_products( $request ) {
    $product_id = (int) $request['id'];
    $product = wc_get_product( $product_id );

    if ( ! $product ) {
        return new WP_Error( 'product_not_found', 'محصولی با این شناسه یافت نشد.', array( 'status' => 404 ) );
    }

    // دریافت دسته‌بندی‌های محصول
    $category_ids = $product->get_category_ids();
    if ( empty($category_ids) ) {
        return new WP_Error( 'no_categories', 'محصول در هیچ دسته‌بندی قرار ندارد.', array( 'status' => 404 ) );
    }

    // کوئری برای محصولات هم‌دسته
    $args = array(
        'post_type'      => 'product',
        'posts_per_page' => 5,
        'post__not_in'   => array( $product_id ), // حذف خود محصول از نتایج
        'tax_query'      => array(
            array(
                'taxonomy' => 'product_cat',
                'field'    => 'term_id',
                'terms'    => $category_ids,
            ),
        ),
    );

    $related_query = new WP_Query( $args );

    if ( !$related_query->have_posts() ) {
        return new WP_REST_Response( array(), 200 ); // اگر محصول مرتبطی نبود، آرایه خالی برگردان
    }

    $related_products_data = array();
    foreach ( $related_query->posts as $related_post ) {
        $related_product = wc_get_product( $related_post->ID );
        $related_products_data[] = array(
            'id'    => $related_product->get_id(),
            'name'  => $related_product->get_name(),
            'price' => $related_product->get_price_html(),
            'image' => wp_get_attachment_url( $related_product->get_image_id() ),
        );
    }

    return new WP_REST_Response( $related_products_data, 200 );
}

نحوه تست: اگر محصولی با شناسه 123 دارید، کافیست آدرس زیر را فراخوانی کنید: https://yourdomain.com/wp-json/my-store/v1/products/123/related-smart

خروجی JSON نمونه:

JSON
وردپرس نیاز 
[
  {
    "id": 456,
    "name": "محصول هم‌دسته ۱",
    "price": "<span class=\"woocommerce-Price-amount amount\"><bdi>50,000&nbsp;<span class=\"woocommerce-Price-currencySymbol\">تومان</span></bdi></span>",
    "image": "https://yourdomain.com/wp-content/uploads/2025/10/product-image.jpg"
  },
  {
    "id": 789,
    "name": "محصول هم‌دسته ۲",
    "price": "<span class=\"woocommerce-Price-amount amount\"><bdi>75,000&nbsp;<span class=\"woocommerce-Price-currencySymbol\">تومان</span></bdi></span>",
    "image": "https://yourdomain.com/wp-content/uploads/2025/10/product-image-2.jpg"
  }
]

مثال دوم: ساخت API برای افزودن محصول به علاقه‌مندی‌ها (بدون افزونه)

صورت مسئله: می‌خواهیم به کاربران لاگین کرده اجازه دهیم محصولات را به لیست علاقه‌مندی‌های شخصی خود اضافه کنند. این اطلاعات در user_meta (داده‌های اضافی کاربر) ذخیره می‌شود. این یک قابلیت کلیدی برای شخصی‌سازی تجربه خرید در اپلیکیشن است.

کد کامل:

PHP
وردپرس نیاز 
// فایل functions.php
add_action( 'rest_api_init', 'register_wishlist_routes' );

function register_wishlist_routes() {
    // Endpoint برای افزودن به علاقه‌مندی‌ها
    register_rest_route( 'my-store/v1', '/wishlist/add', array(
        'methods'  => 'POST', // چون در حال تغییر داده هستیم
        'callback' => 'add_to_wishlist_callback',
        'permission_callback' => function() {
            return is_user_logged_in(); // فقط برای کاربران لاگین کرده
        },
        'args' => array(
            'product_id' => array(
                'required' => true,
                'validate_callback' => function($param) {
                    return is_numeric($param) && wc_get_product($param); // باید محصول معتبر باشد
                }
            )
        )
    ) );

    // Endpoint برای مشاهده لیست علاقه‌مندی‌ها
    register_rest_route( 'my-store/v1', '/wishlist', array(
        'methods'  => 'GET',
        'callback' => 'get_wishlist_callback',
        'permission_callback' => function() {
            return is_user_logged_in(); // فقط برای کاربران لاگین کرده
        }
    ) );
}

// تابع افزودن محصول به لیست
function add_to_wishlist_callback( $request ) {
    $user_id = get_current_user_id();
    $product_id = (int) $request['product_id'];

    // دریافت لیست علاقه‌مندی‌های فعلی کاربر
    $wishlist = get_user_meta( $user_id, '_user_wishlist', true );
    if ( !is_array($wishlist) ) {
        $wishlist = array();
    }

    // اگر محصول از قبل در لیست نیست، آن را اضافه کن
    if ( !in_array($product_id, $wishlist) ) {
        $wishlist[] = $product_id;
        update_user_meta( $user_id, '_user_wishlist', $wishlist );
        return new WP_REST_Response( array('status' => 'success', 'message' => 'محصول به علاقه‌مندی‌ها اضافه شد.'), 200 );
    } else {
        return new WP_REST_Response( array('status' => 'exists', 'message' => 'این محصول از قبل در لیست شما وجود دارد.'), 200 );
    }
}

// تابع نمایش لیست
function get_wishlist_callback() {
    $user_id = get_current_user_id();
    $wishlist_ids = get_user_meta( $user_id, '_user_wishlist', true );

    if ( empty($wishlist_ids) || !is_array($wishlist_ids) ) {
        return new WP_REST_Response( array(), 200 );
    }

    $wishlist_products = array();
    foreach($wishlist_ids as $product_id) {
        $product = wc_get_product($product_id);
        if ($product) {
            $wishlist_products[] = array(
                'id' => $product->get_id(),
                'name' => $product->get_name(),
                'price' => $product->get_price(),
                'image' => wp_get_attachment_url( $product->get_image_id() ),
            );
        }
    }
    return new WP_REST_Response( $wishlist_products, 200 );
}

نحوه تست:

  • ابتدا باید احراز هویت شوید (مثلاً با افزونه JWT یا لاگین در وردپرس و استفاده از کوکی).
  • یک درخواست POST به آدرس https://yourdomain.com/wp-json/my-store/v1/wishlist/add با بدنه {"product_id": 123} ارسال کنید.
  • یک درخواست GET به https://yourdomain.com/wp-json/my-store/v1/wishlist ارسال کنید تا لیست کامل را ببینید.

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

پرسش‌های متداول درباره توسعه API در ووکامرس ❓

در این بخش به سوالاتی پاسخ می‌دهیم که اغلب برای کاربران در حین کار با REST API وردپرس و ووکامرس پیش می‌آید. این پاسخ‌ها به شما کمک می‌کنند تا درک عمیق‌تری از این تکنولوژی پیدا کنید و با اطمینان بیشتری پروژه‌های خود را پیش ببرید.

تفاوت اصلی بین REST API وردپرس و REST API ووکامرس چیست؟

این یک سوال بسیار مهم است. این دو API با هم کار می‌کنند اما اهداف متفاوتی دارند:

  • REST API وردپرس (WordPress Core API): این API هسته اصلی است و برای مدیریت محتوای عمومی سایت طراحی شده است. با استفاده از آن می‌توانید به نوشته‌ها، برگه‌ها، دسته‌بندی‌ها، کاربران، دیدگاه‌ها و رسانه‌ها دسترسی داشته باشید. آدرس‌های آن معمولاً با /wp-json/wp/v2/ شروع می‌شود.
  • REST API ووکامرس (WooCommerce API): این API به عنوان یک لایه تخصصی روی API وردپرس ساخته شده و به طور انحصاری برای مدیریت داده‌های فروشگاهی است. از طریق آن می‌توانید محصولات، سفارش‌ها، مشتریان، کوپن‌های تخفیف و گزارشات فروش را مدیریت کنید. آدرس‌های آن معمولاً با /wp-json/wc/v3/ شروع می‌شود. به زبان ساده، اگر با بلاگ و محتوای سایت کار دارید، از API وردپرس استفاده می‌کنید. اگر با فروشگاه و عملیات تجارت الکترونیک سر و کار دارید، API ووکامرس ابزار شماست.

آیا برای استفاده از API ووکامرس حتماً باید SSL (HTTPS) داشته باشیم؟

بله، حتماً و مطلقاً. ووکامرس برای حفظ امنیت داده‌های حساس فروشگاه شما (مانند اطلاعات مشتریان و سفارش‌ها)، استفاده از کلیدهای API را فقط روی یک ارتباط امن و رمزنگاری شده (HTTPS) مجاز می‌داند. اگر سایت شما SSL نداشته باشد، در هنگام تلاش برای ارسال درخواست‌های احراز هویت شده با خطای 401 (Unauthorized) مواجه خواهید شد. این یک محدودیت نیست، بلکه یک ویژگی امنیتی ضروری است. امروزه دریافت گواهینامه SSL رایگان (مانند Let’s Encrypt) بسیار آسان است و هیچ بهانه‌ای برای نداشتن آن وجود ندارد.

چگونه می‌توانم خروجی API را به جای JSON در فرمت دیگری دریافت کنم؟

REST API وردپرس به طور ذاتی و بر اساس استانداردهای وب، برای استفاده از فرمت JSON (JavaScript Object Notation) طراحی شده است. JSON بسیار سبک، خوانا و به راحتی توسط تمام زبان‌های برنامه‌نویسی مدرن قابل پردازش است. از نظر فنی، با کدنویسی سفارشی و تغییر هدرهای پاسخ، امکان ارسال داده در فرمت‌های دیگر مانند XML وجود دارد، اما این کار به هیچ عنوان توصیه نمی‌شود. این کار شما را از استانداردهای وب دور می‌کند، پیچیدگی‌های غیرضروری ایجاد می‌کند و تقریباً هیچ مزیتی نسبت به JSON ندارد. پس بهتر است به این استاندارد پایبند بمانید.

آیا می‌توانم دسترسی به Endpointهای خاصی را محدود به نقش‌های کاربری خاص کنم؟

بله، این یکی از قدرتمندترین ویژگی‌های ساخت API سفارشی است. همانطور که در بخش کدنویسی دیدیم، پارامتر permission_callback در تابع register_rest_route دقیقاً برای همین منظور طراحی شده است. این تابع باید true یا false برگرداند. شما می‌توانید در این تابع هر منطقی را پیاده‌سازی کنید. برای مثال، برای محدود کردن دسترسی به مدیران فروشگاه:

PHP
وردپرس نیاز 
'permission_callback' => function() {
    return current_user_can('manage_woocommerce');
}

در اینجا، manage_woocommerce یکی از قابلیت‌های (Capabilities) وردپرس است. شما می‌توانید بر اساس نقش‌های کاربری (shop_manager, administrator) یا هر شرط دیگری، دسترسی را کنترل کنید. این کار به شما اجازه می‌دهد APIهای مختلف با سطوح دسترسی متفاوت برای تیم‌های مختلف سازمانتان (فروش، بازاریابی، انبارداری) ایجاد کنید.

بهترین ابزار برای تست کردن Endpointهای API چیست؟

تست کردن API مستقیماً در مرورگر فقط برای درخواست‌های ساده GET که نیاز به احراز هویت ندارند، امکان‌پذیر است. برای تست حرفه‌ای درخواست‌های POST, PUT, DELETE و ارسال هدرهای سفارشی (مانند توکن احراز هویت)، شما به یک ابزار تخصصی نیاز دارید.

دو مورد از محبوب‌ترین و قدرتمندترین ابزارها در این زمینه عبارتند از:

  • Postman: این نرم‌افزار یک استاندارد صنعتی برای توسعه و تست API است. با رابط کاربری گرافیکی آن می‌توانید انواع درخواست‌ها را بسازید، هدرها و بدنه درخواست را تنظیم کنید، متغیرهای محیطی تعریف کنید و پاسخ‌های دریافتی را به شکلی زیبا و خوانا مشاهده کنید.
  • Insomnia: یک جایگزین عالی و سبک‌تر برای Postman است که بسیاری از توسعه‌دهندگان به دلیل سادگی و سرعت بالاتر، آن را ترجیح می‌دهند.

استفاده از این ابزارها در فرآیند توسعه API برای اپلیکیشن یا هر پروژه دیگری، نه تنها یک گزینه، بلکه یک ضرورت است و سرعت و دقت کار شما را به شدت افزایش می‌دهد.

تصویر امین زاهد
امین زاهد
پیشنهاد میکنیم این مقالات را هم بخوانید
لیست کامل پرامپت‌های سئو ۲۰۲۵: تولید محتوای فروشگاهی با هوش مصنوعی

سئو فروشگاهی با هوش مصنوعی: تولید محتوای فروشگاهی با هوش مصنوعی

  • امین زاهد
  • 9 دقیقه
  • 0
ادامه مطلب
تجربه کاربری (UX) چیست و چگونه می‌تواند یک بازدیدکننده کنجکاو را به مشتری وفادار در فروشگاه ووکامرس شما تبدیل کند؟

تجربه کاربری (UX) چیست و چگونه می‌تواند یک بازدیدکننده کنجکاو را به مشتری وفادار در فروشگاه ووکامرس شما تبدیل کند؟

  • امین زاهد
  • 16 دقیقه
  • 0
ادامه مطلب
نرخ تبدیل (CRO) چیست و چگونه می‌تواند درآمد فروشگاه ووکامرس شما را بدون افزایش ترافیک، دو برابر کند؟

نرخ تبدیل (CRO) چیست و چگونه می‌تواند درآمد فروشگاه ووکامرس شما را بدون افزایش ترافیک، دو برابر کند؟

  • امین زاهد
  • 16 دقیقه
  • 0
ادامه مطلب
قیف فروش چیست؟ آموزش کامل ساخت Sales Funnel در ووکامرس

قیف فروش چیست و چگونه یک مسیر خودکار برای تبدیل بازدیدکننده به مشتری وفادار در ووکامرس بسازیم؟

  • امین زاهد
  • 12 دقیقه
  • 0
ادامه مطلب
لندینگ پیج چیست و چرا هر فروشگاه اینترنتی ووکامرس به آن نیاز دارد؟

لندینگ پیج چیست و چرا هر فروشگاه اینترنتی ووکامرس به آن نیاز دارد؟ معرفی انواع لندینگ پیج

  • امین زاهد
  • 9 دقیقه
  • 0
ادامه مطلب
چگونه با هوش مصنوعی کپی‌رایت انواع تبلیغات (بیلبورد، لندینگ پیج، گوگل ادز، یکتانت) بنویسیم؟

چگونه با هوش مصنوعی کپی‌رایت انواع تبلیغات (بیلبورد، لندینگ پیج، گوگل ادز، یکتانت) بنویسیم؟

  • امین زاهد
  • 21 دقیقه
  • 0
ادامه مطلب
چگونه تایتل و H1 صفحات دسته‌بندی را با پرامپت‌های هوش مصنوعی به آهنربای کلیک تبدیل کنیم؟

چگونه تایتل و H1 صفحات دسته‌بندی را با پرامپت‌های هوش مصنوعی به آهنربای کلیک تبدیل کنیم؟

  • امین زاهد
  • 9 دقیقه
  • 0
ادامه مطلب
چگونه با هوش مصنوعی یک سیستم پیشنهاد محصول در وردپرس طراحی کنیم و فروش خود را متحول سازیم؟

چگونه با هوش مصنوعی یک سیستم پیشنهاد محصول در وردپرس طراحی کنیم و فروش خود را متحول سازیم؟

  • امین زاهد
  • 17 دقیقه
  • 0
ادامه مطلب

دیدگاهتان را بنویسید