GROperator

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

English

الشحنات

تُنشأ الشحنة عبر المحرك نفسه الذي تستخدمه لوحة التحكم: فحص التغطية، والحصة الشهرية، والتسعير من بطاقة الأسعار، وتاريخ التسليم المتوقع، ورقم التتبع، وحدث الـ Webhook shipment.created كلها مطابقة. يشرح هذا الدليل إنشاء الشحنات لتاجر أو لمرسل لمرة واحدة، وكيف تعمل المرتجعات والاستبدال، وكيف تنتقل الشحنة بين حالاتها، وكيف تتتبعها وتطبع بوليصتها وتعدّلها وتلغيها.

النطاقات: shipments:write للإنشاء والتعديل والإلغاء؛ وshipments:read للعرض والتتبع والطباعة. الكتابة لا تشمل القراءة. وفي الدخول بكلمة المرور تُفحص صلاحية لوحة التحكم بالضبط: orders:create للإنشاء وorders:update للتعديل وorders:cancel للإلغاء. ومفتاح الـ API يحتاج النطاق فقط.

للأرقام حدود عليا (مثلاً الوزن حتى 9,999,999 كجم وكل بعد حتى 100,000 سم)؛ والقيم الأكبر ترد بـ 400 validation_failed. راجع الاصطلاحات.

الطلب POST /shipments يرد 201 مع الشحنة كاملة. لا تُرسل رسوم الشحن أبداً: تُحسب من بطاقة أسعار شركتك. ولعرض الرسوم قبل الطلب استخدم عرض سعر.

الخيار sender.type = "merchant" يحجز الشحنة لأحد تجارك. sender.merchant هو معرّف التاجر أو اسم الحساب بدقة (لا فرق بين الصغير والكبير ولا بين صيغ الحروف العربية). اسم يشترك فيه تاجران يرد بـ 422 merchant.ambiguous ومعه details.candidates: استخدم المعرّف. وحين تحذف pickup يكون عنوان التاجر الرئيسي المحفوظ هو عنوان الاستلام.

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
  }
}'
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
}

الخيار sender.type = "custom" لشخص أو جهة ليست من تجارك، مثل عميل في موقعك يشحن طرداً. يحتاج sender.name وsender.phone وعنوان pickup. وتُحجز الشحنة على حساب الزبائن المشترك للشركة. الأماكن هنا بأسماء عربية: اختلافات الإملاء تُعالج عنك (الأماكن بالاسم).

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: web-order-58213" \
  -d '{
  "reference": "WEB-58213",
  "serviceTier": "express",
  "sender": {
    "type": "custom",
    "name": "Sara Ahmed",
    "phone": "0501234567",
    "email": "sara@example.com"
  },
  "pickup": {
    "country": "SA",
    "city": "الرياض",
    "district": "حي العليا",
    "addressLine": "طريق الملك فهد، مبنى 12",
    "shortAddress": "RNBA6769",
    "latitude": 24.7136,
    "longitude": 46.6753
  },
  "recipient": {
    "country": "SA",
    "city": "جده",
    "district": "حي البرية",
    "addressLine": "شارع الأمير سلطان، عمارة 4",
    "shortAddress": "JEDA2345",
    "name": "خالد العتيبي",
    "phone": "0555123456",
    "secondaryPhone": "0555987654"
  },
  "parcel": {
    "weightKg": 3,
    "lengthCm": 40,
    "widthCm": 30,
    "heightCm": 20,
    "description": "Clothes",
    "declaredValue": 600
  },
  "payment": {
    "codAmount": 0,
    "freightOnDelivery": true
  }
}'

الحقول المطلوبة موضّحة. وما عداها اختياري.

