GROperator

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

English

النماذج (Schemas)

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

PublicAddressDtoكائن#

A resolved address.

الحقلالنوعالوصف
countryPublicNamedRef

A catalog entry shown in both languages.

cityPublicNamedRef

A catalog entry shown in both languages.

districtPublicNamedRef

A catalog entry shown in both languages.

addressLine
مطلوب
string

Street, building and landmark.

shortAddressstringيقبل null

Saudi national short address.

latitudenumber (double)يقبل null

Latitude.

longitudenumber (double)يقبل null

Longitude.

PublicApiErrorكائن#

Error envelope returned for every non-2xx response of the public API (/api/public/v1).

الحقلالنوعالوصف
code
مطلوب
string

Stable machine-readable code, e.g. shipment.not_found or validation_failed.

message
مطلوب
string

Human readable message. Arabic by default; English when Accept-Language prefers English.

status
مطلوب
integer (int32)

HTTP status code, repeated in the body.

detailsobjectيقبل null

Extra data: errors (field to messages) for validation_failed; level, input and candidates for geo errors; messageAr when the message is English.

traceId
مطلوب
string

Correlation id of the request, quote it when contacting support.

PublicApiKeyDtoكائن#

The API key behind a key-authenticated call.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

API key id.

namestringيقبل null

Label given to the key.

PublicBranchDtoكائن#

Public-safe view of a branch (no manager, capacity, counters or other internal fields).

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Branch id.

name
مطلوب
string

Branch name.

code
مطلوب
string

Branch code.

city
مطلوب
string

City name as entered on the branch.

phonestringيقبل null

Branch phone, when set.

latitudenumber (double)يقبل null

Latitude, when set.

longitudenumber (double)يقبل null

Longitude, when set.

isActive
مطلوب
boolean

Whether the branch is active.

PublicBranchDtoPublicPageكائن#

Standard paged response of every public list endpoint.

الحقلالنوعالوصف
items
مطلوب
array<PublicBranchDto>

Items of the requested page.

page
مطلوب
integer (int32)

Current page number, starting at 1.

pageSize
مطلوب
integer (int32)

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

totalCount
مطلوب
integer (int32)

Total number of items across all pages.

totalPages
مطلوب
integer (int32)

Total number of pages.

PublicBranchRefكائن#

A branch reference.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Branch id.

name
مطلوب
string

Branch name.

PublicCancelShipmentRequestكائن#

Body of POST /shipments/{trackingNumber}/cancel.

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

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

مثال: Customer cancelled the order

PublicCityCoverageDtoكائن#

Whether the company delivers to / picks up from a city.

الحقلالنوعالوصف
city
مطلوب
PublicGeoNodeDto

A resolved geography node (id and both names).

delivery
مطلوب
boolean

True when the company delivers to the city.

pickup
مطلوب
boolean

True when the company picks up from the city.

PublicCityDtoكائن#

City item of the public geography endpoints.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

City id.

nameAr
مطلوب
string

Arabic name.

nameEn
مطلوب
string

English name.

codestringيقبل null

City code (unique within its country), when defined.

countryId
مطلوب
string (uuid)

Id of the country the city belongs to.

pending
مطلوب
boolean

True for a city created by your company that the platform has not approved yet.

PublicCityDtoPublicPageكائن#

Standard paged response of every public list endpoint.

الحقلالنوعالوصف
items
مطلوب
array<PublicCityDto>

Items of the requested page.

page
مطلوب
integer (int32)

Current page number, starting at 1.

pageSize
مطلوب
integer (int32)

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

totalCount
مطلوب
integer (int32)

Total number of items across all pages.

totalPages
مطلوب
integer (int32)

Total number of pages.

PublicColdChainRangeقائمة قيم#

Temperature range of cold-chain goods.

القيم: frozenchilledambient

PublicCompanyDtoكائن#

Company identity shown by the public auth/me endpoint.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Company id.

name
مطلوب
string

Company name.

