GROperator

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

English

Merchants

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

GET

/api/public/v1/merchants

#

List merchants

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

Ordered by name, paginated. No banking, commission, API key or pricing fields are exposed.

المعاملات

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

Page number, starting at 1.

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

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

searchquerystring

Text matched against name, contact person, phone and email.

isActivequeryboolean

Only active (true) or only inactive (false) merchants.

مثال طلب

GET /merchants
curl -G "https://api.goldrock.live/api/public/v1/merchants" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  --data-urlencode 'search=noor' \
  --data-urlencode 'isActive=true'

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

الاستجابات

200A page of merchants.

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

Items of the requested page.

id
items[].id
string (uuid)

Merchant id.

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

Account name.

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

Contact person.

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

Contact phone.

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

Contact email.

isActive
items[].isActive
boolean

Whether the merchant can book shipments.

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

Creation time (UTC).

primaryAddress
items[].primaryAddress
PublicMerchantAddressDto

A saved pickup address of a merchant.

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

Address id.

label
items[].primaryAddress.label
stringيقبل null

Short label.

contactName
items[].primaryAddress.contactName
stringيقبل null

Contact person at the address.

contactPhone
items[].primaryAddress.contactPhone
stringيقبل null

Phone at the address.

country
items[].primaryAddress.country
PublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
items[].primaryAddress.country.nameAr
stringيقبل null

Arabic name.

nameEn
items[].primaryAddress.country.nameEn
stringيقبل null

English name.

city
items[].primaryAddress.city
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

district
items[].primaryAddress.district
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

addressLine
items[].primaryAddress.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
items[].primaryAddress.shortAddress
stringيقبل null

Saudi national short address.

latitude
items[].primaryAddress.latitude
number (double)يقبل null

Latitude.

longitude
items[].primaryAddress.longitude
number (double)يقبل null

Longitude.

isPrimary
items[].primaryAddress.isPrimary
boolean

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

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 · مثال استجابة
{
  "page": 1,
  "pageSize": 1,
  "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.

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

POST

/api/public/v1/merchants

#

Create a merchant

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

Uses the dashboard's rules: commercial registration number and email are required, the VAT number is required unless notVatRegistered is true, and the primary pickup address is required (country/city/district by names, matched strictly; nothing is created). Data that matches another merchant on the platform is refused with 409 (merchant.email_taken_format, merchant.same_merchant_format) or, when it only looks similar, with 409 merchant.possible_duplicate unless confirmPossibleDuplicate is true. Unlike the dashboard, no merchant login and no email are created. Retries are safe with Idempotency-Key.

المعاملات

الاسمالموضعالنوعالوصف
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.

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

The merchant.

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

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يقبل null

Contact email. Required; unique across the platform.

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

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

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

addressPublicMerchantAddressInput

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
address.label
مطلوب
stringيقبل null

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

مثال: Main warehouse

contactName
address.contactName
stringيقبل null

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

مثال: Omar Hassan

contactPhone
address.contactPhone
مطلوب
stringيقبل null

Phone at this address. Required.

مثال: 0501234567

country
address.country
stringيقبل null

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

مثال: SA

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

City id, code or name. Required.

مثال: Riyadh

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

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

مثال: Al Olaya

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

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

مثال: King Fahd Road, Warehouse 4

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

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

مثال: RNBA6769

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

Latitude (optional).

مثال: 24.7136

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

Longitude (optional).

مثال: 46.6753

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

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

مثال طلب

POST /merchants
curl -X POST "https://api.goldrock.live/api/public/v1/merchants" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: merchant-1010123456" \
  -d '{
  "name": "Noor Electronics",
  "contactName": "Omar Hassan",
  "contactPhone": "0501234567",
  "contactEmail": "orders@noor-electronics.example",
  "commercialRegNo": "1010123456",
  "taxId": "300123456700003",
  "notVatRegistered": false,
  "address": {
    "label": "Main warehouse",
    "contactPhone": "0501234567",
    "country": "SA",
    "city": "Riyadh",
    "district": "Al Olaya",
    "addressLine": "King Fahd Road, Warehouse 4",
    "shortAddress": "RNBA6769"
  }
}'

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

