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://apiv1.groperator.com/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.

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

Items of the requested page.

id
items[].id
مطلوب
string (uuid)

Merchant id.

name
items[].name
مطلوب
string

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

Short label.

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

Contact person at the address.

contactPhone
items[].primaryAddress.contactPhone
مطلوب
string

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

Arabic name.

nameEn
items[].primaryAddress.country.nameEn
مطلوب
string

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

Arabic name.

nameEn
items[].primaryAddress.city.nameEn
مطلوب
string

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

Arabic name.

nameEn
items[].primaryAddress.district.nameEn
مطلوب
string

English name.

addressLine
items[].primaryAddress.addressLine
مطلوب
string

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

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.

200 · مثال استجابة
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "isActive": false,
      "createdAt": "2026-01-15T09:30:00Z",
      "primaryAddress": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "label": "string",
        "contactPhone": "string",
        "country": {
          "nameAr": "string",
          "nameEn": "string"
        },
        "city": {
          "nameAr": "string",
          "nameEn": "string"
        },
        "district": {
          "nameAr": "string",
          "nameEn": "string"
        },
        "addressLine": "string",
        "isPrimary": false
      }
    }
  ],
  "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

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.

label
address.label
مطلوب
string

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

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

City id, code or name. Required.

مثال: Riyadh

district
address.district
مطلوب
string

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

مثال: Al Olaya

addressLine
address.addressLine
مطلوب
string

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://apiv1.groperator.com/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.

الاستجابات · الحقل
الحقلالنوعالوصف
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.

id
primaryAddress.id
مطلوب
string (uuid)

Address id.

label
primaryAddress.label
مطلوب
string

Short label.

contactName
primaryAddress.contactName
stringيقبل null

Contact person at the address.

contactPhone
primaryAddress.contactPhone
مطلوب
string

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

Arabic name.

nameEn
primaryAddress.country.nameEn
مطلوب
string

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

Arabic name.

nameEn
primaryAddress.city.nameEn
مطلوب
string

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

Arabic name.

nameEn
primaryAddress.district.nameEn
مطلوب
string

English name.

addressLine
primaryAddress.addressLine
مطلوب
string

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://apiv1.groperator.com/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.

الاستجابات · الحقل
الحقلالنوعالوصف
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.

id
primaryAddress.id
مطلوب
string (uuid)

Address id.

label
primaryAddress.label
مطلوب
string

Short label.

contactName
primaryAddress.contactName
stringيقبل null

Contact person at the address.

contactPhone
primaryAddress.contactPhone
مطلوب
string

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

Arabic name.

nameEn
primaryAddress.country.nameEn
مطلوب
string

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

Arabic name.

nameEn
primaryAddress.city.nameEn
مطلوب
string

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

Arabic name.

nameEn
primaryAddress.district.nameEn
مطلوب
string

English name.

addressLine
primaryAddress.addressLine
مطلوب
string

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://apiv1.groperator.com/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.

الاستجابات · الحقل
الحقلالنوعالوصف
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.

id
primaryAddress.id
مطلوب
string (uuid)

Address id.

label
primaryAddress.label
مطلوب
string

Short label.

contactName
primaryAddress.contactName
stringيقبل null

Contact person at the address.

contactPhone
primaryAddress.contactPhone
مطلوب
string

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

Arabic name.

nameEn
primaryAddress.country.nameEn
مطلوب
string

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

Arabic name.

nameEn
primaryAddress.city.nameEn
مطلوب
string

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

Arabic name.

nameEn
primaryAddress.district.nameEn
مطلوب
string

English name.

addressLine
primaryAddress.addressLine
مطلوب
string

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://apiv1.groperator.com/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.

الاستجابات · الحقل
الحقلالنوعالوصف
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.

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

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

nameAr
[].country.nameAr
مطلوب
string

Arabic name.

nameEn
[].country.nameEn
مطلوب
string

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

Arabic name.

nameEn
[].city.nameEn
مطلوب
string

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

Arabic name.

nameEn
[].district.nameEn
مطلوب
string

English name.

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

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

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

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

مثال طلب

POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses
curl -X POST "https://apiv1.groperator.com/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.

الاستجابات · الحقل
الحقلالنوعالوصف
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.

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

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

nameAr
country.nameAr
مطلوب
string

Arabic name.

nameEn
country.nameEn
مطلوب
string

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

Arabic name.

nameEn
city.nameEn
مطلوب
string

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

Arabic name.

nameEn
district.nameEn
مطلوب
string

English name.

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

201 · مثال استجابة
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "label": "string",
  "contactPhone": "string",
  "country": {
    "nameAr": "string",
    "nameEn": "string"
  },
  "city": {
    "nameAr": "string",
    "nameEn": "string"
  },
  "district": {
    "nameAr": "string",
    "nameEn": "string"
  },
  "addressLine": "string",
  "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

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

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

مثال طلب

PUT /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/3fa85f64-5717-4562-b3fc-2c963f66afa6
curl -X PUT "https://apiv1.groperator.com/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.

الاستجابات · الحقل
الحقلالنوعالوصف
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.

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

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

nameAr
country.nameAr
مطلوب
string

Arabic name.

nameEn
country.nameEn
مطلوب
string

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

Arabic name.

nameEn
city.nameEn
مطلوب
string

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

Arabic name.

nameEn
district.nameEn
مطلوب
string

English name.

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

200 · مثال استجابة
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "label": "string",
  "contactPhone": "string",
  "country": {
    "nameAr": "string",
    "nameEn": "string"
  },
  "city": {
    "nameAr": "string",
    "nameEn": "string"
  },
  "district": {
    "nameAr": "string",
    "nameEn": "string"
  },
  "addressLine": "string",
  "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://apiv1.groperator.com/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://apiv1.groperator.com/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.

الاستجابات · الحقل
الحقلالنوعالوصف
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.

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

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

nameAr
country.nameAr
مطلوب
string

Arabic name.

nameEn
country.nameEn
مطلوب
string

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

Arabic name.

nameEn
city.nameEn
مطلوب
string

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

Arabic name.

nameEn
district.nameEn
مطلوب
string

English name.

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

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

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