الشحنات
تُنشأ الشحنة عبر المحرك نفسه الذي تستخدمه لوحة التحكم: فحص التغطية، والحصة الشهرية، والتسعير من بطاقة الأسعار، وتاريخ التسليم المتوقع، ورقم التتبع، وحدث الـ 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 يكون عنوان التاجر الرئيسي المحفوظ هو عنوان الاستلام.
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
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "order-1001"
},
body: JSON.stringify({
"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
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: order-1001',
],
CURLOPT_POSTFIELDS => json_encode([
'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_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "order-1001",
},
json={
"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,
},
},
timeout=30,
)
print(response.status_code, response.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. وتُحجز الشحنة على حساب الزبائن المشترك للشركة. الأماكن هنا بأسماء عربية: اختلافات الإملاء تُعالج عنك (الأماكن بالاسم).
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
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "web-order-58213"
},
body: JSON.stringify({
"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
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: web-order-58213',
],
CURLOPT_POSTFIELDS => json_encode([
'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,
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "web-order-58213",
},
json={
"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,
},
},
timeout=30,
)
print(response.status_code, response.json())الحقول المطلوبة موضّحة. وما عداها اختياري.
| الحقل | التفاصيل |
|---|---|
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).
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"
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "return-ORD-1001"
},
body: JSON.stringify({
"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"
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: return-ORD-1001',
],
CURLOPT_POSTFIELDS => json_encode([
'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',
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "return-ORD-1001",
},
json={
"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",
},
},
timeout=30,
)
print(response.status_code, response.json())الاستبدال (serviceType: "exchange") يوصّل صنفاً بديلاً إلى المستلم ويأتي معه شحنة إرجاع مرتبطة للصنف العائد. تنشئه كتوصيل عادي مع recipient. وإلغاء الاستبدال يلغي معه المرتجع المعلّق، ولا يمكن تغيير نوع الخدمة بعد إنشاء المرتجع المرتبط.
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"
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "exchange-ORD-1001"
},
body: JSON.stringify({
"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"
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: exchange-ORD-1001',
],
CURLOPT_POSTFIELDS => json_encode([
'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',
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "exchange-ORD-1001",
},
json={
"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",
},
},
timeout=30,
)
print(response.status_code, response.json())أرسل Idempotency-Key مع كل إنشاء، مشتقاً من طلبك أنت (مثل order-1001). إن ضاع الرد فأعد الإرسال نفسه: يرجع الرد الأول مع Idempotent-Replayed: true ولا تُنشأ شحنة ثانية. راجع الاصطلاحات.
الجسم الذي يخالف قاعدة يُرفض بـ 400 validation_failed، ويربط details.errors كل مسار حقل فاشل برسائله، فتعرض كل المشاكل دفعة واحدة:
{
"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"
}العناوين في السعودية تحتاج العنوان المختصر. هنا كان الاستلام في السعودية ولم يُرسل:
{
"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؛ اجلبه مرة وخزّنه. واستخدم المفتاح في شيفرتك.
المراحل والمسار المعتاد:
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) | الاسم | نهائية |
|---|---|---|---|---|
| الاستلام | 1010 | draft | مسودة Draft | |
| الاستلام | 1020 | created | تم إنشاء الطلب Order Created | |
| الاستلام | 1030 | pickupScheduled | مجدول للاستلام Pickup Scheduled | |
| الاستلام | 1040 | outForPickup | خرج للاستلام Out For Pickup | |
| الاستلام | 1050 | pickedUp | تم الاستلام Picked Up | |
| الفرز والنقل بين المدن | 2010 | arrivedAtOriginHub | وصل مركز الفرز الأول Arrived at Origin Hub | |
| الفرز والنقل بين المدن | 2020 | inTransit | جاري النقل بين المدن In Transit | |
| الفرز والنقل بين المدن | 2030 | arrivedAtDestinationHub | وصل مركز التوزيع النهائي Arrived at Destination Hub | |
| الفرز والنقل بين المدن | 2040 | sortedToShelf | مفروز على الرف Sorted to Shelf | |
| التخزين بالمستودع | 3010 | onHoldWarehouse | مخزن بالمستودع On Hold in Warehouse | |
| التخزين بالمستودع | 3020 | holdExpiredPendingAction | انتهت مهلة التخزين Hold Expired - Action Needed | |
| التوصيل النهائي | 4005 | assignedToCourier | مسندة للمندوب Assigned to Courier | |
| التوصيل النهائي | 4010 | outForDelivery | خرج للتوصيل Out For Delivery | |
| التوصيل النهائي | 4020 | deliveryAttempted | محاولة توصيل فاشلة Delivery Attempted | |
| التوصيل النهائي | 4030 | postponedByCustomer | مؤجل بطلب العميل Postponed by Customer | |
| التوصيل النهائي | 4040 | delivered | تم التسليم بنجاح Delivered | نعم |
| التوصيل النهائي | 4050 | partiallyDelivered | تسليم جزئي Partially Delivered | |
| التوصيل النهائي | 4060 | withCourier | بعهدة المندوب (تعذّر التوصيل) With courier (failed attempt) | |
| الإرجاع والاستثناءات | 5010 | rtoInitiated | بدء الإرجاع للمرسل RTO Initiated | |
| الإرجاع والاستثناءات | 5020 | rtoInTransit | المرتجع في الطريق RTO In Transit | |
| الإرجاع والاستثناءات | 5030 | returnedToSender | تم الإرجاع للمرسل Returned to Sender | نعم |
| الإرجاع والاستثناءات | 5040 | cancelled | ملغاة Cancelled | نعم |
| الإرجاع والاستثناءات | 5050 | lost | مفقودة Lost | نعم |
| الإرجاع والاستثناءات | 5060 | damaged | تالفة Damaged | |
| الإرجاع والاستثناءات | 5070 | disposed | تم الإتلاف Disposed | نعم |
وعلى الشحنة إشارتان تغنيانك عن التخمين: canCancel (ما زال الإلغاء ممكناً) وisEditable (ما زال التعديل ممكناً).
الطلب GET /shipments/{trackingNumber}/tracking يرجع الحالة الحالية وتاريخ التسليم المتوقع والمسار الزمني من الأقدم. لا يتضمن أسماء موظفين داخليين. وnote موجود فقط عند محاولات التسليم الفاشلة والتأجيل والإلغاء والإرجاع والفقد والتلف، ويحمل سبباً يمكنك عرضه. أما location فمحجوز وغير مملوء حالياً.
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"const response = await fetch("https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking", {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.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 نص حر.
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'const params = new URLSearchParams({
"status": "created,outForDelivery",
"createdFrom": "2026-01-01T00:00:00Z",
"page": "1",
"pageSize": "25"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/shipments?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments?' . http_build_query([
'status' => 'created,outForDelivery',
'createdFrom' => '2026-01-01T00:00:00Z',
'page' => '1',
'pageSize' => '25',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"status": "created,outForDelivery",
"createdFrom": "2026-01-01T00:00:00Z",
"page": "1",
"pageSize": "25",
},
timeout=30,
)
print(response.status_code, response.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.
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.pdfconst response = await fetch("https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/label", {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
if (!response.ok) throw new Error(await response.text());
await require("node:fs/promises").writeFile("AWB-RUH-000123.pdf", Buffer.from(await response.arrayBuffer()));<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/label';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
file_put_contents('AWB-RUH-000123.pdf', $result);import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/label",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
response.raise_for_status()
with open("AWB-RUH-000123.pdf", "wb") as f:
f.write(response.content)الطلب PUT /shipments/{trackingNumber} يغيّر ما ترسله فقط. reason مطلوب (حتى 300 محرف) ويُحفظ في سجل تدقيق الشحنة. ويلزم حقل آخر واحد على الأقل.
يمكنك تغيير: reference المرجع، والمستلم (الاسم والهواتف والعنوان بالأسماء والإحداثيات)، والطرد (الوزن والأبعاد والقطع والقيمة المصرّح بها)، والدفع (codAmount وfreightOnDelivery). عند إرسال حقول العنوان يُعاد حل عنوان المستلم. يمكنك إرسال district وحده: يُبحث عنه حينئذ داخل المدينة الحالية للشحنة. أما إن أرسلت city فيجب إرسال district معها (400 validation_failed). والأماكن تقبل معرّفاً أو رمزاً أو اسماً كما في كل مكان. وتُعاد حسبة الرسوم إن تغيّر ما يؤثر فيها.
لا يمكن تغيير المرسل ولا عنوان الاستلام ولا نوع الخدمة ودرجتها ولا علامات المناولة. وحسابات التجار لا تعدّل الشحنات.
التعديل مسموح حتى تبلغ الشحنة حالة نهائية. وبعد أن تخرج للتوصيل يمكن تعديل بيانات التواصل والعنوان ومبلغ التحصيل فقط (shipment.field_locked_out_for_delivery).
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
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123", {
method: "PUT",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"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
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'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,
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"PUT",
"https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"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,
},
},
timeout=30,
)
print(response.status_code, response.json())الطلب POST /shipments/{trackingNumber}/cancel مع reason اختياري (حتى 500 محرف). ممكن حين تكون الشحنة مسودة أو منشأة أو مجدولة للاستلام. وبعدها يرد 422 shipment.cannot_cancel. افحص canCancel أولاً. وحسابات التجار لا تلغي عبر الـ API.
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"
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/cancel", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"reason": "Customer cancelled the order"
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/cancel';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'Customer cancelled the order',
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/cancel",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"reason": "Customer cancelled the order",
},
timeout=30,
)
print(response.status_code, response.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 نفسه مع جسم مختلف |
راجع مرجع الأخطاء لكل الرموز.