ProofSnap ProofSnap

وثائق API من ProofSnap

في عام 2026، تفتح واجهة REST API من ProofSnap أي عنوان URL في متصفح على خوادم ProofSnap وتُصدر حزمة أدلة مختومة: لقطة شاشة (screenshot) وHTML وبيانات وصفية وتقرير PDF وبيانًا (manifest) ببصمات SHA-256. يُوقَّع البيان بمفتاح RSA-4096، وتُرسل بصمته إلى OpenTimestamps لربطها بسلسلة كتل Bitcoin. آخر تحديث: 25 أكتوبر 2026.

عنوان URL الأساسي: https://api.getproofsnap.com/v1. المصادقة: مفتاح API يُرسَل رمزًا من نوع Bearer. في الأمثلة أدناه يُؤخذ العنوان الأساسي من متغير بيئة: export PROOFSNAP_API_BASE=https://api.getproofsnap.com/v1

البدء

  1. 1

    أنشئ مفتاح API

    سجّل الدخول إلى لوحة التحكم، وافتح قسم «المطورون» ثم «مفاتيح API»، وانقر على «+ مفتاح جديد». يُعرض المفتاح مرة واحدة فقط، لذا احفظه فورًا في مكان آمن. تبدأ المفاتيح بـ ps_live_ أو ps_test_. هل تفتح لوحة التحكم لأول مرة؟ يشرح لك دليل الخطوات الأولى في لوحة تحكم ProofSnap خطوة بخطوة كيفية التسجيل واختيار الخطة وإجراء أول عملية التقاط. ولمزيد من التفاصيل، راجع الأدلة الإرشادية للوحة التحكم.

  2. 2

    أجرِ أول عملية التقاط

    مرِّر المفتاح بوصفه رمز Bearer. تستجيب واجهة API فورًا بالرمز 202 وتعيد capture_id وstatus: "processing".

    curl -X POST "$PROOFSNAP_API_BASE/captures" \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
  3. 3

    استلم النتيجة

    استعلم دوريًا عبر GET /captures/{capture_id} إلى أن تصبح قيمة status إمّا completed وإمّا failed. تتضمن استجابة عملية الالتقاط المكتملة package_url (رابط موقّع مسبقًا لملف ZIP يبقى صالحًا 24 ساعة على الأكثر) وmanifest_hash. ويمكنك الحصول على رابط جديد بطلب بيانات عملية الالتقاط مرة أخرى. وبدلًا من الاستعلام الدوري، يمكنك تحديد نقطة نهاية HTTPS في options.webhook_url لتستقبل الحدث capture.completed أو capture.failed موقّعًا بـ HMAC-SHA256.

    curl "$PROOFSNAP_API_BASE/captures/cap_..." \
  -H "Authorization: Bearer ps_live_..."
  4. 4

    تحقّق من الحزمة

    تتحقق نقطة النهاية POST /captures/{capture_id}/verify من جديد من مطابقة كل بصمة SHA-256 مدرجة في البيان لبصمة الملف المخزن المقابل، وتتحقق من توقيع RSA-4096 للبيان، وتجيب بـ match أو modified أو invalid. إضافة إلى ذلك، يستطيع أي شخص أن يشغّل البرامج النصية الموجودة في المجلد verification/ من الحزمة دون اتصال بالإنترنت، أو أن يبحث عبر GET /ledger/{hash} عن بصمة SHA-256 للملف manifest.json في السجل العام للحزم الصادرة. ولا يحتاج أي منهما إلى مفتاح API.

    curl -X POST "$PROOFSNAP_API_BASE/captures/cap_.../verify" \
  -H "Authorization: Bearer ps_live_..."

المصادقة

مرِّر مفتاح API (API key) في الترويسة Authorization: Bearer ps_live_.... تبدأ المفاتيح بـ ps_live_ أو ps_test_. ينشئ المفتاح الفعلي عمليات التقاط مدفوعة، وينشئ مفتاح الاختبار حزمًا كاملة تحمل علامة مائية دون أي رسوم. وإذا لم تُربط الفوترة بالحساب، يُعامَل المفتاح الفعلي معاملة مفتاح الاختبار. عند غياب المفتاح تجيب واجهة API بالرمز 401 MISSING_API_KEY، وعند استخدام مفتاح غير معروف أو مُبطَل تجيب بالرمز 401 INVALID_API_KEY. مفاتيح خطة Website Archive للقراءة فقط (403 PLAN_API_READ_ONLY). وتعمل ثلاثة مسارات دون مفتاح: GET /health وGET /ledger/{hash} وGET /matter-verify.

يبدأ الحساب الجديد في وضع الاختبار (sandbox) ومعه 50 عملية التقاط تجريبية مجانية. الاستخدام التجريبي محدود بـ 200 وحدة لكل حساب في اليوم بتوقيت UTC (429 TEST_MODE_DAILY_LIMIT)، وتحمل لقطة الشاشة وملف PDF علامة مائية بلغة عملية الالتقاط (options.language): في عملية التقاط بالعربية «اختبار (TEST): غير صالح للاستخدام القانوني»، ودون تحديد لغة «TEST - NOT FOR LEGAL USE». ويحتاج include_eidas إلى مفتاح فعلي (403 EIDAS_REQUIRES_LIVE_KEY).

Webhooks

