بيانات طلب Shop Cash وتكاملات الجهات الخارجية

عند استخدام العميل لـ Shop Cash في أحد الطلبات، يتم التعامل مع Shop Cash كطريقة دفع. وهو ليس خصمًا، أو بطاقة هدية، أو رصيد متجر. ويُدفع أي رصيد متبقٍّ للطلب باستخدام Shop Pay أو تقسيط Shop Pay.

على سبيل المثال، إذا استخدم عميل 25 دولارًا أمريكيًا من Shop Cash في طلب بقيمة 100 دولار أمريكي، فسيتضمن الطلب مدفوعات Shop Cash بقيمة 25 دولارًا أمريكيًا ومدفوعات Shop Pay بقيمة 75 دولارًا أمريكيًا. يمكن أن تتضمن بيانات طلبك أكثر من طريقة دفع واحدة للطلب نفسه.

يظهر Shop Cash كمعاملة طلب لها قيمة البوابة shop_cash حيثما تتوفر قيم البوابة. تتبع معاملة Shop Cash دورة حياة المعاملة القياسية، مثل التفويض، والتحصيل، والإلغاء، والاسترداد. ولا تستخدم Shop Cash نوع معاملات البيع المشتركة.

إذا استخدم العميل أيضًا عرض Shop من إحدى Shop Campaigns، فسيتم تضمين القيمة الممولة من الحملة في نفس مبلغ معاملة طلب shop_cash. لا يتم تمثيل الجزء الخاص برصيد المشتري والجزء الممول من الحملة كمعاملات طلب منفصلة. اعتبارًا من يناير 2026، ستُفرض تكاليف الحملات على فاتورة Shopify الخاصة بك بدلاً من خصمها من دفعاتك، لذلك فإن معاملات فواتير الحملة في نشاط الدفعات تنطبق فقط على الحملات التي تم تشغيلها قبل ذلك التاريخ. لمزيد من المعلومات، راجع الرسوم، وShop Campaigns، وShop Cash.

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

راجع المتطلبات التالية مع مزود نظام الجهة الخارجية الخاص بك:

• يمكن للنظام دعم أكثر من طريقة دفع في طلب واحد.
• يمكن للنظام تعيين shop_cash كطريقة دفع.
• لا يعامل النظام Shop Cash كخصم، أو بطاقة هدية، أو رصيد متجر.
• يخزن النظام مُعرّف معاملة الطلب لكل تفويض، أو تحصيل، أو إلغاء، أو استرداد لـ Shop Cash.
• يخزن النظام قيمة تفويض Shop Cash بالكامل دون اقتطاعها، إذا كانت هذه القيمة متضمنة في البيانات التي يستوردها النظام.
• يتعامل النظام مع قيم التفويض كسلاسل نصية مبهمة ولا يقوم بتحليلها، أو فك تشفيرها، أو تسويتها، أو تجزئتها، أو استنتاج معنى منها.
• يمكن للنظام معالجة عمليات الاسترداد التي تعيد الأموال إلى كل من Shop Pay وShop Cash.
• يمكن للنظام تسوية معاملات دفعات Shop Cash بشكل منفصل عن معاملات الدفع بالبطاقة.
• لا يفترض النظام إرجاع المعاملات بترتيب معين.

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

قيمة التفويض في معاملة Shop Cash هي سلسلة نصية مبهمة متغيرة الطول. وهي ليست رمز تفويض قصير لبطاقة وغير قابلة للقراءة من قِبل البشر.

إذا كان نظام تخطيط موارد المؤسسات (ERP)، أو نظام إدارة الطلبات (OMS)، أو أي نظام جهة خارجية آخر خاص بك يستورد قيم تفويض Shop Cash، فخزن القيمة الكاملة تمامًا كما تم توفيرها. استخدم حقل نص متغير الطول أو غير محدود حيثما أمكن ذلك.

عندما يخزن نظامك قيم تفويض Shop Cash، اتبع هذه الإرشادات:

• لا تقتطع القيمة إلى طول ثابت قصير، مثل 50 أو 100 حرف.
• لا تقم بتحليل أو استنتاج أي معنى من أي جزء من القيمة.
• لا تستخدم قيمة التفويض لتحديد المعاملات في عمليات واجهة برمجة التطبيقات (API) الخاصة بالتحصيل، أو الإلغاء، أو الاسترداد.

