الأخطاء

كل استجابة غير ناجحة تستخدم مظروفاً واحداً متوقَّعاً. اقرأcode لتفريع سلوك التكامل، واعرض messageالقابلة للقراءة على المشغلين.

مظروف الخطأ

{
  "code": "INVALID_SIGNATURE",
  "message": "Invalid X-Signature header.",
  "correlationId": "01J7XKQE4E30000000000000"
}

كل استجابة — سواء نجحت أم فشلت — تتضمن header استجابةX-Correlation-Id. سجّله. عند حاجتك لدعم الشركاء لتتبّع استدعاء محدد، هذا المعرّف يمكّننا من إيجاد الطلب بالضبط في ثوانٍ.

اتفاقيات حالة HTTP

الحالة	المعنى
`200 OK`	نجاح متزامن.
`400 Bad Request`	طلب مشوّه أو خطأ عميل دائم — لا تُعِد المحاولة.
`401 Unauthorized`	مفتاح API أو التوقيع أو حالة الاتصال غير صالحة.
`422 Unprocessable Entity`	قاعدة أعمال رفضت كتابة متزامنة (التحقق من الاستبدال) — مُخطط، لا يوجد endpoint حيّ يُرجِع 422 بعد.
`503 Service Unavailable`	التكامل موقوف أو المستقبِل غير جاهز — أعد المحاولة وفق جدول التباعد لديك.

رموز الأخطاء

code	الحالة	المعنى
`MISSING_API_KEY`	401	Header `X-Api-Key` غير موجود.
`INVALID_API_KEY`	401	مفتاح API غير معروف أو مُلغى أو من بيئة خاطئة.
`INVALID_SIGNATURE`	401	توقيع HMAC لا يطابق الجسم الخام تحت أي سر توقيع نشط.
`SIGNATURE_EXPIRED`	401	الطابع الزمني للتوقيع خارج نافذة السماح ٥ دقائق.
`INTEGRATION_NOT_CONNECTED`	401	التاجر لم يُفعِّل التكامل بعد.
`INTEGRATION_ALREADY_DISCONNECTED`	401	التاجر فصل التكامل. مطلوب اعتمادات جديدة.
`INTEGRATION_PAUSED`	503	التاجر أوقف التكامل. أعد المحاولة وفق جدول التباعد.
`MISSING_IDEMPOTENCY_KEY`	400	مُخطط. محجوز لنقاط الكتابة المتزامنة القادمة (التحقق من الاستبدال/تأكيده، فحص الإرجاع). الـ endpoint الحالي `/events` يمنع التكرار على `eventId` ولا يحتاج `Idempotency-Key`. راجع أمان إعادة المحاولة.
`UNKNOWN_EVENT_TYPE`	400	`eventType` غير مُتعرَّف عليه عند المستقبِل.
`INVALID_PAYLOAD`	400	جسم الحدث ليس JSON صالحاً أو ينقصه حقل إلزامي.
`INVALID_REQUEST`	400	مُعامِلات الاستعلام غير صالحة — مثلاً عدم إرسال أيٍّ من `phone` و`customerId` أو إرسالهما معاً في بحث العميل.
`EVENT_HANDLER_NOT_REGISTERED`	503	نوع الحدث صحيح لكن المستقبِل لم يُطلق معالجاً له بعد. أعد المحاولة وفق جدول التباعد — تسليم لاحق سينجح.
`WRONG_EVENT_DIRECTION`	400	هذا النوع مُصدَّر من قروش (webhook صادر) ولا يجب إرساله إلى `/events`. أوقف إعادة المحاولة.

رموز معالجة الأحداث

تُرجَع من POST /events عندما يفشل حدث في فحوصات الأعمال.400 يعني أن الحدث لا يمكن معالجته كما أُرسل. لعيوب الـ payload: صحّح البيانات وأرسل حدثاً جديداً. أما الرموز المعتمدة على حالة التاجر (ربط فرع غير مؤكد، ربط عميل مفقود، عميل مجمّد، برنامج أو بطاقة غير نشطة) فيمكنك إعادة تسليم نفس الحدث بعد أن يصحح التاجر الإعداد — التسليمات الفاشلة لا تُخزَّن أبداً، فإعادة التسليم تُعالَج من جديد. 503 يعني أعد المحاولة وفق جدول التباعد لديك.

code	الحالة	المعنى
`CUSTOMER_MAPPING_NOT_FOUND`	400	لا يوجد ربط لـ `externalCustomerId` — أرسل `CustomerSynced` أولاً.
`BRANCH_MAPPING_NOT_FOUND`	400	لا يوجد ربط لـ `externalBranchId` — أرسل `BranchSynced` أولاً.
`BRANCH_MAPPING_UNCONFIRMED`	400	الفرع معروف لكن التاجر لم يؤكد الربط في لوحة قروش بعد.
`CUSTOMER_INACTIVE`	400	حساب العميل مجمّد لدى هذا المتجر.
`MISSING_STAMP_CARD_ID`	400	`earnType = "Stamps"` بدون `stampCardId`.
`STAMP_CARD_NOT_FOUND`	400	`stampCardId` غير معروف لهذا المتجر.
`STAMP_CARD_INACTIVE`	400	بطاقة الأختام غير نشطة.
`STAMP_CARD_FREE_ENTRY_ONLY`	400	طريقة الكسب الوحيدة للبطاقة هي `FreeEntry` — لا تُحتسب أبداً من فاتورة شريك.
`NO_ACTIVE_POINTS_PROGRAM`	400	لا يوجد برنامج نقاط نشط لهذا المتجر.
`NO_ACTIVE_EARNING_METHOD`	400	لا توجد طريقة كسب نشطة على برنامج النقاط أو بطاقة الأختام.
`PARTNER_INVOICE_ALREADY_EARNED`	400	سبق احتساب الكسب لهذه الفاتورة (`externalInvoiceId`) — تُرفض حتى مع `eventId` جديد.
`SUBSCRIPTION_LAPSED`	503	اشتراك التاجر في قروش غير نشط. أعد المحاولة — التسليم بعد التجديد سينجح.
`CONCURRENCY_CONFLICT`	503	تحديث متزامن على السجل تعارض مع هذا الحدث. أعد المحاولة.