الحقل التفاصيل
reference مرجع طلبك، حتى 100 محرف. يُطبع على البوليصة ويمكن البحث به
serviceType delivery (الافتراضي) أو exchange أو return
serviceTier standard (الافتراضي) أو express أو sameDay. يحدد تاريخ التسليم المتوقع
sender مطلوب لاعتماد المفتاح والموظفين. type هو merchant أو custom. حساب التاجر يرسل دائماً باسم تاجره ولا يستطيع custom (403)
sender.merchant مطلوب عند type: merchant: المعرّف أو الاسم بدقة
sender.name وsender.phone مطلوبان عند type: custom. وsender.email اختياري
pickup مكان استلام المندوب. اختياري لمرسل تاجر (يُستخدم العنوان الرئيسي)، ومطلوب للمرسل المخصص وللمرتجع
pickup.country اختياري حين يكون اسم المدينة غير ملتبس
pickup.city وpickup.district مطلوبان عند إرسال pickup. معرّف أو رمز أو اسم
pickup.addressLine مطلوب، حتى 500 محرف: الشارع والمبنى ومعلم
pickup.shortAddress العنوان الوطني المختصر، 4 أحرف ثم 4 أرقام. مطلوب للاستلام داخل السعودية
pickup.latitude وpickup.longitude اختياريان، من -90 إلى 90 ومن -180 إلى 180
pickup.branch معرّف أو رمز أو اسم فرع، اختياري. افتراضياً يُختار الفرع الذي يغطي حي الاستلام تلقائياً؛ وإن لم يغطه فرع أو غطاه أكثر من فرع فيجب تسمية فرع (branch_coverage.no_coverage_for_city وbranch_coverage.ambiguous_coverage)
recipient مطلوب إلا في المرتجعات. حقول العنوان نفسها في pickup وكلها مطلوبة بالطريقة نفسها
recipient.name مطلوب، حتى 200 محرف
recipient.phone مطلوب، حتى 30 محرفاً: أرقام ومسافات و+ و- وأقواس
recipient.secondaryPhone هاتف ثانٍ اختياري بالصيغة نفسها
parcel.weightKg مطلوب، أكبر من 0. وزن الشحنة كلها
parcel.lengthCm وwidthCm وheightCm مطلوبة، أكبر من 0. أبعاد الشحنة كلها
parcel.pieces من 1 إلى 1000، الافتراضي 1
parcel.description محتوى الطرد، حتى 500 محرف، يظهر على البوليصة
parcel.declaredValue قيمة البضاعة، 0 أو أكثر، الافتراضي 0
parcel.fragile وflammable وhazardous وcontainsAlcohol وliquid وhighValue علامات مناولة، الافتراضي false. قد تضيف رسوم مناولة
parcel.requiresColdChain الافتراضي false. عند true يصبح parcel.coldChainRange مطلوباً: frozen أو chilled أو ambient
payment.codAmount المبلغ الذي يحصّله المندوب من المستلم، 0 أو أكثر، الافتراضي 0. يجب أن يكون 0 في المرتجع
payment.freightOnDelivery true حين يدفع المستلم رسوم الشحن عند الباب. الافتراضي false
delivery.allowOpenPackage يحق للمستلم فتح الطرد قبل القبول. الافتراضي false
delivery.requireSignature التوقيع مطلوب. الافتراضي true
delivery.requireIdVerification يتحقق المندوب من هوية المستلم. الافتراضي false
delivery.allowNeighborDelivery يجوز أن يستلم الجار. الافتراضي true

الحقل parcel.chargeableWeightKg في الرد هو الأكبر من الوزن الفعلي والوزن الحجمي؛ وعليه يُبنى سعرك.

المرتجع يستلم طرداً من عميل ويعيده إلى التاجر. استخدم serviceType: "return" مع مرسل تاجر. pickup هو عنوان العميل (المكان الذي يستلم منه المندوب) وهو مطلوب. لا يوجد recipient: يذهب الطرد إلى عنوان التاجر الرئيسي المحفوظ، وتؤخذ بيانات المستلم منه. ولا يجوز أن يحمل المرتجع مبلغ دفع عند الاستلام (payment.codAmount يجب أن يكون 0).

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: return-ORD-1001" \
  -d '{
  "reference": "RET-1001",
  "serviceType": "return",
  "sender": {
    "type": "merchant",
    "merchant": "Noor Electronics"
  },
  "pickup": {
    "country": "SA",
    "city": "Riyadh",
    "district": "Al Olaya",
    "addressLine": "King Fahd Road, Building 12, Floor 3",
    "shortAddress": "RNBA6769"
  },
  "parcel": {
    "weightKg": 1.5,
    "lengthCm": 20,
    "widthCm": 15,
    "heightCm": 10,
    "description": "Returned phone case"
  }
}'