يمكن أن تؤدي قيم التفويض المقتطعة إلى فشل استيرادات الجهات الخارجية أو فشل المعالجة اللاحقة في أنظمة ERP وOMS.

لدعم عمليات التحصيل، والإلغاء، والاسترداد من خلال Admin API، خزن مُعرّفات معاملات الطلب وعلاقات المعاملات الأصلية. تحدد عمليات التحصيل والإلغاء في Admin API معاملة التفويض باستخدام parentTransactionId. بينما تحدد عمليات الاسترداد معاملة التحصيل القابلة للاسترداد باستخدام parentId.

عندما يُصدر تطبيق أو تكامل عملية استرداد لـ Shop Cash من خلال واجهة برمجة التطبيقات (API)، يجب أن تتبع عملية الاسترداد معاملة تحصيل Shop Cash كمعاملة أصلية، وليس معاملة تفويض Shop Cash. يتم رفض عمليات الاسترداد التي تتم مقابل معاملة التفويض.

يجب أن تحدد تطبيقات الاسترداد ومعالجات Webhook معاملة تحصيل Shop Cash القابلة للاسترداد، وتحسب المبلغ المتبقي القابل للاسترداد لهذا التحصيل، وتنشئ عملية الاسترداد بناءً على مُعرّف معاملة التحصيل.

عند استخدام Admin API، أو عمليات تصدير الطلبات، أو تصدير الدفعات، أو تصدير تطبيقات الجهات الخارجية، عامل Shop Cash كبيانات دفع. وبناءً على التصدير أو مورد واجهة برمجة التطبيقات الذي تستخدمه، يمكن تمثيل معلومات Shop Cash من خلال طريقة الدفع، أو البوابة، أو معاملة الطلب، أو معاملة الدفعة، أو بيانات الاسترداد.

عند إنشاء أو تحديث عملية دمج، خزّن المعلومات التالية للطلبات التي تتضمن Shop Cash:

• رقم الطلب واسم الطلب.
• طريقة الدفع أو قيمة البوابة، مثل shop_cash حيثما توفرت.
• مُعرّفات معاملات الطلب لكل معاملة دفع.
• نوع المعاملة وحالتها، مثل التفويض، أو التحصيل، أو الاسترداد، أو الإلغاء.
• مبلغ المعاملة وعملتها.
• علاقات المعاملة الأصلية، عند توفرها.
• مُعرّفات الدفع، حيثما توفرت.
• قيم التفويض الكاملة، إذا كان نظامك يستوردها.
• مُعرّفات الدفعات ومُعرّفات معاملات الرصيد عند تسوية الدفعات.
• مُعرّفات معاملات الاسترداد عند تسوية المرتجعات.

للحصول على تفاصيل حول حقول Admin API المتاحة، راجع وثائق المطوّرين الخاصة بـ معاملة طلب Admin API. تجنّب الاعتماد على الحقول المهملة مثل OrderTransaction.authorizationCode لعمليات الدمج الجديدة.

يوضح المثال المبسط التالي طلب شراء بقيمة 100 دولار أمريكي تم دفعه بواقع 75 دولارًا أمريكيًا من خلال Shopify Payments و25 دولارًا أمريكيًا من خلال Shop Cash. القيم هي للتوضيح فقط.

{
  "transactions": [
    {
      "kind": "authorization",
      "gateway": "shopify_payments",
      "status": "success",
      "amount": "75.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "ch_3OabcXYZ..."
    },
    {
      "kind": "authorization",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "<long-opaque-variable-length-string>"
    },
    {
      "kind": "capture",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": "<shop-cash-authorization-transaction-id>",
      "authorization": null
    }
  ]
}

يمكن أن يبدو Shop Cash مشابهًا لقيم الدفع أو القيم الترويجية الأخرى، ولكن يجب أن تتعامل أنظمتك مع كل قيمة على حدة:

قبل الاعتماد على نظام تابع لجهة خارجية للطلبات التي تتضمن Shop Cash، تأكد من المتطلبات التالية:

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

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