GROperator

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

English

نظرة عامة وبداية سريعة

واجهة LastMile البرمجية العامة تمكّن شركة الشحن من بناء موقعها أو تطبيقها أو تكاملها الداخلي فوق حسابها في LastMile. هي واجهة JSON عبر HTTPS: كل ما تفعله بالشحنة من لوحة التحكم (إنشاؤها وتسعيرها وتتبعها وطباعة بوليصتها وإلغاؤها) يمكنك فعله من شيفرتك، إضافة إلى البيانات المساندة لبناء تجربة جيدة مثل الدول والمدن والأحياء والتغطية والتجار وعناوينهم المحفوظة.

كل نقاط النهاية تحت مسار واحد ذي إصدار: /api/public/v1. الأمثلة في هذا الموقع تستخدم عنوان الواجهة المضبوط لهذه الوثائق متبوعاً بهذا المسار.

  • صفحة تتبع: ابحث عن أي شحنة برقم التتبع واعرض مسار حالتها.
  • حاسبة أسعار وفاحص تغطية للزائر الذي لم يطلب بعد.
  • نموذج طلب شحن يتحقق من العنوان ويعرض السعر ثم ينشئ الشحنة.
  • بوابة للتجار يسجّل فيها كل تاجر بحسابه (اسم المستخدم وكلمة المرور) ويرى شحناته فقط.
  • أتمتة داخلية: إنشاء الشحنات بالجملة من جدول بيانات أو من منصة متجر إلكتروني، مع وصول تحديثات الحالة إليك عبر Webhook.
مفتاح API وسرّه اسم المستخدم وكلمة المرور
الآلية أرسل X-API-Key و X-API-Secret مع كل طلب POST /auth/login ثم Authorization: Bearer <accessToken>
من ينشئه مدير الشركة في لوحة التحكم (الإعدادات ثم الربط البرمجي) مستخدم قائم في لوحة التحكم، ومنه حساب التاجر
الصلاحيات النطاقات (Scopes) التي تختارها للمفتاح صلاحيات ذلك المستخدم
الأنسب لـ المواقع والتكامل بين الخوادم العمل باسم مستخدم محدد، أو بوابة التجار

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

لا تعمل الواجهة لشركتك إلا بعد خطوتي تفعيل: أن تكون المنصة قد منحت شركتك قناة الربط البرمجي (API)، وأن يكون مدير الشركة قد شغّلها. وإلا ردّت كل الطلبات بـ 403 channel_disabled. يشرح تفعيل الواجهة الخطوتين وإنشاء المفتاح.

تحتاج مفتاح API وسراً بالنطاقات geography:read و pricing:read و shipments:read و shipments:write. الأمثلة تستخدم قيماً نائبة؛ استبدلها بقيمك.

الطلب GET /auth/me لا يحتاج نطاقاً. يخبرك بأي شركة أنت وما النطاقات التي يحملها الاعتماد.

GET /auth/me
curl "https://api.goldrock.live/api/public/v1/auth/me" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"
JSON
{
  "authMethod": "api_key",
  "company": {
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "name": "Fast Express",
    "slug": "fast-express"
  },
  "user": null,
  "apiKey": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Website integration"
  },
  "scopes": [
    "geography:read",
    "pricing:read",
    "shipments:read",
    "shipments:write"
  ],
  "permissions": [
    "orders:create",
    "orders:read"
  ]
}

إن ظهر 401 unauthorized فإحدى الترويستين مفقودة أو خاطئة. وإن ظهر 403 channel_disabled فالواجهة غير مفعّلة للشركة بعد.

تُطابَق الأماكن بالاسم، عربياً أو إنجليزياً، ولا يُنشأ شيء من طلب API. تحقق من العنوان قبل استخدامه. اختلافات الإملاء مقبولة: هنا جده تطابق جدة و حي البرية تطابق البرية. راجع الأماكن بالاسم.

GET /geography/resolve
curl -G "https://api.goldrock.live/api/public/v1/geography/resolve" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  --data-urlencode 'country=SA' \
  --data-urlencode 'city=جده' \
  --data-urlencode 'district=حي البرية'
JSON
{
  "country": {
    "id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
    "nameAr": "المملكة العربية السعودية",
    "nameEn": "Saudi Arabia"
  },
  "city": {
    "id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
    "nameAr": "جدة",
    "nameEn": "Jeddah"
  },
  "district": {
    "id": "e4b7a9d2-6c13-4d8e-b1f0-2a5c7e9f3b18",
    "nameAr": "البرية",
    "nameEn": "Al Bariyah"
  }
}

عرض السعر لا ينشئ شيئاً ولا يستهلك الحصة. إن كانت الشركة لا تغطي المسار فالرد يبقى 200 مع deliverable: false و reason.

POST /pricing/quote
curl -X POST "https://api.goldrock.live/api/public/v1/pricing/quote" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "merchant": "Noor Electronics",
  "pickup": {
    "country": "SA",
    "city": "Riyadh",
    "district": "Al Olaya"
  },
  "recipient": {
    "country": "SA",
    "city": "Jeddah",
    "district": "Al Rawdah"
  },
  "parcel": {
    "weightKg": 1.5,
    "lengthCm": 20,
    "widthCm": 15,
    "heightCm": 10
  },
  "payment": {
    "codAmount": 199.5
  },
  "serviceType": "delivery",
  "serviceTier": "standard"
}'
JSON
{
  "deliverable": true,
  "reason": null,
  "shippingFee": 25,
  "codFee": 5,
  "total": 30,
  "chargeableWeightKg": 1.5,
  "zone": {
    "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",
    "name": "Zone 2"
  },
  "breakdown": [
    {
      "code": "baseShipping",
      "label": "Base shipping",
      "amount": 25
    },
    {
      "code": "codFee",
      "label": "Cash on delivery fee",
      "amount": 5
    }
  ]
}

