GROperator

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

English

Shipments

كل عمليات واجهة LastMile العامة، مولَّدة من وثيقة OpenAPI. نص المرجع بالإنجليزية في اللغتين.

POST

/api/public/v1/shipments

#

Create a shipment

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: shipments:writeيدعم Idempotency-Key

Books a shipment through the same engine as the dashboard: coverage, quota, rate-card pricing, estimated delivery date, tracking number, and the shipment.created webhook event are all identical. The fee is computed from the rate card; it cannot be sent.

Sender. sender.type = "merchant" takes sender.merchant (an id, or the exact account name; ambiguous names answer 422 merchant.ambiguous with details.candidates). When pickup is omitted the merchant's primary saved address is the pickup. sender.type = "custom" books a one-off sender on the company's shared walk-in account and requires sender.name, sender.phone and pickup. A merchant login always sends as its own merchant and cannot use custom.

Places. country, city and district of pickup and recipient accept an id, a code or a name in Arabic or English. They are matched strictly and nothing is ever created: failures answer 422 with geo_country_not_found, geo_city_not_found, geo_district_not_found, geo_city_ambiguous or geo_district_ambiguous; details.field is pickup or recipient and details.candidates lists suggestions. For addresses in Saudi Arabia shortAddress (4 letters + 4 digits) is required.

Pickup branch. Chosen from the pickup district's branch coverage unless pickup.branch names one.

Retries. Send Idempotency-Key to make a retry safe.

المعاملات

الاسمالموضعالنوعالوصف
Idempotency-Keyheaderstring

Optional key (up to 128 characters, no spaces; X-Idempotency-Key is accepted too) that makes a retry safe. The same key with the same body within 24 hours returns the first response (header Idempotent-Replayed: true); the same key with a different body answers 409 idempotency_key_reused. Scoped to your company and credential.

جسم الطلب · PublicCreateShipmentRequestapplication/json

The shipment.

الحقلالنوعالوصف
referencestringيقبل null

Your own order reference (shown on the label and searchable). Up to 100 characters.

مثال: ORD-1001

serviceTypeenum

Kind of service requested for a shipment.

القيم: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

القيم: standardexpresssameDay

senderPublicSenderInput

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

القيم: merchantcustom

merchant
sender.merchant
stringيقبل null

For merchant: the merchant id, or the exact account name (compared ignoring case and Arabic letter variants).

مثال: 3fa85f64-5717-4562-b3fc-2c963f66afa6

name
sender.name
stringيقبل null

For custom: sender name (required).

مثال: Sara Ahmed

phone
sender.phone
stringيقبل null

For custom: sender phone (required).

مثال: 0501234567

email
sender.email
stringيقبل null

For custom: sender email (optional).

مثال: sara@example.com

pickupPublicPickupInput

The pickup address.

country
pickup.country
stringيقبل null

Country id, ISO code or name. Optional when the city name is unambiguous.

مثال: SA

city
pickup.city
مطلوب
stringيقبل null

City id, code or name. Required.

مثال: Riyadh

district
pickup.district
مطلوب
stringيقبل null

District id, code or name. Required. Unknown districts are never created: you get geo_district_not_found.

مثال: Al Olaya

addressLine
pickup.addressLine
مطلوب
stringيقبل null

Street, building and landmark. Required, up to 500 characters.

مثال: King Fahd Road, Building 12, Floor 3

shortAddress
pickup.shortAddress
مشروط
stringيقبل null

Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia.

مثال: RNBA6769

latitude
pickup.latitude
number (double)يقبل null

Latitude, -90 to 90 (optional).

مثال: 24.7136

longitude
pickup.longitude
number (double)يقبل null

Longitude, -180 to 180 (optional).

مثال: 46.6753

branch
pickup.branch
stringيقبل null

Branch that handles the pickup: branch id, code or name. Optional; by default the branch covering the pickup district is chosen automatically (branch_coverage.no_coverage_for_city when none covers it).

مثال: RUH-01

recipientPublicRecipientInput

The recipient and the delivery address.

country
recipient.country
stringيقبل null

Country id, ISO code or name. Optional when the city name is unambiguous.

مثال: SA

city
recipient.city
مطلوب
stringيقبل null

City id, code or name. Required.

مثال: Riyadh

district
recipient.district
مطلوب
stringيقبل null

District id, code or name. Required. Unknown districts are never created: you get geo_district_not_found.

مثال: Al Olaya

addressLine
recipient.addressLine
مطلوب
stringيقبل null

Street, building and landmark. Required, up to 500 characters.

مثال: King Fahd Road, Building 12, Floor 3

shortAddress
recipient.shortAddress
مشروط
stringيقبل null

Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia.

مثال: RNBA6769

latitude
recipient.latitude
number (double)يقبل null

Latitude, -90 to 90 (optional).

مثال: 24.7136

longitude
recipient.longitude
number (double)يقبل null

