استيراد وتصدير المنتجات بالجملة (CSV)

إضافة المنتجات واحداً تلو الآخر مناسبة لقائمة صغيرة، لكنها تصبح بطيئة عندما يكون لديك كتالوج حقيقي. يتيح لك الاستيراد بالجملة بناء كل منتج داخل جدول بيانات (إكسل أو Google Sheets أو Numbers)، وحفظه كملف CSV، ثم رفعه مرة واحدة لتتحول كل الصفوف إلى منتجات فعلية خلال ثوانٍ. أما التصدير فيقوم بالعكس: ينزّل كتالوجك الحالي كملف CSV يمكنك الاحتفاظ به نسخةً احتياطية أو تعديله دفعةً واحدة أو نقله إلى متجر آخر.

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

يجب أن يحتوي ملف الاستيراد على صف عناوين (الصف الأول) يضم هذه الأعمدة التسعة، بأي ترتيب لكن بنفس التهجئة تماماً: category_id وbadge وproduct_image وproduct_name وproduct_short_description وproduct_description وregular_price وsales_price وproduct_status. يقوم النظام تلقائياً بإزالة المسافات وتحويل العناوين إلى أحرف صغيرة وحذف علامة BOM المخفية الخاصة بإكسل، لذا يُتسامح مع حالة الأحرف في صف العناوين، لكن الكلمات نفسها يجب أن تتطابق. أي عمود مفقود أو مكتوب خطأً يوقف الاستيراد بالكامل قبل إنشاء أي منتج.

حقل category_id هو الأهم: فهو الرمز القصير لفئة موجودة فعلاً في متجرك (مثل 68b8a837ea78f)، وليس اسم الفئة. تحصل على هذا الرمز بفتح قسم الفئات في متجرك أولاً؛ ويجب أن يستخدم كل صف منتج رمزاً موجوداً مسبقاً، وإلا فسيُتجاوز ذلك الصف مع ظهور خطأ. ضع كل منتج تحت الفئة التي تريد ظهوره فيها في واجهة المتجر.

product_name هو العنوان الظاهر، وproduct_short_description هو السطر التشويقي القصير الظاهر على البطاقات، وproduct_description هو النص الكامل للوصف. أما badge فهو الشارة الصغيرة على المنتج (مثل Best Seller أو Save 25%). انتبه لملاحظة مهمة: في الاستيراد تُعامَل الأعمدة التسعة كلها كحقول مطلوبة — حتى badge وproduct_short_description وproduct_description. فإذا تركت أياً منها فارغاً، سيُرفض ذلك الصف. وإذا كنت لا تريد شارة فعلاً، ضع قيمة بديلة مثل شرطة واحدة - بدلاً من ترك الخلية فارغة.

regular_price هو السعر الأساسي وsales_price هو السعر بعد الخصم؛ وكلاهما أرقام مجردة (استخدم 49.99 وليس $49.99 أو 49,99). وproduct_image هو الصورة: الصق نفس مسار الصورة أو رابطها الذي يستخدمه محرر المتجر، أو انسخه من ملف مُصدَّر. ويقبل product_status قيمتين فقط: instock أو outstock — وأي كلمة أخرى ستُعرض بشكل خاطئ، لذا لا تكتب هنا "In Stock" أو "متوفر". أما المعرّف الفريد للمنتج فيُولَّد لك تلقائياً عند الاستيراد، لذلك لا يوجد عمود product_id لتعبئته.

التصدير أولاً هو أأمن طريقة لتعلّم التنسيق، لأنه يمنحك ملف CSV حقيقياً مطابقاً لمتجرك بالفعل. افتح متجرك في المحرر، وانتقل إلى قسم المنتجات، وانظر إلى شريط الأدوات في أعلى يمين ترويسة الصفحة. ثم انقر على زر تصدير (الزر الذي يحمل أيقونة التنزيل).

سيقوم متصفحك فوراً بتنزيل ملف يحمل اسم متجرك، مثل mystore_products.csv. افتحه في إكسل أو Google Sheets. ستجد أن الملف يحتوي على أربعة عشر عموداً — أعمدة الاستيراد التسعة بالإضافة إلى خمسة أعمدة إضافية يضيفها التصدير: card_id وproduct_id وstatus وcreated_at وupdated_at. هذه الأعمدة الإضافية للمرجعية والنسخ الاحتياطي؛ فهي تسجّل المتجر الذي ينتمي إليه المنتج ووقت إنشائه.

تنبيه قبل أن تعيد استيراد ملف مُصدَّر: يتوقع الاستيراد تسعة أعمدة بالضبط في كل صف، لذا فإن ملف التصدير غير المعدّل والذي يحتوي على أربعة عشر عموداً سيُرفض مع رسالة "عدم تطابق الأعمدة". إذا كان هدفك التعديل وإعادة الاستيراد، فاحذف الأعمدة الخمسة الإضافية (card_id وproduct_id وstatus وcreated_at وupdated_at) وأبقِ فقط على أعمدة الاستيراد التسعة. تعامل مع التصدير كأداة للنسخ الاحتياطي والقالب، لا كرحلة ذهاب وإياب بنقرة واحدة.

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

