# تصميم HTTP API

تُعرَّف واجهة HTTP في `specs/openapi.draft.json`. وهي عقد بروتوكول وليست نقطة نهاية حية. ترد الواجهات المتاحة في [حالة التنفيذ](https://proof21.xyz/ar/docs/start/status/).

| العملية المقترحة | الغرض |
| --- | --- |
| `POST /v0/evaluations` | إرسال تقييم أدلة مدعوم |
| `POST /v0/verifications` | التحقق من تقرير وسياق متوقع مقدمين |
| `GET /v0/jobs/{jobId}` | تفقد مهمة غير متزامنة |
| `GET /health` | صحة التشغيل، لا صحة الإثبات |

## مبادئ الطلب

اطلب ملفاً وإصداره ومعرّف عملية وسياقاً متوقعاً صريحاً ومراجع أدلة محدودة. لا تنفّذ كوداً أو سياسات اعتباطية يرسلها المستخدم. استخدم سلاسل أعداد صحيحة للقيم المالية مع شبكة وهوية أصل دقيقة. تخضع العناوين غير الموثوقة لسياسة الجلب.

يربط مفتاح عدم التكرار الجهة المستدعية وملخص الطلب. تفشل إعادة استخدام المفتاح مع مدخلات مختلفة. تحدد كل نقطة نهاية متاحة متطلبات المصادقة والدفع والصلاحيات.

## الاستجابات

تبقى حالة المعالجة وصحة الأثر والتقييم والقبول المحلي حقولًا منفصلة. التقييم المكتمل بنتيجة FAIL ليس خطأ خادم. تنتج الأدلة الناقصة INDETERMINATE. تتضمن رموز الأخطاء المنظمة شرحًا ومتطلبات مقروءة آليًا.

مثّل الطوابع الزمنية والاختيارات المعتمدة على مصدر مستقبلي كمهام غير متزامنة. لا يجوز لنقطة متزامنة أن تعد بأدلة Bitcoin مؤكدة قبل وجودها.

## حدود OpenAPI

يوثّق المخطط الأولي بنية الواجهة، لا الصلاحية التشفيرية. لا يصادق على النهائية أو خوارزميات التوقيع أو سلوك رد الأموال أو التفويض الإنتاجي. يحتاج دليل الأخطاء وملف التوقيع وتوحيد التمثيل إلى اختبارات قبل إعلان توافق التنفيذ.

<!-- p21-source-payment-v08 -->

## أدلة الدفع والقيد المحاسبي مرة واحدة

تربط الفاتورة المستدعي وملخص الطلب ومفتاح منع التكرار وهوية الشبكة والأصل الدقيقة ومستلم التاجر والمبلغ الصحيح بوحدات ذرية واستحقاق رصيد الخدمة والانتهاء وسياسة التسوية. يتحقق المحول من حدث تحويل منفذ ووجهته ومقداره وهوية النشر والكتلة المعتمدة والتأكيدات وتغطية المفهرس وإصدار القواعد. معرّف المعاملة أو مشاهدتها في mempool أو إنشاء نقش أو صورة رصيد المحفظة ليست تسوية للدفع.

تُحفظ فرادة الحدث باستخدام الشبكة ونشر الأصل والمعاملة وهوية العملية أو النقش. تُربط ملكية الفاتورة بالمستدعي وفق عقد الفاتورة، بدلاً من قبول أي تجزئة معاملة مقدمة. تستخدم إضافة الرصيد وحجز المهمة والاستهلاك والتحرير معاملات دفتر ذرية وقيود فرادة. لا تؤدي إعادة المحاولة أو تكرار webhook إلى رصيد أو خصم مكرر. تظل الأدلة الناقصة أو الفهارس المتأخرة أو المتعارضة أو إعادة التنظيم معلقة أو قيد المراجعة. يُحدد قيد تعويضي وسياسة لتحمل المشغل خسائر إعادة التنظيم العميقة؛ ولا تُخصم دفعة عميل أخرى خفيةً.


## التفعيل التجاري وحالة التنفيذ

يجب أن يجتاز NAT وUSDC معاً اختبار قبول الإطلاق التجاري الأول. الوثائق العامة والشيفرة وحالات اختبار السياسة ليست نقاط دفع حية. يسرد مورد سياسة الدفع الثابت الوسائل المطلوبة مع `enabled: false`، دون مستلم أو نقطة تشغيل حية، حتى يجتاز كل مسار اختبارات التسوية الشاملة والمحاسبة والفشل وإعادة التنظيم والأمان وموافقة المالك. لا يوصف إصدار USDC وحده بأنه استكمال لنطاق المدفوعات الأولي.

لا يصدر هذا الإصدار رمزاً ولا يعلن عنصر المصدر ولا ينشئ نقشاً على الشبكة الرئيسية ولا يخصم من العملاء ولا ينفذ مبادلة للخزانة ولا يمنح تفويضاً لمحفظة. إتاحة الخدمة الإنتاجية منفصلة عن نشر الموقع. لا يُفهم منه وجود شراكة مع Trac أو SLA للاستضافة أو تدقيق تشفيري مستقل.


[1] https://digital-matter-theory.gitbook.io/digital-matter-theory/introduction/digital-elements/.element-registry

[2] https://github.com/Trac-Systems/ord-tap/blob/b8f6ea35cf6b9d405d4db7c58555e3c8ab33e8cd/src/index/updater/inscription_updater/tap/ops/dmt_element.rs

[3] https://digital-matter-theory.gitbook.io/digital-matter-theory/introduction/nat-use-cases/usdnat-method-1-live

[4] https://digital-matter-theory.gitbook.io/digital-matter-theory/introduction/non-arbitrary-tokens-nats/nat-token-transfer

[5] https://docs.x402.org/core-concepts/network-and-token-support

[6] https://github.com/Trac-Systems/ord-tap/blob/b8f6ea35cf6b9d405d4db7c58555e3c8ab33e8cd/README.md

[7] https://arxiv.org/abs/1605.04559

<!-- p21-enforcement-v10 -->

## مخططات Authorization ليست نقاط نهاية حية

ينشر المستودع مسودات JSON Schema لـ `p21.authorization.v1` و`p21.consumer-decision.v1` و`p21.equivocation-evidence.v1` للتشغيل البيني واختبارات المطابقة. لا تعرض وثيقة OpenAPI الحالية مسارات production authorization/signing/decision/dispute، ولا يجوز للعميل استنتاج سلطة تنفيذ من وجود schema.