أمارسوفت: الربط والسحب والحجز والطلب

الربط

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

المصادقة: Authorization: token مفتاح:سر. الغلاف { message }. اللاحق يُبنى بنقطة: catalogue، prices، availability، reserve، release، order.

الويب هوك واختبار موقّع

العنوان: https://جذرك/api/erp/availability. الرؤوس: توقيع HMAC-SHA256 على جسم الطلب الخام فقط، وختم زمني يُرفض بعد خمس دقائق، واسم الحدث. الأسرار من بيئة الاستضافة (الأساسي والقديم أثناء التدوير). الجسم يحتاج event_id وbarcode إلا في حدث الاختبار. التكرار يُعترف به ولا يُنفَّذ مرتين. حدث test يُسجَّل فقط ويظهر في تغذية الأحداث.

سحب الكتالوج والأسعار

اسحب المسودة من زر السحب أو npm run erp:pull-draft. الاستيراد اليدوي JSON يكتب على الباركود نفسه. القطع تُحفظ مسودة. الصفحة ٢٠٠ والحد ٥٠٠. مؤشر تالف يعيد ٤١٧. الأسعار كل خمس دقائق أو «تحديث الأسعار». metal_cost لا يُخزَّن — المعدن من سعرنا الحي.

قدم التكلفة وقفل العرض

تكلفة أمارسوفت أقدم من عتبة القدم (افتراضي ٩٠٠ ثانية في قواعد العرض) ترفض التسعير بـ erpCostStale. قفل السلة ٦٠٠ ثانية. قفل الطلب عندهم ٦٠٠ ثانية من sealed_at. حجز القطعة عندهم ٩٠٠ ثانية. حجز القطعة الفريدة عندنا ١٥ دقيقة. سعر السوق إن قدم أكثر من ٦٠٠ ثانية يرفض التسعير.

أحداث التوفّر

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

أسماء الحقول

تُحفظ كما وردت (gold_color، item_style، type، category). التحويل الدلالي للكميات والهوية فقط. type شكل القطعة وcategory تصنيف المعدن — لا تخلطهما.

هوامش المجوهرات

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

الحجز ثم الطلب

عند عرض السلة والدفع للمجوهرات المستوردة فقط: reserve بنفس رقم الطلب. الفشل يغلق الدفع ويسقط السطر. إعادة تسعير العشر دقائق تُبقي الحجز. الإلغاء والهجر وفشل البطاقة: release. بعد تأكيد الدفع: نرسل order بالأسعار المختومة (الهامش حقل مستقل). فاتورتهم مسودة؛ عند اعتمادها عندهم يُستهلك الحجز (consumed) — لا نرسل release بعد الدفع. السبائك وكتالوجنا لا تُرسل لأمارسوفت.

إن رفضوا price_lock_expired لا تُسقط الطلب المدفوع. يظهر في تفاصيل الطلب مع إعادة إرسال بعد موافقة إعادة الختم (نفس المبالغ، sealed_at جديد).

بوابة الإطلاق

المجوهرات والألماس والساعات تبقى مسودة حتى JOHAR_JEWELLERY_STOREFRONT_LIVE=1 بعد قبول طلب تجريبي.