الاستجابات

201The created merchant.

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

Merchant id.

namestringيقبل null

Account name.

contactNamestringيقبل null

Contact person.

contactPhonestringيقبل null

Contact phone.

contactEmailstringيقبل null

Contact email.

isActiveboolean

Whether the merchant can book shipments.

createdAtstring (date-time)

Creation time (UTC).

primaryAddressPublicMerchantAddressDto

A saved pickup address of a merchant.

id
primaryAddress.id
string (uuid)

Address id.

label
primaryAddress.label
stringيقبل null

Short label.

contactName
primaryAddress.contactName
stringيقبل null

Contact person at the address.

contactPhone
primaryAddress.contactPhone
stringيقبل null

Phone at the address.

country
primaryAddress.country
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

city
primaryAddress.city
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

district
primaryAddress.district
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

addressLine
primaryAddress.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
primaryAddress.shortAddress
stringيقبل null

Saudi national short address.

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

Latitude.

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

Longitude.

isPrimary
primaryAddress.isPrimary
boolean

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

201 · مثال استجابة
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Noor Electronics",
  "contactName": "Omar Hassan",
  "contactPhone": "0501234567",
  "contactEmail": "orders@noor-electronics.example",
  "isActive": true,
  "createdAt": "2026-01-10T08:00:00Z",
  "primaryAddress": {
    "id": "9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42",
    "label": "Main warehouse",
    "contactName": "Omar Hassan",
    "contactPhone": "0501234567",
    "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,
    "isPrimary": 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).

409

Conflict

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/merchants/{id}

#

Get a merchant

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

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

المعاملات

الاسمالموضعالنوعالوصف
id
مطلوب
pathstring (uuid)

Merchant id.

مثال طلب

GET /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6
curl "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

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

الاستجابات

200The merchant with its primary address.

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

Merchant id.

namestringيقبل null

Account name.

contactNamestringيقبل null

Contact person.

contactPhonestringيقبل null

Contact phone.

contactEmailstringيقبل null

Contact email.

isActiveboolean

Whether the merchant can book shipments.

createdAtstring (date-time)

Creation time (UTC).

primaryAddressPublicMerchantAddressDto

A saved pickup address of a merchant.

id
primaryAddress.id
string (uuid)

Address id.

label
primaryAddress.label
stringيقبل null

Short label.

contactName
primaryAddress.contactName
stringيقبل null

Contact person at the address.

contactPhone
primaryAddress.contactPhone
stringيقبل null

Phone at the address.

country
primaryAddress.country
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

city
primaryAddress.city
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

district
primaryAddress.district
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

addressLine
primaryAddress.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
primaryAddress.shortAddress
stringيقبل null

Saudi national short address.

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

Latitude.

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

Longitude.

isPrimary
primaryAddress.isPrimary
boolean

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

200 · مثال استجابة
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Noor Electronics",
  "contactName": "Omar Hassan",
  "contactPhone": "0501234567",
  "contactEmail": "orders@noor-electronics.example",
  "isActive": true,
  "createdAt": "2026-01-10T08:00:00Z",
  "primaryAddress": {
    "id": "9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42",
    "label": "Main warehouse",
    "contactName": "Omar Hassan",
    "contactPhone": "0501234567",
    "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,
    "isPrimary": 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 merchant.not_found.

429

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

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

PUT

/api/public/v1/merchants/{id}

#

Update a merchant

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

Changes the name and contact fields you send; everything else (registration numbers, pricing, banking) is untouched.

المعاملات

الاسمالموضعالنوعالوصف
id
مطلوب
pathstring (uuid)

Merchant id.

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

The changes.

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

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

مثال طلب

PUT /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6
curl -X PUT "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "contactName": "Omar Hassan",
  "contactPhone": "0509876543"
}'

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

الاستجابات

200The updated merchant.

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

Merchant id.

namestringيقبل null

Account name.

contactNamestringيقبل null

Contact person.

contactPhonestringيقبل null

Contact phone.

contactEmailstringيقبل null

Contact email.

isActiveboolean

Whether the merchant can book shipments.

createdAtstring (date-time)

Creation time (UTC).

