10 نقاط نهاية
الويب هوكس
عناوين الاستقبال لديكم، وأسرار توقيعها، وقائمة الأحداث المُرسَلة، وتفاصيل كل تسليم.
عناوين النقاط وأوصافها تأتي من عقد OpenAPI، بالإنجليزية — فلا يمكن أن تحيد عن الواجهة.
بكلمات بسيطة
الإشعارات الموقَّعة التي يرسلها ChariPay إلى خادمكم.
متى تستعملونها
منذ أول دفعة. فبدون ويب هوك لن يعرف نظامكم أبدًا بشكل موثوق أن دفعة نجحت.
كيف تدمجونها
- 1صرّحوا بعنوان مع القائمة الصريحة للأحداث التي تهمّكم.
- 2احصلوا على سر التوقيع واحفظوه كما تحفظون مفتاح واجهة.
- 3أرسلوا حدث اختبار للتحقق من استقبالكم من طرف إلى طرف.
- 4راجعوا سجل التسليمات متى بدا حدث مفقودًا — فهو يقول هل أرسلنا، وبماذا ردّ خادمكم.
- 5دوّروا السر دوريًا، وأعيدوا تفعيل نقطة قد نكون علّقناها بعد إخفاقات كثيرة.
الأحداث المُرسَلة فعليًا
هذه هي أنواع الأحداث الوحيدة التي ترسلها الواجهة. وتظهر قيم أخرى في تعداد العقد، لكنها محجوزة ولا تُرسَل أبدًا — والاشتراك في إحداها يُنتج فرعًا ميتًا.
- المدفوعات
payment.succeededpayment.failedorder.paid
- الاشتراكات
subscription.payment_succeededsubscription.payment_failedsubscription.canceled
- الاسترجاعات
refund.succeededrefund.failed
- حركات الحساب
merchant_transfer.completedmerchant_transfer.failedtopup.succeededtopup.failedbill_payment.pendingbill_payment.succeededbill_payment.failed
- التوزيع
wallet.activatedwallet.rejectedpayout.completedpayout.failedsubmerchant.near_cap
- GET
/api/v1/partner/webhooks/endpointsعرض نقاط نهاية ويب هوك للشريك - POST
/api/v1/partner/webhooks/endpointsتسجيل نقطة نهاية ويب هوك للشريك - POST
/api/v1/partner/webhooks/endpoints/{id}/testإرسال حدث تجريبي إلى نقطة نهاية ويب هوك خاصة بشريك - POST
/api/v1/partner/webhooks/endpoints/{id}/rotate-secretتدوير سر توقيع ويب هوك الشريك - POST
/api/v1/partner/webhooks/endpoints/{id}/activateإعادة تفعيل نقطة نهاية ويب هوك شريك معلّقة - GET
/api/v1/partner/webhooks/endpoints/{id}استرجاع نقطة نهاية ويب هوك خاصة بشريك - PATCH
/api/v1/partner/webhooks/endpoints/{id}تحديث نقطة نهاية ويب هوك خاصة بشريك - DELETE
/api/v1/partner/webhooks/endpoints/{id}حذف نقطة نهاية ويب هوك للشريك - GET
/api/v1/partner/webhooks/eventsعرض قائمة أحداث ويب هوك الصادرة - GET
/api/v1/partner/webhooks/events/{deliveryId}استرجاع حدث ويب هوك واحد تم إصداره
عرض نقاط نهاية ويب هوك للشريك
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
pageable | Pageable | query | مطلوب |
تسجيل نقطة نهاية ويب هوك للشريك
يُعيد سرّ التوقيع مرة واحدة فقط؛ ولا تكشفه القراءات اللاحقة. احفظوه في مدير أسرار. تنتمي نقطة النهاية حصريًا إلى بيئة SANDBOX أو PRODUCTION الخاصة بمفتاح API. اشتركوا في subscription.payment_succeeded لوسم فترة فوترة التاجر كمدفوعة، وفي subscription.payment_failed للحصول على معلومات استرجاع موحّدة، وفي subscription.canceled للمرحلة النهائية من المطالبة بالسداد. تتضمن الأحداث ExternalId وPeriodDate وmetadata التاجر لأغراض المطابقة.
المخطط · WebhookEndpointRequest
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
url | string | body | مطلوب | عنوان URL عام للمستقبِل عبر HTTPS على المنفذ 443. تُرفض الأهداف الخاصة، وloopback، وlink-local، وغير HTTPS. |
description | string | body | اختياري | تسمية نقطة النهاية من جهة التاجر. |
enabledEvents | array of enum | body | اختياري | قائمة سماح صريحة للأحداث. القيمة null أو الفارغة تشترك في جميع الأحداث الحالية والمستقبلية؛ ويُنصح بقائمة صريحة للتكاملات المستقرة. |
customHeaders | object | body | اختياري | ترويسات توجيه ثابتة اختيارية. لا يمكن تجاوز Host وAuthorization وCookie وChari-* وX-CHARI-*. |
apiVersion | string | body | اختياري | إصدار عقد حمولة ويب هوك. |
enabled | boolean | body | اختياري | ما إذا كان التسليم يبدأ فوراً. |
environment | enum | body | اختياري | SANDBOX أو PRODUCTION. لمسارات البوابة فقط — القيمة الافتراضية PRODUCTION عند الإغفال. يُتجاهل على /api/v1/partner/** حيث يحدد مفتاح API البيئة، ويُتجاهل عند التحديث (لا يمكن نقل نقطة نهاية بين البيئات؛ احذفوها ثم أعيدوا إنشاءها).القيم SANDBOXPRODUCTION |
إرسال حدث تجريبي إلى نقطة نهاية ويب هوك خاصة بشريك
تضع في قائمة الانتظار حدث payment.succeeded اصطناعيًا يحمل Test: true، موقّعًا تمامًا مثل حدث حقيقي، مع تجاهل قائمة الأحداث المسموح بها. تُرجع معرّف التسليم؛ اقرؤوه مجددًا عبر GET /api/v1/partner/webhooks/events/{deliveryId} للاطلاع على استجابة المستقبِل لديكم.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
id | string (uuid) | path | مطلوب |
تدوير سر توقيع ويب هوك الشريك
يُبطل السر السابق فورًا ويُعيد السر البديل مرة واحدة فقط. حدّثوا المستقبِل بشكل ذرّي لتجنّب رفض عمليات التسليم.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
id | string (uuid) | path | مطلوب |
إعادة تفعيل نقطة نهاية ويب هوك شريك معلّقة
تُعلَّق نقاط النهاية تلقائياً بعد تكرار فشل التسليم؛ ويُحتفظ بالأحداث الموجودة في الطابور ويُستأنف تسليمها بالترتيب عند إعادة التفعيل.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
id | string (uuid) | path | مطلوب |
استرجاع نقطة نهاية ويب هوك خاصة بشريك
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
id | string (uuid) | path | مطلوب |
تحديث نقطة نهاية ويب هوك خاصة بشريك
يحدّث عنوان URL، أو قائمة السماح الصريحة للأحداث، أو ترويسات التوجيه المخصصة، أو حالة التفعيل. استخدموا قائمة enabledEvents صريحة لتفادي الاستقبال التلقائي للأحداث المستحدثة.
المخطط · WebhookEndpointRequest
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
id | string (uuid) | path | مطلوب | |
url | string | body | مطلوب | عنوان URL عام للمستقبِل عبر HTTPS على المنفذ 443. تُرفض الأهداف الخاصة، وloopback، وlink-local، وغير HTTPS. |
description | string | body | اختياري | تسمية نقطة النهاية من جهة التاجر. |
enabledEvents | array of enum | body | اختياري | قائمة سماح صريحة للأحداث. القيمة null أو الفارغة تشترك في جميع الأحداث الحالية والمستقبلية؛ ويُنصح بقائمة صريحة للتكاملات المستقرة. |
customHeaders | object | body | اختياري | ترويسات توجيه ثابتة اختيارية. لا يمكن تجاوز Host وAuthorization وCookie وChari-* وX-CHARI-*. |
apiVersion | string | body | اختياري | إصدار عقد حمولة ويب هوك. |
enabled | boolean | body | اختياري | ما إذا كان التسليم يبدأ فوراً. |
environment | enum | body | اختياري | SANDBOX أو PRODUCTION. لمسارات البوابة فقط — القيمة الافتراضية PRODUCTION عند الإغفال. يُتجاهل على /api/v1/partner/** حيث يحدد مفتاح API البيئة، ويُتجاهل عند التحديث (لا يمكن نقل نقطة نهاية بين البيئات؛ احذفوها ثم أعيدوا إنشاءها).القيم SANDBOXPRODUCTION |
حذف نقطة نهاية ويب هوك للشريك
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
id | string (uuid) | path | مطلوب |
عرض قائمة أحداث ويب هوك الصادرة
يُعيد الأحداث الصادرة لبيئة مفتاح API هذا، الأحدث أولًا. يمكنكم التصفية حسب نقطة النهاية (endpoint) أو نوع الحدث أو حالة التسليم أو نافذة الإنشاء. تستخدم أنواع الأحداث قيمتها المنقوطة مثل payment.succeeded؛ والكتالوج الكامل متاح عبر GET /api/v1/partner/webhooks/event-types. لا تُدرَج الحمولات (payloads) هنا؛ اقرؤوا حدثًا واحدًا للحصول على الجسم الموقّع بدقة.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
endpointId | string (uuid) | query | اختياري | |
eventType | enum | query | اختياري | القيم payment_link.createdpayment_link.updatedpayment_link.expiredpayment_link.cancelledpayment.initiatedpayment.requires_actionpayment.succeededpayment.failedsubscription.payment_succeededsubscription.payment_failedsubscription.canceledrefund.initiatedrefund.succeededrefund.failedsecurity.token_reusedsecurity.rate_limit_exceededsecurity.invalid_signaturewallet.activatedwallet.rejectedpayout.completedpayout.failedsubmerchant.near_capwallet.fundedwallet.transfer_completedmerchant_transfer.completedmerchant_transfer.failedtopup.pendingtopup.succeededtopup.failedtopup.reversedbill_payment.pendingbill_payment.succeededbill_payment.failedbill_payment.reversedvoucher.issuedvoucher.failedvoucher.redeemedvoucher.expiredsavings.deposit_succeededsavings.withdrawal_succeededsavings.instruction_failedsavings.goal_reachedorder.paid |
status | enum | query | اختياري | القيم pendingsendingdeliveredfailedretryingexhaustedskipped |
from | string (date-time) | query | اختياري | |
to | string (date-time) | query | اختياري | |
pageable | Pageable | query | مطلوب |
استرجاع حدث ويب هوك واحد تم إصداره
يتضمّن الحمولة الموقّعة كما أُرسلت بالضبط إلى المستقبِل، ما يتيح للشريك إعادة إنتاج التوقيع محليًا قبل إعادة الإرسال.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
deliveryId | string (uuid) | path | مطلوب |
سؤال حول الدمج؟
يجيب فريقنا التقني فرق الإدماج، من أول استدعاء في السندبوكس حتى الانتقال إلى الإنتاج.