كيفية إنشاء ملف Excel يسحب بيانات العملاء من WooCommerce باستخدام Python

لماذا قد تحتاج إلى تصدير بيانات عملاء WooCommerce إلى Excel؟

في كثير من فرق التجارة الإلكترونية، يتكرر طلب قسم التسويق بالحصول على بيانات العملاء بسرعة، خصوصاً عند الاستعداد لإطلاق حملة بريدية أو إعداد قائمة تواصل مخصصة. وغالباً ما تكون البيانات المطلوبة بسيطة وواضحة، مثل الاسم الأول والبريد الإلكتروني، لكن التحدي الحقيقي يكمن في استخراجها بصيغة مناسبة وسهلة التعديل.

في هذه الحالة، كان المطلوب إنشاء ملف Excel يحتوي على بيانات العملاء المسجلين في متجر يعمل عبر WooCommerce. ورغم أن WooCommerce يوفّر خيارات تصدير افتراضية، إلا أن الحصول على ملف Excel جاهز للاستخدام المباشر ليس دائماً الخيار المتاح بشكل افتراضي.

فهم المشكلة: لماذا لا يكفي التصدير الافتراضي في WooCommerce؟

يوفر WooCommerce إمكانية تصدير بيانات العملاء، لكنه يعتمد غالباً على صيغ مثل CSV أو XML. وهذه الصيغ مفيدة تقنياً، لكنها قد لا تكون الأنسب لبعض الفرق التشغيلية التي تحتاج إلى ملف Excel قابل للمراجعة والتعديل قبل استخدامه في حملة تسويقية.

عند البحث عن حل، تظهر عادة ثلاثة مسارات رئيسية:

• استخدام إضافة WordPress: خيار سريع نظرياً، لكنه يفتح باباً لتكاليف الصيانة، ومراجعات الأمان، ومشكلات التوافق.
• تحويل CSV إلى Excel عبر خدمات خارجية: قد يبدو عملياً، لكنه يثير مخاوف تتعلق بالخصوصية وأمن البيانات.
• بناء Script مخصص: وهو الخيار الأكثر مرونة وتحكماً، خصوصاً عندما تكون لديك واجهات API موثقة جيداً.

لهذا السبب، كان الحل الأفضل هو الاعتماد على WooCommerce REST API مع Python لإنشاء ملف Excel مخصص يحتوي على عمودين فقط:

• الاسم الأول
• البريد الإلكتروني

لماذا تم اختيار Python لهذا النوع من المهام؟

تُعد Python من أفضل الخيارات عند التعامل مع البيانات، لعدة أسباب عملية:

• توفر مكتبات قوية للتعامل مع APIs والملفات.
• سهولة كتابة Script قصير وفعال.
• مرونة عالية في معالجة JSON وتحويله إلى صيغ أخرى.
• تكامل ممتاز مع مكتبات مثل Pandas وOpenpyxl.

وبالاعتماد على هذه الأدوات، يمكن تنفيذ المهمة بالكامل خلال عدد قليل من الأسطر البرمجية، مع قابلية التوسع لاحقاً لإنشاء تقارير دورية أو مهام تلقائية.

الحصول على مفاتيح WooCommerce API قبل البدء

قبل كتابة الكود، يجب إنشاء مفاتيح الوصول إلى WooCommerce API. هذه المفاتيح تتيح للـ Script الاتصال بالمتجر وسحب بيانات العملاء بطريقة آمنة ومنظمة.

لإنشاء المفاتيح، سجّل الدخول إلى لوحة تحكم WooCommerce ثم انتقل إلى:

• WooCommerce
• Settings
• Advanced
• REST API

بعد ذلك، أضف وصفاً مناسباً للمفتاح، وحدد المستخدم المرتبط به، ثم اختر الصلاحيات المناسبة مثل Read أو Read/Write، وبعدها اضغط على Generate API key.

عند الإنشاء، ستحصل على قيمتين أساسيتين:

• Consumer Key
• Consumer Secret

تجهيز بيئة العمل في Python

لبناء هذا الحل، ستحتاج إلى تثبيت ثلاث مكتبات أساسية:

1) تثبيت مكتبة WooCommerce لـ Python

pip install woocommerce

2) تثبيت مكتبة Pandas لمعالجة البيانات

pip install pandas

3) تثبيت مكتبة Openpyxl للتعامل مع ملفات Excel

pip install openpyxl

هذا المزيج يمنحك كل ما تحتاج إليه: الاتصال بالـ API، قراءة البيانات، ثم تصديرها إلى ملف Excel بصيغة منظمة.

خطوات إنشاء ملف Excel من بيانات العملاء

الاتصال بواجهة WooCommerce API

في البداية، نستخدم الدالة API من مكتبة WooCommerce لتهيئة الاتصال بالمتجر. ستحتاج إلى تمرير رابط المتجر الأساسي، بالإضافة إلى Consumer Key وConsumer Secret وإصدار الـ API.

wcdata = API(
    url='<BASE_URL>',
    consumer_key='ck_XXXXXXXXXXXXXXXXXXXX',
    consumer_secret='cs_XXXXXXXXXXXXXXXXXXXX',
    version='wc/v3'
)

