من الطلب إلى رقم التتبّع: ربط شركة الشحن بموقعك

حدّد متى تُنشأ الشحنة بالضبط

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

احفظ مفتاح شركة الشحن

المفتاح ينحفظ بلوحة «الأسرار» أو عبر حقل الإدخال الآمن داخل المحادثة — القيمة تروح للخادم مباشرة وما تمرّ بالنموذج ولا بسجل المحادثة. الاسم بصيغة SHIPPING_API_KEY، حروف كبيرة وأرقام وشرطة سفلية حتى 40 حرفاً. أغلب شركات الشحن تعطيك مفتاحين: واحد للاختبار وواحد للإنتاج. احفظ الاثنين بأسماء مختلفة واضحة.

اكتب دالة إنشاء الشحنة

الدالة تاخذ رقم الطلب، تقرأ الصف بـ ebnii.db، تقرأ المفتاح بـ ebnii.secrets.get، وتنادي واجهة الشركة بـ ebnii.fetch. رد الشركة يرجع نصاً خاماً فالدالة تحلّله وتاخذ منه رقم التتبّع ورابط البوليصة، وتحدّث صف الطلب بـ ebnii.db.update. لا تحاول تسوي أكثر من هذا بنفس التشغيلة: عندك 10 ثوانٍ فقط لطلب الزائر، وebnii.sleep أقصاها خمس ثوانٍ فالانتظار الطويل مو خيار.

افتح ويبهوك الحالة

ملف الويبهوك لازم يكون باسم ينتهي بـ -webhook.js — مثلاً functions/shipping-webhook.js. هذي القاعدة أمنية: الملفات اللي تنتهي بهالصيغة فقط هي المتاحة على رابط عام، وباقي دوالك تبقى خاصة ما تنفتح من برّا. رابط الويبهوك اللي تعطيه للشركة بشكل: اسم-موقعك.ebnii.com/api/site/اسم-موقعك/hook/shipping، ويستقبل POST وGET. جوّا الدالة توصلك البايتات الخام بـ req.raw والترويسات بـ req.headers ومعاملات الرابط بـ req.query.

بلّغ العميل

من داخل الدالة، ebnii.email.send توصل لأي عنوان — بعكس كود الصفحة اللي محصور ببريدك أو ببريد المستخدم المسجّل دخوله. الحد خمس رسائل بالتشغيلة الواحدة، وهذا أكثر من كافٍ لتحديث حالة. الإرسال يخصم من نفس الحصة: 500 رسالة مجانية بالشهر لكل مشروع، وسقف يومي 300 رسالة.

رقم التتبّع على صفحة طلبه

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

رابط البوليصة كما ترجعه الشركة

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

ثلاث رسائل لا أكثر

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

صفحة تتبّع بالرقم للزائر غير المسجّل

الزائر يدخل رقم طلبه ويشوف الحالة بدون ما تنفتح قاعدة البيانات كلها. cloud.db فيه أربعة مستويات وصول، فتخلي حالة الشحنة قابلة للقراءة بالمعرّف وتبقي بيانات العميل مقفولة.

تنبيه لك أنت لما تعلق شحنة

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

يشتغل بلا مشاكل

• شركة الشحن عندها REST API عام بمفتاح: الربط كله يتم داخل ابني بلا خادم خارجي.
• ebnii.crypto فيه HMAC وtimingSafeEqual جاهزين للتحقق من تواقيع الويبهوك بلا مكتبات.
• الويبهوك يستقبل والموقع مسكّر ومحد فاتحه — الاستقبال على الخادم.
• رد الشركة يُقبل حتى 2 ميغابايت، وهذا أوسع بمراحل من رد شحنة عادي.
• حساب سعر الشحن قبل تأكيد الطلب يتم بنداء واحد داخل مهلة العشر ثوانٍ.

احسب حسابه

• مزوّد بدون API عام، أو يشتغل بملفات إكسل فقط: ما ينربط برمجياً.
• تحديث كل الشحنات المفتوحة بتشغيلة وحدة مو ممكن: ebnii.db.list جوّا الدالة يوقف عند 200 صف، و8 نداءات خارجية بالتشغيلة — قسّمها بـ ebnii.jobs.enqueue بحد 10 مهام بالتشغيلة و500 باليوم.
• طباعة البوليصة أو تحويلها لصيغة ثانية غير مدعومة داخل الدوال.
• لو واجهة الشركة على شبكة داخلية أو عنوان محلي، النداء مرفوض — العناوين الداخلية محجوبة وكل قفزة تحويل تُفحص لحالها.
• ebnii.sleep أقصاها خمس ثوانٍ، فما تنفع للانتظار حتى تجهز الشحنة عند مزوّد بطيء.