الاستبدال (serviceType: "exchange") يوصّل صنفاً بديلاً إلى المستلم ويأتي معه شحنة إرجاع مرتبطة للصنف العائد. تنشئه كتوصيل عادي مع recipient. وإلغاء الاستبدال يلغي معه المرتجع المعلّق، ولا يمكن تغيير نوع الخدمة بعد إنشاء المرتجع المرتبط.

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: exchange-ORD-1001" \
  -d '{
  "reference": "EXC-1001",
  "serviceType": "exchange",
  "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,
    "description": "Replacement phone case"
  }
}'

أرسل Idempotency-Key مع كل إنشاء، مشتقاً من طلبك أنت (مثل order-1001). إن ضاع الرد فأعد الإرسال نفسه: يرجع الرد الأول مع Idempotent-Replayed: true ولا تُنشأ شحنة ثانية. راجع الاصطلاحات.

الجسم الذي يخالف قاعدة يُرفض بـ 400 validation_failed، ويربط details.errors كل مسار حقل فاشل برسائله، فتعرض كل المشاكل دفعة واحدة:

JSON
{
  "code": "validation_failed",
  "message": "One or more fields are invalid.",
  "status": 400,
  "details": {
    "errors": {
      "recipient.phone": [
        "Recipient phone is required."
      ],
      "parcel.weightKg": [
        "Weight must be greater than 0."
      ],
      "recipient.shortAddress": [
        "Short address must be 4 letters followed by 4 digits, for example RNBA6769."
      ]
    },
    "messageAr": "بعض الحقول غير صالحة."
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

العناوين في السعودية تحتاج العنوان المختصر. هنا كان الاستلام في السعودية ولم يُرسل:

JSON
{
  "code": "validation_failed",
  "message": "One or more fields are invalid.",
  "status": 400,
  "details": {
    "errors": {
      "pickup.shortAddress": [
        "Short address is required for a pickup in Saudi Arabia (e.g. RNBA6769)."
      ]
    },
    "messageAr": "بعض الحقول غير صالحة."
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

لكل شحنة مفتاح status (نص مثل outForDelivery) ورمزها الرقمي statusCode وتسميتان باللغتين وإشارة isFinal. الفهرس واحد للجميع ويقدمه GET /shipments/statuses؛ اجلبه مرة وخزّنه. واستخدم المفتاح في شيفرتك.

المراحل والمسار المعتاد:

Text
Pickup        created → pickupScheduled → outForPickup → pickedUp
Linehaul      arrivedAtOriginHub → inTransit → arrivedAtDestinationHub → sortedToShelf
Warehouse     onHoldWarehouse → (holdExpiredPendingAction)
Delivery      assignedToCourier → outForDelivery → delivered
                                   ↘ deliveryAttempted / postponedByCustomer / withCourier
                                     (a new attempt returns to outForDelivery)
Exceptions    rtoInitiated → rtoInTransit → returnedToSender
              cancelled, lost, damaged, disposed, partiallyDelivered

لا يلزم أن تمر الشحنة بكل حالة، والأرقام تجمّع المراحل ولا تضمن ترتيباً. والحالات النهائية لا تتغير بعدها أبداً: delivered وreturnedToSender وcancelled وlost وdisposed.

المرحلةالرمزالمفتاح (status)الاسمنهائية
الاستلام1010draftمسودة
Draft
الاستلام1020createdتم إنشاء الطلب
Order Created
الاستلام1030pickupScheduledمجدول للاستلام
Pickup Scheduled
الاستلام1040outForPickupخرج للاستلام
Out For Pickup
الاستلام1050pickedUpتم الاستلام
Picked Up
الفرز والنقل بين المدن2010arrivedAtOriginHubوصل مركز الفرز الأول
Arrived at Origin Hub
الفرز والنقل بين المدن2020inTransitجاري النقل بين المدن
In Transit
الفرز والنقل بين المدن2030arrivedAtDestinationHubوصل مركز التوزيع النهائي
Arrived at Destination Hub
الفرز والنقل بين المدن2040sortedToShelfمفروز على الرف
Sorted to Shelf
التخزين بالمستودع3010onHoldWarehouseمخزن بالمستودع
On Hold in Warehouse
التخزين بالمستودع3020holdExpiredPendingActionانتهت مهلة التخزين
Hold Expired - Action Needed
التوصيل النهائي4005assignedToCourierمسندة للمندوب
Assigned to Courier
التوصيل النهائي4010outForDeliveryخرج للتوصيل
Out For Delivery
التوصيل النهائي4020deliveryAttemptedمحاولة توصيل فاشلة
Delivery Attempted
التوصيل النهائي4030postponedByCustomerمؤجل بطلب العميل
Postponed by Customer
التوصيل النهائي4040deliveredتم التسليم بنجاح
Delivered
نعم
التوصيل النهائي4050partiallyDeliveredتسليم جزئي
Partially Delivered
التوصيل النهائي4060withCourierبعهدة المندوب (تعذّر التوصيل)
With courier (failed attempt)
الإرجاع والاستثناءات5010rtoInitiatedبدء الإرجاع للمرسل
RTO Initiated
الإرجاع والاستثناءات5020rtoInTransitالمرتجع في الطريق
RTO In Transit
الإرجاع والاستثناءات5030returnedToSenderتم الإرجاع للمرسل
Returned to Sender
نعم
الإرجاع والاستثناءات5040cancelledملغاة
Cancelled
نعم
الإرجاع والاستثناءات5050lostمفقودة
Lost
نعم
الإرجاع والاستثناءات5060damagedتالفة
Damaged
الإرجاع والاستثناءات5070disposedتم الإتلاف
Disposed
نعم

وعلى الشحنة إشارتان تغنيانك عن التخمين: canCancel (ما زال الإلغاء ممكناً) وisEditable (ما زال التعديل ممكناً).

الطلب GET /shipments/{trackingNumber}/tracking يرجع الحالة الحالية وتاريخ التسليم المتوقع والمسار الزمني من الأقدم. لا يتضمن أسماء موظفين داخليين. وnote موجود فقط عند محاولات التسليم الفاشلة والتأجيل والإلغاء والإرجاع والفقد والتلف، ويحمل سبباً يمكنك عرضه. أما location فمحجوز وغير مملوء حالياً.

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
    }
  ]
}

ولمتابعة التغييرات دون استعلام متكرر اشترك في الـ Webhooks.

الطلب GET /shipments/{trackingNumber} يرجع الشحنة الكاملة أعلاه. وشحنة تخص جهة أخرى ترد بـ 404 shipment.not_found.

أما GET /shipments فيسرد الشحنات من الأحدث، مرقّماً، مع فلاتر تجتمع بـ AND: status (واحدة أو أكثر مفصولة بفواصل، بالمفاتيح أو الأكواد الرقمية)، وmerchant (المعرّف أو الاسم بدقة)، وreference (تطابق تام دون اعتبار حالة الأحرف)، وtrackingNumber، وrecipientPhone (جزء منه)، وcity (مدينة الوجهة: معرّف أو رمز أو اسم)، وcreatedFrom وcreatedTo (ISO 8601)، وsearch نص حر.

GET /shipments
curl -G "https://api.goldrock.live/api/public/v1/shipments" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  --data-urlencode 'status=created,outForDelivery' \
  --data-urlencode 'createdFrom=2026-01-01T00:00:00Z' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=25'
JSON
{
  "items": [
    {
      "trackingNumber": "AWB-RUH-000123",
      "reference": "ORD-1001",
      "status": "outForDelivery",
      "statusLabelAr": "خرج للتوصيل",
      "statusLabelEn": "Out For Delivery",
      "merchant": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Noor Electronics"
      },
      "senderName": "Noor Electronics",
      "recipientName": "Khaled Alotaibi",
      "recipientPhone": "0555123456",
      "city": {
        "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
        "nameAr": "الرياض",
        "nameEn": "Riyadh"
      },
      "district": {
        "id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
        "nameAr": "العليا",
        "nameEn": "Al Olaya"
      },
      "codAmount": 199.5,
      "shippingFee": 30,
      "createdAt": "2026-01-15T09:30:00Z",
      "estimatedDeliveryDate": "2026-01-17"
    }
  ],
  "page": 1,
  "pageSize": 25,
  "totalCount": 1,
  "totalPages": 1
}