Longitude, -180 to 180 (optional).

مثال: 46.6753

name
recipient.name
مطلوب
stringيقبل null

Recipient name. Required, up to 200 characters.

مثال: Khaled Alotaibi

phone
recipient.phone
مطلوب
stringيقبل null

Recipient phone. Required; digits, spaces, +, - and brackets.

مثال: 0555123456

secondaryPhone
recipient.secondaryPhone
stringيقبل null

Second phone (optional).

مثال: 0555987654

parcelPublicParcelInput

The parcel. Weight and dimensions describe the whole shipment.

weightKg
parcel.weightKg
مطلوب
number (double)

Actual weight in kilograms, greater than 0.

مثال: 1.5

lengthCm
parcel.lengthCm
مطلوب
number (double)

Length in centimetres, greater than 0.

مثال: 20

widthCm
parcel.widthCm
مطلوب
number (double)

Width in centimetres, greater than 0.

مثال: 15

heightCm
parcel.heightCm
مطلوب
number (double)

Height in centimetres, greater than 0.

مثال: 10

pieces
parcel.pieces
integer (int32)يقبل null

Number of pieces (default 1).

مثال: 1

description
parcel.description
stringيقبل null

What is inside (optional, shown on the label).

مثال: Mobile phone case

declaredValue
parcel.declaredValue
number (double)يقبل null

Declared value of the goods (default 0).

مثال: 250

fragile
parcel.fragile
boolean

Fragile goods.

مثال: false

requiresColdChain
parcel.requiresColdChain
مشروط
boolean

Needs cold chain; then coldChainRange is required.

مثال: false

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

القيم: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable goods.

مثال: false

hazardous
parcel.hazardous
boolean

Hazardous goods.

مثال: false

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

مثال: false

liquid
parcel.liquid
boolean

Liquid goods.

مثال: false

highValue
parcel.highValue
boolean

High-value goods.

مثال: false

paymentPublicPaymentInput

Cash on delivery and freight payment.

codAmount
payment.codAmount
number (double)يقبل null

Amount the courier collects from the recipient (cash on delivery). Default 0. Must be 0 for return.

مثال: 199.5

freightOnDelivery
payment.freightOnDelivery
booleanيقبل null

True when the recipient pays the shipping fee on delivery.

مثال: false

deliveryPublicDeliveryOptionsInput

Handover rules at the recipient's door. Omitted values use the system defaults shown.

allowOpenPackage
delivery.allowOpenPackage
booleanيقبل null

The recipient may open the package before accepting. Default false.

مثال: false

requireSignature
delivery.requireSignature
مشروط
booleanيقبل null

A signature is required on delivery. Default true.

مثال: true

requireIdVerification
delivery.requireIdVerification
booleanيقبل null

The courier must verify the recipient's ID. Default false.

مثال: false

allowNeighborDelivery
delivery.allowNeighborDelivery
booleanيقبل null

A neighbour may accept the parcel. Default true.

مثال: true

وثيقة OpenAPI لا تعلّم الحقول المطلوبة رسمياً، لذلك تُقرأ كلمة «مطلوب» من وصف كل حقل. تسرد الأدلة الحقول المطلوبة لكل طلب.

مثال طلب

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

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

201The created shipment.

الاستجابات · الحقل
الحقلالنوعالوصف
trackingNumberstringيقبل null

Tracking number; identifies the shipment in every route.

referencestringيقبل null

Your order reference.

statusstringيقبل null

Status key, e.g. created, outForDelivery, delivered. See GET /shipments/statuses.

statusCodeinteger (int32)

Numeric status code.

statusLabelArstringيقبل null

Arabic status label.

statusLabelEnstringيقبل null

English status label.

isFinalboolean

True when the shipment reached a final status.

serviceTypeenum

Kind of service requested for a shipment.

القيم: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

القيم: standardexpresssameDay

sourceenum

How the order reached the system.

القيم: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAtstring (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)يقبل null

Estimated delivery date (yyyy-MM-dd), when known.

senderPublicSenderDto

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

القيم: merchantcustom

name
sender.name
stringيقبل null

Sender name.

phone
sender.phone
stringيقبل null

Sender phone.

email
sender.email
stringيقبل null

Sender email.

merchant
sender.merchant
PublicMerchantRef

A merchant reference.

id
sender.merchant.id
string (uuid)

Merchant id.

name
sender.merchant.name
stringيقبل null

Merchant account name.

pickupPublicAddressDto

A resolved address.

country
pickup.country
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.country.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.country.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.country.nameEn
stringيقبل null

English name.

city
pickup.city
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.city.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.city.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.city.nameEn
stringيقبل null

English name.

district
pickup.district
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.district.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.district.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.district.nameEn
stringيقبل null

English name.

addressLine
pickup.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
pickup.shortAddress
stringيقبل null

Saudi national short address.

latitude
pickup.latitude
number (double)يقبل null

