GROperator

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

English

تفعيل الواجهة

استخدام الواجهة يحتاج خطوتي تفعيل ومفتاح API واحداً. الخطوة الأولى من جهة المنصة، والثانية في إعدادات شركتك، أما مفتاح الـ API فيُنشئه مدير الشركة من لوحة التحكم.

تقرر المنصة (GROperator) أي الشركات يحق لها استخدام الواجهة، وتسمى القناة الربط البرمجي (API integration). إن لم تُمنح لشركتك، فستخبرك صفحة الربط البرمجي في لوحة التحكم بذلك وتطلب منك التواصل مع المنصة، وتردّ كل طلبات الـ API بـ 403 channel_disabled.

يفتح مدير الشركة الإعدادات ثم الشركة ويجد قسم قنوات إنشاء الشحنات والربط (في لوحة التحكم العربية). شغّل الربط البرمجي (API). وما دامت القناة متوقفة فإن المفاتيح الموجودة تتوقف أيضاً عن العمل، ولا يمكن إنشاء مفاتيح جديدة.

  1. افتح الإعدادات ثم الربط البرمجي (API access).
  2. أنشئ مفتاحاً وسمِّه باسم يدل على ما يستخدمه، مثل Website أو Google Sheets.
  3. اختر النطاقات (Scopes) من الجدول أدناه، وامنح المفتاح ما يحتاجه التكامل فقط. ولا يمكن لمفتاح أن يحمل أكثر مما يملكه المدير الذي ينشئه: إن طلبت نطاقاً لا تملك أنت شخصياً صلاحيات لوحة التحكم التي يقوم عليها، يُرفض الإنشاء.
  4. اختيارياً، حدّد تاريخ انتهاء.
  5. احفظ. تعرض لوحة التحكم المفتاح (يبدأ بـ lmc_live_) والسر.

السر يظهر مرة واحدة فقط. انسخه فوراً إلى مخزن أسرار الخادم لديك. إن فقدته فألغِ المفتاح وأنشئ غيره: المنصة تخزّن بصمة أحادية الاتجاه للسر فقط ولا تستطيع عرضه مرة أخرى.

المفاتيح الملغاة والمنتهية ترد بـ 401 unauthorized. يمكن للشركة أن تحمل 20 مفتاحاً فعّالاً كحد أقصى، فألغِ ما لم تعد تستخدمه. بعد الإلغاء يمكن حذف المفتاح.

النطاق صلاحية مرتبطة بالمفتاح. النطاق الذي يكتب فقط لا يشمل القراءة: التكامل الذي ينشئ الشحنات ثم يقرأها يحتاج shipments:write و shipments:read معاً.

النطاقما يسمح بهنقاط النهاية
shipments:read
قراءة الشحنات
عرض الشحنات وتفاصيلها ومسار تتبعها وبوليصتها وكتالوج الحالات.
  • GET /shipments
  • GET /shipments/statuses
  • GET /shipments/{trackingNumber}
  • GET /shipments/{trackingNumber}/label
  • GET /shipments/{trackingNumber}/tracking
shipments:write
إدارة الشحنات
إنشاء الشحنات وتعديلها وإلغاؤها. لا يشمل القراءة: أضف shipments:read أيضاً.
  • POST /shipments
  • PUT /shipments/{trackingNumber}
  • POST /shipments/{trackingNumber}/cancel
merchants:read
قراءة التجار
عرض التجار وتفاصيلهم وعناوينهم المحفوظة.
  • GET /merchants
  • GET /merchants/{id}
  • GET /merchants/{id}/addresses
merchants:write
إدارة التجار
إنشاء التجار وتعديلهم وإدارة عناوينهم المحفوظة. لا يشمل القراءة.
  • POST /merchants
  • PUT /merchants/{id}
  • POST /merchants/{id}/addresses
  • PUT /merchants/{id}/addresses/{addressId}
  • DELETE /merchants/{id}/addresses/{addressId}
  • POST /merchants/{id}/addresses/{addressId}/primary
geography:read
قراءة الجغرافيا
الدول والمدن والأحياء والتحقق من العناوين (resolve) والتغطية.
  • GET /geography/cities
  • GET /geography/countries
  • GET /geography/coverage
  • GET /geography/coverage/cities
  • GET /geography/districts
  • GET /geography/resolve
pricing:read
قراءة التسعير
عرض سعر شحنة.
  • POST /pricing/quote
branches:read
قراءة الفروع
عرض فروع الشركة وقراءة فرع واحد.
  • GET /branches
  • GET /branches/{id}
webhooks:manage
إدارة الـ Webhooks
إنشاء اشتراكات الـ Webhooks وعرضها واختبارها وتدوير سرها وحذفها، وقراءة كتالوج الأحداث.
  • GET /merchants/{merchantId}/webhooks
  • POST /merchants/{merchantId}/webhooks
  • DELETE /merchants/{merchantId}/webhooks/{id}
  • POST /merchants/{merchantId}/webhooks/{id}/rotate-secret
  • POST /merchants/{merchantId}/webhooks/{id}/test
  • GET /webhooks/events

استدعاء نقطة نهاية بلا نطاقها يرد بـ 403 forbidden ومعه details.requiredScope باسم النطاق الناقص. نقطة GET /auth/me ونقطتا تسجيل الدخول لا تحتاجان نطاقاً.

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"

الرد 200 يؤكد صحة الاعتماد والنطاقات وتشغيل القناة. بعدها تابع إلى المصادقة لقواعد الأمان، أو انتقل مباشرة إلى البداية السريعة.

إن فضّلت العمل باسم مستخدم (أو إعطاء التجار حساباً)، فلا حاجة إلى مفتاح: يسجّل المستخدم الدخول عبر POST /auth/login. وتبقى قناة الـ API مطلوبة لتكون مفعّلة للشركة. راجع المصادقة.