> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# التحقق من التصديق

> تحقق من حالة السجل، وبيانات تعريف المصدر، والأدلة المتاحة. قم بتوفير payload_b64url الأصلي بالضبط للتحقق من التوقيع التشفيري. سيعيد البحث بمعرف فقط أو ببصمة ملف فقط حالة INCOMPLETE مع signature_verified false إذا لم ينطبق فشل أقوى. VALID يعني أن الحمولة المقدمة اجتازت فحوصات التوقيع؛ ولا يثبت ذلك صحة الادعاءات أو يضمن اكتمال فحوصات السياسة والشفافية الاختيارية. افحص الأسباب و log.proof_checked. لا تتطلب الطلبات العامة مفتاح API؛ يتم تحديد نطاق الطلبات المصادق عليها وقياسها مقابل مساحة عمل المتصل.

تحقق من الحالة الحالية للسجل والأدلة المتاحة. للتحقق من توقيعه التشفيري، أرسل **الحمولة الأصلية الموقعة بالضبط** كـ `payload_b64url`. لا يمكن لمعرف السجل أو بصمة الملف وحدها توفير تلك البايتات.

### اختر الفحص الذي تحتاجه

| الإدخال | ما الذي يتحقق منه |
| - | - |
| `attestation_id` | يعثر على سجل يمكن الوصول إليه ويتحقق من حالته الحالية، وبيانات تعريف المُصدر، وأدلة السجل المتاحة. |
| المعرف بالإضافة إلى `payload_b64url` | يتحقق أيضًا من ملخص الحمولة والتوقيع مقابل المفتاح العام المسجل. قم بترميز البايتات الأصلية؛ إعادة تنسيق JSON يمكن أن يغير هذه البايتات. |
| المعرف بالإضافة إلى `document_hash_hex` | يقارن بصمة SHA-256 المقدمة مع بصمة المستند المسجلة. هذا لا يحل محل التحقق من الحمولة الموقعة. |

يعيد فحص المعرف فقط أو البصمة فقط `INCOMPLETE` و `signature_verified: false` ما لم تنطبق نتيجة أقوى مثل `REVOKED` أو `EXPIRED` أو `ALTERED`. قم بتوفير الحمولة الأصلية لإجراء فحص توقيع كامل.

يجب أن تحدد `attestation` المضمنة سجلًا مسجلًا باستخدام `attestation_id`. يتم تحميل الحالة عبر الإنترنت وهوية المفتاح من هذا السجل؛ لا يمكن للحقول المقدمة من المتصل تجاوز مصدرها أو إلغائها. استخدم مدققًا غير متصل متوافقًا لإجراء فحوصات التوقيع المستقلة.

### تفسير الاستجابة

| الحكم | المعنى |
| - | - |
| `VALID` | اجتاز الحمولة المقدمة فحص التوقيع الخاص بها ولم يتم إرجاع أي فشل حظر. افحص الأسباب والفحوصات الفردية. |
| `INCOMPLETE` | لم يتم توفير المحتوى الأصلي المطلوب؛ لم يتم التحقق من التوقيع. |
| `ALTERED` | فشل حمولة أو توقيع أو بصمة مستند مقدمة في فحص السلامة. |
| `REVOKED` | تم إلغاء السجل. |
| `SUPERSEDED` | يحل سجل أحدث محل هذا السجل. اطلب من المصدر سجله الحالي. |
| `EXPIRED` | انتهت صلاحية السجل أو مفتاح التوقيع. |
| `INVALID` | فشل إدخال مطلوب أو فحص تحقق. |
| `NOT_FOUND` | لم يتطابق أي سجل متاح مع الطلب وبيئته. |
| `UNKNOWN_ISSUER` | تعذر قبول مفتاح توقيع المُصدر. |

`signature_verified` يبلغ عن فحص التوقيع على وجه التحديد. `log.proof_checked` يبلغ عن التحقق الناجح من تضمين الشفافية. ينتج عن الإثبات المفقود سبب وفهرس ورقة فارغ؛ الصفر هو ورقة أولى مشروعة. لا يعني عدم وجود قيمة `expires_at_unix` أنه يجب اختراع تاريخ انتهاء صلاحية جديد لسجل تاريخي.

> [!WARNING]
>
> لا يثبت التوقيع الصالح الملكية أو الصلاحية القانونية أو صحة كل ادعاء. اقرأ `reasons`، وحوكمة المصدر الحالية، والأدلة المتاحة قبل الاعتماد على سجل. قد تكون فحوصات السياسة أو السجل الاختيارية غير متاحة حتى عندما ينجح توقيع الحمولة.

### المصادقة والقيود

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

شارك سجلًا يمكن الوصول إليه باستخدام `https://verify.truthlocks.com/proof/{attestation_id}`. لا يمنح عنوان URL المشترك الوصول إلى الحمولات الخاصة.


## OpenAPI