Latitude.

longitude
pickup.longitude
number (double)يقبل null

Longitude.

recipientPublicRecipientDto

The recipient.

name
recipient.name
stringيقبل null

Recipient name.

phone
recipient.phone
stringيقبل null

Recipient phone.

secondaryPhone
recipient.secondaryPhone
stringيقبل null

Second phone.

country
recipient.country
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.country.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.country.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.country.nameEn
stringيقبل null

English name.

city
recipient.city
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.city.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.city.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.city.nameEn
stringيقبل null

English name.

district
recipient.district
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.district.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.district.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.district.nameEn
stringيقبل null

English name.

addressLine
recipient.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
recipient.shortAddress
stringيقبل null

Saudi national short address.

latitude
recipient.latitude
number (double)يقبل null

Latitude.

longitude
recipient.longitude
number (double)يقبل null

Longitude.

parcelPublicParcelDto

Parcel data of a shipment.

weightKg
parcel.weightKg
number (double)

Actual weight.

lengthCm
parcel.lengthCm
number (double)

Length.

widthCm
parcel.widthCm
number (double)

Width.

heightCm
parcel.heightCm
number (double)

Height.

chargeableWeightKg
parcel.chargeableWeightKg
number (double)

Weight used for pricing: the larger of actual and volumetric weight.

pieces
parcel.pieces
integer (int32)

Number of pieces.

description
parcel.description
stringيقبل null

What is inside.

declaredValue
parcel.declaredValue
number (double)

Declared value.

fragile
parcel.fragile
boolean

Fragile.

requiresColdChain
parcel.requiresColdChain
boolean

Needs cold chain.

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

القيم: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable.

hazardous
parcel.hazardous
boolean

Hazardous.

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

liquid
parcel.liquid
boolean

Liquid.

highValue
parcel.highValue
boolean

High value.

deliveryPublicDeliveryOptionsDto

Handover rules.

allowOpenPackage
delivery.allowOpenPackage
boolean

The recipient may open the package.

requireSignature
delivery.requireSignature
boolean

Signature required.

requireIdVerification
delivery.requireIdVerification
boolean

ID check required.

allowNeighborDelivery
delivery.allowNeighborDelivery
boolean

Neighbour delivery allowed.

paymentPublicPaymentDto

Payment data of a shipment.

codAmount
payment.codAmount
number (double)

Cash to collect from the recipient.

shippingFee
payment.shippingFee
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
payment.freightOnDelivery
boolean

True when the recipient pays the fee.

piecesarray<PublicPieceDto>يقبل null

The pieces.

barcode
pieces[].barcode
stringيقبل null

Piece barcode (the tracking number followed by -P1, -P2...).

branchPublicBranchRef

A branch reference.

id
branch.id
string (uuid)

Branch id.

name
branch.name
stringيقبل null

Branch name.

canCancelboolean

True while the shipment can still be cancelled.

isEditableboolean

True while the shipment can still be edited.

201 · مثال استجابة
{
  "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
}
الحالةالوصف
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

Scope missing, or a merchant login named another merchant or a custom sender.

404

Merchant or branch not found (merchant.not_found, branch.not_found).

409

The Idempotency-Key was used with a different body (idempotency_key_reused).

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/shipments

#

List shipments

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: shipments:read

Newest first, paginated. All filters are optional and combine with AND. city filters by destination city (id, code or name; an unknown city answers 422 geo_city_not_found). search matches the tracking number, reference, recipient name and phone, and sender name.

المعاملات

الاسمالموضعالنوعالوصف
pagequeryinteger (int32)
الافتراضي: 1

Page number, starting at 1.

pageSizequeryinteger (int32)
الافتراضي: 25

Items per page, 1 to 100 (larger values are clamped to 100).

statusquerystring

One status or several separated by commas, as keys (delivered,outForDelivery) or numeric codes. See GET /shipments/statuses.

merchantquerystring

Merchant id or exact account name.

referencequerystring

Your order reference (exact match, ignoring case).

trackingNumberquerystring

Exact tracking number.

recipientPhonequerystring

Part of the recipient's phone.

cityquerystring

Destination city: id, code or name.

createdFromquerystring (date-time)

Created at or after this instant (ISO 8601, e.g. 2026-01-01T00:00:00Z).

createdToquerystring (date-time)

Created at or before this instant (ISO 8601).

searchquerystring

Free text.

مثال طلب

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'

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200A page of shipments.

الاستجابات · الحقل
الحقلالنوعالوصف
itemsarray<PublicShipmentSummaryDto>يقبل null

Items of the requested page.

trackingNumber
items[].trackingNumber
stringيقبل null

Tracking number.

reference
items[].reference
stringيقبل null

Your order reference.

status
items[].status
stringيقبل null

Status key.

statusLabelAr
items[].statusLabelAr
stringيقبل null

Arabic status label.