slug
مطلوب
string

Company slug.

PublicCountryDtoكائن#

Country item of the public geography endpoints.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Country id.

nameAr
مطلوب
string

Arabic name.

nameEn
مطلوب
string

English name.

code
مطلوب
string

ISO 3166-1 alpha-2 code.

PublicCountryDtoPublicPageكائن#

Standard paged response of every public list endpoint.

الحقلالنوعالوصف
items
مطلوب
array<PublicCountryDto>

Items of the requested page.

page
مطلوب
integer (int32)

Current page number, starting at 1.

pageSize
مطلوب
integer (int32)

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

totalCount
مطلوب
integer (int32)

Total number of items across all pages.

totalPages
مطلوب
integer (int32)

Total number of pages.

PublicCoveredCityDtoكائن#

A city the company covers.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

City id.

nameAr
مطلوب
string

Arabic name.

nameEn
مطلوب
string

English name.

codestringيقبل null

City code, when defined.

countryId
مطلوب
string (uuid)

Country id.

delivery
مطلوب
boolean

True when the company delivers to the city.

pickup
مطلوب
boolean

True when the company picks up from the city.

PublicCoveredCityDtoPublicPageكائن#

Standard paged response of every public list endpoint.

الحقلالنوعالوصف
items
مطلوب
array<PublicCoveredCityDto>

Items of the requested page.

page
مطلوب
integer (int32)

Current page number, starting at 1.

pageSize
مطلوب
integer (int32)

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

totalCount
مطلوب
integer (int32)

Total number of items across all pages.

totalPages
مطلوب
integer (int32)

Total number of pages.

PublicCreateMerchantAddressRequestكائن#

Body of POST /merchants/{id}/addresses.

الحقلالنوعالوصف
label
مطلوب
string

Short label of the address, for example "Main warehouse". Required, up to 100 characters.

مثال: Main warehouse

contactNamestringيقبل null

Person to contact at this address (defaults to the merchant name).

مثال: Omar Hassan

contactPhone
مطلوب
string

Phone at this address. Required.

مثال: 0501234567

countrystringيقبل null

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

مثال: SA

city
مطلوب
string

City id, code or name. Required.

مثال: Riyadh

district
مطلوب
string

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

مثال: Al Olaya

addressLine
مطلوب
string

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

مثال: King Fahd Road, Warehouse 4

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

Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia.

مثال: RNBA6769

latitudenumber (double)يقبل null

Latitude (optional).

مثال: 24.7136

longitudenumber (double)يقبل null

Longitude (optional).

مثال: 46.6753

makePrimaryboolean

Make this the primary address (the first address of a merchant is always primary).

مثال: false

PublicCreateMerchantRequestكائن#

Body of POST /merchants.

الحقلالنوعالوصف
name
مطلوب
string

Account (store) name. Not unique, but a name that matches another merchant on the platform needs confirmPossibleDuplicate. Required, up to 200 characters.

مثال: Noor Electronics

contactNamestringيقبل null

Contact person.

مثال: Omar Hassan

contactPhonestringيقبل null

Contact phone.

مثال: 0501234567

contactEmail
مطلوب
string

Contact email. Required; unique across the platform.

مثال: orders@noor-electronics.example

commercialRegNo
مطلوب
string

Commercial registration number (or freelance licence number). Required.

مثال: 1010123456

taxId
مشروط
stringيقبل null

VAT number. Required unless notVatRegistered is true.

مثال: 300123456700003

notVatRegisteredboolean

True when the merchant is not registered for VAT.

مثال: false

address
مطلوب
PublicMerchantAddressInput

A saved pickup address of a merchant, given by names. Country, city and district each accept an id, a code or a name in Arabic or English.

confirmPossibleDuplicateboolean

Confirm that this is a different store even though its registration number, VAT number or name matches another merchant on the platform. Without it such a request is refused with 409 merchant.possible_duplicate.

مثال: false

PublicCreateShipmentRequestكائن#

Body of POST /shipments. Prices are computed from the company's rate card; never send a fee.

الحقلالنوعالوصف
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.

pickupPublicPickupInput

The pickup address.

recipientPublicRecipientInput

The recipient and the delivery address.

parcel
مطلوب
PublicParcelInput

The parcel. Weight and dimensions describe the whole shipment.

paymentPublicPaymentInput

Cash on delivery and freight payment.

deliveryPublicDeliveryOptionsInput

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

PublicCreateWebhookRequestكائن#

Body of POST /merchants/{merchantId}/webhooks.

الحقلالنوعالوصف
url
مطلوب
string

HTTPS URL that receives the events. Private and local addresses are refused.

مثال: https://shop.example.com/hooks/lastmile

events
مطلوب
array<string>

Event types to receive, from GET /webhooks/events. Wildcards: shipment.* (all shipment events) or * (everything). At least one.

مثال: ["shipment.created","shipment.delivered"]

descriptionstringيقبل null

Free text to recognise the subscription (optional, up to 200 characters).

مثال: Order system

PublicDeliveryOptionsDtoكائن#

Handover rules.

الحقلالنوعالوصف
allowOpenPackage
مطلوب
boolean

The recipient may open the package.

requireSignature
مطلوب
boolean

Signature required.

requireIdVerification
مطلوب
boolean

ID check required.

allowNeighborDelivery
مطلوب
boolean

Neighbour delivery allowed.

PublicDeliveryOptionsInputكائن#

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

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

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

مثال: false

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

A signature is required on delivery. Default true.

مثال: true

requireIdVerificationbooleanيقبل null

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

مثال: false

allowNeighborDeliverybooleanيقبل null

A neighbour may accept the parcel. Default true.

مثال: true

PublicDistrictDtoكائن#

District item of the public geography endpoints.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

District id.

nameAr
مطلوب
string

Arabic name.

nameEn
مطلوب
string

English name.

codestringيقبل null

District code, when defined.

cityId
مطلوب
string (uuid)

Id of the city the district belongs to.

pending
مطلوب
boolean

True for a district created by your company that the platform has not approved yet.

PublicDistrictDtoPublicPageكائن#

Standard paged response of every public list endpoint.

الحقلالنوعالوصف
items
مطلوب
array<PublicDistrictDto>

Items of the requested page.

page
مطلوب
integer (int32)

Current page number, starting at 1.

pageSize
مطلوب
integer (int32)

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

totalCount
مطلوب
integer (int32)

Total number of items across all pages.

totalPages
مطلوب
integer (int32)

Total number of pages.

PublicGeoNodeDtoكائن#

A resolved geography node (id and both names).

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Resolved id.

nameAr
مطلوب
string

Arabic name.

nameEn
مطلوب
string

English name.

PublicLoginRequestكائن#

Credentials of a user of the shipping company.

الحقلالنوعالوصف
username
مطلوب
string

Username or e-mail address.

password
مطلوب
string

Password.

PublicMerchantAddressDtoكائن#

A saved pickup address of a merchant.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Address id.

label
مطلوب
string

Short label.

contactNamestringيقبل null

Contact person at the address.

contactPhone
مطلوب
string

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

cityPublicNamedRef

A catalog entry shown in both languages.

districtPublicNamedRef

A catalog entry shown in both languages.

addressLine
مطلوب
string

Street, building and landmark.

shortAddressstringيقبل null

Saudi national short address.

latitudenumber (double)يقبل null

Latitude.

longitudenumber (double)يقبل null

Longitude.

isPrimary
مطلوب
boolean

True for the primary address (used by default as the pickup of the merchant's shipments).

PublicMerchantAddressInputكائن#

A saved pickup address of a merchant, given by names. Country, city and district each accept an id, a code or a name in Arabic or English.

الحقلالنوعالوصف
label
مطلوب
string

Short label of the address, for example "Main warehouse". Required, up to 100 characters.

مثال: Main warehouse

contactNamestringيقبل null

Person to contact at this address (defaults to the merchant name).

مثال: Omar Hassan

contactPhone
مطلوب
string

Phone at this address. Required.

مثال: 0501234567

countrystringيقبل null

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

مثال: SA

city
مطلوب
string

City id, code or name. Required.

مثال: Riyadh

district
مطلوب
string

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

مثال: Al Olaya

addressLine
مطلوب
string

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

مثال: King Fahd Road, Warehouse 4

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

Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia.

مثال: RNBA6769

latitudenumber (double)يقبل null

Latitude (optional).

مثال: 24.7136

longitudenumber (double)يقبل null

Longitude (optional).

مثال: 46.6753

PublicMerchantDtoكائن#

A merchant of the company (no banking, commission, API keys or pricing details).

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Merchant id.

name
مطلوب
string

Account name.

contactNamestringيقبل null

Contact person.

contactPhonestringيقبل null

Contact phone.

contactEmailstringيقبل null

Contact email.

isActive
مطلوب
boolean

Whether the merchant can book shipments.

createdAt
مطلوب
string (date-time)

Creation time (UTC).

primaryAddressPublicMerchantAddressDto

A saved pickup address of a merchant.

PublicMerchantDtoPublicPageكائن#

Standard paged response of every public list endpoint.

الحقلالنوعالوصف
items
مطلوب
array<PublicMerchantDto>

Items of the requested page.

page
مطلوب
integer (int32)

Current page number, starting at 1.

pageSize
مطلوب
integer (int32)

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

totalCount
مطلوب
integer (int32)

Total number of items across all pages.

totalPages
مطلوب
integer (int32)

Total number of pages.

PublicMerchantRefكائن#

A merchant reference.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Merchant id.

name
مطلوب
string

Merchant account name.

PublicMeResponseكائن#

Identity and permissions of the current caller.

الحقلالنوعالوصف
authMethod
مطلوب
string

password or api_key.

company
مطلوب
PublicCompanyDto

Company identity shown by the public auth/me endpoint.

userPublicUserDto

The user behind a password-authenticated call.

apiKeyPublicApiKeyDto

The API key behind a key-authenticated call.

scopes
مطلوب
array<string>

API scopes granted (for password callers: the scopes the user's permissions cover).

permissions
مطلوب
array<string>

Permission codes held by the caller.

PublicNamedRefكائن#

A catalog entry shown in both languages.

الحقلالنوعالوصف
idstring (uuid)يقبل null

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

nameAr
مطلوب
string

Arabic name.

nameEn
مطلوب
string

English name.

PublicOrderSourceقائمة قيم#

How the order reached the system.

القيم: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

PublicParcelDtoكائن#

Parcel data of a shipment.

الحقلالنوعالوصف
weightKg
مطلوب
number (double)

Actual weight.

lengthCm
مطلوب
number (double)

Length.

widthCm
مطلوب
number (double)

Width.

heightCm
مطلوب
number (double)

Height.

chargeableWeightKg
مطلوب
number (double)

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

pieces
مطلوب
integer (int32)

Number of pieces.

descriptionstringيقبل null

What is inside.

declaredValue
مطلوب
number (double)

Declared value.

fragile
مطلوب
boolean

Fragile.

requiresColdChain
مطلوب
boolean

Needs cold chain.

coldChainRangeenum

Temperature range of cold-chain goods.

القيم: frozenchilledambient

flammable
مطلوب
boolean

Flammable.

hazardous
مطلوب
boolean

Hazardous.

containsAlcohol
مطلوب
boolean

Contains alcohol.

liquid
مطلوب
boolean

Liquid.

highValue
مطلوب
boolean

High value.

PublicParcelInputكائن#

The parcel. Weight and dimensions describe the whole shipment.

الحقلالنوعالوصف
weightKg
مطلوب
number (double)

Actual weight in kilograms, greater than 0.

مثال: 1.5

lengthCm
مطلوب
number (double)

Length in centimetres, greater than 0.

مثال: 20

widthCm
مطلوب
number (double)

Width in centimetres, greater than 0.

مثال: 15

heightCm
مطلوب
number (double)

Height in centimetres, greater than 0.

مثال: 10

piecesinteger (int32)يقبل null

Number of pieces (default 1).

مثال: 1

descriptionstringيقبل null

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

مثال: Mobile phone case

declaredValuenumber (double)يقبل null

Declared value of the goods (default 0).

مثال: 250

fragileboolean

Fragile goods.

مثال: false

requiresColdChain
مشروط
boolean

Needs cold chain; then coldChainRange is required.

مثال: false

coldChainRangeenum

Temperature range of cold-chain goods.

القيم: frozenchilledambient

flammableboolean

Flammable goods.

مثال: false

hazardousboolean

Hazardous goods.

مثال: false

containsAlcoholboolean

Contains alcohol.

مثال: false

liquidboolean

Liquid goods.

مثال: false

highValueboolean

High-value goods.

مثال: false

PublicPaymentDtoكائن#

Payment data of a shipment.

الحقلالنوعالوصف
codAmount
مطلوب
number (double)

Cash to collect from the recipient.

shippingFee
مطلوب
number (double)

Shipping fee computed from the rate card.

freightOnDelivery
مطلوب
boolean

True when the recipient pays the fee.

PublicPaymentInputكائن#

Cash on delivery and freight payment.

الحقلالنوعالوصف
codAmountnumber (double)يقبل null

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

مثال: 199.5

freightOnDeliverybooleanيقبل null

True when the recipient pays the shipping fee on delivery.

مثال: false

PublicPickupInputكائن#

The pickup address.

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

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

مثال: SA

city
مطلوب
string

City id, code or name. Required.

مثال: Riyadh

district
مطلوب
string

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

مثال: Al Olaya

addressLine
مطلوب
string

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

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

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

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

مثال: RNBA6769

latitudenumber (double)يقبل null

Latitude, -90 to 90 (optional).

مثال: 24.7136

longitudenumber (double)يقبل null

Longitude, -180 to 180 (optional).

مثال: 46.6753

branchstringيقبل null

Leave this out: the system assigns the branch that covers the pickup address automatically. Send a branch id, code or name only to override that choice, which is needed when no branch or more than one branch covers the pickup area (branch_coverage.no_coverage_for_city, branch_coverage.ambiguous_coverage).

PublicPieceDtoكائن#

One piece of a shipment.

الحقلالنوعالوصف
barcode
مطلوب
string

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

PublicQuoteDtoكائن#

A price quote. Nothing is created or consumed: no tracking number, no quota.

الحقلالنوعالوصف
deliverable
مطلوب
boolean

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.

breakdown
مطلوب
array<PublicQuoteLineDto>

Price lines; they add up to total.

PublicQuoteLineDtoكائن#

One line of a price.

الحقلالنوعالوصف
code
مطلوب
string

baseShipping, handling, codFee or reverseAdjustment.

label
مطلوب
string

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

amount
مطلوب
number (double)

Amount of the line.

PublicQuoteLocationInputكائن#

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

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

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

مثال: SA

city
مطلوب
string

City id, code or name. Required.

مثال: Jeddah

districtstringيقبل null

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

مثال: Al Rawdah

PublicQuoteRequestكائن#

Body of POST /pricing/quote.

الحقلالنوعالوصف
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

pickup
مطلوب
PublicQuoteLocationInput

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

recipient
مطلوب
PublicQuoteLocationInput

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

parcel
مطلوب
PublicParcelInput

The parcel. Weight and dimensions describe the whole shipment.

paymentPublicPaymentInput

Cash on delivery and freight payment.

serviceTypeenum

Kind of service requested for a shipment.

القيم: deliveryexchangereturn

serviceTierenum

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

القيم: standardexpresssameDay

PublicRecipientDtoكائن#

The recipient.

الحقلالنوعالوصف
name
مطلوب
string

Recipient name.

phone
مطلوب
string

Recipient phone.

secondaryPhonestringيقبل null

Second phone.

countryPublicNamedRef

A catalog entry shown in both languages.

cityPublicNamedRef

A catalog entry shown in both languages.

districtPublicNamedRef

A catalog entry shown in both languages.

addressLine
مطلوب
string

Street, building and landmark.

shortAddressstringيقبل null

Saudi national short address.

latitudenumber (double)يقبل null

Latitude.

longitudenumber (double)يقبل null

Longitude.

PublicRecipientInputكائن#

The recipient and the delivery address.

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

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

مثال: SA

city
مطلوب
string

City id, code or name. Required.

مثال: Riyadh

district
مطلوب
string

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

مثال: Al Olaya

addressLine
مطلوب
string

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

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

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

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

مثال: RNBA6769

latitudenumber (double)يقبل null

Latitude, -90 to 90 (optional).

مثال: 24.7136

longitudenumber (double)يقبل null

Longitude, -180 to 180 (optional).

مثال: 46.6753

name
مطلوب
string

Recipient name. Required, up to 200 characters.

مثال: Khaled Alotaibi

phone
مطلوب
string

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

مثال: 0555123456

secondaryPhonestringيقبل null

Second phone (optional).

مثال: 0555987654

PublicRefreshRequestكائن#

Request to exchange a refresh token for a new token pair.

الحقلالنوعالوصف
refreshToken
مطلوب
string

The refresh token returned by login or by a previous refresh (single use).

PublicResolvedLocationDtoكائن#

Result of validating a location by names.

الحقلالنوعالوصف
countryPublicGeoNodeDto

A resolved geography node (id and both names).

cityPublicGeoNodeDto

A resolved geography node (id and both names).

districtPublicGeoNodeDto

A resolved geography node (id and both names).

PublicSenderDtoكائن#

The sender of a shipment.

الحقلالنوعالوصف
type
مطلوب
enum

Who sends the shipment.

القيم: merchantcustom

name
مطلوب
string

Sender name.

phonestringيقبل null

Sender phone.

emailstringيقبل null

Sender email.

merchantPublicMerchantRef

A merchant reference.

PublicSenderInputكائن#

The sender of a shipment.

الحقلالنوعالوصف
typeenum

Who sends the shipment.

القيم: merchantcustom

merchantstringيقبل null

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

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

namestringيقبل null

For custom: sender name (required).

مثال: Sara Ahmed

phonestringيقبل null

For custom: sender phone (required).

مثال: 0501234567

emailstringيقبل null

For custom: sender email (optional).

مثال: sara@example.com

PublicSenderTypeقائمة قيم#

Who sends the shipment.

القيم: merchantcustom

PublicServiceTierقائمة قيم#

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

القيم: standardexpresssameDay

PublicServiceTypeقائمة قيم#

Kind of service requested for a shipment.

القيم: deliveryexchangereturn

PublicShipmentDtoكائن#

A shipment as returned by the public API.

الحقلالنوعالوصف
trackingNumber
مطلوب
string

Tracking number; identifies the shipment in every route.

reference
مطلوب
string

Your order reference.

status
مطلوب
string

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

statusCode
مطلوب
integer (int32)

Numeric status code.

statusLabelAr
مطلوب
string

Arabic status label.

statusLabelEn
مطلوب
string

English status label.

isFinal
مطلوب
boolean

True when the shipment reached a final status.

serviceType
مطلوب
enum

Kind of service requested for a shipment.

القيم: deliveryexchangereturn

serviceTier
مطلوب
enum

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

القيم: standardexpresssameDay

source
مطلوب
enum

How the order reached the system.

القيم: dashboardexcelImportmerchantPortalapiintegrationinviteLinkpublicWebsitephonewhatsAppsocialMediawalkInother

createdAt
مطلوب
string (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)يقبل null

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

sender
مطلوب
PublicSenderDto

The sender of a shipment.

pickup
مطلوب
PublicAddressDto

A resolved address.

recipient
مطلوب
PublicRecipientDto

The recipient.

parcel
مطلوب
PublicParcelDto

Parcel data of a shipment.

delivery
مطلوب
PublicDeliveryOptionsDto

Handover rules.

payment
مطلوب
PublicPaymentDto

Payment data of a shipment.

pieces
مطلوب
array<PublicPieceDto>

The pieces.

branch
مطلوب
PublicBranchRef

A branch reference.

canCancel
مطلوب
boolean

True while the shipment can still be cancelled.

isEditable
مطلوب
boolean

True while the shipment can still be edited.

PublicShipmentSummaryDtoكائن#

A shipment row of the list endpoint.

الحقلالنوعالوصف
trackingNumber
مطلوب
string

Tracking number.

reference
مطلوب
string

Your order reference.

status
مطلوب
string

Status key.

statusLabelAr
مطلوب
string

Arabic status label.

statusLabelEn
مطلوب
string

English status label.

merchantPublicMerchantRef

A merchant reference.

senderName
مطلوب
string

Sender name.

recipientName
مطلوب
string

Recipient name.

recipientPhone
مطلوب
string

Recipient phone.

cityPublicNamedRef

A catalog entry shown in both languages.

districtPublicNamedRef

A catalog entry shown in both languages.

codAmount
مطلوب
number (double)

Cash on delivery amount.

shippingFee
مطلوب
number (double)

Shipping fee.

createdAt
مطلوب
string (date-time)

Creation time (UTC).

estimatedDeliveryDatestring (date)يقبل null

Estimated delivery date.

PublicShipmentSummaryDtoPublicPageكائن#

Standard paged response of every public list endpoint.

الحقلالنوعالوصف
items
مطلوب
array<PublicShipmentSummaryDto>

Items of the requested page.

page
مطلوب
integer (int32)

Current page number, starting at 1.

pageSize
مطلوب
integer (int32)

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

totalCount
مطلوب
integer (int32)

Total number of items across all pages.

totalPages
مطلوب
integer (int32)

Total number of pages.

PublicStatusDtoكائن#

A shipment status of the catalog.

الحقلالنوعالوصف
code
مطلوب
integer (int32)

Numeric status code.

key
مطلوب
string

Status key used in the API.

nameAr
مطلوب
string

Arabic name.

nameEn
مطلوب
string

English name.

isFinal
مطلوب
boolean

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

PublicTokenResponseكائن#

Token pair returned by login and refresh.

الحقلالنوعالوصف
accessToken
مطلوب
string

JWT to send as Authorization: Bearer ....

refreshToken
مطلوب
string

Single-use refresh token.

tokenType
مطلوب
string

Always Bearer.

expiresIn
مطلوب
integer (int32)

Lifetime of the access token in seconds.

PublicTrackingDtoكائن#

Tracking of one shipment.

الحقلالنوعالوصف
trackingNumber
مطلوب
string

Tracking number.

status
مطلوب
string

Current status key.

statusLabelAr
مطلوب
string

Arabic label of the current status.

statusLabelEn
مطلوب
string

English label of the current status.

estimatedDeliveryDatestring (date)يقبل null

Estimated delivery date.

events
مطلوب
array<PublicTrackingEventDto>

Timeline, oldest first.

PublicTrackingEventDtoكائن#

One step of the status timeline.

الحقلالنوعالوصف
status
مطلوب
string

Status key.

statusLabelAr
مطلوب
string

Arabic label.

statusLabelEn
مطلوب
string

English label.

at
مطلوب
string (date-time)

When the status was set (UTC).

notestringيقبل null

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

locationstringيقبل null

Reserved; not populated yet.

PublicUpdateMerchantRequestكائن#

Body of PUT /merchants/{id}. Only the fields you send change.

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

New account name.

مثال: Noor Electronics

contactNamestringيقبل null

New contact person.

مثال: Omar Hassan

contactPhonestringيقبل null

New contact phone.

مثال: 0501234567

contactEmailstringيقبل null

New contact email.

مثال: orders@noor-electronics.example

PublicUpdateParcelInputكائن#

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

الحقلالنوعالوصف
weightKgnumber (double)يقبل null

Weight in kilograms.

مثال: 2

lengthCmnumber (double)يقبل null

Length in centimetres.

مثال: 20

widthCmnumber (double)يقبل null

Width in centimetres.

مثال: 15

heightCmnumber (double)يقبل null

Height in centimetres.

مثال: 10

piecesinteger (int32)يقبل null

Number of pieces.

مثال: 1

declaredValuenumber (double)يقبل null

Declared value of the goods.

مثال: 300

PublicUpdateRecipientInputكائن#

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

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

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

مثال: SA

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

City id, code or name. Required.

مثال: Riyadh

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

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

مثال: Al Olaya

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

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

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

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

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

مثال: RNBA6769

latitudenumber (double)يقبل null

Latitude, -90 to 90 (optional).

مثال: 24.7136

longitudenumber (double)يقبل null

Longitude, -180 to 180 (optional).

مثال: 46.6753

namestringيقبل null

Recipient name.

مثال: Khaled Alotaibi

phonestringيقبل null

Recipient phone.

مثال: 0555123456

secondaryPhonestringيقبل null

Second phone.

مثال: 0555987654

PublicUpdateShipmentRequestكائن#

Body of PUT /shipments/{trackingNumber}. Every field except reason is optional: only the fields you send change, everything else keeps its current value. At least one field is required.

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

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).

parcelPublicUpdateParcelInput

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

paymentPublicPaymentInput

Cash on delivery and freight payment.

PublicUserDtoكائن#

The user behind a password-authenticated call.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

User id.

namestringيقبل null

Full name.

PublicWebhookCreatedDtoكائن#

A newly created subscription. The signing secret is returned here once and cannot be read again.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Subscription id.

merchantId
مطلوب
string (uuid)

The merchant whose shipments trigger the events.

url
مطلوب
string

The receiving URL.

events
مطلوب
array<string>

Subscribed event types.

descriptionstringيقبل null

Description.

isActive
مطلوب
boolean

Whether it is active.

createdAt
مطلوب
string (date-time)

Creation time (UTC).

secret
مطلوب
string

Signing secret: keep it safe, use it to verify the X-Signature header of every delivery.

PublicWebhookDtoكائن#

A webhook subscription of a merchant.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Subscription id.

merchantId
مطلوب
string (uuid)

The merchant whose shipments trigger the events.

url
مطلوب
string

The receiving URL.

events
مطلوب
array<string>

Subscribed event types.

descriptionstringيقبل null

Description.

isActive
مطلوب
boolean

False when the subscription is paused.

createdAt
مطلوب
string (date-time)

Creation time (UTC).

PublicWebhookEventDtoكائن#

An event type that can be subscribed to.

الحقلالنوعالوصف
type
مطلوب
string

Event type, e.g. shipment.delivered.

description
مطلوب
string

When the event is sent.

examplePayload
مطلوب
any

An example of the JSON body of the delivery (event, occurredAt, data).

PublicWebhookSecretDtoكائن#

A rotated signing secret (shown once; the previous secret stops working immediately).

الحقلالنوعالوصف
secret
مطلوب
string

The new signing secret.

PublicWebhookTestDtoكائن#

Result of a test delivery request.

الحقلالنوعالوصف
queued
مطلوب
boolean

True when a signed ping event was queued for delivery.

eventType
مطلوب
string

The event type sent (ping).

PublicZoneRefكائن#

A pricing zone.

الحقلالنوعالوصف
id
مطلوب
string (uuid)

Zone id.

name
مطلوب
string

Zone name.