المصادقة

كل طلب من الشركاء يحمل headerين يُثبتان هوية المُرسل وسلامة الرسالة معاً:

الحصول على مفتاح API

كل مفاتيح الربط يُصدرها التاجر من صفحةالتكاملات مع الشركاء في لوحة تحكم قروش. تفعيل التكامل يُصدر مفتاح API والسر الموقِّع معاً؛ تظهر القيمتان الخام مرة واحدة فقط ولا يمكن استرجاعهما بعدها. للتاجر تجديد أو إلغاء أي منهما في أي وقت من نفس الصفحة. راجع البدء السريع للخطوات التفصيلية.

المفاتيح تبدأ بـ qpk_. بيئة الاختبار والإنتاج منفصلتان بلوحتين منفصلتين — مفتاح صادر من بيئة الاختبار يُصادق فقط علىapi-staging.quroosh.io، ومفتاح الإنتاج فقط علىapi.quroosh.io.

حساب التوقيع

تنسيق قيمة الـ header:

X-Signature: t=<unix_timestamp>,v1=<hex_hmac>[,v1=<hex_hmac>...]

الحمولة الموقَّعة: "{timestamp}.{raw_body}" — الطابع الزمني Unix، ثم نقطة .، ثم بايتات الطلب الخام. HMAC-SHA256 بالسر الموقِّع، والناتج بترميز hex بأحرف صغيرة.

يُسمح بأكثر من مقطع v1=. أثناء نافذة تجديد مفاتيح قروش يُصدر قروش v1= واحدة لكل سر نشط؛ وعند تجديدك لسرك الموقِّع يمكنك إرسال قيمتَي v1= ليقبل قروش أياً منهما.

التسامح مع الطابع الزمني هو ±٥ دقائق. اضبط ساعة خادمك (NTP) وإلا سترفض الطلبات بـ SIGNATURE_EXPIRED.

using System.Security.Cryptography;
using System.Text;

var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
using var hmac = IncrementalHash.CreateHMAC(
    HashAlgorithmName.SHA256,
    Encoding.UTF8.GetBytes(signingSecret));
hmac.AppendData(Encoding.UTF8.GetBytes($"{timestamp}."));
hmac.AppendData(rawBody);
var mac = hmac.GetHashAndReset();
var signature = $"t={timestamp},v1={Convert.ToHexStringLower(mac)}";

تجديد المفاتيح

التجديد يتم دون أي انقطاع: التجديد يُصدر مفتاحاًجديداً ويبقى القديم صالحاً حتى يُلغيه التاجر صراحةً من اللوحة — لا توجد مدة انتهاء تلقائية. حدّث إعدادات منصتك بالمفتاح الجديد أولاً، ثم يُلغي التاجر القديم. إلغاء آخر مفتاح نشط مرفوض، فلا يمكن للتكامل أن يقفل نفسه أبداً. الأسرار الموقِّعة تُجدَّد بنفس الطريقة؛ وأثناء فترة التداخل تحمل Webhooks قروش مقطع v1=واحداً لكل سر نشط.

استجابات فشل المصادقة

راجع الأخطاء للقائمة الكاملة بالرموز، بما فيها رموز معالجة الأحداث التي يُرجِعها /api/partner/v1/events.