GROperator

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

English

التجار والعناوين

التاجر حساب عميل لدى شركة الشحن: متجر يشحن عن طريقك. تُحجز الشحنات باسم تاجر، وتُسعَّر ببطاقة أسعاره، وتنطلق من أحد عناوين الاستلام المحفوظة له. واشتراكات الـ Webhooks تتبع تاجراً أيضاً.

النطاقات: merchants:read للعرض والقراءة؛ وmerchants:write للإنشاء والتغيير. الكتابة لا تشمل القراءة. وحساب التاجر يقرأ سجل تاجره وعناوينه فقط ولا يكتب.

تعرض الواجهة بيانات التاجر التجارية التي تلزمك، وتحجب عمداً البيانات البنكية والعمولة ومفاتيح الـ API وتفاصيل التسعير.

GET /merchants مرقّم ومرتب بالاسم. الفلاتر: search (يُطابق الاسم وجهة الاتصال والهاتف والبريد) وisActive. وGET /merchants/{id} يرجع تاجراً مع عنوانه الرئيسي.

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'
JSON
{
  "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
  }
}

الطلب POST /merchants يطبق قواعد لوحة التحكم:

  • name وcontactEmail وcommercialRegNo (السجل التجاري أو رقم وثيقة العمل الحر) مطلوبة. وcontactEmail فريد على مستوى المنصة.
  • taxId (الرقم الضريبي) مطلوب ما لم تكن notVatRegistered تساوي true.
  • address (عنوان الاستلام الرئيسي) مطلوب. الدولة والمدينة والحي تُطابَق بالأسماء ولا يُنشأ شيء (الأماكن بالاسم). والعنوان السعودي يحتاج shortAddress.
  • بخلاف لوحة التحكم، لا يُنشأ حساب دخول للتاجر ولا يُرسل بريد. حساب دخول التاجر يُنشأ من لوحة التحكم.
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"
  }
}'

البيانات التي تطابق تاجراً آخر على المنصة تُرفض بـ 409: merchant.email_taken_format حين يكون البريد لتاجر قائم، وmerchant.same_merchant_format حين يوجد تاجر بالاسم والسجل التجاري نفسيهما. وحين تكون البيانات مشابهة فقط (السجل أو الرقم الضريبي نفسه أو اسم مشابه) يكون الرد 409 merchant.possible_duplicate. وإن كنت متأكداً أنه متجر مختلف فأرسل الطلب نفسه مع confirmPossibleDuplicate: true.

أرسل Idempotency-Key حتى لا تُنشئ التاجر مرتين عند إعادة المحاولة.

PUT /merchants/{id} يغيّر ما ترسله فقط: name وcontactName وcontactPhone وcontactEmail. أرقام السجل والتسعير والبيانات البنكية لا تُمس.

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"
}'

للتاجر عنوان استلام محفوظ واحد أو أكثر. الرئيسي هو الاستلام الافتراضي لشحنات التاجر ووجهة مرتجعاته. والعنوان الأول يكون رئيسياً دائماً.

العملية ملاحظات
GET /merchants/{id}/addresses الرئيسي أولاً
POST /merchants/{id}/addresses إضافة عنوان. makePrimary: true يجعله رئيسياً. يدعم Idempotency-Key
PUT /merchants/{id}/addresses/{addressId} يستبدل العنوان كاملاً؛ ولا يتغير كونه رئيسياً
POST /merchants/{id}/addresses/{addressId}/primary اجعل هذا العنوان الرئيسي
DELETE /merchants/{id}/addresses/{addressId} العنوان الوحيد لا يُحذف. وحذف الرئيسي يرقّي أقدم العناوين المتبقية

يحتاج العنوان label (حتى 100 محرف) وcontactPhone وcity وdistrict وaddressLine (حتى 500 محرف). وcontactName الافتراضي اسم التاجر. والأسماء غير المطابقة تفشل بأخطاء geo_* وقيمة details.field فيها address.

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
}'
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"
الرمز السبب
merchant.not_found معرّف خاطئ، أو حساب تاجر طلب تاجراً آخر
merchant.address_not_found معرّف العنوان لا يتبع هذا التاجر
merchant.possible_duplicate وmerchant.email_taken_format وmerchant.same_merchant_format كشف التكرار، انظر أعلاه
validation_failed حقل مطلوب مفقود أو خاطئ الصيغة
geo_* اسم مكان لم يطابق