واجهة API لبائع GGsel — خيارات الأتمتة

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

المقال تقني لكنه مقروء بلا خبرة سابقة في التكاملات. وإن كنت تبدأ من الصفر فاقرأ أولًا البداية السريعة مع API.

أين تعيش الواجهة فعلًا

تقوم GGsel كواجهة متجر على بنية Digiseller — وهذه الطبقة هي التي تتولّى قبول الدفع وبطاقات المنتجات والتسليم الآلي للسلع الرقمية. عمليًا يعني هذا أن قدرات البائع البرمجية تحدّدها تلك الطبقة لا منتج مستقل يُسمّى واجهة GGsel.

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

والقاعدة الثانية — ابدأ بمنتج واحد. دورة كاملة على منتج واحد (طلب، تسليم، حالة، نزاع) تكشف كل الاختناقات بكلفة أقل بكثير من ترحيل كتالوج من ألف عنصر.

ما الذي يستحق الأتمتة

مزامنة المخزون

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

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

مزامنة الأسعار

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

التسليم الآلي للأكواد

طريقتان:

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

حالات الطلب

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

البنية — المورّد، الوسيط، المنصة

النمط الوحيد الذي يصمد هو:

واجهة المورّد ← وسيطك ← المنصة

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

لماذا لا يمكن وصل المورّد بالمنصة مباشرة:

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

ومع تعدّد المصادر يُضاف التوجيه — أي مورّد ينفّذ منتجًا بعينه في طلب بعينه. موضوع مستقل تجده في توجيه التنفيذ متعدّد المصادر.

عدم التكرار — الحد الأدنى الإلزامي

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

العقد العملي:

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

الحالات الحدّية والأخطاء الشائعة في تعمّق في مفاتيح عدم التكرار.

الويب هوك — كيف لا تفقد الأحداث

القواعد بسيطة وتُخالَف دائمًا تقريبًا:

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

المعالجة الكاملة في تكامل الويب هوك.

أنماط الفشل التي يجب تصميمها

لا شيء من هذا استثنائي — كلها تحدث بانتظام، والفرق بين عمل هادئ وآخر مرهق هو ما إذا كُتب المعالج مسبقًا. التعافي من نفاد المخزون مشروح في التعافي من نفاد المخزون.

من أين يأتي تدفّق المخزون

لا تؤتي الأتمتة ثمارها إلا فوق مورّد بواجهة برمجية يمكن التنبؤ بها. FoxReload يقدّم هذا السطح تحديدًا: أكثر من 900 منتج بين الألعاب وبطاقات الهدايا والشحن وeSIM والبرمجيات، وواجهة REST API واحدة بتسليم آلي، ومنتجات متعدّدة المناطق — مصدر واحد يتصل به وسيطك بدل عشر قنوات يدوية. ولاختيار المصدر وما يجب طلبه مكتوبًا راجع من أين يجلب بائعو GGsel مفاتيح الألعاب.

ونكرّر الأهم — دوال المنصة وحدودها ومتطلباتها تتغيّر. تحقّق من توثيق Digiseller الحالي وقواعد GGsel قبل التطوير ولا تنقل تكاملًا قديمًا بلا اختبار.