تفعيل الواجهة
استخدام الواجهة يحتاج خطوتي تفعيل ومفتاح API واحداً. الخطوة الأولى من جهة المنصة، والثانية في إعدادات شركتك، أما مفتاح الـ API فيُنشئه مدير الشركة من لوحة التحكم.
تقرر المنصة (GROperator) أي الشركات يحق لها استخدام الواجهة، وتسمى القناة الربط البرمجي (API integration). إن لم تُمنح لشركتك، فستخبرك صفحة الربط البرمجي في لوحة التحكم بذلك وتطلب منك التواصل مع المنصة، وتردّ كل طلبات الـ API بـ 403 channel_disabled.
يفتح مدير الشركة الإعدادات ثم الشركة ويجد قسم قنوات إنشاء الشحنات والربط (في لوحة التحكم العربية). شغّل الربط البرمجي (API). وما دامت القناة متوقفة فإن المفاتيح الموجودة تتوقف أيضاً عن العمل، ولا يمكن إنشاء مفاتيح جديدة.
- افتح الإعدادات ثم الربط البرمجي (API access).
- أنشئ مفتاحاً وسمِّه باسم يدل على ما يستخدمه، مثل
WebsiteأوGoogle Sheets. - اختر النطاقات (Scopes) من الجدول أدناه، وامنح المفتاح ما يحتاجه التكامل فقط. ولا يمكن لمفتاح أن يحمل أكثر مما يملكه المدير الذي ينشئه: إن طلبت نطاقاً لا تملك أنت شخصياً صلاحيات لوحة التحكم التي يقوم عليها، يُرفض الإنشاء.
- اختيارياً، حدّد تاريخ انتهاء.
- احفظ. تعرض لوحة التحكم المفتاح (يبدأ بـ
lmc_live_) والسر.
السر يظهر مرة واحدة فقط. انسخه فوراً إلى مخزن أسرار الخادم لديك. إن فقدته فألغِ المفتاح وأنشئ غيره: المنصة تخزّن بصمة أحادية الاتجاه للسر فقط ولا تستطيع عرضه مرة أخرى.
المفاتيح الملغاة والمنتهية ترد بـ 401 unauthorized. يمكن للشركة أن تحمل 20 مفتاحاً فعّالاً كحد أقصى، فألغِ ما لم تعد تستخدمه. بعد الإلغاء يمكن حذف المفتاح.
النطاق صلاحية مرتبطة بالمفتاح. النطاق الذي يكتب فقط لا يشمل القراءة: التكامل الذي ينشئ الشحنات ثم يقرأها يحتاج shipments:write و shipments:read معاً.
| النطاق | ما يسمح به | نقاط النهاية |
|---|---|---|
shipments:readقراءة الشحنات | عرض الشحنات وتفاصيلها ومسار تتبعها وبوليصتها وكتالوج الحالات. |
|
shipments:writeإدارة الشحنات | إنشاء الشحنات وتعديلها وإلغاؤها. لا يشمل القراءة: أضف shipments:read أيضاً. |
|
merchants:readقراءة التجار | عرض التجار وتفاصيلهم وعناوينهم المحفوظة. |
|
merchants:writeإدارة التجار | إنشاء التجار وتعديلهم وإدارة عناوينهم المحفوظة. لا يشمل القراءة. |
|
geography:readقراءة الجغرافيا | الدول والمدن والأحياء والتحقق من العناوين (resolve) والتغطية. |
|
pricing:readقراءة التسعير | عرض سعر شحنة. |
|
branches:readقراءة الفروع | عرض فروع الشركة وقراءة فرع واحد. |
|
webhooks:manageإدارة الـ Webhooks | إنشاء اشتراكات الـ Webhooks وعرضها واختبارها وتدوير سرها وحذفها، وقراءة كتالوج الأحداث. |
|
استدعاء نقطة نهاية بلا نطاقها يرد بـ 403 forbidden ومعه details.requiredScope باسم النطاق الناقص. نقطة GET /auth/me ونقطتا تسجيل الدخول لا تحتاجان نطاقاً.
curl "https://api.goldrock.live/api/public/v1/auth/me" \
-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/auth/me", {
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/auth/me';
$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/auth/me",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.json())الرد 200 يؤكد صحة الاعتماد والنطاقات وتشغيل القناة. بعدها تابع إلى المصادقة لقواعد الأمان، أو انتقل مباشرة إلى البداية السريعة.
إن فضّلت العمل باسم مستخدم (أو إعطاء التجار حساباً)، فلا حاجة إلى مفتاح: يسجّل المستخدم الدخول عبر POST /auth/login. وتبقى قناة الـ API مطلوبة لتكون مفعّلة للشركة. راجع المصادقة.