حدِّد options.webhook_url في طلب منفرد، أو أنشئ اشتراكات webhook للحساب كله عبر POST /webhook-subscriptions. تتبع webhooks مواصفة Standard Webhooks وتحمل الترويسات webhook-id وwebhook-timestamp وwebhook-signature (القيمة v1, يليها HMAC-SHA256 للمعرّف والطابع الزمني وجسم الطلب، محسوبًا بسر whsec_). أنواع الأحداث: capture.completed وcapture.failed وcapture.anchor_confirmed وcertify.completed وcertify.failed وredaction.completed وredaction.failed وmonitor.change_detected وschedule.paused. لا يُسلَّم الحدثان capture.anchor_confirmed وschedule.paused إلا إلى اشتراكات الحساب كله. ويتاح كل حدث أيضًا لمدة 30 يومًا عبر GET /events. مهلة محاولة التسليم الواحدة 10 ثوانٍ، وتُعاد المحاولات الفاشلة بعد 5 دقائق و30 دقيقة وساعتين و8 ساعات و24 ساعة. وخلال 24 ساعة من إنشاء سر جديد تُوقَّع webhooks بالسرّين القديم والجديد معًا.

تُوقَّع webhooks المرسلة إلى webhook_url المحدد في الطلب بسر مفتاح API الذي أُرسل به الطلب. يُعرض سر webhook هذا مرة واحدة فقط، عند إنشاء المفتاح في قسم «المطورون» من لوحة التحكم. ولاشتراك webhook سره الخاص الذي لا يُعرض إلا مرة واحدة عند إنشائه. تحقّق من التوقيع على الجسم الخام للطلب قبل تحليله. ارفض أي webhook تختلف فيه قيمة webhook-timestamp عن وقت خادمك بأكثر من 5 دقائق. وعالِج كل webhook-id مرة واحدة فقط. وكل مكتبة تدعم Standard Webhooks تتولى ذلك عنك.

الحدود والأخطاء

يخضع معدل الطلبات المدفوعة (POST /captures و/captures/batch و/compare و/captures/{capture_id}/redact و/certify-hash، وكذلك طلبات التحقق والحفظ القانوني ومهام التصدير والاستيراد) لحدٍّ لكل حساب في نوافذ زمنية ثابتة مدة كلٍّ منها 60 ثانية، وتشترك جميع مفاتيح API للحساب وجلسته في لوحة التحكم في نافذة واحدة. يستهلك الطلب المجمّع أو توثيق عدة بصمات وحدة واحدة لكل عنوان URL أو بصمة. الوحدات لكل نافذة: sandbox 10، وDeveloper 60، وStartup 120، وGrowth 300، وLegal Solo 60، وLegal Company 120، وWebsite Archive 60، وArchive only 30. تحمل استجابات هذه المسارات الترويستين RateLimit-Policy وRateLimit والترويسات القديمة X-RateLimit-*، وتحمل استجابة 429 أيضًا Retry-After.

تُخصم عمليات الالتقاط الفعلية من الحصة الشهرية للخطة (402 QUOTA_EXCEEDED)، وما دام دفع الخطة متأخرًا تجيب واجهة API عن طلبات الحساب بالرمز 402 PAYMENT_REQUIRED. وعدد عمليات الالتقاط التي يعالجها الحساب في الوقت نفسه محدود (429 CONCURRENT_CAPTURE_LIMIT). إذا أرسلت الترويسة Idempotency-Key، فإن تكرار الطلب خلال 24 ساعة يعيد النتيجة الأصلية مع Idempotent-Replay: true بدلًا من إنشاء عملية التقاط ثانية. تُعاد الأخطاء في صورة كائن JSON يتضمن الحقلين error.code وerror.message، والحقل error.details عند الحاجة. وعند التواصل مع الدعم اذكر قيمة ترويسة الاستجابة X-Request-ID. القائمة الكاملة للرموز في الوثائق أدناه.

نظرة سريعة على نقاط النهاية

  • عمليات الالتقاط: POST /captures، POST /captures/batch (من 2 إلى 50 عنوان URL)، GET /captures، GET /captures/hosts، GET /captures/{capture_id}، PATCH وDELETE /captures/{capture_id}، POST /captures/{capture_id}/verify
  • التنقيح والمقارنة والتوثيق: POST /captures/{capture_id}/redact، POST /compare، POST /certify-hash (حتى 100 بصمة)
  • الأتمتة: /scheduled-captures (عمليات التقاط مجدولة مع سجل مرات التشغيل /runs)، /webhook-subscriptions، GET /webhook-events/{capture_id}، GET /events، GET /captures/events
  • الميزات القانونية: /matters (القضايا: الختم والتصدير ورابط تحقق عام)، POST /legal-holds (الحفظ القانوني)، /imports، /captures/export-jobs
  • الحساب والمسارات العامة: GET /whoami، GET /health، GET /ledger/{hash}، GET /matter-verify

الوثائق الكاملة

جميع نقاط النهاية (endpoints) مع المعاملات والاستجابات والمخططات، مولّدة من مواصفة OpenAPI 3. يمكن تنزيل المواصفة في ملف openapi.json (بالإنجليزية، لمولّدات الشيفرة) أو openapi-ar.json (الأوصاف بالعربية). لتجربة نقطة نهاية دون كتابة شيفرة، أنشئ نسخة (fork) من مجموعة ProofSnap API في Postman. لا توجد حزمة SDK رسمية: أنشئ عميلًا بأي مولّد OpenAPI 3، وتحقّق من توقيعات webhooks بمكتبة Standard Webhooks.