عندما يكون جدول بياناتك جاهزاً، احفظه بصيغة CSV (في إكسل: ملف ← حفظ باسم ← CSV UTF-8؛ وفي Google Sheets: ملف ← تنزيل ← قيم مفصولة بفواصل). يكتشف المستورد تلقائياً ما إذا كان ملفك يستخدم الفواصل أو علامات الجدولة كفواصل، فكلاهما يعمل، لكن وجود امتداد .csv حقيقي مطلوب — فالرفع لا يقبل سوى ملفات CSV، وليس مصنفات .xlsx.

عُد إلى صفحة المنتجات وانقر على زر استيراد في شريط الأدوات (الزر الذي يحمل أيقونة الصندوق). سيُفتح مربع حوار استيراد صغير يحتوي على حقل ملف واحد. وإذا لم تكن متأكداً من التخطيط، فانقر أولاً على زر نموذج CSV أسفل مربع الحوار لتنزيل قالب يمكنك تعبئته.

انقر على حقل الملف، واختر ملف .csv الخاص بك، ثم انقر على زر استيراد الأزرق. سترفع الصفحة الملف وتعالج كل صف تباعاً. وعند النجاح ستظهر رسالة خضراء تم استيراد المنتجات بنجاح، ويُغلق مربع الحوار، ويتحدّث جدول المنتجات ليُظهر العناصر الجديدة فوراً — دون الحاجة إلى إعادة تحميل الصفحة.

حالة حافة مهمة: الاستيراد ليس مبدأ الكل أو لا شيء. ينشئ النظام كل صف صالح أثناء معالجته، ويجمع فقط الصفوف الخاطئة ليبلغ عنها في النهاية. فإذا كانت الصفوف من 2 إلى 5 سليمة بينما الصف 6 ينقصه حقل، فإن الصفوف من 2 إلى 5 تكون قد حُفظت بالفعل بينما يُتجاوز الصف 6 ويُدرَج في رسالة خطأ حمراء. وإذا فشل الاستيراد جزئياً، فأصلِح فقط الصفوف المُبلَّغ عنها في ملفك، واحذف الصفوف التي استُوردت بالفعل، ثم أعد الرفع — وإلا فستنشئ نسخاً مكررة.

"CSV is missing required columns: …" (ملف CSV تنقصه أعمدة مطلوبة) — يعني أن صف العناوين مفقود أو يحوي خطأ إملائياً في أحد الأعمدة التسعة. افتح الملف وتحقق من الصف الأول حرفاً بحرف مقابل القائمة المطلوبة؛ وانتبه لصيغ الجمع (prices بدلاً من price)، أو مسافة زائدة داخل عنوان، أو عمود حذفته. أصلِح العناوين وأعد الرفع. هذا الخطأ يوقف الاستيراد بالكامل، فلم يُنشأ أي شيء.

"Row N: Column mismatch." (الصف N: عدم تطابق الأعمدة) — يعني أن هذا الصف يحوي خلايا أكثر أو أقل من صف العناوين. والسبب المعتاد هو فاصلة داخل وصف أو سعر تقسم الخلية، أو أعمدة إضافية متبقية من ملف مُصدَّر. ضع أي نص يحتوي على فاصلة بين علامتي اقتباس مزدوجتين ("صلصة حلوة، مدخّنة")، أو أعد حفظ الملف من جدول البيانات الذي يقتبس هذه الحقول تلقائياً. وإذا بدأت من ملف تصدير، فاحذف الأعمدة الخمسة الإضافية ليصبح في كل صف تسعة أعمدة بالضبط.

"Row N: Missing value for 'field'." (الصف N: قيمة مفقودة للحقل 'field') — يعني أن خلية مطلوبة في ذلك الصف فارغة. تذكّر أن كلاً من الأعمدة التسعة يجب تعبئته، بما في ذلك badge وproduct_short_description وproduct_description. عبّئ الخلية الفارغة (استخدم شرطة - إن لم يكن لديك شيء ذو معنى للشارة)، ثم أعد استيراد الصفوف المصحّحة فقط.

"Row N: Category ID '…' does not exist." (الصف N: معرّف الفئة '…' غير موجود) — يعني أن category_id في ذلك الصف لا يطابق أي فئة في متجرك. أعد فتح قسم الفئات، وتأكد من وجود الفئة، وانسخ معرّفها بالضبط (هذه الرموز حساسة لحالة الأحرف ولا تحتوي على مسافات). ومن الأخطاء الشائعة كتابة اسم الفئة بدلاً من معرّفها، أو الاستيراد إلى المتجر الخطأ. أنشئ الفئة المفقودة أولاً، ثم أعد الاستيراد.

