ما هي الإيصالات؟
الإيصالات هي سجلات موقعة وغير قابلة للتغيير لأحداث منفصلة - مدفوعات، حوادث أمنية، فحوصات امتثال، عمليات تسليم، والمزيد. على عكس السجلات أو مسارات التدقيق، كل إيصال هو:- موقعة تشفيريًا بمفتاح المصدر الخاص بك (Ed25519 أو ES256)
- مرتكز في سجل الشفافية مع إثبات تضمين ميركل
- قابلة للتحقق دون اتصال عبر تصدير حزمة الإثبات
- متطابق - ينتج نفس الحدث دائمًا نفس الإيصال
أنواع الإيصالات
تتوفر أنواع الإيصالات المعرفة بالمنصة لجميع المستأجرين. يحتوي كل نوع على مخطط JSON يتم التحقق من صحة حقلpayload مقابله قبل التوقيع.
اكتشاف الأنواع المتاحة
استدعِGET /v1/receipt-types لسرد كل نوع يمكن للمستأجر الخاص بك استخدامه، أو GET /v1/receipt-types/{name} لجلب نوع واحد وفحص مخطط JSON الخاص به.
سك إيصال
يستخدم المثال معرفات وقيم حمولة توضيحية. استبدلها بمعرف المصدر الخاص بمساحة العمل الخاصة بك، ومفتاح التوقيع المتاح، وحمولة مطابقة لمخطط نوع الإيصال المحدد. لا ترسل المثال كسجل دفع حقيقي.1
اختر نوع الإيصال
استدعِ
GET /v1/receipt-types لسرد الأنواع المتاحة وفحص المخطط للحقول المطلوبة.2
بناء حمولتك
قم بإنشاء كائن
payload المطابق للحقول المطلوبة لنوع الإيصال الخاص بك. لـ payment_receipt، تحتاج إلى amount، وcurrency، وprovider، وprovider_reference، وsubject.3
الإنشاء عبر واجهة برمجة التطبيقات
4
تخزين receipt_id
يتضمن الرد
receipt_id و log.leaf_index. قم بتخزين كليهما للتحقق المستقبلي.أمثلة SDK
إيصالات القائمة
استرداد إيصال
أحداث خطاف الويب (Webhook)
اشترك في أحداث الإيصالات عن طريق تكوين نقطة نهاية webhook في وحدة التحكم:إلغاء إيصال
الإلغاء دائم ويتم تسجيله في سجل الشفافية. تظل الإيصالات ذات الحالةrevoked قابلة للاستعلام ويتم تضمين طابعها الزمني للإلغاء في حزم الإثبات. يمكنك تضمين reason اختياري لتسجيل سبب إلغاء الإيصال.
التحقق من إيصال
استخدم نقطة نهاية التحقق للتحقق من الصلاحية التشفيرية للإيصال وحالته الحالية. تتحقق واجهة برمجة التطبيقات من التوقيع وحالة المفتاح وحالة الإلغاء، ثم تُرجع حكمًا.الأحكام
حزم الإثبات
حزمة الإثبات هي حزمة مكتفية ذاتيًا للتحقق دون اتصال بالإنترنت. تتضمن مظروف الإيصال الموقّع، وإثبات تضمين ميركل من سجل الشفافية، ولقطة مفتاح المصدر وقت الإصدار. بعد تنزيل حزمة إثبات، يمكنك التحقق من الإيصال دون إجراء أي مكالمات API إضافية.البحث عن الإيصالات
ابحث في إيصالاتك باستخدام البحث بالنص الكامل والفلاتر المتعددة. يدعم فهرس البحث الاستعلامات مقابل محتوى الحمولة، ويمكنك تضييق النتائج حسب النوع أو الحالة أو النطاق الزمني أو حقول الحمولة المفهرسة.عوامل تصفية البحث
تصدير الإيصالات
وضع تصدير مجمع غير متزامن للإيصالات بتنسيق JSON أو CSV في قائمة الانتظار. تعود واجهة برمجة التطبيقات فورًا بمعرف مهمة. استعلم عن نقطة نهاية حالة التصدير حتى يصبحstatus complete، ثم قم بالتنزيل من عنوان URL الموقّع مسبقًا.
قيم حالة التصدير
تنقيح الإيصالات
يزيل التنقيح معلومات التعريف الشخصية (PII) بشكل دائم من حمولة الإيصال مع الحفاظ على الإثبات التشفيري. يظل توقيع الإيصال، وإدخال سجل الشفافية، وإثبات تضمين Merkle سليمًا - يتم استبدالpayload_json فقط بعلامة تنقيح.
استخدم هذا لطلبات حق المسح بموجب اللائحة العامة لحماية البيانات (GDPR) على الإيصالات التي تحتوي على بيانات شخصية.
statusيتغير إلىredactedpayload_jsonيتم استبداله بـ{"redacted": true, "redacted_by": "tenant_request"}- يتم تثبيت حدث
RECEIPT_REDACTفي سجل الشفافية - يتم الاحتفاظ بجميع الحقول الأخرى (التوقيع، إثبات السجل، نوع الإيصال)
إدارة الإيصالات في وحدة التحكم
يمكنك إدارة دورة حياة الإيصالات الكاملة من وحدة التحكم دون كتابة أي رمز. افتح الإيصالات في الشريط الجانبي لوحدة التحكم للوصول إلى الميزات التالية.البحث عن الإيصالات
تتضمن صفحة قائمة الإيصالات شريط بحث وفلاتر. اكتب كلمة رئيسية للبحث عبر حمولات الإيصالات، أو استخدم عناصر التحكم في الفلتر لتضييق النتائج حسب نوع الإيصال أو حالته أو مُصدره أو النطاق الزمني. يتم تحديث النتائج في الوقت الفعلي أثناء تحسين استعلامك.تصدير الإيصالات
انقر فوق تصدير من قائمة الإيصالات لجدولة تصدير مجمع كملف CSV أو JSON. يظهر شريط حالة في أعلى الصفحة يتتبع المهمة عبر حالاتpending وrunning وcomplete. بمجرد انتهاء التصدير، انقر فوق الشريط لتنزيل الملف. يمكنك أيضًا مراقبة مهام التصدير من واجهة برمجة التطبيقات باستخدام GET /v1/receipt-exports/{id} — راجع تصدير الإيصالات.
تنزيل حزمة إثبات
افتح صفحة تفاصيل أي إيصال وانقر على تنزيل حزمة الإثبات لحفظ حزمة تحقق مستقلة. تتضمن الحزمة مغلف الإيصال الموقع، وإثبات تضمين Merkle، ولقطة مفتاح المصدر — كل ما يلزم للتحقق دون اتصال.إخفاء إيصال
من صفحة تفاصيل أي إيصال نشط، انقر فوق إخفاء لإزالة المعلومات الشخصية من الحمولة بشكل دائم. يشرح مربع حوار التأكيد أن الإخفاء لا رجعة فيه قبل المتابعة. الإخفاء متاح فقط للإيصالات ذات حالةactive. بعد الإخفاء، يتم الاحتفاظ بالإثبات التشفيري وإدخال سجل الشفافية — يتم إزالة محتوى الحمولة فقط. راجع إخفاء الإيصالات للحصول على تفاصيل حول ما يتغير.
سياسة الاستبقاء
يتم تنظيف الإيصالات تلقائيًا بناءً على سياسة الاستبقاء المحددة وقت الإنشاء. يقوم عامل خلفي بمسح الإيصالات منتهية الصلاحية بانتظام. عيّنretention_policy عند سك العملة:
يمكن تنقيح الإيصالات التي تقترب من موعد الاحتفاظ بها بدلاً من حذفها إذا كنت بحاجة إلى الحفاظ على الإثبات التشفيري مع إزالة بيانات الحمولة.
الخطوات التالية
مواصفات حزمة الإثبات
الهيكل الكامل وخطوات التحقق دون اتصال لحزم الإثبات.
مرجع واجهة برمجة تطبيقات الإيصالات
مرجع API كامل لسك، والبحث، والتصدير، وتنقيح الإيصالات.
الويب هوكس
اشترك في أحداث الاستلام ومعالجتها في الوقت الفعلي.
سياسات الإصدار
فرض سير عمل الموافقات والقيود على سك الإيصالات.