````yaml ar/mint-openapi.yaml POST /v1/verify
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks هي بنية تحتية عالمية للتحقق من المستندات وبيانات الاعتماد والأصول
    الرقمية.يحدد هذا المواصفات واجهة برمجة التطبيقات (API) الأساسية للتفاعل مع
    خدمات Truthlocks.


    ## عناوين URL الأساسية

    - **الإنتاج**: `https://api.truthlocks.com`

    - **البيئة التجريبية (Sandbox)**: `https://sandbox-api.truthlocks.com`


    ## المصادقة

    - **مفاتيح API**: استخدم رأس `X-API-Key` للعمليات من جهاز إلى جهاز

    - **رموز Bearer**: استخدم `Authorization: Bearer <jwt>` للعمليات التي يبدأها
    المستخدم


    ## هوية المستأجر

    في بيئة الإنتاج، تُستمد هوية المستأجر من السياق المصادق عليه (مفتاح API أو
    JWT).

    يتم تجاهل رأس `X-Tenant-ID` في بيئة الإنتاج لمنع الانتحال.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: واجهة برمجة تطبيقات الإنتاج
  - url: https://sandbox-api.truthlocks.com
    description: بيئة اختبار (Sandbox)
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: إدارة مفاتيح ورموز API
  - name: Issuers
    description: تسجيل المصدر وإدارة الثقة
  - name: Keys
    description: إدارة المفاتيح التشفيرية لجهات الإصدار
  - name: Attestations
    description: دورة حياة الإشهاد (السك، الإلغاء، الاستبدال)
  - name: Verification
    description: حزم التحقق والإثبات للإشهاد
  - name: Governance
    description: سير عمل حوكمة المصدر (للمسؤول فقط)
  - name: Identity
    description: إدارة المنظمة والمستخدمين والأدوار
  - name: Audit
    description: استعلامات أحداث التدقيق
  - name: Tenant Console
    description: ملف تعريف المستأجر ونقاط نهاية دورة الحياة
  - name: Health
    description: نقاط نهاية صحة الخدمة وجاهزيتها
  - name: Risk
    description: استيعاب إشارة المخاطر واكتشاف الاحتيال
  - name: Risk Enforcement
    description: إجراءات إنفاذ المخاطر — الحظر والتحدي والحجر والتكوين
  - name: Billing
    description: إدارة الفوترة والاشتراكات والإضافات
  - name: Machine Identity
    description: >-
      بروتوكول هوية وكيل الآلة (MAIP) — تسجيل الوكيل، الجلسات، الثقة، الشهادة،
      الامتثال، التنسيق، والمراقبة
externalDocs:
  description: واجهة برمجة تطبيقات الشفافية للقراءة فقط (مواصفات خدمة منفصلة)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/verify:
    post:
      tags:
        - Verification
      summary: التحقق من التصديق
      description: >-
        تحقق من حالة السجل، وبيانات تعريف المصدر، والأدلة المتاحة. قم بتوفير
        payload_b64url الأصلي بالضبط للتحقق من التوقيع التشفيري. سيعيد البحث
        بمعرف فقط أو ببصمة ملف فقط حالة INCOMPLETE مع signature_verified false
        إذا لم ينطبق فشل أقوى. VALID يعني أن الحمولة المقدمة اجتازت فحوصات
        التوقيع؛ ولا يثبت ذلك صحة الادعاءات أو يضمن اكتمال فحوصات السياسة
        والشفافية الاختيارية. افحص الأسباب و log.proof_checked. لا تتطلب الطلبات
        العامة مفتاح API؛ يتم تحديد نطاق الطلبات المصادق عليها وقياسها مقابل
        مساحة عمل المتصل.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                attestation:
                  description: >-
                    مغلف البحث عبر الإنترنت. مطلوب معرف attestation_id مسجل هنا
                    أو على مستوى الطلب. الحالة المخزنة، والمصدر، والمفتاح، ووقت
                    الإصدار هي سلطة؛ لا يمكن للنسخ المقدمة تجاوزها.
                  nullable: true
                  properties:
                    attestation_id:
                      type: string
                    document_hash:
                      type: string
                    expires_at_unix:
                      type: integer
                      format: int64
                      nullable: true
                      description: >-
                        تاريخ انتهاء الصلاحية الموقع المسجل بثواني يونكس؛ يعني
                        null عدم تسجيل تاريخ انتهاء صلاحية. لا يتم تعيين تاريخ
                        انتهاء صلاحية جديد للسجلات القديمة.
                    issued_at_unix:
                      type: integer
                    issuer_id:
                      type: string
                    log:
                      type: object
                      properties:
                        log_id:
                          type: string
                        leaf_index:
                          type: integer
                          nullable: true
                          description: >-
                            فهرس ورقة الشفافية المستند إلى الصفر. يشير Null إلى
                            تعذر استرداد مرجع السجل؛ الصفر هو إدخال أول صالح.
                        status:
                          type: string
                          enum:
                            - recorded
                            - unavailable
                          description: توفر مرجع السجل المخزن؛ هذا لا يؤسس حكم إدراج متحقق.
                        leaf_hash:
                          type: string
                        proof_url:
                          type: string
                    payload_hash:
                      type: string
                    signature:
                      type: object
                      properties:
                        alg:
                          type: string
                        kid:
                          type: string
                        value:
                          type: string
                    status:
                      type: string
                    tenant_id:
                      type: string
                      format: uuid
                    version:
                      type: string
                  type: object
                attestation_id:
                  type: string
                document_hash_hex:
                  type: string
                payload_b64url:
                  type: string
              type: object
      responses:
        '200':
          description: نتيجة التحقق
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
              examples:
                valid:
                  summary: Valid attestation
                  value:
                    verdict: VALID
                    valid: true
                    details:
                      issuer_id: 550e8400-e29b-41d4-a716-446655440000
                      issuer_name: Acme University
                      log_index: 42
                revoked:
                  summary: Revoked attestation
                  value:
                    verdict: REVOKED
                    valid: false
                    details:
                      revoked_at: '2026-01-13T15:00:00.000Z'
                      reason: Certificate holder no longer employed
      security:
        - APIKey: []
        - {}
