GROperator

جارٍ التحميل…

English

ابنِ موقع شركة الشحن

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

قاعدة واحدة تشكّل كل شيء: مفتاح الـ API وسرّه يبقيان على خادمك، ولا يصلان المتصفح أبداً. المتصفح يكلّم خادم موقعك، وخادمك يكلّم LastMile.

المتصفحصفحاتك بلا أسرارخادم موقعكيحمل المفتاح والسرواجهة LastMile/api/public/v1Webhooks موقّعة/api/...المفتاح + السر

صفحة موقعك طلبات خادمك النطاقات
صفحة التتبع GET /shipments/{trackingNumber} (للتحقق من الزائر) ثم GET /shipments/{trackingNumber}/tracking shipments:read
حاسبة الأسعار GET /geography/coverage/cities وGET /geography/districts وPOST /pricing/quote geography:read وpricing:read
فاحص التغطية GET /geography/coverage geography:read
نموذج «اشحن الآن» GET /geography/resolve وPOST /pricing/quote وPOST /shipments وGET /shipments/{trackingNumber}/label geography:read وpricing:read وshipments:write وshipments:read
منطقة دخول التجار POST /auth/login وPOST /auth/refresh ثم GET /shipments وPOST /shipments برمز التاجر صلاحيات حساب التاجر نفسه
تحديثات الحالة Webhooks إلى خادمك؛ وPOST /merchants/{merchantId}/webhooks مرة واحدة للاشتراك webhooks:manage وmerchants:read

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

كل شيء يبدأ بدالة مساعدة صغيرة على خادمك تضيف بيانات الاعتماد. والمسارات تحتها هي نقاط النهاية التي تستدعيها صفحاتك. استبدل متغيرات البيئة LASTMILE_* بقيمك؛ وLASTMILE_API_URL هو العنوان الأساسي للواجهة.

// server.js — Node.js 18+ and Express. The key and secret live in environment variables on this server only.
import express from "express";
import crypto from "node:crypto";

const API = `${process.env.LASTMILE_API_URL}/api/public/v1`;
const app = express();

