متجر إلكتروني في المغرب مع الدفع: انشروا منتجاتكم في المتجر المستضاف وتابعوا طلبياتكم

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

المتجر المستضاف بوضوح

ChariPay منصة دفع مغربية، مزوّد خدمات دفع (PSP) تشغّله Chari Money، مؤسسة أداء مرخَّصة من بنك المغرب. ومتجرها المستضاف يجيب عن وضعية محددة: لا موقع لكم بعد؟ انشروا منتجاتكم في واجهتكم المستضافة وتابعوا طلبياتكم — في انتظار الأداء، مدفوعة، مشحونة، مسلَّمة — من بوابة التاجر. وعبر API، تحمل وحدة المنتجات سعر كل منتج ومخزونه الاختياري وصفحة بيعه.

عمليًا، تقوم الأداة بأمرين، وتقوم بهما ببساطة:

• صفحة بيع لكل منتج. تعرض المنتج وسعره، وتُشارَك كما يُشارَك الرابط.
• تتبّع الطلبيات. كل طلبية تُمرَّر في هذه الصفحة تظهر في بوابة التاجر بحالتها.

ومن جهة الأداء، في المتجر المستضاف، يختار المشتري عند الطلب الأداء بالبطاقة — على صفحة الدفع المستضافة مع ‎3-D Secure — أو نقدًا: فيتلقى مرجعًا يسدّده في وكالة من شبكة Chari. ويتم الأداء بالبطاقة في صفحة الدفع المستضافة نفسها: فلا ترون رقم البطاقة أبدًا.

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

نشر منتج من بوابة التاجر

من بوابة التاجر، يتم النشر في بضع خطوات:

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

جرّبوا ذلك بمنتج حقيقي من كتالوجكم: ابدؤوا في وضع الاختبار. ثلاثة حقول (الاسم، والبريد الإلكتروني المهني، والمؤسسة)، ورابط تفعيل يصلكم بالبريد لاختيار كلمة المرور، ثم بوابة التاجر حيث تنشرون منتجكم وتنشئون، إن كنتم تدمجون عبر API، مفتاح الاختبار بعد إعادة مصادقة. ادفعوا طلبيتكم التجريبية ببطاقة الاختبار ‎4918 9141 0719 5005، CVV 123، وأي تاريخ انتهاء مستقبلي، ورمز ‎3-D Secure 555: هذه البطاقة هي الوحيدة المقبولة، ولا يتحرك أي مال حقيقي. ووضع الاختبار مجاني، بلا حد زمني وبلا التزام؛ ولا يحاكي إيداعًا نقديًا حقيقيًا في الوكالة.

النشر عبر API: وحدة المنتجات

إن كان كتالوجكم يعيش أصلًا في أداة أخرى، أو أردتم الأتمتة، فإن وحدة «المنتجات» في توثيق API تتيح ست نقاط نهاية على العنوان الأساسي الوحيد https://api-psp.charipay.ma:

إنشاء منتج بـcurl:

curl -X POST 'https://api-psp.charipay.ma/v1/products' \
  -H 'X-CHARI-PAY-API-KEY: chari_sk_test_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Coffret savon noir 500 g",
    "description": "Savon noir artisanal, coffret cadeau",
    "price": 149.90,
    "stockQuantity": 40,
    "externalId": "sku-savon-noir-500",
    "metadata": { "sku": "SN-500" }
  }'

الحقلان المطلوبان وحدهما هما name وprice. والسعر بالدرهم وبالوحدات الرئيسية (149.90 = 149,90 درهمًا)؛ وstockQuantity اختياري، وغيابه يعني مخزونًا غير محدود؛ وتكمّل description وimageUrl وexpiresAt (تاريخ نهاية البيع، في المستقبل) بطاقة المنتج. ويحمل الرد — 201، أو 200 إن كان externalId موجودًا من قبل — مرجع المنتج reference (prod_…) وshopUrl، أي صفحة البيع التي تشاركونها، إلى جانب الكميتين المتاحة والمحجوزة. وmetadata اختياري، ويُعاد كما هو في قراءات المنتج وفي حدث الأداء الخاص بطلبيات هذا المنتج.

يعمل المفتاح chari_sk_test_… في السندبوكس؛ والطلب نفسه بمفتاح الإنتاج ينشر في الإنتاج. والمفتاح سرّ: لا يوضع أبدًا في المتصفح، ولا في تطبيق محمول، ولا في مستودع git، ولا في لقطة شاشة.

مشاركة صفحة منتج مع الدفع

لا قيمة لصفحة منتج مع الدفع إلا إذا رآها زبناؤكم. شاركوها حيثما تتحدثون إليهم:

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