components:
  schemas:
    VerifyResponse:
      type: object
      required:
        - verdict
      description: >-
        أدلة التحقق العامة. افحص الأسباب والفحوصات الفردية؛ لا يتحقق الفحص الذي
        يعتمد على المعرف فقط من المحتوى الأصلي الذي قدمه المتصل.
      properties:
        verdict:
          $ref: '#/components/schemas/Verdict'
        signature_verified:
          type: boolean
          description: >-
            صحيح فقط عندما تكون الحمولة الأصلية المقدمة قد اجتازت التحقق من
            التوقيع التشفيري. تعيد عمليات التحقق من المعرف فقط وبصمة الإصبع فقط
            قيمة خاطئة.
        reasons:
          type: array
          items:
            type: string
        attestation_id:
          type: string
          format: uuid
        issuer_id:
          type: string
          format: uuid
        expires_at_unix:
          type: integer
          format: int64
          nullable: true
          description: >-
            تاريخ انتهاء الصلاحية الموقع المسجل بثواني يونكس؛ يعني null عدم
            تسجيل تاريخ انتهاء صلاحية. لا يتم تعيين تاريخ انتهاء صلاحية جديد
            للسجلات القديمة.
        issued_at_unix:
          type: integer
          format: int64
          description: >-
            وقت الإصدار المخزن الأصلي بالثواني Unix. هذا ليس وقت الفحص الحالي أو
            تنزيل الشهادة. غائب إذا كان غير متاح.
        kid:
          type: string
          description: معرف مفتاح التوقيع.
        alg:
          type: string
          description: خوارزمية التوقيع المعلنة.
        payload_hash:
          type: string
          description: ملخص SHA-256 المشفر بـ Base64url للحمولة القانونية.
        document_hash:
          type: string
          description: بصمة SHA-256 السداسية عشرية للملف الأصلي، عند تخزينه.
        log:
          type: object
          properties:
            log_id:
              type: string
            leaf_index:
              type: integer
              format: int64
              nullable: true
              description: >-
                فهرس ورقة الشفافية الذي تم التحقق منه؛ يكون فارغًا عندما يكون
                التحقق من الإثبات غير متاح. الصفر هو ورقة أولى صالحة.
            leaf_hash:
              type: string
              description: ملخص ورقة التضمين الذي تم التحقق منه، عند توفره.
            proof_checked:
              type: boolean
              description: ما إذا تم التحقق من تضمين الشفافية بنجاح لهذه الاستجابة.
        governance:
          type: object
          properties:
            issuer_display_name:
              type: string
            issuer_status:
              type: string
            issuer_trust_tier:
              type: string
            issuer_risk_rating:
              type: string
            issuer_jurisdiction:
              type: string
            primary_color:
              type: string
            accent_color:
              type: string
            logo_url:
              type: string
            snapshot_status:
              type: string
            snapshot_trust_tier:
              type: string
            snapshot_risk_rating:
              type: string
            snapshot_jurisdiction:
              type: string
    Verdict:
      type: string
      enum:
        - VALID
        - INCOMPLETE
        - INVALID
        - REVOKED
        - ALTERED
        - SUPERSEDED
        - EXPIRED
        - UNKNOWN_ISSUER
        - NOT_FOUND
      description: >-
        افحص الأسباب، ومدخلات التحقق المقدمة، و log.proof_checked جنبًا إلى جنب
        مع هذا الحكم. VALID وحده لا يثبت الملكية أو يثبت كل مطالبة في السجل.
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: مفتاح API للمصادقة من جهاز إلى جهاز
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT للعمليات التي يبدأها المستخدم

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.