سحب بيانات العملاء من endpoint الخاص بالعملاء

بعد تهيئة الاتصال، يمكن استدعاء endpoint باسم customers باستخدام طلب GET. ثم نحفظ البيانات الناتجة في ملف JSON محلي ليسهل التعامل معها لاحقاً.

newJson = wcdata.get('customers').json()

with open('contacts.json', 'w') as f:
    json.dump(newJson, f, ensure_ascii=False, indent=4)

هذه الخطوة مفيدة إذا كنت ترغب في فحص البيانات الخام أو الاحتفاظ بنسخة وسيطة قبل تحويلها إلى Excel.

تحويل JSON إلى DataFrame باستخدام Pandas

الآن نقرأ ملف JSON داخل كائن DataFrame، وهو الهيكل الذي توفّره مكتبة Pandas لمعالجة البيانات بكفاءة.

df_json = pd.read_json('contacts.json')

تصدير البيانات إلى ملف Excel

في الخطوة الأخيرة، نستخدم الدالة to_excel() لإنشاء ملف Excel يحتوي فقط على الأعمدة المهمة، وهي first_name وemail. كما نوقف طباعة الفهرس لأننا لا نحتاج إلى معرف السجل داخل الملف النهائي.

df_json.to_excel(
    'customers_contacts.xlsx',
    index=False,
    columns=('first_name', 'email')
)

النتيجة النهائية

بعد تشغيل الـ Script، ستحصل على ملف customers_contacts.xlsx جاهز للمشاركة مع فريق التسويق أو أي قسم آخر يحتاج إلى بيانات العملاء بصيغة سهلة القراءة والتعديل.

اللافت في هذا الحل أنه بسيط وعملي، ويمكن تنفيذه بأقل من 20 سطراً برمجياً تقريباً، مع إمكانية تطويره لاحقاً ليشمل خصائص إضافية مثل:

• إضافة أعمدة أخرى مثل last_name أو date_created.
• تصفية العملاء حسب الدولة أو تاريخ التسجيل.
• تشغيل الـ Script بشكل دوري عبر cron job.
• إنشاء تقارير آلية لفريق التسويق أو المبيعات.

ملاحظات تقنية مهمة قبل اعتماد الحل في بيئة العمل

التحقق من عدد السجلات

إذا كان متجرك يحتوي على عدد كبير من العملاء، فقد تحتاج إلى التعامل مع pagination في WooCommerce API، لأن بعض endpoints لا تعيد جميع النتائج دفعة واحدة.

حماية المفاتيح السرية

لا تضع Consumer Key وConsumer Secret مباشرة داخل مستودعات عامة أو ملفات مشتركة. الأفضل استخدام متغيرات بيئة Environment Variables للحفاظ على سرية بيانات الوصول.

تنظيف البيانات قبل التصدير

في بعض الحالات، قد تجد سجلات ناقصة أو عناوين بريد غير مكتملة. لذلك من الأفضل إضافة خطوة تحقق بسيطة قبل إنشاء ملف Excel النهائي.

مثال مبسط على الفكرة الكاملة

يوضح المثال التالي تسلسلاً منطقياً مختصراً للعملية من البداية حتى إنشاء الملف:

from woocommerce import API
import pandas as pd
import json

wcdata = API(
    url='<BASE_URL>',
    consumer_key='ck_XXXXXXXXXXXXXXXXXXXX',
    consumer_secret='cs_XXXXXXXXXXXXXXXXXXXX',
    version='wc/v3'
)

newJson = wcdata.get('customers').json()

with open('contacts.json', 'w') as f:
    json.dump(newJson, f, ensure_ascii=False, indent=4)

df_json = pd.read_json('contacts.json')

df_json.to_excel(
    'customers_contacts.xlsx',
    index=False,
    columns=('first_name', 'email')
)

متى يكون هذا النهج أفضل من الإضافات الجاهزة؟

أفضل استخدامات هذا الحل داخل مشاريع التجارة الإلكترونية

1. إنشاء قوائم بريدية لحملات التسويق.
2. إعداد تقارير دورية عن العملاء.
3. تجهيز البيانات لفرق المبيعات وخدمة العملاء.
4. أرشفة بيانات محددة بصيغ سهلة المراجعة.
5. بناء مسارات أتمتة داخل بيئة العمل.

الخلاصة التقنية

إذا كنت تبحث عن طريقة موثوقة ومرنة لاستخراج بيانات العملاء من WooCommerce إلى ملف Excel، فإن استخدام Python مع WooCommerce API وPandas وOpenpyxl يُعد خياراً ذكياً وعملياً. هذا النهج لا يمنحك فقط ملفاً قابلاً للتعديل، بل يفتح الباب أيضاً أمام الأتمتة والتخصيص والتوسع مستقبلاً، وهو ما يجعله مناسباً للمتاجر التي تتعامل مع بيانات عملاء متجددة وتحتاج إلى حلول تقنية مستقرة وقابلة للتطوير.