أرسل Idempotency-Key حتى لا تُنشأ نسخة مكررة عند إعادة المحاولة بعد خطأ في الشبكة. العناوين في السعودية تتطلب العنوان الوطني المختصر (4 أحرف و4 أرقام). رسوم الشحن تأتي دائماً من بطاقة أسعار شركتك: لا يمكنك إرسال رسوم.

POST /shipments
curl -X POST "https://api.goldrock.live/api/public/v1/shipments" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
  "reference": "ORD-1001",
  "serviceType": "delivery",
  "serviceTier": "standard",
  "sender": {
    "type": "merchant",
    "merchant": "Noor Electronics"
  },
  "recipient": {
    "country": "SA",
    "city": "Riyadh",
    "district": "Al Olaya",
    "addressLine": "King Fahd Road, Building 12, Floor 3",
    "shortAddress": "RNBA6769",
    "name": "Khaled Alotaibi",
    "phone": "0555123456"
  },
  "parcel": {
    "weightKg": 1.5,
    "lengthCm": 20,
    "widthCm": 15,
    "heightCm": 10,
    "pieces": 1,
    "description": "Mobile phone case",
    "declaredValue": 250,
    "fragile": false
  },
  "payment": {
    "codAmount": 199.5,
    "freightOnDelivery": false
  },
  "delivery": {
    "allowOpenPackage": false,
    "requireSignature": true
  }
}'

الرد 201 مع الشحنة كاملة. احتفظ بـ trackingNumber: هو ما يعرّف الشحنة في كل المسارات الأخرى.

JSON
{
  "trackingNumber": "AWB-RUH-000123",
  "reference": "ORD-1001",
  "status": "created",
  "statusCode": 1020,
  "statusLabelAr": "تم إنشاء الطلب",
  "statusLabelEn": "Order Created",
  "isFinal": false,
  "serviceType": "delivery",
  "serviceTier": "standard",
  "source": "api",
  "createdAt": "2026-01-15T09:30:00Z",
  "estimatedDeliveryDate": "2026-01-17",
  "sender": {
    "type": "merchant",
    "name": "Noor Electronics",
    "phone": "0501234567",
    "email": "orders@noor-electronics.example",
    "merchant": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Noor Electronics"
    }
  },
  "pickup": {
    "country": {
      "id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
      "nameAr": "المملكة العربية السعودية",
      "nameEn": "Saudi Arabia"
    },
    "city": {
      "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
      "nameAr": "الرياض",
      "nameEn": "Riyadh"
    },
    "district": {
      "id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
      "nameAr": "العليا",
      "nameEn": "Al Olaya"
    },
    "addressLine": "King Fahd Road, Warehouse 4",
    "shortAddress": "RNBA6769",
    "latitude": null,
    "longitude": null
  },
  "recipient": {
    "name": "Khaled Alotaibi",
    "phone": "0555123456",
    "secondaryPhone": null,
    "country": {
      "id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
      "nameAr": "المملكة العربية السعودية",
      "nameEn": "Saudi Arabia"
    },
    "city": {
      "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
      "nameAr": "الرياض",
      "nameEn": "Riyadh"
    },
    "district": {
      "id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
      "nameAr": "العليا",
      "nameEn": "Al Olaya"
    },
    "addressLine": "King Fahd Road, Building 12, Floor 3",
    "shortAddress": "RNBA6769",
    "latitude": null,
    "longitude": null
  },
  "parcel": {
    "weightKg": 1.5,
    "lengthCm": 20,
    "widthCm": 15,
    "heightCm": 10,
    "chargeableWeightKg": 1.5,
    "pieces": 1,
    "description": "Mobile phone case",
    "declaredValue": 250,
    "fragile": false,
    "requiresColdChain": false,
    "coldChainRange": null,
    "flammable": false,
    "hazardous": false,
    "containsAlcohol": false,
    "liquid": false,
    "highValue": false
  },
  "delivery": {
    "allowOpenPackage": false,
    "requireSignature": true,
    "requireIdVerification": false,
    "allowNeighborDelivery": true
  },
  "payment": {
    "codAmount": 199.5,
    "shippingFee": 30,
    "freightOnDelivery": false
  },
  "pieces": [
    {
      "barcode": "AWB-RUH-000123-P1"
    }
  ],
  "branch": {
    "id": "8d3c7f52-4b1e-4a90-b6d2-1e5f9a0c3b74",
    "name": "Riyadh Hub"
  },
  "canCancel": true,
  "isEditable": true
}
GET /shipments/AWB-RUH-000123/tracking
curl "https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"
JSON
{
  "trackingNumber": "AWB-RUH-000123",
  "status": "outForDelivery",
  "statusLabelAr": "خرج للتوصيل",
  "statusLabelEn": "Out For Delivery",
  "estimatedDeliveryDate": "2026-01-17",
  "events": [
    {
      "status": "created",
      "statusLabelAr": "تم إنشاء الطلب",
      "statusLabelEn": "Order Created",
      "at": "2026-01-15T09:30:00Z",
      "note": null,
      "location": null
    },
    {
      "status": "pickedUp",
      "statusLabelAr": "تم الاستلام",
      "statusLabelEn": "Picked Up",
      "at": "2026-01-15T14:05:00Z",
      "note": null,
      "location": null
    },
    {
      "status": "outForDelivery",
      "statusLabelAr": "خرج للتوصيل",
      "statusLabelEn": "Out For Delivery",
      "at": "2026-01-17T07:40:00Z",
      "note": null,
      "location": null
    }
  ]
}