API الشركاء — قروش
API الشركاء هي القناة بين خوادم أنظمة نقاط البيع، أنظمة ERP، ومنصات الولاء المتكاملة مع قروش. تُستخدم لإصدار النقاط والأختام، استرداد المكافآت، واستقبال أحداث Webhooks الفورية عن نشاط العملاء.
عناوين البيئات
بيئة الاختبار: https://api-staging.quroosh.io/api/partner/v1
بيئة الإنتاج: https://api.quroosh.io/api/partner/v1
ما تحصل عليه
- REST و JSON — كل endpoint يستقبل ويُعيد JSON، ورموز حالة HTTP قياسية، ومظروف خطأ موحّد.
- مفتاح API وتوقيع HMAC — طلب إرسال الأحداث (POST) يحمل header
X-Api-Keyو header توقيعX-Signatureموقّعاً بسر الويبهوك؛ أما قراءات GET فتحتاج مفتاح API فقط. - إعادة محاولة آمنة — endpoint الأحداث يمنع التكرار على
eventIdفي الجسم، فإعادة إرسال حدث لا تُحتسب مرتين. - Webhooks — تغييرات قواعد الولاء وتغييرات حالة التكامل تُسلَّم إلى endpoint عندك بنفس آلية HMAC (والمزيد من الأحداث قادم).
- بيئة اختبار كاملة — كامل سطح API مقابل بيانات اختبار ومفاتيح اختبار.
التوفّر
يُطرَح الـ API على مراحل. كل endpoint وحدث وآلية في هذه الوثائق موسومة بـ متاح أومُخطط لتعرف دائماً ما يعمل اليوم مقابل ما تطوّر مقابله لاحقاً.
من أين تبدأ
- البدء السريع — مسار التكامل كاملاً: مفاتيح الربط، اختبار الاتصال، ربط الفروع، وأول حدث بيع.
- المصادقة — إصدار المفاتيح، الـ headers، والتوقيع.
- البحث عن العميل — اقرأ رصيد العميل ومستواه ومكافآته القابلة للاسترداد عند الدفع.
- أنواع الأحداث — الكتالوج الكامل للأحداث وأشكال الـ payload.
- Webhooks — التحقق من التوقيع، إعادة المحاولة، كتالوج الأحداث.
- مرجع API — قائمة كاملة بالـ endpoints مع أداة تجربة مباشرة.
الدعم
الدعم الفني للشركاء: support@quroosh.io. اذكر اسم الشريك، وعند وجود طلب فاشل أرفق قيمة headerX-Correlation-Id من الاستجابة — نستخدمها لتتبّع الاستدعاء من البداية إلى النهاية عبر سجلاّتنا.