التجار والعناوين
التاجر حساب عميل لدى شركة الشحن: متجر يشحن عن طريقك. تُحجز الشحنات باسم تاجر، وتُسعَّر ببطاقة أسعاره، وتنطلق من أحد عناوين الاستلام المحفوظة له. واشتراكات الـ Webhooks تتبع تاجراً أيضاً.
النطاقات: merchants:read للعرض والقراءة؛ وmerchants:write للإنشاء والتغيير. الكتابة لا تشمل القراءة. وحساب التاجر يقرأ سجل تاجره وعناوينه فقط ولا يكتب.
تعرض الواجهة بيانات التاجر التجارية التي تلزمك، وتحجب عمداً البيانات البنكية والعمولة ومفاتيح الـ API وتفاصيل التسعير.
GET /merchants مرقّم ومرتب بالاسم. الفلاتر: search (يُطابق الاسم وجهة الاتصال والهاتف والبريد) وisActive. وGET /merchants/{id} يرجع تاجراً مع عنوانه الرئيسي.
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'const params = new URLSearchParams({
"search": "noor",
"isActive": "true"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/merchants?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants?' . http_build_query([
'search' => 'noor',
'isActive' => 'true',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/merchants",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"search": "noor",
"isActive": "true",
},
timeout=30,
)
print(response.status_code, response.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.- بخلاف لوحة التحكم، لا يُنشأ حساب دخول للتاجر ولا يُرسل بريد. حساب دخول التاجر يُنشأ من لوحة التحكم.
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"
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/merchants", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "merchant-1010123456"
},
body: JSON.stringify({
"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"
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: merchant-1010123456',
],
CURLOPT_POSTFIELDS => json_encode([
'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',
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/merchants",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "merchant-1010123456",
},
json={
"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",
},
},
timeout=30,
)
print(response.status_code, response.json())البيانات التي تطابق تاجراً آخر على المنصة تُرفض بـ 409: merchant.email_taken_format حين يكون البريد لتاجر قائم، وmerchant.same_merchant_format حين يوجد تاجر بالاسم والسجل التجاري نفسيهما. وحين تكون البيانات مشابهة فقط (السجل أو الرقم الضريبي نفسه أو اسم مشابه) يكون الرد 409 merchant.possible_duplicate. وإن كنت متأكداً أنه متجر مختلف فأرسل الطلب نفسه مع confirmPossibleDuplicate: true.
أرسل Idempotency-Key حتى لا تُنشئ التاجر مرتين عند إعادة المحاولة.
PUT /merchants/{id} يغيّر ما ترسله فقط: name وcontactName وcontactPhone وcontactEmail. أرقام السجل والتسعير والبيانات البنكية لا تُمس.
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"
}'const response = await fetch("https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6", {
method: "PUT",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"contactName": "Omar Hassan",
"contactPhone": "0509876543"
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'contactName' => 'Omar Hassan',
'contactPhone' => '0509876543',
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"PUT",
"https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"contactName": "Omar Hassan",
"contactPhone": "0509876543",
},
timeout=30,
)
print(response.status_code, response.json())للتاجر عنوان استلام محفوظ واحد أو أكثر. الرئيسي هو الاستلام الافتراضي لشحنات التاجر ووجهة مرتجعاته. والعنوان الأول يكون رئيسياً دائماً.
| العملية | ملاحظات |
|---|---|
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.
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
}'const response = await fetch("https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"label": "Jeddah branch",
"contactPhone": "0501234567",
"country": "SA",
"city": "جده",
"district": "حي الروضة",
"addressLine": "Tahlia Street, Shop 9",
"shortAddress": "JEDA2345",
"makePrimary": false
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'label' => 'Jeddah branch',
'contactPhone' => '0501234567',
'country' => 'SA',
'city' => 'جده',
'district' => 'حي الروضة',
'addressLine' => 'Tahlia Street, Shop 9',
'shortAddress' => 'JEDA2345',
'makePrimary' => false,
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"label": "Jeddah branch",
"contactPhone": "0501234567",
"country": "SA",
"city": "جده",
"district": "حي الروضة",
"addressLine": "Tahlia Street, Shop 9",
"shortAddress": "JEDA2345",
"makePrimary": False,
},
timeout=30,
)
print(response.status_code, response.json())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"const response = await fetch("https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/addresses/9b2f6c1e-5d1a-4c35-8a3e-0b6b8f7c1d42/primary",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.json())| الرمز | السبب |
|---|---|
merchant.not_found |
معرّف خاطئ، أو حساب تاجر طلب تاجراً آخر |
merchant.address_not_found |
معرّف العنوان لا يتبع هذا التاجر |
merchant.possible_duplicate وmerchant.email_taken_format وmerchant.same_merchant_format |
كشف التكرار، انظر أعلاه |
validation_failed |
حقل مطلوب مفقود أو خاطئ الصيغة |
geo_* |
اسم مكان لم يطابق |