يطلب الزبون من الصفحة المستضافة، ثم يؤدي بالبطاقة مع ‎3-D Secure، أو يختار النقد ويتلقى مرجعًا يسدّده في الوكالة. أما لخدمة ليست منتجًا من الكتالوج — عرض أسعار، أو إصلاح، أو مبلغ يتغير في كل مرة — فالأداة المناسبة هي رابط الدفع: انظروا إنشاء رابط دفع.

تتبّع طلبياتكم وحالاتها

كل طلبية تُمرَّر في صفحة منتج تظهر في بوابة التاجر بحالتها. وهذه المراحل الأربع لمسارها، وما تعنيه بالنسبة إلى عملكم.

وعند الحالة «مدفوعة» يكون المال قد وصل: بمجرد نجاح أداء — بطاقة مصادَق عليها بـ‎3-D Secure أو مرجع مسدَّد نقدًا في الوكالة — يصبح المبلغ متاحًا في حساب الأداء ChariPay الخاص بكم وقابلًا للاستعمال فورًا. و«متاح في اللحظة في الحساب» لا يعني «تحويلًا بنكيًا فوريًا»: فالدفعة نحو بنككم تبقى عملية مستقلة.

وإن أرجع زبون منتجًا أدّاه بالبطاقة، فاستردّوا له من بوابة التاجر أو عبر API، كليًا أو جزئيًا: الاسترداد مجاني، ويُخصم مبلغه من رصيدكم المتاح، وهو ليس فوريًا من جهة البنك.

التوصل بالإشعار: order.paid وpayment.succeeded

للتفاعل آليًا مع طلبية مدفوعة — خفض المخزون في أداتكم، أو إخطار الورشة، أو إرسال تأكيدكم الخاص — صرّحوا بنقطة استقبال للويب هوكس. وحدثان يعنيانكم:

• `order.paid` يُعلم بأن طلبية من متجركم قد أُدّيت.
• `payment.succeeded`، حدث الأداء المرافق له، يحمل metadata منتجكم كما هو. ففي payment.succeeded، لا في order.paid، تجدون معرّفاتكم الخاصة، مثل sku في المثال أعلاه.

وثلاث قواعد للاستقبال، مشتركة بين كل الويب هوكس: تحقّقوا من التوقيع (X-CHARI-SIGNATURE، X-CHARI-TIMESTAMP) على المتن الخام؛ ووجّهوا المعالجة حسب الترويسة Chari-Event-Type؛ واعتمدوا في إزالة التكرار على Chari-Event-Id لا على Chari-Webhook-Id — فهذا الأخير يحدد عملية التسليم لا الحدث.

ولا يغني الويب هوك عن القراءة: أعيدوا قراءة طلبيات منتج عبر GET /v1/products/{reference}/orders للمطابقة أو بعد توقف خادمكم. وبالنسبة إلى طلبية أُدّيت نقدًا في الوكالة، لا تبنوا معالجتكم على حدث: تابعوا حالة الطلبية في بوابة التاجر، أو أعيدوا قراءتها عبر API.

مزامنة كتالوج قائم عبر API

هل يعيش كتالوجكم في جدول بيانات أو في برنامج تدبير؟ اجعلوه هو المصدر، ودعوا المتجر المستضاف يعكسه.

1. 1أنشئوا كل منتج مرة واحدة، عبر POST /v1/products، مع externalId لكل منتج — أي مرجع السلعة لديكم. وإن أُعيد النداء، بعد انتهاء مهلة أو إعادة تشغيل برنامج، أعادت API المنتج الموجود بـ200 بدل إنشاء منتج ثانٍ.
2. 2حدّثوا عبر `PATCH`، بإرسال ما يتغير فقط: سعر، أو مخزون، أو وصف.
3. 3عطّلوا بدل الحذف: DELETE /v1/products/{reference} يعطّل المنتج فلا يعود قابلًا للطلب.

وتحديث السعر والمخزون يبدو هكذا:

curl -X PATCH 'https://api-psp.charipay.ma/v1/products/prod_2Bc9Zt' \
  -H 'X-CHARI-PAY-API-KEY: chari_sk_test_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "price": 159.90,
    "stockQuantity": 25
  }'

ولسرد منتجاتكم، تصفّحوا القائمة صفحة بعد صفحة (page ابتداءً من الصفر، وsize) إلى غاية totalPages. وإن كنتم تزامنون منتجات كثيرة دفعة واحدة، فاحترموا حدود المعدل: فالرد 429 RATE_LIMITED يبيّن، عبر الترويسة Retry-After، متى تعيدون المحاولة. واحتفظوا بـexternalId محورًا بين أداتكم وChariPay: فهو الذي يجعل كل مزامنة قابلة للإعادة دون تكرار.

