> ## 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.

# إصدار إشهاد

> صك إثبات موقع باستخدام مخطط وهياكل منظمة، أو حمولة مشفرة.
احتفظ بنفس Idempotency-Key والنص عند إعادة محاولة هذا الطلب.


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

## اختر نوع السجل

لسجل منظم، اختر `schema` من القائمة المنسدلة لنوع السجل وأدخل كائن JSON في `claims`. اترك `payload_b64url` فارغًا. يقوم الخادم بتسلسل هذه الحقول في حمولة JSON الموقعة. هذا يحدد نوع السجل؛ ولا يثبت بشكل مستقل أن المطالبات صحيحة.

## اختر حزمة تحقق

تنتمي حزم التحقق إلى مساحة عملك. استخدم المحدد أدناه بنفس البيئة ومفتاح API كما في Try it، ثم انسخ المعرف المحدد إلى `pack_id`. احذف هذا الحقل لسجل مستقل. يمكنك أيضًا استخدام [List verification packs](https://docs.truthlocks.com/ar/api-reference/verification-packs/list.md) أو [Mint in Console](https://console.truthlocks.com/attestations/mint).

**Select a workspace verification pack**

This read-only lookup sends your key directly to the selected Truthlocks API. It keeps the key only in this componentâ€™s memory and does not mint a record.

API environment
Workspace API key

Clear key and results

Verification pack

## استخدام حمولة موجودة

إذا كان لديك البايتات الدقيقة للتوقيع بالفعل، فاحذف `schema` و `claims`. قم بترميز البايتات الأصلية كـ **base64url غير مبطن** في `payload_b64url`. بالنسبة لـ JSON، قم بتسلسل الكائن أولاً. تنتمي حقول التطبيق مثل `subject` و `claims` و `schema` داخل تلك البايتات المشفرة؛ استخدمها إما من خلال الإدخال المنظم أعلاه أو داخل البايتات المشفرة، ولا تستخدم كليهما أبدًا. لا تتحقق نقطة النهاية هذه بشكل مستقل من صحة المطالبات المقدمة أو تتحقق من صحة مخططات الاعتماد العشوائية.

استخدم `kid` للمفتاح و `alg` المطابق. لا يؤدي تسجيل المفتاح العام وحده إلى توفير مفتاح توقيع خاص. انظر [مفاتيح المُصدر](https://docs.truthlocks.com/ar/api-reference/issuers/keys.md).

## انتهاء الصلاحية الاختياري

لـ `schema` و `claims` المنظمين، اضبط `expires_at_unix` على طابع زمني Unix مستقبلي بـ **الثواني**. يتضمن Truthlocks ذلك في جذر حمولة JSON الموقعة. مع `payload_b64url`، ضع هذا الحقل داخل حمولة JSON الدقيقة قبل ترميزها وحذف حقل الطلب المنفصل.

بعد تلك اللحظة، يعيد التحقق `EXPIRED`. لا يمكن تمديد انتهاء الصلاحية أو إزالته من سجل موقع موجود؛ قم بإنشاء بديل. احذفه عندما لا ترغب في انتهاء صلاحية التصديق. التواريخ داخل المطالبات الفردية، مثل `expiry_date` لجواز السفر، هي مطالبات منفصلة ولا تحدد تلقائيًا انتهاء صلاحية التصديق. لا يتم تعيين تاريخ للسجلات الموجودة بأثر رجعي.

احتفظ بالحمولة الدقيقة وتاريخ انتهاء الصلاحية عند إعادة المحاولة. تعيد المحاولة المتطابقة السجل الأصلي حتى بعد انتهاء صلاحيته.

## إعادة المحاولة بأمان

`Idempotency-Key` مطلوب. قم بإنشاء قيمة واحدة لكل سك مقصود واحتفظ بها مع الطلب الأصلي لإعادة المحاولات. لا تعيد استخدامها لمحتوى مختلف.

## سلامة المستندات

يتم تحديد تجزئة المستند المخزنة بهذا الترتيب:

1. `claims.document.sha256` داخل حمولة JSON.
2. `document_hash` للطلب.
3. SHA-256 لبايتات الحمولة المفككة.

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

مرر `document_hash_hex` إلى [verification](https://docs.truthlocks.com/ar/api-reference/verify.md) لمقارنة تجزئة ملف. احتفظ بالحمولة الأصلية للتحقق من سلامة الحمولة.

## الاستجابة والتسليم

يعيد HTTP 201 `attestation_id`، `issued_at_unix`، `signature`، و `log`. موقع السجل هو `log.leaf_index`، وليس `log_index` على المستوى الأعلى.

`recipient_email` يطلب إشعارًا غير متزامن. يؤكد HTTP 201 السك، وليس تسليم البريد الإلكتروني. احذفه عند توزيع السجل بنفسك.

راجع [دليل البدء السريع](https://docs.truthlocks.com/ar/quickstart.md) لطلب يستخدم حقول الإدخال والاستجابة الفعلية.

## دليل حقل نوع السجل

هذه الحقول هي هياكل مطالبات مقترحة، وليست ضمانًا للتحقق من المطالبة أو التحقق من الهوية.

| معرف المخطط | الاسم | الفئة | حقول المطالبة |
| - | - | - | - |
| `verifiable-id` | هوية قابلة للتحقق | الهوية | `full_name, employee_id, department, title, start_date` |
| `passport` | جواز سفر | الهوية | `full_name, nationality, passport_number, date_of_birth, expiry_date, issuing_country` |
| `drivers-license` | رخصة قيادة | الهوية | `full_name, license_number, state, class, expiry_date, date_of_birth` |
| `government-id` | هوية حكومية | الهوية | `full_name, id_number, id_type, issuing_authority, country, expiry_date` |
| `self-sovereign-id` | هوية ذاتية السيادة | الهوية | `did, display_name, created_at` |
| `employment-verification` | التحقق من التوظيف | التوظيف | `employee_name, employer, position, department, employment_type, start_date, end_date` |
| `professional-role` | دور مهني | التوظيف | `full_name, title, organization, department, effective_date` |
| `membership-card` | بطاقة عضوية | التوظيف | `member_name, organization, membership_id, tier, valid_from, valid_to` |
| `professional-certification` | شهادة مهنية | التوظيف | `holder_name, certification_name, issuing_body, certification_id, issued_date, expiry_date` |
| `license` | ترخيص | التوظيف | `holder_name, license_type, license_number, issuing_authority, jurisdiction, issued_date, expiry_date` |
| `accreditation` | اعتماد | التوظيف | `entity_name, accreditation_body, standard, scope, valid_from, valid_to` |
| `degree` | درجة | التعليم | `student_name, institution, degree_type, field_of_study, graduation_date, honors` |
| `completion-cert` | شهادة إتمام | التعليم | `participant_name, program_name, institution, completion_date, hours` |
| `course-credit` | رصيد الدورة | التعليم | `student_name, course_name, institution, credits, grade, semester` |
| `transcript` | كشف الدرجات | التعليم | `student_name, institution, program, gpa, total_credits, issue_date` |
| `micro-credential` | شهادة مصغرة | التعليم | `earner_name, credential_name, issuer, skills, earned_date` |
| `training-completion` | إتمام التدريب | تعليم | `trainee_name, training_program, provider, completion_date, score, certificate_id` |
| `medical-license` | ترخيص طبي | الرعاية الصحية | `practitioner_name, license_number, specialty, state, issued_date, expiry_date` |
| `dea-registration` | تسجيل DEA | الرعاية الصحية | `registrant_name, dea_number, schedules, business_activity, expiry_date` |
| `board-certification` | شهادة مجلس الإدارة | رعاية صحية | `physician_name, board, specialty, certification_date, expiry_date` |
| `health-credential` | شهادة صحية | الرعاية الصحية | `patient_name, credential_type, provider, date, details` |
| `vaccination-record` | سجل التطعيم | رعاية صحية | `patient_name, vaccine_name, manufacturer, lot_number, date_administered, dose_number, site` |
| `aml-kyc` | فحص AML/KYC | الامتثال | `entity_name, check_type, result, risk_level, verified_by, verified_at` |
| `security-clearance` | تصريح أمني | امتثال | `holder_name, clearance_level, granting_agency, granted_date, expiry_date` |
| `sam-gov` | تسجيل SAM.gov | الامتثال | `entity_name, cage_code, uei, registration_status, expiry_date` |
| `jurisdiction-approval` | موافقة الولاية القضائية | امتثال | `entity_name, jurisdiction, approval_type, approved_date, conditions` |
| `attestation-of-will` | تصديق وصية | امتثال | `declarant_name, declaration, witness, date` |
| `bank-verification` | التحقق المصرفي | المالية | `account_holder, bank_name, account_type, routing_number_last4, verified_date` |
| `credit-attestation` | تصديق ائتماني | مالي | `entity_name, credit_score_range, reporting_agency, assessment_date` |
| `income-verification` | التحقق من الدخل | مالي | `individual_name, employer, annual_income_range, verification_date, tax_year` |
| `skill-badge` | شارة المهارة | المهارات والتدريب | `earner_name, skill_name, proficiency_level, assessed_by, earned_date` |
| `competency` | إثبات الكفاءة | المهارات والتدريب | `individual_name, competency, level, assessor, assessment_date` |
| `industry-cert` | شهادة صناعية | المهارات والتدريب | `holder_name, certification, issuing_body, cert_id, issued_date, expiry_date` |
| `product-authenticity` | أصالة المنتج | سلسلة التوريد | `product_name, sku, serial_number, manufacturer, manufactured_date, origin_country` |
| `chain-of-custody` | سلسلة الحضانة | سلسلة التوريد | `item_description, from_entity, to_entity, transfer_date, location, condition` |
| `origin-verification` | التحقق من الأصل | سلسلة التوريد | `product_name, origin_country, origin_region, certifying_body, verified_date` |
| `custom` | مخصص | أخرى | `subject, type, details` |
| `attestation` | إثبات عام | أخرى | `subject, claim, evidence` |


## OpenAPI

````yaml ar/mint-openapi.yaml POST /v1/attestations/mint
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/attestations/mint:
    post:
      tags:
        - Attestations
      summary: صك إثبات
      description: |
        صك إثبات موقع باستخدام مخطط وهياكل منظمة، أو حمولة مشفرة.
        احتفظ بنفس Idempotency-Key والنص عند إعادة محاولة هذا الطلب.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: احتفظ بنفس القيمة ونص الطلب عند إعادة محاولة سك واحد.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: >-
                اختر سجل منظم لتحديد نوع السجل وإدخال المطالبات، أو حمولة مشفرة
                لتوقيع البايتات الموجودة. لا تجمع أبدًا بين تنسيقي الإدخال.
              oneOf:
                - title: Structured record
                  type: object
                  required:
                    - issuer_id
                    - kid
                    - alg
                    - schema
                    - claims
                  properties:
                    alg:
                      $ref: '#/components/schemas/SigningAlgorithm'
                      description: يجب أن يتطابق مع مفتاح توقيع جهة الإصدار المحدد.
                    attestation_id:
                      type: string
                    content_type:
                      type: string
                      description: >-
                        نوع MIME للبايتات الأصلية، مثل application/json أو
                        application/pdf أو image/png. يتطلب إدخال
                        المخطط/المطالبات المنظمة application/json.
                      example: application/json
                    document_hash:
                      type: string
                      description: >-
                        تجزئة مستند SHA-256 سداسية عشرية اختيارية. تأخذ
                        claims.document.sha256 المضمنة الأسبقية؛ وإلا يتم
                        استخدام هذا الحقل، ثم تجزئة الحمولة المفككة.
                    issuer_id:
                      type: string
                      description: معرف UUID للمصدر الذي ينشئ الشهادة
                      format: uuid
                      example: 550e8400-e29b-41d4-a716-446655440000
                    kid:
                      type: string
                      description: معرف المفتاح لمفتاح التوقيع
                      example: es256-key-1
                    pack_id:
                      type: string
                      description: >-
                        معرف UUID لحزمة التحقق من مساحة العمل الاختيارية. استخدم
                        قائمة حزم التحقق بنفس مفتاح API لتحديد حزمة نشطة موجودة؛
                        احذفها لسجل مستقل.
                      format: uuid
                    expires_at_unix:
                      type: integer
                      format: int64
                      minimum: 1
                      maximum: 253402300799
                      description: >-
                        طابع زمني Unix مستقبلي اختياري بالثواني لإدخال
                        المخطط/المطالبات المهيكلة. يتم تضمينه في حمولة JSON
                        الموقعة. بالنسبة لإدخال payload_b64url، احذف حقل الطلب
                        هذا وقم بتضمين expires_at_unix في جذر حمولة JSON الدقيقة
                        بدلاً من ذلك. لا يمكن تغيير تاريخ انتهاء الصلاحية في
                        مكانه.
                    recipient_email:
                      type: string
                      description: >-
                        مستلم اختياري للإشعار غير المتزامن بعد السك. لا يؤكد رد
                        السك الناجح التسليم.
                      format: email
                    schema:
                      type: string
                      description: >-
                        نوع السجل للإدخال المنظم. قدم المطالبات واحذف
                        payload_b64url. هذا التصنيف لا يتحقق بشكل مستقل من صحة
                        المطالبات.
                      enum:
                        - verifiable-id
                        - passport
                        - drivers-license
                        - government-id
                        - self-sovereign-id
                        - employment-verification
                        - professional-role
                        - membership-card
                        - professional-certification
                        - license
                        - accreditation
                        - degree
                        - completion-cert
                        - course-credit
                        - transcript
                        - micro-credential
                        - training-completion
                        - medical-license
                        - dea-registration
                        - board-certification
                        - health-credential
                        - vaccination-record
                        - aml-kyc
                        - security-clearance
                        - sam-gov
                        - jurisdiction-approval
                        - attestation-of-will
                        - bank-verification
                        - credit-attestation
                        - income-verification
                        - skill-badge
                        - competency
                        - industry-cert
                        - product-authenticity
                        - chain-of-custody
                        - origin-verification
                        - custom
                        - attestation
                      example: verifiable-id
                    claims:
                      type: object
                      additionalProperties: true
                      description: >-
                        حقول سجل منظمة. مطلوبة مع المخطط؛ لا يمكن دمجها مع
                        payload_b64url.
                      example:
                        full_name: Example recipient
                        employee_id: QA-001
                - title: Encoded payload
                  type: object
                  required:
                    - issuer_id
                    - kid
                    - alg
                    - payload_b64url
                  properties:
                    alg:
                      $ref: '#/components/schemas/SigningAlgorithm'
                      description: يجب أن يتطابق مع مفتاح توقيع جهة الإصدار المحدد.
                    attestation_id:
                      type: string
                    content_type:
                      type: string
                      description: >-
                        نوع MIME للبايتات الأصلية، مثل application/json أو
                        application/pdf أو image/png. يتطلب إدخال
                        المخطط/المطالبات المنظمة application/json.
                      example: application/json
                    document_hash:
                      type: string
                      description: >-
                        تجزئة مستند SHA-256 سداسية عشرية اختيارية. تأخذ
                        claims.document.sha256 المضمنة الأسبقية؛ وإلا يتم
                        استخدام هذا الحقل، ثم تجزئة الحمولة المفككة.
                    issuer_id:
                      type: string
                      description: معرف UUID للمصدر الذي ينشئ الشهادة
                      format: uuid
                      example: 550e8400-e29b-41d4-a716-446655440000
                    kid:
                      type: string
                      description: معرف المفتاح لمفتاح التوقيع
                      example: es256-key-1
                    pack_id:
                      type: string
                      description: >-
                        معرف UUID لحزمة التحقق من مساحة العمل الاختيارية. استخدم
                        قائمة حزم التحقق بنفس مفتاح API لتحديد حزمة نشطة موجودة؛
                        احذفها لسجل مستقل.
                      format: uuid
                    recipient_email:
                      type: string
                      description: >-
                        مستلم اختياري للإشعار غير المتزامن بعد السك. لا يؤكد رد
                        السك الناجح التسليم.
                      format: email
                    payload_b64url:
                      type: string
                      description: >-
                        base64url غير محشو للبايتات الدقيقة المراد توقيعها.
                        استخدم هذا أو المخطط بالإضافة إلى المطالبات.
      responses:
        '201':
          description: تم سك الإشهاد
          content:
            application/json:
              schema:
                type: object
                properties:
                  attestation_id:
                    type: string
                    format: uuid
                  issuer_id:
                    type: string
                    format: uuid
                  version:
                    type: string
                  status:
                    type: string
                  expires_at_unix:
                    type: integer
                    format: int64
                    nullable: true
                    description: >-
                      تاريخ انتهاء الصلاحية الموقع المسجل بثواني يونكس؛ يعني
                      null عدم تسجيل تاريخ انتهاء صلاحية. لا يتم تعيين تاريخ
                      انتهاء صلاحية جديد للسجلات القديمة.
                  issued_at_unix:
                    type: integer
                    format: int64
                  payload_hash:
                    type: string
                  signature:
                    type: object
                    properties:
                      alg:
                        type: string
                      kid:
                        type: string
                      value:
                        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
                  governance:
                    type: object
                    nullable: true
        '400':
          description: طلب غير صالح
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: الحمولة كبيرة جداً
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                code: PAYLOAD_TOO_LARGE
                message: Request body exceeds maximum size of 1MB
                http_status: 413
        '429':
          description: تجاوز حد المعدل أو الحصة
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Rate limit exceeded
                http_status: 429
                retry_after_ms: 60000
      security:
        - APIKey: []
components:
  schemas:
    SigningAlgorithm:
      type: string
      enum:
        - Ed25519
        - ES256
        - ES384
        - ES512
        - RS256
        - RS384
        - RS512
        - PS256
        - PS384
        - PS512
      description: خوارزمية التوقيع لتوليد المفتاح
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: رمز خطأ قابل للقراءة آليًا
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: رسالة خطأ مقروءة بشريًا
        http_status:
          type: integer
          description: رمز حالة HTTP
        retry_after_ms:
          type: integer
          description: عدد المللي ثانية للانتظار قبل إعادة المحاولة (لحدود المعدل)
        details:
          type: object
          description: سياق خطأ إضافي
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  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.