primaryAddressPublicMerchantAddressDto

A saved pickup address of a merchant.

id
primaryAddress.id
string (uuid)

Address id.

label
primaryAddress.label
stringيقبل null

Short label.

contactName
primaryAddress.contactName
stringيقبل null

Contact person at the address.

contactPhone
primaryAddress.contactPhone
stringيقبل null

Phone at the address.

country
primaryAddress.country
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

city
primaryAddress.city
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

district
primaryAddress.district
PublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

addressLine
primaryAddress.addressLine
stringيقبل null

Street, building and landmark.

shortAddress
primaryAddress.shortAddress
stringيقبل null

Saudi national short address.

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

Latitude.

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

Longitude.

isPrimary
primaryAddress.isPrimary
boolean

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

200 · مثال استجابة
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Noor Electronics",
  "contactName": "Omar Hassan",
  "contactPhone": "0501234567",
  "contactEmail": "orders@noor-electronics.example",
  "isActive": true,
  "createdAt": "2026-01-10T08:00:00Z",
  "primaryAddress": {
    "id": "9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42",
    "label": "Main warehouse",
    "contactName": "Omar Hassan",
    "contactPhone": "0501234567",
    "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,
    "isPrimary": 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 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.

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

GET

/api/public/v1/merchants/{id}/addresses

#

List the saved pickup addresses of a merchant

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

The primary address first.

المعاملات

الاسمالموضعالنوعالوصف
id
مطلوب
pathstring (uuid)

Merchant id.

مثال طلب

GET /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses
curl "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

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

الاستجابات

200The addresses.

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

Address id.

labelstringيقبل null

Short label.

contactNamestringيقبل null

Contact person at the address.

contactPhonestringيقبل null

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
[].country.nameAr
stringيقبل null

Arabic name.

nameEn
[].country.nameEn
stringيقبل null

English name.

cityPublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

districtPublicNamedRef

A catalog entry shown in both languages.

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

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

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

Arabic name.

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

English name.

addressLinestringيقبل null

Street, building and landmark.

shortAddressstringيقبل null

Saudi national short address.

latitudenumber (double)يقبل null

Latitude.

longitudenumber (double)يقبل null

Longitude.

isPrimaryboolean

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

200 · مثال استجابة
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "country": {},
    "city": {},
    "district": {},
    "isPrimary": 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).

404

Code merchant.not_found.

429

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

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

POST

/api/public/v1/merchants/{id}/addresses

#

Add a saved pickup address

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

Country, city and district are matched strictly by id, code or name (Arabic or English); nothing is created (geo_* errors with details.field = address). A short address is required for Saudi addresses. The first address of a merchant is always primary.

المعاملات

الاسمالموضعالنوعالوصف
id
مطلوب
pathstring (uuid)

Merchant id.

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.

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

The address.

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

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يقبل null

Phone at this address. Required.

مثال: 0501234567

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, 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

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

مثال طلب

POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses
curl -X POST "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Jeddah branch",
  "contactPhone": "0501234567",
  "country": "SA",
  "city": "جده",
  "district": "حي الروضة",
  "addressLine": "Tahlia Street, Shop 9",
  "shortAddress": "JEDA2345",
  "makePrimary": false
}'

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

الاستجابات

201The created address.

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

Address id.

labelstringيقبل null

Short label.

contactNamestringيقبل null

Contact person at the address.

contactPhonestringيقبل null

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
country.nameAr
stringيقبل null

Arabic name.

nameEn
country.nameEn
stringيقبل null

English name.

cityPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
city.nameAr
stringيقبل null

Arabic name.

nameEn
city.nameEn
stringيقبل null

English name.

districtPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
district.nameAr
stringيقبل null

Arabic name.

nameEn
district.nameEn
stringيقبل null

English name.

addressLinestringيقبل null

Street, building and landmark.

shortAddressstringيقبل null

Saudi national short address.

latitudenumber (double)يقبل null

Latitude.

longitudenumber (double)يقبل null

Longitude.

isPrimaryboolean

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

201 · مثال استجابة
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "country": {},
  "city": {},
  "district": {},
  "isPrimary": false
}
الحالةالوصف
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 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.

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