statusLabelEn
items[].statusLabelEn
stringيقبل null

English status label.

merchant
items[].merchant
PublicMerchantRef

A merchant reference.

id
items[].merchant.id
string (uuid)

Merchant id.

name
items[].merchant.name
stringيقبل null

Merchant account name.

senderName
items[].senderName
stringيقبل null

Sender name.

recipientName
items[].recipientName
stringيقبل null

Recipient name.

recipientPhone
items[].recipientPhone
stringيقبل null

Recipient phone.

city
items[].city
PublicNamedRef

A catalog entry shown in both languages.

id
items[].city.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
items[].city.nameAr
stringيقبل null

Arabic name.

nameEn
items[].city.nameEn
stringيقبل null

English name.

district
items[].district
PublicNamedRef

A catalog entry shown in both languages.

id
items[].district.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
items[].district.nameAr
stringيقبل null

Arabic name.

nameEn
items[].district.nameEn
stringيقبل null

English name.

codAmount
items[].codAmount
number (double)

Cash on delivery amount.

shippingFee
items[].shippingFee
number (double)

Shipping fee.

createdAt
items[].createdAt
string (date-time)

Creation time (UTC).

estimatedDeliveryDate
items[].estimatedDeliveryDate
string (date)يقبل null

Estimated delivery date.

pageinteger (int32)

Current page number, starting at 1.

pageSizeinteger (int32)

Requested page size (1 to 100, default 25).

totalCountinteger (int32)

Total number of items across all pages.

totalPagesinteger (int32)

Total number of pages.

200 · مثال استجابة
{
  "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
}
الحالةالوصف
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/shipments/statuses

#

List shipment statuses

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: shipments:read

The catalog of statuses with their keys, codes, Arabic and English names and whether they are final. Use key to map statuses in your system; status of a shipment is one of these keys.

مثال طلب

GET /shipments/statuses
curl "https://api.goldrock.live/api/public/v1/shipments/statuses" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200All statuses in code order.

الاستجابات · الحقل
الحقلالنوعالوصف
codeinteger (int32)

Numeric status code.

keystringيقبل null

Status key used in the API.

nameArstringيقبل null

Arabic name.

nameEnstringيقبل null

English name.

isFinalboolean

True when no further status follows (delivered, returned to sender, cancelled, lost, disposed).

200 · مثال استجابة
[
  {
    "code": 1,
    "isFinal": false
  }
]
الحالةالوصف
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/shipments/{trackingNumber}

#

Get a shipment

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: shipments:read

Required scope (API key) or equivalent permission (password): shipments:read.

المعاملات

الاسمالموضعالنوعالوصف
trackingNumber
مطلوب
pathstring

Tracking number.

مثال طلب

GET /shipments/AWB-RUH-000123
curl "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"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The shipment.

الاستجابات · الحقل
الحقلالنوعالوصف
trackingNumberstringيقبل null

Tracking number; identifies the shipment in every route.

referencestringيقبل null

Your order reference.

statusstringيقبل null

Status key, e.g. created, outForDelivery, delivered. See GET /shipments/statuses.

statusCodeinteger (int32)

Numeric status code.

statusLabelArstringيقبل null

Arabic status label.

statusLabelEnstringيقبل null

English status label.

isFinalboolean

True when the shipment reached a final status.

serviceTypeenum

Kind of service requested for a shipment.

القيم: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

القيم: standardexpresssameDay

sourceenum

How the order reached the system.

القيم: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAtstring (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)يقبل null

Estimated delivery date (yyyy-MM-dd), when known.

senderPublicSenderDto

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

القيم: merchantcustom

name
sender.name
stringيقبل null

Sender name.

phone
sender.phone
stringيقبل null

Sender phone.

email
sender.email
stringيقبل null

Sender email.

merchant
sender.merchant
PublicMerchantRef

A merchant reference.

id
sender.merchant.id
string (uuid)

Merchant id.

name
sender.merchant.name
stringيقبل null

Merchant account name.

pickupPublicAddressDto

A resolved address.

country
pickup.country
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.country.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.country.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.country.nameEn
stringيقبل null

English name.

city
pickup.city
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.city.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.city.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.city.nameEn
stringيقبل null

English name.

district
pickup.district
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.district.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.district.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.district.nameEn
stringيقبل null

English name.

addressLine
pickup.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
pickup.shortAddress
stringيقبل null

Saudi national short address.

latitude
pickup.latitude
number (double)يقبل null

Latitude.

longitude
pickup.longitude
number (double)يقبل null

Longitude.

recipientPublicRecipientDto

The recipient.

name
recipient.name
stringيقبل null

Recipient name.

phone
recipient.phone
stringيقبل null

Recipient phone.

secondaryPhone
recipient.secondaryPhone
stringيقبل null

Second phone.

country
recipient.country
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.country.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.country.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.country.nameEn
stringيقبل null

English name.