متى تنتقلون إلى Shopify أو WooCommerce أو إلى موقعكم الخاص

المتجر المستضاف مصمَّم للانطلاق وللكتالوجات القصيرة. وبعض الحاجات تشير إلى أن وقت الانتقال إلى أداة أكثر اكتمالًا قد حان:

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

يلبّي Shopify وWooCommerce هذه الحاجات، والدفع يتبع. لا توجد إضافة ChariPay لـShopify ولا لـWooCommerce: ترسلون رابط دفع لكل طلبية، دون سطر شفرة واحد، أو تربطون صفحة الدفع المستضافة عبر API لإعادة توجيه تلقائية. أما الموقع المصمَّم حسب الطلب فيعتمد جلسات الدفع والويب هوكس. والصورة الشاملة لهذه التركيبات في صفحتنا حول الدفع الإلكتروني للتجارة الإلكترونية في المغرب. وإن كنتم في البداية تمامًا، فمسار المبتدئ كاملًا في كيف تبدؤون التجارة الإلكترونية في المغرب.

أسئلة شائعة

كيف أنشئ متجرًا إلكترونيًا في المغرب مع الدفع دون مطوّر؟

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

ما هو المتجر المستضاف عمليًا؟

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

هل يمكن تدبير مخزون المنتجات؟

نعم، إن شئتم: فالمخزون اختياري. حدّدوا كمية المخزون عند إنشاء المنتج، من بوابة التاجر أو عبر stockQuantity في API؛ ودون تحديدها يبقى المنتج معروضًا للبيع بلا حد. ويمكنكم تحديث الكمية في أي وقت، مثلًا عبر PATCH من برنامج التدبير لديكم، وتميّز API بين الكمية المتاحة والكمية المحجوزة.

ما حالات الطلبية التي تظهر في بوابة التاجر؟

يتبع التتبّع مسار الطلبية: في انتظار الأداء، مدفوعة، مشحونة، مسلَّمة. والحالة «مدفوعة» هي إشارة تحضير الطلبية: فالمبلغ حينها متاح في حساب الأداء. أما «مشحونة» و«مسلَّمة» فتساعدانكم على متابعة ما يلي، والرد على أسئلة زبنائكم دون البحث في رسائلكم أو جداولكم.

هل يتولى المتجر المستضاف التوصيل؟

لا. المتجر المستضاف ينشر منتجاتكم، ويستخلص الأداءات، ويتابع الطلبيات؛ ولا يدبّر التوصيل ولا الناقلين. فأنتم من يختار من يوصل ومتى، ويُستحسن أن يكون ذلك بعد الحالة «مدفوعة». وإن احتجتم إلى توصيل مدمج في مسار الشراء، فتلك إشارة للانتقال إلى Shopify أو WooCommerce أو موقع حسب الطلب.

كيف أتوصل بإشعار عن طلبية جديدة مدفوعة؟

في بوابة التاجر، تظهر كل طلبية بحالتها. ومن جهة الخادم، صرّحوا بنقطة استقبال للويب هوكس: يُعلم order.paid بالطلبية المدفوعة، ويحمل payment.succeeded المرافق له metadata منتجكم. وجّهوا المعالجة حسب Chari-Event-Type، وأزيلوا التكرار حسب Chari-Event-Id، وأعيدوا قراءة الطلبيات عند الحاجة عبر GET /v1/products/{reference}/orders، خاصة بعد توقف خادمكم.

هل يمكن استيراد كتالوج قائم؟

نعم، عبر API: أنشئوا كل منتج عبر POST /v1/products مع externalId يساوي مرجع السلعة لديكم، ثم حدّثوه عبر PATCH. وإن أُعيد إنشاء منتج، أعادت API المنتج الموجود بـ200 بدل تكراره، فتبقى كل مزامنة قابلة للإعادة دون نسخ مكرَّرة. وعطّلوا المنتجات المسحوبة عبر DELETE: فلا تعود قابلة للطلب.

متى ينبغي الانتقال إلى Shopify أو WooCommerce؟

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

الخطوة التالية

انشروا منتجين أو ثلاثة في وضع الاختبار، وشاركوا صفحة مع أنفسكم، وتابعوا طلبية تجريبية إلى غاية الحالة «مدفوعة»: ابدؤوا في وضع الاختبار. ثم حضّروا الانتقال إلى الإنتاج، وإن كان كتالوجكم يعيش في مكان آخر، فاربطوا المزامنة بالاستعانة بـوحدة «المنتجات» في توثيق API.