ربط شركات الشحن مع سوق المساعدين

متاجر شركات الشحن

كيف يعمل الربط

1. 1. إسناد

   نسند لشركتك طلب متجرٍ في مدنك وخدمتك (assigned).

2. 2. قبول

   تقبلونه برقم البوليصة — عندها فقط يُطلب الدفع من العميل، فلا يُخصم منه شيءٌ قبل وجود ناقل.

3. 3. استلام وتسليم

   picked_up ⇦ in_transit ⇦ out_for_delivery ⇦ delivered، والعميل يُشعَر عند الشحن والتسليم.

4. 4. تحصيل

   في «الدفع عند الاستلام» تصلكم قيمة التحصيل في تفاصيل الشحنة.

الأمان

• مفتاح API وسرّ توقيعٍ لكل شركة يُعرضان مرّةً واحدة عند الإصدار؛ لا نحفظ المفتاح نفسه بل بصمته، والسرّ مشفّرٌ لدينا.
• كلّ نداءٍ موقَّع بـHMAC-SHA256 على الوقت والـnonce والفعل والمسار وبصمة الجسم؛ تغيير حرفٍ يُبطله، والـnonce لا يُقبل مرّتين، والطابع الزمنيّ ±5 دقائق.
• صلاحياتٌ لكل مفتاح (shipments:read: قراءة الشحنات المسندة؛ shipments:write: قبول الشحنات وتحديث حالتها)، وحدٌّ للنداءات، وقصرٌ اختياريّ على عناوين IP لشركتك.
• كلّ شركةٍ ترى شحناتها وحدها؛ وإيقاف المفتاح فوريّ من لوحة سوق المساعدين.

الواجهة (v1)

الترويسات: Authorization: Bearer mcar_… وX-Mosaiden-Timestamp (ثوانٍ) وX-Mosaiden-Nonce (16–64 حرفاً جديدةً لكل نداء) وX-Mosaiden-Signature: v1=<hex> — حيث التوقيع HMAC-SHA256 بسرّ التوقيع على: timestamp\nnonce\nMETHOD\npath?query\nsha256(body).

الحالات: assigned (مسنَدة — بانتظار قبول الشركة)، accepted (قبلتها الشركة برقم بوليصة)، rejected (اعتذرت الشركة)، picked_up (استُلمت من المتجر)، in_transit (في الطريق)، out_for_delivery (خرجت للتسليم)، delivered (سُلِّمت)، failed (تعذّر التسليم)، returned (أُعيدت للمتجر)، cancelled (ألغتها الإدارة).

import { createHash, createHmac, randomBytes } from "node:crypto";

const API_KEY = process.env.MOSAIDEN_API_KEY;        // mcar_xxxxxxxxxxxxxxxx.xxxx
const SECRET  = process.env.MOSAIDEN_SIGNING_SECRET; // mcsig_xxxx

async function call(method, path, body = "") {
  const ts = Math.floor(Date.now() / 1000).toString();
  const nonce = randomBytes(16).toString("hex");          // جديدٌ لكل نداء
  const bodyHash = createHash("sha256").update(body).digest("hex");
  const line = `${ts}\n${nonce}\n${method}\n${path}\n${bodyHash}`;
  const sig = "v1=" + createHmac("sha256", SECRET).update(line).digest("hex");
  const r = await fetch("https://mosaiden.com" + path, {
    method, body: body || undefined,
    headers: { Authorization: `Bearer ${API_KEY}`, "X-Mosaiden-Timestamp": ts,
               "X-Mosaiden-Nonce": nonce, "X-Mosaiden-Signature": sig, "Content-Type": "application/json" },
  });
  return r.json();
}

await call("GET", "/api/carrier/v1/shipments?status=assigned");
await call("POST", "/api/carrier/v1/shipments/<id>/status",
  JSON.stringify({ status: "accepted", trackingNumber: "TRD123456" }));