// One helper that every route uses. The browser never sees the headers.
async function lastmile(path, { method = "GET", body, idempotencyKey, acceptLanguage = "en" } = {}) {
  const response = await fetch(`${API}${path}`, {
    method,
    headers: {
      "X-API-Key": process.env.LASTMILE_API_KEY,
      "X-API-Secret": process.env.LASTMILE_API_SECRET,
      "Accept-Language": acceptLanguage,
      ...(body ? { "Content-Type": "application/json" } : {}),
      ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = response.status === 204 ? null : await response.json();
  return { status: response.status, data };
}

// Webhook route first: it needs the raw body, so it is registered before express.json().
app.post("/hooks/lastmile", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", process.env.LASTMILE_WEBHOOK_SECRET).update(req.body).digest("hex");
  const received = String(req.get("X-Signature") ?? "");
  const ok = expected.length === received.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  // Save it and answer quickly. Update your own order, notify the customer.
  console.log("webhook", event.event, event.data.trackingNumber);
  res.sendStatus(200);
});

app.use(express.json());

// ---- Coverage checker: GET /api/coverage?city=جده ----------------------------------------------------------------
app.get("/api/coverage", async (req, res) => {
  const query = new URLSearchParams({ country: "SA", city: String(req.query.city ?? "") });
  const { status, data } = await lastmile(`/geography/coverage?${query}`);
  res.status(status).json(data);
});

// ---- Cities and districts for the form dropdowns (cache these in production) -------------------------------------
app.get("/api/cities", async (_req, res) => {
  const { status, data } = await lastmile("/geography/coverage/cities?country=SA&pageSize=100");
  res.status(status).json(data);
});

app.get("/api/districts", async (req, res) => {
  const query = new URLSearchParams({ country: "SA", city: String(req.query.city ?? ""), pageSize: "100" });
  const { status, data } = await lastmile(`/geography/districts?${query}`);
  res.status(status).json(data);
});

// ---- Address validation as the customer types: GET /api/resolve?city=...&district=... --------------------------------
app.get("/api/resolve", async (req, res) => {
  const query = new URLSearchParams({ country: "SA", city: String(req.query.city ?? ""), district: String(req.query.district ?? "") });
  const { status, data } = await lastmile(`/geography/resolve?${query}`);
  // 422 carries data.details.candidates: show them as "Did you mean...?" buttons.
  res.status(status).json(data);
});

// ---- Price calculator: POST /api/quote ---------------------------------------------------------------------------
app.post("/api/quote", async (req, res) => {
  const { fromCity, toCity, weightKg, lengthCm, widthCm, heightCm, codAmount } = req.body;
  const { status, data } = await lastmile("/pricing/quote", {
    method: "POST",
    body: {
      pickup: { country: "SA", city: fromCity },
      recipient: { country: "SA", city: toCity },
      parcel: { weightKg, lengthCm, widthCm, heightCm },
      payment: { codAmount: codAmount ?? 0 },
      serviceTier: "standard",
    },
  });
  res.status(status).json(data);
});

// ---- Tracking page: GET /api/track/:trackingNumber?phone=1234 -----------------------------------------------------
// The key can read every shipment of the company, so this route decides what a visitor may see:
// the tracking number plus the last 4 digits of the recipient phone.
app.get("/api/track/:trackingNumber", async (req, res) => {
  const tn = encodeURIComponent(req.params.trackingNumber);
  const shipment = await lastmile(`/shipments/${tn}`);
  if (shipment.status !== 200) return res.status(404).json({ message: "Shipment not found" });

  const last4 = String(shipment.data.recipient.phone ?? "").replace(/\D/g, "").slice(-4);
  if (!last4 || last4 !== String(req.query.phone ?? "")) return res.status(404).json({ message: "Shipment not found" });

  const tracking = await lastmile(`/shipments/${tn}/tracking`);
  res.status(tracking.status).json(tracking.data); // statuses come in both languages: statusLabelAr / statusLabelEn
});

// ---- "Ship now" form: POST /api/order ----------------------------------------------------------------------------
app.post("/api/order", async (req, res) => {
  const order = req.body; // validate this with your own schema first
  const { status, data } = await lastmile("/shipments", {
    method: "POST",
    // Derive the key from YOUR order id: a double click or a retry can never create two shipments.
    idempotencyKey: `web-order-${order.id}`,
    body: {
      reference: `WEB-${order.id}`,
      serviceTier: order.express ? "express" : "standard",
      sender: { type: "custom", name: order.senderName, phone: order.senderPhone },
      pickup: order.pickup, // { country, city, district, addressLine, shortAddress }
      recipient: order.recipient, // { country, city, district, addressLine, shortAddress, name, phone }
      parcel: order.parcel, // { weightKg, lengthCm, widthCm, heightCm, description }
      payment: { codAmount: order.codAmount ?? 0 },
    },
  });
  // 422 geo_* errors: show data.details.candidates. 400: show data.details.errors next to the fields.
  res.status(status).json(status === 201 ? { trackingNumber: data.trackingNumber, fee: data.payment.shippingFee } : data);
});

app.listen(3000);

المفتاح بنطاق shipments:read يقرأ كل شحنات الشركة. لو أرجع مسارك العام أي شحنة لأي رقم تتبع لاستطاع أي شخص قراءة أسماء الآخرين وهواتفهم وعناوينهم. لذلك يقرأ المسار أعلاه الشحنة أولاً ولا يجيب إلا إن قدّم الزائر آخر 4 أرقام من هاتف المستلم، ويرجع المسار الزمني لا الشحنة كلها. اختر الإثبات المناسب لعملك، لكن لا تكشف أبداً رد GET /shipments/{trackingNumber} الخام.

تطلب الصفحة رقم التتبع (وفحص الهاتف) وتستدعي /api/track/... وترسم قائمة events. لكل حدث statusLabelAr وstatusLabelEn، فاعرض ما يطابق لغة صفحتك. والحالات النهائية (delivered وreturnedToSender وcancelled وlost وdisposed، راجع فهرس الحالات) لا تتغير بعدها، فأوقف تحديث الصفحة حين تكون الحالة الحالية إحداها.

املأ قائمتي المدينتين من GET /geography/coverage/cities (مخزّنة على خادمك لأنها نادراً ما تتغير). وعند الإرسال استدعِ /api/quote. إن رجع deliverable: false فاعرض «لا نوصّل إلى هناك بعد» بدل السعر. عروض الأسعار مجانية ولا تنشئ شيئاً، فيمكنك التسعير عند كل تغيير. راجع عروض الأسعار.

حقل مدينة (أو القائمة نفسها) يستدعي /api/coverage ويعرض إجابتين: التوصيل إلى هذه المدينة، والاستلام منها. والاسم غير المطابق يرد بـ 422 geo_city_not_found مع اقتراحات: اعرضها. راجع الأماكن بالاسم.

  1. يدخل العميل المرسل والمستلم والطرد والعناوين. فضّل القوائم المنسدلة للمدينة والحي؛ وإن سمحت بالكتابة فاستدعِ /api/resolve حين يفقد الحقل التركيز واعرض details.candidates عند 422.
  2. اعرض السعر من /api/quote قبل أن يؤكد العميل.
  3. عند التأكيد استدعِ /api/order. يرسل الخادم الشحنة مع Idempotency-Key مبني من رقم طلبك أنت، فلا يمكن للنقر المزدوج أو إعادة المحاولة أن تنشئ شحنتين.
  4. عند 201 اعرض trackingNumber وقدّم البوليصة (GET /shipments/{trackingNumber}/label، ملف PDF) ورابط التتبع.
  5. عند 400 اعرض رسائل details.errors بجانب الحقول المقابلة؛ وعند 422 برمز geo_* دع العميل يختار من المقترحات.

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

Express
// Merchant portal on the same Express server: each merchant signs in with its own username and password.
// The token pair stays in a SERVER-side session; the browser only holds the session cookie.
import session from "express-session"; // use a persistent store (Redis, a database) in production

app.use(
  session({
    secret: process.env.SESSION_SECRET,
    resave: false,
    saveUninitialized: false,
    cookie: { httpOnly: true, secure: true, sameSite: "lax", maxAge: 8 * 3600 * 1000 },
  }),
);

async function asUser(req, path, init = {}) {
  const s = req.session.lastmile;
  if (!s) return { status: 401, data: { code: "unauthorized" } };

  // Refresh one minute early. The refresh token is single use: store the new pair.
  if (Date.now() > s.expiresAt) {
    const r = await fetch(`${API}/auth/refresh`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ refreshToken: s.refreshToken }),
    });
    if (!r.ok) {
      req.session.destroy(() => {});
      return { status: 401, data: { code: "unauthorized" } };
    }
    const t = await r.json();
    req.session.lastmile = { ...t, expiresAt: Date.now() + (t.expiresIn - 60) * 1000 };
  }

  const response = await fetch(`${API}${path}`, {
    ...init,
    headers: { "Content-Type": "application/json", ...init.headers, Authorization: `Bearer ${req.session.lastmile.accessToken}` },
  });
  return { status: response.status, data: await response.json() };
}