city
recipient.city
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.city.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.city.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.city.nameEn
stringيقبل null

English name.

district
recipient.district
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.district.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.district.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.district.nameEn
stringيقبل null

English name.

addressLine
recipient.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
recipient.shortAddress
stringيقبل null

Saudi national short address.

latitude
recipient.latitude
number (double)يقبل null

Latitude.

longitude
recipient.longitude
number (double)يقبل null

Longitude.

parcelPublicParcelDto

Parcel data of a shipment.

weightKg
parcel.weightKg
number (double)

Actual weight.

lengthCm
parcel.lengthCm
number (double)

Length.

widthCm
parcel.widthCm
number (double)

Width.

heightCm
parcel.heightCm
number (double)

Height.

chargeableWeightKg
parcel.chargeableWeightKg
number (double)

Weight used for pricing: the larger of actual and volumetric weight.

pieces
parcel.pieces
integer (int32)

Number of pieces.

description
parcel.description
stringيقبل null

What is inside.

declaredValue
parcel.declaredValue
number (double)

Declared value.

fragile
parcel.fragile
boolean

Fragile.

requiresColdChain
parcel.requiresColdChain
boolean

Needs cold chain.

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

القيم: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable.

hazardous
parcel.hazardous
boolean

Hazardous.

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

liquid
parcel.liquid
boolean

Liquid.

highValue
parcel.highValue
boolean

High value.

deliveryPublicDeliveryOptionsDto

Handover rules.

allowOpenPackage
delivery.allowOpenPackage
boolean

The recipient may open the package.

requireSignature
delivery.requireSignature
boolean

Signature required.

requireIdVerification
delivery.requireIdVerification
boolean

ID check required.

allowNeighborDelivery
delivery.allowNeighborDelivery
boolean

Neighbour delivery allowed.

paymentPublicPaymentDto

Payment data of a shipment.

codAmount
payment.codAmount
number (double)

Cash to collect from the recipient.

shippingFee
payment.shippingFee
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
payment.freightOnDelivery
boolean

True when the recipient pays the fee.

piecesarray<PublicPieceDto>يقبل null

The pieces.

barcode
pieces[].barcode
stringيقبل null

Piece barcode (the tracking number followed by -P1, -P2...).

branchPublicBranchRef

A branch reference.

id
branch.id
string (uuid)

Branch id.

name
branch.name
stringيقبل null

Branch name.

canCancelboolean

True while the shipment can still be cancelled.

isEditableboolean

True while the shipment can still be edited.

200 · مثال استجابة
{
  "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
}
الحالةالوصف
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found (also when the shipment belongs to someone else).

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

PUT

/api/public/v1/shipments/{trackingNumber}

#

Update a shipment

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: shipments:write

Changes the recipient (name, phones, address by names, coordinates), the order reference, COD amount, who pays the freight and the parcel (weight, dimensions, pieces, declared value). Only the fields you send change. The fee is recalculated when something that affects it changes. reason is required and goes to the shipment's audit trail. Allowed until the shipment reaches a final status; once it is out for delivery only contact details, address and COD can change (shipment.field_locked_out_for_delivery). Not editable through the API: sender, pickup address, service type and tier, handling flags. Merchant logins cannot edit shipments.

المعاملات

الاسمالموضعالنوعالوصف
trackingNumber
مطلوب
pathstring

Tracking number.

جسم الطلب · PublicUpdateShipmentRequestapplication/json

The changes.

الحقلالنوعالوصف
reason
مطلوب
stringيقبل null