PUT

/api/public/v1/merchants/{id}/addresses/{addressId}

#

Replace a saved pickup address

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

The body replaces the whole address (same fields as when adding). The primary flag is unchanged; use the primary route to change it.

المعاملات

الاسمالموضعالنوعالوصف
id
مطلوب
pathstring (uuid)

Merchant id.

addressId
مطلوب
pathstring (uuid)

Address id.

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

The address.

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

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يقبل null

Phone at this address. Required.

مثال: 0501234567

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, 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

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

مثال طلب

PUT /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/3fa85f64-5717-4562-b3fc-2c963f66afa6
curl -X PUT "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Main warehouse",
  "contactName": "Omar Hassan",
  "contactPhone": "0501234567",
  "country": "SA",
  "city": "Riyadh",
  "district": "Al Olaya",
  "addressLine": "King Fahd Road, Warehouse 4",
  "shortAddress": "RNBA6769",
  "latitude": 24.7136,
  "longitude": 46.6753
}'

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

الاستجابات

200The updated address.

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

Address id.

labelstringيقبل null

Short label.

contactNamestringيقبل null

Contact person at the address.

contactPhonestringيقبل null

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
country.nameAr
stringيقبل null

Arabic name.

nameEn
country.nameEn
stringيقبل null

English name.

cityPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
city.nameAr
stringيقبل null

Arabic name.

nameEn
city.nameEn
stringيقبل null

English name.

districtPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
district.nameAr
stringيقبل null

Arabic name.

nameEn
district.nameEn
stringيقبل null

English name.

addressLinestringيقبل null

Street, building and landmark.

shortAddressstringيقبل null

Saudi national short address.

latitudenumber (double)يقبل null

Latitude.

longitudenumber (double)يقبل null

Longitude.

isPrimaryboolean

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

200 · مثال استجابة
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "country": {},
  "city": {},
  "district": {},
  "isPrimary": false
}
الحالةالوصف
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 merchant.not_found or merchant.address_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.

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

DELETE

/api/public/v1/merchants/{id}/addresses/{addressId}

#

Delete a saved address

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

The only address of a merchant cannot be deleted. When the primary one is deleted, the oldest remaining becomes primary.

المعاملات

الاسمالموضعالنوعالوصف
id
مطلوب
pathstring (uuid)

Merchant id.

addressId
مطلوب
pathstring (uuid)

Address id.

مثال طلب

DELETE /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/3fa85f64-5717-4562-b3fc-2c963f66afa6
curl -X DELETE "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

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

الاستجابات

204Deleted.

الحالةالوصف
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 merchant.not_found or merchant.address_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.

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

POST

/api/public/v1/merchants/{id}/addresses/{addressId}/primary

#

Make an address the primary one

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

The primary address is the default pickup of the merchant's shipments and the destination of its returns.

المعاملات

الاسمالموضعالنوعالوصف
id
مطلوب
pathstring (uuid)

Merchant id.

addressId
مطلوب
pathstring (uuid)

Address id.

مثال طلب

POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary
curl -X POST "https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

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

الاستجابات

200The address, now primary.

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

Address id.

labelstringيقبل null

Short label.

contactNamestringيقبل null

Contact person at the address.

contactPhonestringيقبل null

Phone at the address.

countryPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
country.nameAr
stringيقبل null

Arabic name.

nameEn
country.nameEn
stringيقبل null

English name.

cityPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
city.nameAr
stringيقبل null

Arabic name.

nameEn
city.nameEn
stringيقبل null

English name.

districtPublicNamedRef

A catalog entry shown in both languages.

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

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

nameAr
district.nameAr
stringيقبل null

Arabic name.

nameEn
district.nameEn
stringيقبل null

English name.

addressLinestringيقبل null

Street, building and landmark.

shortAddressstringيقبل null

Saudi national short address.

latitudenumber (double)يقبل null

Latitude.

longitudenumber (double)يقبل null

Longitude.

isPrimaryboolean

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

200 · مثال استجابة
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "country": {},
  "city": {},
  "district": {},
  "isPrimary": 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).

404

Code merchant.not_found or merchant.address_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.

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