app.post("/portal/login", async (req, res) => {
  const response = await fetch(`${API}/auth/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ username: req.body.username, password: req.body.password }),
  });
  const tokens = await response.json();
  if (!response.ok) return res.status(response.status).json({ code: tokens.code, message: tokens.message });

  req.session.lastmile = { ...tokens, expiresAt: Date.now() + (tokens.expiresIn - 60) * 1000 };
  res.sendStatus(204);
});

// A merchant login only ever sees its own merchant's shipments: no filter by merchant is needed.
app.get("/portal/shipments", async (req, res) => {
  const { status, data } = await asUser(req, `/shipments?page=${Number(req.query.page) || 1}&pageSize=25`);
  res.status(status).json(data);
});

app.post("/portal/shipments", async (req, res) => {
  const { status, data } = await asUser(req, "/shipments", {
    method: "POST",
    headers: { "Idempotency-Key": `portal-${req.session.id}-${req.body.clientRequestId}` },
    body: JSON.stringify({
      reference: req.body.reference,
      // sender is optional for a merchant login: it always sends as its own merchant, from its primary address
      recipient: req.body.recipient,
      parcel: req.body.parcel,
      payment: { codAmount: req.body.codAmount ?? 0 },
    }),
  });
  res.status(status).json(data);
});

اشترك مرة لكل تاجر ودع خادمك يستقبل الأحداث. يصل الإرسال الموقّع إلى /hooks/lastmile (موجود في الخادم أعلاه). حدّث الطلب في قاعدة بياناتك ثم أشعر العميل برسالة نصية أو بريد. راجع الـ Webhooks.

POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks
curl -X POST "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://shop.example.com/hooks/lastmile",
  "events": [
    "shipment.created",
    "shipment.out_for_delivery",
    "shipment.delivered"
  ],
  "description": "Order system"
}'
  • المفتاح والسر في متغيرات بيئة الخادم فقط.
  • مساراتك العامة (/api/track و/api/quote و/api/order) عليها تحديد معدل أو CAPTCHA، لأنها تستهلك حصتك (120 طلباً في الدقيقة لكل مفتاح).
  • تخزّن الدول والمدن والأحياء والحالات.
  • كل إنشاء يرسل Idempotency-Key مأخوذاً من بياناتك.
  • تحوّل code الأخطاء إلى رسائل ودودة باللغتين، وتعرض details.candidates للأماكن.
  • تتحقق من توقيع الـ Webhooks وترد 2xx بسرعة.
  • لا ترسل message الخام للعميل قبل التأكد أنه مناسب لصفحتك.