تخطي إلى المحتوى
دليل

كيف تربط شام كاش API بمتجرك

بقلم فايز الشامينُشر: قراءة لمدة 10 دقائق
الخلاصة

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

ماذا يعني ربط شام كاش API بمتجرك

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

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

لماذا يبقى التأكيد اليدوي عالقًا في منتصف الطلب

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

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

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

ما الذي يجب أن يكون جاهزًا

تحتاج حساب شام كاش تملكه. البوابة تتصل بحساب موجود؛ فتح الحساب لدى شام كاش ليس جزءًا منها. هذا يُنسى أحيانًا حين يظن صاحب المتجر أن الاشتراك يعني إصدار محفظة جديدة باسم الموقع.

ونظام الطلبات يجب أن يُنشئ سجلًا قبل الدفع: المبلغ بالليرة، ورقمًا داخليًا، ومهلة، وحالات واضحة (بانتظار الدفع، مدفوع، يحتاج مراجعة، منتهٍ). يستوي في هذا موقع مخصص أو ووكومرس أو بوت طلبات. ما يربك المطابقة هو أن يدفع الزبون أولًا ثم تحاول لاحقًا أن تخمّن لأي حديث في واتساب كانت هذه العملية.

تحويل شام كاش لا يتيح حقل ملاحظة أو مرجع يكتبه الزبون. لا تطلب منه أن يكتب رقم الطلب داخل التحويل، لأن الحقل غير موجود. بعد الدفع يظهر له رقم العملية، وهذا الرقم هو ما يدخله عندك.

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

البوابة نفسها تغطي سيريتل كاش وشام كاش. بنيتها وأشغّلها بنفسي. موقعك يتصل بالواجهة الجاهزة؛ لا تحتاج أن تشغّل قارئ محفظة عندك.

وأبقِ في اللوحة تدخلًا يدويًا للتأكيد والرفض. أنا لا أشغّل مطابقة تلقائية من دون هذا الزر، حتى في المتاجر الصغيرة.

التدفق كما يعيشه طلب واحد

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

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

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

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

خطوات ربط شام كاش API بمتجرك

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

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

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

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

الإشعارات تأتي بعد حفظ الحالة، لا قبلها. وإذا فشل إرسال الرسالة، تعيد المحاولة دون أن تعيد تعليم الطلب مدفوعًا. هذا التفصيل يمنع شحن طلبين من عملية واحدة بعد انقطاع قصير في الإرسال.

مقارنة سريعة مع سيريتل كاش (السعر هناك دولاران للرقم شهريًا، وهنا خمسة دولارات للحساب، وكل محفظة تُدار وحدها) موجودة في مقال API سيريتل كاش مقابل API شام كاش.

كيف يتحدث موقعك مع بوابة الدفع

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

```php <?php // كيف يتحدث موقعك مع بوابة الدفع الجاهزة // استبدل YOUR_GATEWAY_URL وYOUR_API_KEY وأسماء الحقول بما يصلك عند الإعداد

function confirmByTransactionId(array $order, string $transactionId, callable $alreadyUsed, callable $markUsed, callable $markPaid, callable $flagReview): array { if ($alreadyUsed($transactionId)) { return ['status' => 'rejected', 'reason' => 'transaction_already_used']; }

$payload = json_encode(['transactionId' => $transactionId]); $ch = curl_init('YOUR_GATEWAY_URL'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => $payload, CURLOPT_RETURNTRANSFER => true, ]); $raw = curl_exec($ch); curl_close($ch);

$result = json_decode($raw, true); // حقول تقريبية في الرد: found, amount, receivedAt, senderNumber

if (!$result || empty($result['found'])) { return ['status' => 'not_found']; }

if ((int) $result['amount'] !== (int) $order['amount']) { $markUsed($transactionId); $flagReview($order['id'], $transactionId, $result); return ['status' => 'wrong_amount', 'paid' => $result['amount']]; }

$markUsed($transactionId); $markPaid($order['id'], $transactionId, $result['receivedAt'] ?? null, $result['senderNumber'] ?? null); notifyCustomerAndMerchant($order); return ['status' => 'paid', 'orderId' => $order['id']]; } ```

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

إذا لم تظهر العملية بعد، لا تختر أول طلب مشابه بالمبلغ. دع الزبون يعيد المحاولة، أو راجع الرقم من اللوحة. ورقم المرسل يُحفظ ولا يُشترط تطابقه مع هاتف الزبون في الطلب.

ما الذي يحدث حين لا ينطبق المبلغ

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

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

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

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

إذا كنت تقبل سيريتل كاش أيضًا

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

الاشتراك في البوابتين شائع عند المتاجر التي تقبل المحفظتين، وكل واحدة تُحاسب وتُدار بشكل منفصل. خطوات سيريتل كاش كتبتها في كيف تربط سيريتل كاش بمتجرك الإلكتروني.

إذا كان البيع أصلًا على واتساب أو تيليغرام، يمكن لبوت الدفع أن يستعمل هذه البوابة ويؤكد التحويل داخل المحادثة بعد أن يرسل الزبون رقم العملية. الباقة تبدأ من 120 دولارًا مرة واحدة، وتتصل بشام كاش أو سيريتل كاش بحسب السوق. للمتجر على موقع، الاشتراك الشهري مع باك إندك يكفي في معظم الحالات التي أعمل عليها.

قائمة تحقق قبل استقبال دفعات حقيقية

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

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

أسئلة تتكرر

هل أحتاج حساب شام كاش خاصًا بي؟

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

هل يكتب الزبون ملاحظة في التحويل؟

لا. تحويل شام كاش ما فيه حقل ملاحظة. المطابقة تتم برقم العملية الذي يدخله الزبون بعد الدفع.

هل يمكن تشغيل شام كاش وسيريتل كاش معًا؟

نعم. يُحاسب كل منهما ويُدار على حدة. احفظ على كل طلب المحفظة التي اختارها الزبون حتى لا تخلط التحقق.

ماذا لو حوّل الزبون مبلغًا مختلفًا، أو حوّل بعد إلغاء الطلب؟

علّق العملية وأبلغ الطرفين، واربط رقم العملية بالطلب حتى لا يُستخدم في مكان آخر. القاعدة تُكتب قبل الإطلاق: في بدايتي مع متجر جديد أفضل المراجعة اليدوية على أي إغلاق تلقائي لمبلغ غير مطابق.

كيف أجرّب قبل الربط الحي؟

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

ابدأ بحساب شام كاش وحده

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

إذا بدك بوابة دفع جاهزة لشام كاش، أو للمحفظتين مع بعض، راسلني واذكر شام كاش، وعدد الحسابات، وهل المتجر موقع أم ووكومرس أم بوت. النموذج على fayezalshami.com/ar، والبريد fayezalshami.dev@gmail.com.

أدلّة ومقارنات

تحتاج إلى بناء هذا أو ربطه لعملك؟

استعرض الخدمات