GROperator

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

English

Pricing

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

POST

/api/public/v1/pricing/quote

#

Quote a shipment price

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

Prices exactly like shipment creation (rate card of the merchant, zone of the destination, handling surcharges, COD fee) and applies the company's coverage, but creates nothing: no shipment, no tracking number, no quota is used. total equals the shipping fee the created shipment will carry. Without merchant the company's default pricing applies.

A destination (or pickup) outside the company's coverage is not an error: the answer is 200 with deliverable: false and reason set to destination_not_covered, pickup_not_covered or rate_card_not_found. Locations that do not exist answer 422 with the geo_* codes and details.field = pickup or recipient.

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

The shipment to price.

الحقلالنوعالوصف
merchant
مشروط
stringيقبل null

Merchant id or exact account name; the merchant's own rate card applies. Optional: without it the company's default pricing is used. A merchant login always quotes for itself. Required for return quotes.

مثال: Noor Electronics

pickupPublicQuoteLocationInput

A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English.

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.

مثال: Jeddah

district
pickup.district
stringيقبل null

District id, code or name. Optional for a quote; when sent it must exist.

مثال: Al Rawdah

recipientPublicQuoteLocationInput

A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English.

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.

مثال: Jeddah

district
recipient.district
stringيقبل null

District id, code or name. Optional for a quote; when sent it must exist.

مثال: Al Rawdah

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

serviceTypeenum

Kind of service requested for a shipment.

القيم: deliveryexchangereturn

serviceTierenum

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

القيم: standardexpresssameDay

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

مثال طلب

POST /pricing/quote
curl -X POST "https://api.goldrock.live/api/public/v1/pricing/quote" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "merchant": "Noor Electronics",
  "pickup": {
    "country": "SA",
    "city": "Riyadh",
    "district": "Al Olaya"
  },
  "recipient": {
    "country": "SA",
    "city": "Jeddah",
    "district": "Al Rawdah"
  },
  "parcel": {
    "weightKg": 1.5,
    "lengthCm": 20,
    "widthCm": 15,
    "heightCm": 10
  },
  "payment": {
    "codAmount": 199.5
  },
  "serviceType": "delivery",
  "serviceTier": "standard"
}'

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

الاستجابات

200The quote.

الاستجابات · الحقل
الحقلالنوعالوصف
deliverableboolean

False when the company does not cover the pickup or the destination (see reason).

reasonstringيقبل null

destination_not_covered, pickup_not_covered or rate_card_not_found when not deliverable.

shippingFeenumber (double)يقبل null

Shipping fee without the COD fee (weight price plus handling surcharges).

codFeenumber (double)يقبل null

Fee charged for collecting cash on delivery.

totalnumber (double)يقبل null

What the shipment will be charged: shippingFee + codFee. Equals payment.shippingFee of the created shipment.

chargeableWeightKgnumber (double)يقبل null

The larger of actual and volumetric weight.

zonePublicZoneRef

A pricing zone.

id
zone.id
string (uuid)

Zone id.

name
zone.name
stringيقبل null

Zone name.

breakdownarray<PublicQuoteLineDto>يقبل null

Price lines; they add up to total.

code
breakdown[].code
stringيقبل null

baseShipping, handling, codFee or reverseAdjustment.

label
breakdown[].label
stringيقبل null

Readable label (the handling flag name for handling lines).

amount
breakdown[].amount
number (double)

Amount of the line.

200 · مثال استجابة
{
  "deliverable": true,
  "reason": null,
  "shippingFee": 25,
  "codFee": 5,
  "total": 30,
  "chargeableWeightKg": 1.5,
  "zone": {
    "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",
    "name": "Zone 2"
  },
  "breakdown": [
    {
      "code": "baseShipping",
      "label": "Base shipping",
      "amount": 25
    },
    {
      "code": "codFee",
      "label": "Cash on delivery fee",
      "amount": 5
    }
  ]
}
الحالةالوصف
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

The merchant was not found (merchant.not_found).

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.

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