الطلب GET /shipments/{trackingNumber}/label يرجع بوليصة الشحن PDF (100 × 150 مم) بهوية شركتك. الرد ثنائي: احفظه ولا تحلله كـ JSON.

GET /shipments/AWB-RUH-000123/label
curl "https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/label" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -o AWB-RUH-000123.pdf

الطلب PUT /shipments/{trackingNumber} يغيّر ما ترسله فقط. reason مطلوب (حتى 300 محرف) ويُحفظ في سجل تدقيق الشحنة. ويلزم حقل آخر واحد على الأقل.

يمكنك تغيير: reference المرجع، والمستلم (الاسم والهواتف والعنوان بالأسماء والإحداثيات)، والطرد (الوزن والأبعاد والقطع والقيمة المصرّح بها)، والدفع (codAmount وfreightOnDelivery). عند إرسال حقول العنوان يُعاد حل عنوان المستلم. يمكنك إرسال district وحده: يُبحث عنه حينئذ داخل المدينة الحالية للشحنة. أما إن أرسلت city فيجب إرسال district معها (400 validation_failed). والأماكن تقبل معرّفاً أو رمزاً أو اسماً كما في كل مكان. وتُعاد حسبة الرسوم إن تغيّر ما يؤثر فيها.

لا يمكن تغيير المرسل ولا عنوان الاستلام ولا نوع الخدمة ودرجتها ولا علامات المناولة. وحسابات التجار لا تعدّل الشحنات.

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