Why the shipment is edited (kept in the shipment's audit trail). Required, up to 300 characters.

مثال: Customer changed the delivery address

referencestringيقبل null

New order reference.

مثال: ORD-1001-B

recipientPublicUpdateRecipientInput

Recipient fields that can change. Sending any address field re-resolves the whole address (city and district are then required).

country
recipient.country
stringيقبل null

Country id, ISO code or name. Optional when the city name is unambiguous.

مثال: SA

city
recipient.city
مشروط
stringيقبل null

City id, code or name. Required.

مثال: Riyadh

district
recipient.district
مشروط
stringيقبل null

District id, code or name. Required. Unknown districts are never created: you get geo_district_not_found.

مثال: Al Olaya

addressLine
recipient.addressLine
مشروط
stringيقبل null

Street, building and landmark. Required, up to 500 characters.

مثال: King Fahd Road, Building 12, Floor 3

shortAddress
recipient.shortAddress
مشروط
stringيقبل null

Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia.

مثال: RNBA6769

latitude
recipient.latitude
number (double)يقبل null

Latitude, -90 to 90 (optional).

مثال: 24.7136

longitude
recipient.longitude
number (double)يقبل null

Longitude, -180 to 180 (optional).

مثال: 46.6753

name
recipient.name
stringيقبل null

Recipient name.

مثال: Khaled Alotaibi

phone
recipient.phone
stringيقبل null

Recipient phone.

مثال: 0555123456

secondaryPhone
recipient.secondaryPhone
stringيقبل null

Second phone.

مثال: 0555987654

parcelPublicUpdateParcelInput

Parcel fields that can change. Only the fields you send are changed.

weightKg
parcel.weightKg
number (double)يقبل null

Weight in kilograms.

مثال: 2

lengthCm
parcel.lengthCm
number (double)يقبل null

Length in centimetres.

مثال: 20

widthCm
parcel.widthCm
number (double)يقبل null

Width in centimetres.

مثال: 15

heightCm
parcel.heightCm
number (double)يقبل null

Height in centimetres.

مثال: 10

pieces
parcel.pieces
integer (int32)يقبل null

Number of pieces.

مثال: 1

declaredValue
parcel.declaredValue
number (double)يقبل null

Declared value of the goods.

مثال: 300

paymentPublicPaymentInput

Cash on delivery and freight payment.

codAmount
payment.codAmount
number (double)يقبل null

Amount the courier collects from the recipient (cash on delivery). Default 0. Must be 0 for return.

مثال: 199.5

freightOnDelivery
payment.freightOnDelivery
booleanيقبل null

True when the recipient pays the shipping fee on delivery.

مثال: false

وثيقة OpenAPI لا تعلّم الحقول المطلوبة رسمياً، لذلك تُقرأ كلمة «مطلوب» من وصف كل حقل. تسرد الأدلة الحقول المطلوبة لكل طلب.

مثال طلب

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

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The updated shipment.

الاستجابات · الحقل
الحقلالنوعالوصف
trackingNumberstringيقبل null

Tracking number; identifies the shipment in every route.

referencestringيقبل null

Your order reference.

statusstringيقبل null

Status key, e.g. created, outForDelivery, delivered. See GET /shipments/statuses.

statusCodeinteger (int32)

Numeric status code.

statusLabelArstringيقبل null

Arabic status label.

statusLabelEnstringيقبل null

English status label.

isFinalboolean

True when the shipment reached a final status.

serviceTypeenum

Kind of service requested for a shipment.

القيم: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

القيم: standardexpresssameDay

sourceenum

How the order reached the system.

القيم: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAtstring (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)يقبل null

Estimated delivery date (yyyy-MM-dd), when known.

senderPublicSenderDto

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

القيم: merchantcustom

name
sender.name
stringيقبل null

Sender name.

phone
sender.phone
stringيقبل null

Sender phone.

email
sender.email
stringيقبل null

Sender email.

merchant
sender.merchant
PublicMerchantRef

A merchant reference.

id
sender.merchant.id
string (uuid)

Merchant id.

name
sender.merchant.name
stringيقبل null

Merchant account name.

pickupPublicAddressDto

A resolved address.

country
pickup.country
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.country.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.country.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.country.nameEn
stringيقبل null

English name.

city
pickup.city
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.city.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.city.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.city.nameEn
stringيقبل null

English name.

district
pickup.district
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.district.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.district.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.district.nameEn
stringيقبل null

English name.

addressLine
pickup.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
pickup.shortAddress
stringيقبل null

Saudi national short address.

latitude
pickup.latitude
number (double)يقبل null

Latitude.

longitude
pickup.longitude
number (double)يقبل null

Longitude.

recipientPublicRecipientDto

The recipient.

name
recipient.name
stringيقبل null

Recipient name.

phone
recipient.phone
stringيقبل null

Recipient phone.

secondaryPhone
recipient.secondaryPhone
stringيقبل null

Second phone.

country
recipient.country
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.country.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.country.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.country.nameEn
stringيقبل null

English name.

city
recipient.city
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.city.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.city.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.city.nameEn
stringيقبل null

English name.

district
recipient.district
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.district.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.district.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.district.nameEn
stringيقبل null

English name.

addressLine
recipient.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
recipient.shortAddress
stringيقبل null

Saudi national short address.

latitude
recipient.latitude
number (double)يقبل null

Latitude.

longitude
recipient.longitude
number (double)يقبل null

Longitude.

parcelPublicParcelDto

Parcel data of a shipment.

weightKg
parcel.weightKg
number (double)

Actual weight.

lengthCm
parcel.lengthCm
number (double)

Length.

widthCm
parcel.widthCm
number (double)

Width.

heightCm
parcel.heightCm
number (double)

Height.

chargeableWeightKg
parcel.chargeableWeightKg
number (double)

Weight used for pricing: the larger of actual and volumetric weight.

pieces
parcel.pieces
integer (int32)

Number of pieces.

description
parcel.description
stringيقبل null

What is inside.

declaredValue
parcel.declaredValue
number (double)

Declared value.

fragile
parcel.fragile
boolean

Fragile.

requiresColdChain
parcel.requiresColdChain
boolean

Needs cold chain.

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

القيم: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable.

hazardous
parcel.hazardous
boolean

Hazardous.

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

liquid
parcel.liquid
boolean

Liquid.

highValue
parcel.highValue
boolean

High value.

deliveryPublicDeliveryOptionsDto

Handover rules.

allowOpenPackage
delivery.allowOpenPackage
boolean

The recipient may open the package.

requireSignature
delivery.requireSignature
boolean

Signature required.

requireIdVerification
delivery.requireIdVerification
boolean

ID check required.

allowNeighborDelivery
delivery.allowNeighborDelivery
boolean

Neighbour delivery allowed.

paymentPublicPaymentDto

Payment data of a shipment.

codAmount
payment.codAmount
number (double)

Cash to collect from the recipient.

shippingFee
payment.shippingFee
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
payment.freightOnDelivery
boolean

True when the recipient pays the fee.

piecesarray<PublicPieceDto>يقبل null

The pieces.

barcode
pieces[].barcode
stringيقبل null

Piece barcode (the tracking number followed by -P1, -P2...).

branchPublicBranchRef

A branch reference.

id
branch.id
string (uuid)

Branch id.

name
branch.name
stringيقبل null

Branch name.

canCancelboolean

True while the shipment can still be cancelled.

isEditableboolean

True while the shipment can still be edited.

200 · مثال استجابة
{
  "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
}
الحالةالوصف
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found.

422

Not editable in this state, no change, or an unresolved location.

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

POST

/api/public/v1/shipments/{trackingNumber}/cancel

#

Cancel a shipment

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: shipments:write

Possible while the shipment is a draft, created or scheduled for pickup; later it answers 422 shipment.cannot_cancel. A pending return created with an exchange is cancelled with it. Merchant logins cannot cancel through the API.

المعاملات

الاسمالموضعالنوعالوصف
trackingNumber
مطلوب
pathstring

Tracking number.

جسم الطلب · PublicCancelShipmentRequestapplication/json

The reason.

الحقلالنوعالوصف
reasonstringيقبل null

Why the shipment is cancelled (kept in the shipment history). Up to 500 characters.

مثال: Customer cancelled the order

وثيقة OpenAPI لا تعلّم الحقول المطلوبة رسمياً، لذلك تُقرأ كلمة «مطلوب» من وصف كل حقل. تسرد الأدلة الحقول المطلوبة لكل طلب.

مثال طلب

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

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The cancelled shipment.

الاستجابات · الحقل
الحقلالنوعالوصف
trackingNumberstringيقبل null

Tracking number; identifies the shipment in every route.

referencestringيقبل null

Your order reference.

statusstringيقبل null

Status key, e.g. created, outForDelivery, delivered. See GET /shipments/statuses.

statusCodeinteger (int32)

Numeric status code.

statusLabelArstringيقبل null

Arabic status label.

statusLabelEnstringيقبل null

English status label.

isFinalboolean

True when the shipment reached a final status.

serviceTypeenum

Kind of service requested for a shipment.

القيم: deliveryexchangereturn

serviceTierenum

Speed of the service; it drives the estimated delivery date.

القيم: standardexpresssameDay

sourceenum

How the order reached the system.

القيم: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAtstring (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)يقبل null

Estimated delivery date (yyyy-MM-dd), when known.

senderPublicSenderDto

The sender of a shipment.

type
sender.type
enum

Who sends the shipment.

القيم: merchantcustom

name
sender.name
stringيقبل null

Sender name.

phone
sender.phone
stringيقبل null

Sender phone.

email
sender.email
stringيقبل null

Sender email.

merchant
sender.merchant
PublicMerchantRef

A merchant reference.

id
sender.merchant.id
string (uuid)

Merchant id.

name
sender.merchant.name
stringيقبل null

Merchant account name.

pickupPublicAddressDto

A resolved address.

country
pickup.country
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.country.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.country.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.country.nameEn
stringيقبل null

English name.

city
pickup.city
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.city.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.city.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.city.nameEn
stringيقبل null

English name.

district
pickup.district
PublicNamedRef

A catalog entry shown in both languages.

id
pickup.district.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
pickup.district.nameAr
stringيقبل null

Arabic name.

nameEn
pickup.district.nameEn
stringيقبل null

English name.

addressLine
pickup.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
pickup.shortAddress
stringيقبل null

Saudi national short address.

latitude
pickup.latitude
number (double)يقبل null

Latitude.

longitude
pickup.longitude
number (double)يقبل null

Longitude.

recipientPublicRecipientDto

The recipient.

name
recipient.name
stringيقبل null

Recipient name.

phone
recipient.phone
stringيقبل null

Recipient phone.

secondaryPhone
recipient.secondaryPhone
stringيقبل null

Second phone.

country
recipient.country
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.country.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.country.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.country.nameEn
stringيقبل null

English name.

city
recipient.city
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.city.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.city.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.city.nameEn
stringيقبل null

English name.

district
recipient.district
PublicNamedRef

A catalog entry shown in both languages.

id
recipient.district.id
string (uuid)يقبل null

Catalog id, or null for legacy shipments that only stored a name.

nameAr
recipient.district.nameAr
stringيقبل null

Arabic name.

nameEn
recipient.district.nameEn
stringيقبل null

English name.

addressLine
recipient.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
recipient.shortAddress
stringيقبل null

Saudi national short address.

latitude
recipient.latitude
number (double)يقبل null

Latitude.

longitude
recipient.longitude
number (double)يقبل null

Longitude.

parcelPublicParcelDto

Parcel data of a shipment.

weightKg
parcel.weightKg
number (double)

Actual weight.

lengthCm
parcel.lengthCm
number (double)

Length.

widthCm
parcel.widthCm
number (double)

Width.

heightCm
parcel.heightCm
number (double)

Height.

chargeableWeightKg
parcel.chargeableWeightKg
number (double)

Weight used for pricing: the larger of actual and volumetric weight.

pieces
parcel.pieces
integer (int32)

Number of pieces.

description
parcel.description
stringيقبل null

What is inside.

declaredValue
parcel.declaredValue
number (double)

Declared value.

fragile
parcel.fragile
boolean

Fragile.

requiresColdChain
parcel.requiresColdChain
boolean

Needs cold chain.

coldChainRange
parcel.coldChainRange
enum

Temperature range of cold-chain goods.

القيم: frozenchilledambient

flammable
parcel.flammable
boolean

Flammable.

hazardous
parcel.hazardous
boolean

Hazardous.

containsAlcohol
parcel.containsAlcohol
boolean

Contains alcohol.

liquid
parcel.liquid
boolean

Liquid.

highValue
parcel.highValue
boolean

High value.

deliveryPublicDeliveryOptionsDto

Handover rules.

allowOpenPackage
delivery.allowOpenPackage
boolean

The recipient may open the package.

requireSignature
delivery.requireSignature
boolean

Signature required.

requireIdVerification
delivery.requireIdVerification
boolean

ID check required.

allowNeighborDelivery
delivery.allowNeighborDelivery
boolean

Neighbour delivery allowed.

paymentPublicPaymentDto

Payment data of a shipment.

codAmount
payment.codAmount
number (double)

Cash to collect from the recipient.

shippingFee
payment.shippingFee
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
payment.freightOnDelivery
boolean

True when the recipient pays the fee.

piecesarray<PublicPieceDto>يقبل null

The pieces.

barcode
pieces[].barcode
stringيقبل null

Piece barcode (the tracking number followed by -P1, -P2...).

branchPublicBranchRef

A branch reference.

id
branch.id
string (uuid)

Branch id.

name
branch.name
stringيقبل null

Branch name.

canCancelboolean

True while the shipment can still be cancelled.

isEditableboolean

True while the shipment can still be edited.

200 · مثال استجابة
{
  "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
}
الحالةالوصف
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found.

422

Code shipment.cannot_cancel or another state-machine code.

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/shipments/{trackingNumber}/label

#

Print the shipping label

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: shipments:read

The label (air waybill, 100x150 mm) as a PDF, with the company's branding.

المعاملات

الاسمالموضعالنوعالوصف
trackingNumber
مطلوب
pathstring

Tracking number.

مثال طلب

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

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The PDF file.ملف ثنائي (PDF)

الحالةالوصف
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found.

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/shipments/{trackingNumber}/tracking

#

Track a shipment

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: shipments:read

The status timeline (oldest first) with Arabic and English labels, the current status and the estimated delivery date. It carries no internal user names; note is present only for failed attempts, postponements, cancellation, returns, loss and damage.

المعاملات

الاسمالموضعالنوعالوصف
trackingNumber
مطلوب
pathstring

Tracking number.

مثال طلب

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"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The tracking timeline.

الاستجابات · الحقل
الحقلالنوعالوصف
trackingNumberstringيقبل null

Tracking number.

statusstringيقبل null

Current status key.

statusLabelArstringيقبل null

Arabic label of the current status.

statusLabelEnstringيقبل null

English label of the current status.

estimatedDeliveryDatestring (date)يقبل null

Estimated delivery date.

eventsarray<PublicTrackingEventDto>يقبل null

Timeline, oldest first.

status
events[].status
stringيقبل null

Status key.

statusLabelAr
events[].statusLabelAr
stringيقبل null

Arabic label.

statusLabelEn
events[].statusLabelEn
stringيقبل null

English label.

at
events[].at
string (date-time)

When the status was set (UTC).

note
events[].note
stringيقبل null

Reason, only for failed attempts, postponements, cancellation, returns, loss and damage.

location
events[].location
stringيقبل null

Reserved; not populated yet.

200 · مثال استجابة
{
  "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
    }
  ]
}
الحالةالوصف
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code shipment.not_found.

429

Too many requests (code rate_limited); wait for the Retry-After header.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء