النماذج (Schemas)
كل أنواع البيانات المستخدمة في الطلبات والاستجابات. كل اسم هو هدف رابط، فالنقر على نوع حقل في صفحات العمليات ينقلك إلى هنا.
PublicAddressDtoكائن#
A resolved address.
| الحقل | النوع | الوصف |
|---|---|---|
country | PublicNamedRef | A catalog entry shown in both languages. |
city | PublicNamedRef | A catalog entry shown in both languages. |
district | PublicNamedRef | A catalog entry shown in both languages. |
addressLine | stringيقبل null | Street, building and landmark. |
shortAddress | stringيقبل null | Saudi national short address. |
latitude | number (double)يقبل null | Latitude. |
longitude | number (double)يقبل null | Longitude. |
PublicApiErrorكائن#
Error envelope returned for every non-2xx response of the public API (/api/public/v1).
| الحقل | النوع | الوصف |
|---|---|---|
code | stringيقبل null | Stable machine-readable code, e.g. |
message | stringيقبل null | Human readable message. Arabic by default; English when Accept-Language prefers English. |
status | integer (int32) | HTTP status code, repeated in the body. |
details | objectيقبل null | Extra data: |
traceId | stringيقبل null | 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. |
name | stringيقبل 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يقبل null | Branch name. |
code | stringيقبل null | Branch code. |
city | stringيقبل null | City name as entered on the branch. |
phone | stringيقبل null | Branch phone, when set. |
latitude | number (double)يقبل null | Latitude, when set. |
longitude | number (double)يقبل null | Longitude, when set. |
isActive | boolean | Whether the branch is active. |
PublicBranchDtoPublicPageكائن#
Standard paged response of every public list endpoint.
| الحقل | النوع | الوصف |
|---|---|---|
items | array<PublicBranchDto>يقبل null | 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يقبل null | Branch name. |
PublicCancelShipmentRequestكائن#
Body of POST /shipments/{trackingNumber}/cancel.
| الحقل | النوع | الوصف |
|---|---|---|
reason | stringيقبل null | Why the shipment is cancelled (kept in the shipment history). Up to 500 characters. مثال: |
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يقبل null | Arabic name. |
nameEn | stringيقبل null | English name. |
code | stringيقبل 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>يقبل null | 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يقبل null | Company name. |
slug | stringيقبل null | Company slug. |
PublicCountryDtoكائن#
Country item of the public geography endpoints.
| الحقل | النوع | الوصف |
|---|---|---|
id | string (uuid) | Country id. |
nameAr | stringيقبل null | Arabic name. |
nameEn | stringيقبل null | English name. |
code | stringيقبل null | ISO 3166-1 alpha-2 code. |
PublicCountryDtoPublicPageكائن#
Standard paged response of every public list endpoint.
| الحقل | النوع | الوصف |
|---|---|---|
items | array<PublicCountryDto>يقبل null | 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يقبل null | Arabic name. |
nameEn | stringيقبل null | English name. |
code | stringيقبل 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>يقبل null | 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يقبل null | Short label of the address, for example "Main warehouse". Required, up to 100 characters. مثال: |
contactName | stringيقبل null | Person to contact at this address (defaults to the merchant name). مثال: |
contactPhoneمطلوب | stringيقبل null | Phone at this address. Required. مثال: |
country | stringيقبل null | Country id, ISO code or name. Optional when the city name is unambiguous. مثال: |
cityمطلوب | stringيقبل null | City id, code or name. Required. مثال: |
districtمطلوب | stringيقبل null | District id, code or name. Required. Unknown districts are never created: you get مثال: |
addressLineمطلوب | stringيقبل null | Street, building and landmark. Required, up to 500 characters. مثال: |
shortAddressمشروط | stringيقبل null | Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia. مثال: |
latitude | number (double)يقبل null | Latitude (optional). مثال: |
longitude | number (double)يقبل null | Longitude (optional). مثال: |
makePrimary | boolean | Make this the primary address (the first address of a merchant is always primary). مثال: |
PublicCreateMerchantRequestكائن#
Body of POST /merchants.
| الحقل | النوع | الوصف |
|---|---|---|
nameمطلوب | stringيقبل null | Account (store) name. Not unique, but a name that matches another merchant on the platform needs مثال: |
contactName | stringيقبل null | Contact person. مثال: |
contactPhone | stringيقبل null | Contact phone. مثال: |
contactEmailمطلوب | stringيقبل null | Contact email. Required; unique across the platform. مثال: |
commercialRegNoمطلوب | stringيقبل null | Commercial registration number (or freelance licence number). Required. مثال: |
taxIdمشروط | stringيقبل null | VAT number. Required unless مثال: |
notVatRegistered | boolean | True when the merchant is not registered for VAT. مثال: |
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. |
confirmPossibleDuplicate | boolean | 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 مثال: |
PublicCreateShipmentRequestكائن#
Body of POST /shipments. Prices are computed from the company's rate card; never send a fee.
| الحقل | النوع | الوصف |
|---|---|---|
reference | stringيقبل null | Your own order reference (shown on the label and searchable). Up to 100 characters. مثال: |
serviceType | enum | Kind of service requested for a shipment. القيم: |
serviceTier | enum | Speed of the service; it drives the estimated delivery date. القيم: |
sender | PublicSenderInput | The sender of a shipment. |
pickup | PublicPickupInput | The pickup address. |
recipient | PublicRecipientInput | The recipient and the delivery address. |
parcel | PublicParcelInput | The parcel. Weight and dimensions describe the whole shipment. |
payment | PublicPaymentInput | Cash on delivery and freight payment. |
delivery | PublicDeliveryOptionsInput | Handover rules at the recipient's door. Omitted values use the system defaults shown. |
PublicCreateWebhookRequestكائن#
Body of POST /merchants/{merchantId}/webhooks.
| الحقل | النوع | الوصف |
|---|---|---|
url | stringيقبل null | HTTPS URL that receives the events. Private and local addresses are refused. مثال: |
events | array<string>يقبل null | Event types to receive, from مثال: |
description | stringيقبل null | Free text to recognise the subscription (optional, up to 200 characters). مثال: |
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.
| الحقل | النوع | الوصف |
|---|---|---|
allowOpenPackage | booleanيقبل null | The recipient may open the package before accepting. Default false. مثال: |
requireSignatureمشروط | booleanيقبل null | A signature is required on delivery. Default true. مثال: |
requireIdVerification | booleanيقبل null | The courier must verify the recipient's ID. Default false. مثال: |
allowNeighborDelivery | booleanيقبل null | A neighbour may accept the parcel. Default true. مثال: |
PublicDistrictDtoكائن#
District item of the public geography endpoints.
| الحقل | النوع | الوصف |
|---|---|---|
id | string (uuid) | District id. |
nameAr | stringيقبل null | Arabic name. |
nameEn | stringيقبل null | English name. |
code | stringيقبل 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>يقبل null | 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يقبل null | Arabic name. |
nameEn | stringيقبل null | English name. |
PublicLoginRequestكائن#
Credentials of a user of the shipping company.
| الحقل | النوع | الوصف |
|---|---|---|
username | stringيقبل null | Username or e-mail address. |
password | stringيقبل null | Password. |
PublicMerchantAddressDtoكائن#
A saved pickup address of a merchant.
| الحقل | النوع | الوصف |
|---|---|---|
id | string (uuid) | Address id. |
label | stringيقبل null | Short label. |
contactName | stringيقبل null | Contact person at the address. |
contactPhone | stringيقبل null | Phone at the address. |
country | PublicNamedRef | A catalog entry shown in both languages. |
city | PublicNamedRef | A catalog entry shown in both languages. |
district | PublicNamedRef | A catalog entry shown in both languages. |
addressLine | stringيقبل null | Street, building and landmark. |
shortAddress | stringيقبل null | Saudi national short address. |
latitude | number (double)يقبل null | Latitude. |
longitude | number (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يقبل null | Short label of the address, for example "Main warehouse". Required, up to 100 characters. مثال: |
contactName | stringيقبل null | Person to contact at this address (defaults to the merchant name). مثال: |
contactPhoneمطلوب | stringيقبل null | Phone at this address. Required. مثال: |
country | stringيقبل null | Country id, ISO code or name. Optional when the city name is unambiguous. مثال: |
cityمطلوب | stringيقبل null | City id, code or name. Required. مثال: |
districtمطلوب | stringيقبل null | District id, code or name. Required. Unknown districts are never created: you get مثال: |
addressLineمطلوب | stringيقبل null | Street, building and landmark. Required, up to 500 characters. مثال: |
shortAddressمشروط | stringيقبل null | Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia. مثال: |
latitude | number (double)يقبل null | Latitude (optional). مثال: |
longitude | number (double)يقبل null | Longitude (optional). مثال: |
PublicMerchantDtoكائن#
A merchant of the company (no banking, commission, API keys or pricing details).
| الحقل | النوع | الوصف |
|---|---|---|
id | string (uuid) | Merchant id. |
name | stringيقبل null | Account name. |
contactName | stringيقبل null | Contact person. |
contactPhone | stringيقبل null | Contact phone. |
contactEmail | stringيقبل null | Contact email. |
isActive | boolean | Whether the merchant can book shipments. |
createdAt | string (date-time) | Creation time (UTC). |
primaryAddress | PublicMerchantAddressDto | A saved pickup address of a merchant. |
PublicMerchantDtoPublicPageكائن#
Standard paged response of every public list endpoint.
| الحقل | النوع | الوصف |
|---|---|---|
items | array<PublicMerchantDto>يقبل null | 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يقبل null | Merchant account name. |
PublicMeResponseكائن#
Identity and permissions of the current caller.
| الحقل | النوع | الوصف |
|---|---|---|
authMethod | stringيقبل null |
|
company | PublicCompanyDto | Company identity shown by the public |
user | PublicUserDto | The user behind a password-authenticated call. |
apiKey | PublicApiKeyDto | The API key behind a key-authenticated call. |
scopes | array<string>يقبل null | API scopes granted (for password callers: the scopes the user's permissions cover). |
permissions | array<string>يقبل null | Permission codes held by the caller. |
PublicNamedRefكائن#
A catalog entry shown in both languages.
| الحقل | النوع | الوصف |
|---|---|---|
id | string (uuid)يقبل null | Catalog id, or null for legacy shipments that only stored a name. |
nameAr | stringيقبل null | Arabic name. |
nameEn | stringيقبل null | 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. |
description | stringيقبل null | What is inside. |
declaredValue | number (double) | Declared value. |
fragile | boolean | Fragile. |
requiresColdChain | boolean | Needs cold chain. |
coldChainRange | enum | Temperature range of cold-chain goods. القيم: |
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. مثال: |
lengthCmمطلوب | number (double) | Length in centimetres, greater than 0. مثال: |
widthCmمطلوب | number (double) | Width in centimetres, greater than 0. مثال: |
heightCmمطلوب | number (double) | Height in centimetres, greater than 0. مثال: |
pieces | integer (int32)يقبل null | Number of pieces (default 1). مثال: |
description | stringيقبل null | What is inside (optional, shown on the label). مثال: |
declaredValue | number (double)يقبل null | Declared value of the goods (default 0). مثال: |
fragile | boolean | Fragile goods. مثال: |
requiresColdChainمشروط | boolean | Needs cold chain; then مثال: |
coldChainRange | enum | Temperature range of cold-chain goods. القيم: |
flammable | boolean | Flammable goods. مثال: |
hazardous | boolean | Hazardous goods. مثال: |
containsAlcohol | boolean | Contains alcohol. مثال: |
liquid | boolean | Liquid goods. مثال: |
highValue | boolean | High-value goods. مثال: |
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.
| الحقل | النوع | الوصف |
|---|---|---|
codAmount | number (double)يقبل null | Amount the courier collects from the recipient (cash on delivery). Default 0. Must be 0 for مثال: |
freightOnDelivery | booleanيقبل null | True when the recipient pays the shipping fee on delivery. مثال: |
PublicPickupInputكائن#
The pickup address.
| الحقل | النوع | الوصف |
|---|---|---|
country | stringيقبل null | Country id, ISO code or name. Optional when the city name is unambiguous. مثال: |
cityمطلوب | stringيقبل null | City id, code or name. Required. مثال: |
districtمطلوب | stringيقبل null | District id, code or name. Required. Unknown districts are never created: you get مثال: |
addressLineمطلوب | stringيقبل null | Street, building and landmark. Required, up to 500 characters. مثال: |
shortAddressمشروط | stringيقبل null | Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia. مثال: |
latitude | number (double)يقبل null | Latitude, -90 to 90 (optional). مثال: |
longitude | number (double)يقبل null | Longitude, -180 to 180 (optional). مثال: |
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 ( مثال: |
PublicPieceDtoكائن#
One piece of a shipment.
| الحقل | النوع | الوصف |
|---|---|---|
barcode | stringيقبل null | Piece barcode (the tracking number followed by |
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 | stringيقبل null |
|
shippingFee | number (double)يقبل null | Shipping fee without the COD fee (weight price plus handling surcharges). |
codFee | number (double)يقبل null | Fee charged for collecting cash on delivery. |
total | number (double)يقبل null | What the shipment will be charged: |
chargeableWeightKg | number (double)يقبل null | The larger of actual and volumetric weight. |
zone | PublicZoneRef | A pricing zone. |
breakdown | array<PublicQuoteLineDto>يقبل null | Price lines; they add up to |
PublicQuoteLineDtoكائن#
One line of a price.
| الحقل | النوع | الوصف |
|---|---|---|
code | stringيقبل null |
|
label | stringيقبل null | Readable label (the handling flag name for |
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.
| الحقل | النوع | الوصف |
|---|---|---|
country | stringيقبل null | Country id, ISO code or name. Optional when the city name is unambiguous. مثال: |
cityمطلوب | stringيقبل null | City id, code or name. Required. مثال: |
district | stringيقبل null | District id, code or name. Optional for a quote; when sent it must exist. مثال: |
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 مثال: |
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. |
payment | PublicPaymentInput | Cash on delivery and freight payment. |
serviceType | enum | Kind of service requested for a shipment. القيم: |
serviceTier | enum | Speed of the service; it drives the estimated delivery date. القيم: |
PublicRecipientDtoكائن#
The recipient.
| الحقل | النوع | الوصف |
|---|---|---|
name | stringيقبل null | Recipient name. |
phone | stringيقبل null | Recipient phone. |
secondaryPhone | stringيقبل null | Second phone. |
country | PublicNamedRef | A catalog entry shown in both languages. |
city | PublicNamedRef | A catalog entry shown in both languages. |
district | PublicNamedRef | A catalog entry shown in both languages. |
addressLine | stringيقبل null | Street, building and landmark. |
shortAddress | stringيقبل null | Saudi national short address. |
latitude | number (double)يقبل null | Latitude. |
longitude | number (double)يقبل null | Longitude. |
PublicRecipientInputكائن#
The recipient and the delivery address.
| الحقل | النوع | الوصف |
|---|---|---|
country | stringيقبل null | Country id, ISO code or name. Optional when the city name is unambiguous. مثال: |
cityمطلوب | stringيقبل null | City id, code or name. Required. مثال: |
districtمطلوب | stringيقبل null | District id, code or name. Required. Unknown districts are never created: you get مثال: |
addressLineمطلوب | stringيقبل null | Street, building and landmark. Required, up to 500 characters. مثال: |
shortAddressمشروط | stringيقبل null | Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia. مثال: |
latitude | number (double)يقبل null | Latitude, -90 to 90 (optional). مثال: |
longitude | number (double)يقبل null | Longitude, -180 to 180 (optional). مثال: |
nameمطلوب | stringيقبل null | Recipient name. Required, up to 200 characters. مثال: |
phoneمطلوب | stringيقبل null | Recipient phone. Required; digits, spaces, +, - and brackets. مثال: |
secondaryPhone | stringيقبل null | Second phone (optional). مثال: |
PublicRefreshRequestكائن#
Request to exchange a refresh token for a new token pair.
| الحقل | النوع | الوصف |
|---|---|---|
refreshToken | stringيقبل null | The refresh token returned by login or by a previous refresh (single use). |
PublicResolvedLocationDtoكائن#
Result of validating a location by names.
| الحقل | النوع | الوصف |
|---|---|---|
country | PublicGeoNodeDto | A resolved geography node (id and both names). |
city | PublicGeoNodeDto | A resolved geography node (id and both names). |
district | PublicGeoNodeDto | A resolved geography node (id and both names). |
PublicSenderDtoكائن#
The sender of a shipment.
| الحقل | النوع | الوصف |
|---|---|---|
type | enum | Who sends the shipment. القيم: |
name | stringيقبل null | Sender name. |
phone | stringيقبل null | Sender phone. |
email | stringيقبل null | Sender email. |
merchant | PublicMerchantRef | A merchant reference. |
PublicSenderInputكائن#
The sender of a shipment.
| الحقل | النوع | الوصف |
|---|---|---|
type | enum | Who sends the shipment. القيم: |
merchant | stringيقبل null | For مثال: |
name | stringيقبل null | For مثال: |
phone | stringيقبل null | For مثال: |
email | stringيقبل null | For مثال: |
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يقبل null | Tracking number; identifies the shipment in every route. |
reference | stringيقبل null | Your order reference. |
status | stringيقبل null | Status key, e.g. |
statusCode | integer (int32) | Numeric status code. |
statusLabelAr | stringيقبل null | Arabic status label. |
statusLabelEn | stringيقبل null | English status label. |
isFinal | boolean | True when the shipment reached a final status. |
serviceType | enum | Kind of service requested for a shipment. القيم: |
serviceTier | enum | Speed of the service; it drives the estimated delivery date. القيم: |
source | enum | How the order reached the system. القيم: |
createdAt | string (date-time) | Creation time (UTC). |
estimatedDeliveryDate | string (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>يقبل null | 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يقبل null | Tracking number. |
reference | stringيقبل null | Your order reference. |
status | stringيقبل null | Status key. |
statusLabelAr | stringيقبل null | Arabic status label. |
statusLabelEn | stringيقبل null | English status label. |
merchant | PublicMerchantRef | A merchant reference. |
senderName | stringيقبل null | Sender name. |
recipientName | stringيقبل null | Recipient name. |
recipientPhone | stringيقبل null | Recipient phone. |
city | PublicNamedRef | A catalog entry shown in both languages. |
district | PublicNamedRef | 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). |
estimatedDeliveryDate | string (date)يقبل null | Estimated delivery date. |
PublicShipmentSummaryDtoPublicPageكائن#
Standard paged response of every public list endpoint.
| الحقل | النوع | الوصف |
|---|---|---|
items | array<PublicShipmentSummaryDto>يقبل null | 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يقبل null | Status key used in the API. |
nameAr | stringيقبل null | Arabic name. |
nameEn | stringيقبل null | 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يقبل null | JWT to send as |
refreshToken | stringيقبل null | Single-use refresh token. |
tokenType | stringيقبل null | Always |
expiresIn | integer (int32) | Lifetime of the access token in seconds. |
PublicTrackingDtoكائن#
Tracking of one shipment.
| الحقل | النوع | الوصف |
|---|---|---|
trackingNumber | stringيقبل null | Tracking number. |
status | stringيقبل null | Current status key. |
statusLabelAr | stringيقبل null | Arabic label of the current status. |
statusLabelEn | stringيقبل null | English label of the current status. |
estimatedDeliveryDate | string (date)يقبل null | Estimated delivery date. |
events | array<PublicTrackingEventDto>يقبل null | Timeline, oldest first. |
PublicTrackingEventDtoكائن#
One step of the status timeline.
| الحقل | النوع | الوصف |
|---|---|---|
status | stringيقبل null | Status key. |
statusLabelAr | stringيقبل null | Arabic label. |
statusLabelEn | stringيقبل null | English label. |
at | string (date-time) | When the status was set (UTC). |
note | stringيقبل null | Reason, only for failed attempts, postponements, cancellation, returns, loss and damage. |
location | stringيقبل null | Reserved; not populated yet. |
PublicUpdateMerchantRequestكائن#
Body of PUT /merchants/{id}. Only the fields you send change.
| الحقل | النوع | الوصف |
|---|---|---|
name | stringيقبل null | New account name. مثال: |
contactName | stringيقبل null | New contact person. مثال: |
contactPhone | stringيقبل null | New contact phone. مثال: |
contactEmail | stringيقبل null | New contact email. مثال: |
PublicUpdateParcelInputكائن#
Parcel fields that can change. Only the fields you send are changed.
| الحقل | النوع | الوصف |
|---|---|---|
weightKg | number (double)يقبل null | Weight in kilograms. مثال: |
lengthCm | number (double)يقبل null | Length in centimetres. مثال: |
widthCm | number (double)يقبل null | Width in centimetres. مثال: |
heightCm | number (double)يقبل null | Height in centimetres. مثال: |
pieces | integer (int32)يقبل null | Number of pieces. مثال: |
declaredValue | number (double)يقبل null | Declared value of the goods. مثال: |
PublicUpdateRecipientInputكائن#
Recipient fields that can change. Sending any address field re-resolves the whole address (city and district are then required).
| الحقل | النوع | الوصف |
|---|---|---|
country | stringيقبل null | Country id, ISO code or name. Optional when the city name is unambiguous. مثال: |
cityمطلوب | stringيقبل null | City id, code or name. Required. مثال: |
districtمطلوب | stringيقبل null | District id, code or name. Required. Unknown districts are never created: you get مثال: |
addressLineمطلوب | stringيقبل null | Street, building and landmark. Required, up to 500 characters. مثال: |
shortAddressمشروط | stringيقبل null | Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia. مثال: |
latitude | number (double)يقبل null | Latitude, -90 to 90 (optional). مثال: |
longitude | number (double)يقبل null | Longitude, -180 to 180 (optional). مثال: |
name | stringيقبل null | Recipient name. مثال: |
phone | stringيقبل null | Recipient phone. مثال: |
secondaryPhone | stringيقبل null | Second phone. مثال: |
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يقبل null | Why the shipment is edited (kept in the shipment's audit trail). Required, up to 300 characters. مثال: |
reference | stringيقبل null | New order reference. مثال: |
recipient | PublicUpdateRecipientInput | Recipient fields that can change. Sending any address field re-resolves the whole address (city and district are then required). |
parcel | PublicUpdateParcelInput | Parcel fields that can change. Only the fields you send are changed. |
payment | PublicPaymentInput | Cash on delivery and freight payment. |
PublicUserDtoكائن#
The user behind a password-authenticated call.
| الحقل | النوع | الوصف |
|---|---|---|
id | string (uuid) | User id. |
name | stringيقبل 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يقبل null | The receiving URL. |
events | array<string>يقبل null | Subscribed event types. |
description | stringيقبل null | Description. |
isActive | boolean | Whether it is active. |
createdAt | string (date-time) | Creation time (UTC). |
secret | stringيقبل null | Signing secret: keep it safe, use it to verify the |
PublicWebhookDtoكائن#
A webhook subscription of a merchant.
| الحقل | النوع | الوصف |
|---|---|---|
id | string (uuid) | Subscription id. |
merchantId | string (uuid) | The merchant whose shipments trigger the events. |
url | stringيقبل null | The receiving URL. |
events | array<string>يقبل null | Subscribed event types. |
description | stringيقبل 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يقبل null | Event type, e.g. |
description | stringيقبل null | When the event is sent. |
examplePayload | anyيقبل null | An example of the JSON body of the delivery ( |
PublicWebhookSecretDtoكائن#
A rotated signing secret (shown once; the previous secret stops working immediately).
| الحقل | النوع | الوصف |
|---|---|---|
secret | stringيقبل null | The new signing secret. |
PublicWebhookTestDtoكائن#
Result of a test delivery request.
| الحقل | النوع | الوصف |
|---|---|---|
queued | boolean | True when a signed |
eventType | stringيقبل null | The event type sent ( |
PublicZoneRefكائن#
A pricing zone.
| الحقل | النوع | الوصف |
|---|---|---|
id | string (uuid) | Zone id. |
name | stringيقبل null | Zone name. |