"Something went wrong!" (حدث خطأ ما) — هذا الخطأ العام يعني عادةً أن الرفع نفسه رُفض قبل المعالجة: فالملف لم يكن CSV حقيقياً (مثل ملف .xlsx أُعيدت تسميته إلى .csv)، أو كان فارغاً. أعد الحفظ كملف CSV حقيقي من جدول البيانات وحاول مجدداً. وإذا ظهرت الأسعار خاطئة بعد الاستيراد، فتأكد من استخدامك نقطة للكسور العشرية (9.50) وإزالة أي رموز عملة أو فواصل آلاف.

صدّر أولاً ثم ابنِ انطلاقاً منه. أسرع طريق لملف استيراد نظيف هو إضافة منتج واحد يدوياً في المحرر، ثم التصدير، واستخدام ذلك الصف الحقيقي كقالب لك. ستشاهد تماماً كيف تُنسَّق مسارات product_image ورموز category_id، فتنسخ شكلاً معروف الصحة بدلاً من التخمين.

اختبر بصفوف قليلة قبل الدفعة الكبيرة. استورد ملفاً من 3 صفوف أولاً. فإذا ظهرت بشكل صحيح، تكون قد أثبتّ أن عناوينك ومعرّفات فئاتك وتنسيق أسعارك كلها تعمل، وعندها تستطيع بثقة استيراد الملف الكامل بمئات الصفوف. هذا يحوّل جلسة تصحيح أخطاء مُرهِقة إلى فحص يستغرق 30 ثانية.

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

احفظ بترميز UTF-8. إذا كانت أسماء منتجاتك أو أوصافها بالعربية أو تحتوي على أحرف مُشكَّلة، فاختر دائماً خيار CSV UTF-8 عند الحفظ. فملف CSV العادي أو المرمَّز بترميز ويندوز قد يحوّل النص العربي إلى أحرف مشوّهة بعد الاستيراد. والمستورد يزيل أصلاً علامة BOM المخفية الخاصة بإكسل، لذا فإن UTF-8 هو الخيار الآمن.

تذكّر ما لا يستطيع الاستيراد ضبطه. يتعامل الاستيراد بالجملة مع الحقول الأساسية التسعة فقط. أما عدد المخزون، وخيارات المنتج (المقاسات/الألوان)، وروابط الفيديو فلا تُستورد — بل يجب إضافتها في المحرر لاحقاً. خطّط لذلك: استورد لبناء هيكل الكتالوج بسرعة، ثم افتح المنتجات القليلة التي تحتاج إلى خيارات أو حدود مخزون وأكملها يدوياً.

هل يمكنني رفع ملف إكسل (.xlsx) مباشرةً؟ لا. لا يقبل المستورد سوى ملفات CSV. افتح مصنفك في إكسل أو Google Sheets واستخدم "حفظ باسم" / "تنزيل" لتحويله إلى .csv أولاً. وإعادة تسمية ملف .xlsx إلى .csv لا تعمل وسيُرفض.

هل سيحذف الاستيراد منتجاتي الحالية أو يستبدلها؟ لا. الاستيراد يضيف منتجات جديدة فقط؛ ولا يحدّث أو يحذف أبداً ما هو موجود في متجرك. ويصبح كل صف مستورَد منتجاً جديداً تماماً بمعرّف خاص به مولَّد حديثاً. وإذا استوردت الملف نفسه مرتين، فستحصل على منتجات مكررة، لذا احذف المجموعة الموجودة قبل إعادة استيرادها.

لماذا رُفض ملفي المُصدَّر عندما حاولت استيراده مجدداً؟ لأن التصدير يضيف خمسة أعمدة إضافية (card_id وproduct_id وstatus وcreated_at وupdated_at) ليصبح المجموع أربعة عشر، بينما يتوقع الاستيراد الأعمدة التسعة الأساسية بالضبط. احذف الأعمدة الخمسة الإضافية قبل إعادة الاستيراد. وهذه أكثر المفاجآت شيوعاً عند إعادة استخدام الملف ذهاباً وإياباً.

أين أجد معرّف الفئة لعمود category_id؟ افتح قسم الفئات في محرر متجرك. لكل فئة رمز قصير (شيء مثل 68b8a837ea78f) تستخدمه في ملف CSV — وليس الاسم الظاهر. انسخه بالضبط بمزيجه من الأحرف والأرقام، لأن هذه الرموز حساسة لحالة الأحرف.

ما القيم المسموح بها لـ product_status؟ قيمتان فقط: instock وoutstock. وهما الرمزان المخزَّنان اللذان تفهمهما واجهة المتجر. لا تكتب نصاً ودياً مثل "In Stock" أو "متوفر" في ملف CSV — فذلك مجرد التسمية التي تراها في قائمة المحرر المنسدلة، وليس القيمة التي يتوقعها الاستيراد.

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