PUT /shipments/AWB-RUH-000123
curl -X PUT "https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer changed the delivery address",
  "recipient": {
    "city": "Riyadh",
    "district": "Al Malqa",
    "addressLine": "Anas Bin Malik Road, Villa 7",
    "shortAddress": "RMLA1234",
    "phone": "0555000111"
  },
  "payment": {
    "codAmount": 150
  }
}'

الطلب POST /shipments/{trackingNumber}/cancel مع reason اختياري (حتى 500 محرف). ممكن حين تكون الشحنة مسودة أو منشأة أو مجدولة للاستلام. وبعدها يرد 422 shipment.cannot_cancel. افحص canCancel أولاً. وحسابات التجار لا تلغي عبر الـ API.

POST /shipments/AWB-RUH-000123/cancel
curl -X POST "https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/cancel" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer cancelled the order"
}'
JSON
{
  "code": "shipment.cannot_cancel",
  "message": "The shipment can no longer be cancelled in its current status.",
  "status": 422,
  "details": {
    "messageAr": "لا يمكن إلغاء الشحنة في حالتها الحالية."
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
الرمز السبب
validation_failed حقل مفقود أو خاطئ الصيغة. اقرأ details.errors
geo_*_not_found وgeo_*_ambiguous اسم مكان لم يطابق، راجع الأماكن بالاسم
merchant.not_found وmerchant.ambiguous معرّف التاجر أو اسمه خاطئ، أو اسم يشترك فيه تاجران
coverage.destination_not_covered وcoverage.pickup_not_covered الشركة لا تخدم تلك المدينة
branch_coverage.no_coverage_for_city وbranch_coverage.ambiguous_coverage سمِّ فرع الاستلام صراحة
quota.monthly_shipments_limit_reached بلغت الشركة حد الشحنات الشهري
pricing.default_rate_card_not_found ليس للشركة بطاقة أسعار بعد
shipment.cannot_cancel وshipment.not_editable وshipment.field_locked_out_for_delivery تجاوزت الشحنة النقطة التي يسمح فيها الإجراء
idempotency_key_reused أُرسل Idempotency-Key نفسه مع جسم مختلف

راجع مرجع الأخطاء لكل الرموز.