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

# الإيصالات

> إيصالات موقعة تشفيرياً ومرتبطة بسجل الشفافية لأي حدث

## ما هي الإيصالات؟

الإيصالات هي سجلات موقعة وغير قابلة للتغيير لأحداث منفصلة - مدفوعات، حوادث أمنية، فحوصات امتثال، عمليات تسليم، والمزيد. على عكس السجلات أو مسارات التدقيق، كل إيصال هو:

* **موقعة تشفيريًا** بمفتاح المصدر الخاص بك (Ed25519 أو ES256)
* **مرتكز في سجل الشفافية** مع إثبات تضمين ميركل
* **قابلة للتحقق دون اتصال** عبر تصدير حزمة الإثبات
* **متطابق** - ينتج نفس الحدث دائمًا نفس الإيصال

## أنواع الإيصالات

تتوفر أنواع الإيصالات المعرفة بالمنصة لجميع المستأجرين. يحتوي كل نوع على مخطط JSON يتم التحقق من صحة حقل `payload` مقابله قبل التوقيع.

| النوع | حالة الاستخدام |
| - | - |
| `payment_receipt` | المدفوعات، الفواتير، المبالغ المستردة |
| `security_event_receipt` | أحداث المصادقة، تدوير المفاتيح، الحالات الشاذة |
| `delivery_receipt` | تسليم المستندات، الإشعارات |
| `compliance_receipt` | فحوصات KYC/AML، أدلة تنظيمية |
| `custom_receipt` | أي حدث آخر بنمط مفتوح |

### اكتشاف الأنواع المتاحة

استدعِ [`GET /v1/receipt-types`](https://docs.truthlocks.com/ar/api-reference/receipts/list-types) لسرد كل نوع يمكن للمستأجر الخاص بك استخدامه، أو [`GET /v1/receipt-types/{name}`](https://docs.truthlocks.com/ar/api-reference/receipts/get-type) لجلب نوع واحد وفحص مخطط JSON الخاص به.

```typescript JavaScript theme={null}
const types = await client.receipts.listTypes();

// Inspect a specific type's schema
const paymentType = await client.receipts.getType("payment_receipt");
console.log(paymentType.schema.required); // ["amount", "currency", "provider", ...]
```

```go Go theme={null}
types, _ := client.Receipts.ListTypes(ctx)
for _, t := range types.Items {
    fmt.Println(t.Name, t.Version)
}

// Pin a specific version
rt, _ := client.Receipts.GetType(ctx, "payment_receipt@1.0.0")
```

## سك إيصال

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

**1. اختر نوع الإيصال**

استدعِ `GET /v1/receipt-types` لسرد الأنواع المتاحة وفحص المخطط للحقول المطلوبة.

**2. بناء حمولتك**

قم بإنشاء كائن `payload` المطابق للحقول المطلوبة لنوع الإيصال الخاص بك. لـ `payment_receipt`، تحتاج إلى `amount`، و`currency`، و`provider`، و`provider_reference`، و`subject`.

**3. الإنشاء عبر واجهة برمجة التطبيقات**

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts \
  -H "X-API-Key: tl_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "kid": "ed-key-2026",
    "alg": "Ed25519",
    "receipt_type": "payment_receipt",
    "subject": "customer@example.com",
    "payload": {
      "amount": 5000,
      "currency": "USD",
      "provider": "stripe",
      "provider_reference": "ch_3Px..."
    }
  }'
```

**4. تخزين receipt\_id**

يتضمن الرد `receipt_id` و `log.leaf_index`. قم بتخزين كليهما للتحقق المستقبلي.

## أمثلة SDK

```typescript JavaScript theme={null}
const receipt = await client.receipts.mint({
  issuer_id: 'your-issuer-id',
  kid: 'ed-key-2026',
  alg: 'Ed25519',
  receipt_type: 'payment_receipt',
  subject: 'customer@example.com',
  payload: {
    amount: 5000,
    currency: 'USD',
    provider: 'stripe',
    provider_reference: 'ch_3Px...'
  }
});

console.log(receipt.receipt_id, receipt.log.leaf_index);
```

```go Go theme={null}
receipt, err := client.Receipts.Mint(ctx, &truthlock.MintReceiptRequest{
    IssuerID:    "your-issuer-id",
    KID:         "ed-key-2026",
    Alg:         "Ed25519",
    ReceiptType: "payment_receipt",
    Subject:     "customer@example.com",
    Payload: map[string]interface{}{
        "amount":             5000,
        "currency":           "USD",
        "provider":           "stripe",
        "provider_reference": "ch_3Px...",
    },
})
```

### إيصالات القائمة

```typescript JavaScript theme={null}
const receipts = await client.receipts.list({
  receipt_type: "payment_receipt",
  status: "active",
  limit: 20,
});
```

```go Go theme={null}
receipts, err := client.Receipts.List(ctx, &truthlock.ListReceiptsFilter{
    ReceiptType: "payment_receipt",
    Status:      "active",
    Limit:       20,
})
```

### استرداد إيصال

```typescript JavaScript theme={null}
const receipt = await client.receipts.get("receipt-uuid");
```

```go Go theme={null}
receipt, err := client.Receipts.Get(ctx, "receipt-uuid")
```

## أحداث خطاف الويب (Webhook)

اشترك في أحداث الإيصالات عن طريق تكوين نقطة نهاية webhook في وحدة التحكم:

| الحدث | يتم تشغيله عندما |
| - | - |
| `receipt.created` | تم إنشاء إيصال بنجاح |
| `receipt.revoked` | تم إلغاء إيصال |

## إلغاء إيصال

الإلغاء دائم ويتم تسجيله في سجل الشفافية. تظل الإيصالات ذات الحالة `revoked` قابلة للاستعلام ويتم تضمين طابعها الزمني للإلغاء في حزم الإثبات. يمكنك تضمين `reason` اختياري لتسجيل سبب إلغاء الإيصال.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts/{id}/revoke \
  -H "X-API-Key: tl_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Duplicate charge refunded"}'
```

```typescript JavaScript theme={null}
await client.receipts.revoke("receipt-uuid", {
  reason: "Duplicate charge refunded",
});
```

```go Go theme={null}
_, err := client.Receipts.Revoke(ctx, "receipt-uuid", &truthlock.RevokeReceiptRequest{
    Reason: "Duplicate charge refunded",
})
```

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

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

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts/verify \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "receipt_id": "receipt-uuid" }'
```

```typescript JavaScript theme={null}
const result = await client.receipts.verify("receipt-uuid");

if (result.verdict === "VALID") {
  console.log("Receipt is valid");
}
```

```go Go theme={null}
result, err := client.Receipts.Verify(ctx, "receipt-uuid")
if result.Verdict == "VALID" {
    fmt.Println("Receipt is valid")
}
```

```python Python theme={null}
result = client.receipts.verify("receipt-uuid")

if result["verdict"] == "VALID":
    print("Receipt is valid")
```

### الأحكام

| الحكم | المعنى |
| - | - |
| `VALID` | التوقيع صالح، المفتاح نشط، الإيصال غير ملغى |
| `REVOKED` | تم إلغاء الإيصال صراحةً |
| `INVALID_SIGNATURE` | فشل التحقق من التوقيع التشفيري |
| `KEY_COMPROMISED` | تم وضع علامة على مفتاح التوقيع على أنه مخترق عند الإصدار أو قبله |
| `KEY_INACTIVE` | مفتاح التوقيع لم يعد نشطًا |
| `NOT_FOUND` | لم يتم العثور على إيصال لهذا المستأجر |

## حزم الإثبات

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

بعد تنزيل حزمة إثبات، يمكنك التحقق من الإيصال دون إجراء أي مكالمات API إضافية.

```typescript JavaScript theme={null}
const bundle = await client.receipts.getProofBundle("receipt-uuid");

console.log(bundle.bundle_version);          // "receipt-v1"
console.log(bundle.transparency_log);        // Merkle inclusion proof
```

```go Go theme={null}
bundle, err := client.Receipts.GetProofBundle(ctx, "receipt-uuid")
```

```python Python theme={null}
bundle = client.receipts.get_proof_bundle("receipt-uuid")
```

راجع [مرجع API لحزمة الإثبات](https://docs.truthlocks.com/ar/api-reference/receipts/proof-bundle.md) للحصول على هيكل الحزمة الكامل.

> [!TIP]
>
> يمكنك تنزيل حزم الإثبات مباشرة من وحدة التحكم. افتح صفحة تفاصيل الإيصال وانقر على **تنزيل حزمة الإثبات**. راجع [التنزيل في وحدة التحكم](#downloading-a-proof-bundle).

## البحث عن الإيصالات

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

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/receipts/search \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "q": "stripe",
    "receipt_type": "payment_receipt",
    "from_date": "2026-01-01T00:00:00Z",
    "limit": 20
  }'
```

```typescript JavaScript theme={null}
const results = await client.receipts.search({
  q: "stripe",
  receipt_type: "payment_receipt",
  from_date: "2026-01-01T00:00:00Z",
  limit: 20,
});

for (const r of results.items) {
  console.log(r.receipt_id, r.receipt_type);
}
```

```go Go theme={null}
results, err := client.Receipts.Search(ctx, &truthlock.SearchReceiptsQuery{
    Q:           "stripe",
    ReceiptType: "payment_receipt",
    FromDate:    "2026-01-01T00:00:00Z",
    Limit:       20,
})
```

```python Python theme={null}
results = client.receipts.search(
    q="stripe",
    receipt_type="payment_receipt",
    from_date="2026-01-01T00:00:00Z",
    limit=20,
)
```

### عوامل تصفية البحث

| الحقل | النوع | الوصف |
| - | - | - |
| `q` | string | بحث نصي كامل عبر محتوى الحمولة |
| `receipt_type` | string | التصفية حسب اسم النوع |
| `status` | string | `active`، `revoked`، `superseded`، أو `redacted` |
| `issuer_id` | UUID | التصفية حسب المُصدر |
| `from_date` | RFC 3339 | بداية النطاق الزمني |
| `to_date` | RFC 3339 | نهاية النطاق الزمني |
| `index_key` | string | اسم حقل الحمولة المفهرس |
| `index_value` | string | القيمة المراد مطابقتها لـ `index_key` |
| `limit` | integer | الحد الأقصى للنتائج (1-100، الافتراضي 20) |
| `offset` | integer | إزاحة ترقيم الصفحات |

> [!TIP]
>
> يمكنك أيضًا البحث عن الإيصالات من وحدة التحكم دون كتابة تعليمات برمجية. افتح **الإيصالات** في الشريط الجانبي واستخدم شريط البحث وعناصر التحكم في التصفية. راجع [البحث في وحدة التحكم](#searching-receipts-1).

## تصدير الإيصالات

وضع تصدير مجمع غير متزامن للإيصالات بتنسيق JSON أو CSV في قائمة الانتظار. تعود واجهة برمجة التطبيقات فورًا بمعرف مهمة. استعلم عن نقطة نهاية حالة التصدير حتى يصبح `status` `complete`، ثم قم بالتنزيل من عنوان URL الموقّع مسبقًا.

```typescript JavaScript theme={null}
// Start an export
const job = await client.receipts.export({
  format: "json",
  filters: {
    receipt_type: "payment_receipt",
    status: "active",
  },
});

console.log(job.id, job.status); // "pending"

// Poll for completion
const completed = await client.receipts.getExport(job.id);
if (completed.status === "complete") {
  console.log("Download:", completed.download_url);
}

// List all export jobs
const exports = await client.receipts.listExports();
```

```go Go theme={null}
job, err := client.Receipts.Export(ctx, &truthlock.CreateExportRequest{
    Format: "json",
    Filters: map[string]interface{}{
        "receipt_type": "payment_receipt",
        "status":       "active",
    },
})

// Poll for completion
completed, err := client.Receipts.GetExport(ctx, job.ID)
```

```python Python theme={null}
job = client.receipts.export(
    format="json",
    filters={"receipt_type": "payment_receipt", "status": "active"},
)

# Poll for completion
completed = client.receipts.get_export(job["id"])
if completed["status"] == "complete":
    print("Download:", completed["download_url"])
```

### قيم حالة التصدير

| الحالة | المعنى |
| - | - |
| `pending` | في قائمة الانتظار، لم يبدأ بعد |
| `running` | سجلات المعالجة |
| `complete` | تم — `download_url` متاح |
| `failed` | خطأ — انظر `error_message` |

> [!TIP]
>
> يمكنك وضع الصادرات في قائمة الانتظار وتتبع تقدمها من وحدة التحكم. افتح **الإيصالات**، وانقر على **تصدير**، واختر CSV أو JSON. يتتبع شريط الحالة المهمة حتى يصبح التنزيل جاهزًا. راجع [التصدير في وحدة التحكم](#exporting-receipts-1).

## تنقيح الإيصالات

يزيل التنقيح معلومات التعريف الشخصية (PII) بشكل دائم من حمولة الإيصال مع الحفاظ على الإثبات التشفيري. يظل توقيع الإيصال، وإدخال سجل الشفافية، وإثبات تضمين Merkle سليمًا - يتم استبدال `payload_json` فقط بعلامة تنقيح.

استخدم هذا لطلبات حق المسح بموجب اللائحة العامة لحماية البيانات (GDPR) على الإيصالات التي تحتوي على بيانات شخصية.

```typescript JavaScript theme={null}
await client.receipts.redact("receipt-uuid");
```

```go Go theme={null}
_, err := client.Receipts.Redact(ctx, "receipt-uuid")
```

```python Python theme={null}
client.receipts.redact("receipt-uuid")
```

> [!WARNING]
>
> التنقيح دائم. لا يمكن استعادة الحمولة الأصلية. يظل الإثبات التشفيري صالحًا لأغراض التدقيق.

بعد التنقيح:

* `status` يتغير إلى `redacted`
* `payload_json` يتم استبداله بـ `{"redacted": true, "redacted_by": "tenant_request"}`
* يتم تثبيت حدث `RECEIPT_REDACT` في سجل الشفافية
* يتم الاحتفاظ بجميع الحقول الأخرى (التوقيع، إثبات السجل، نوع الإيصال)

## إدارة الإيصالات في وحدة التحكم

يمكنك إدارة دورة حياة الإيصالات الكاملة من وحدة التحكم دون كتابة أي رمز. افتح **الإيصالات** في الشريط الجانبي لوحدة التحكم للوصول إلى الميزات التالية.

### البحث عن الإيصالات

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

### تصدير الإيصالات

انقر فوق **تصدير** من قائمة الإيصالات لجدولة تصدير مجمع كملف CSV أو JSON. يظهر شريط حالة في أعلى الصفحة يتتبع المهمة عبر حالات `pending` و`running` و`complete`. بمجرد انتهاء التصدير، انقر فوق الشريط لتنزيل الملف. يمكنك أيضًا مراقبة مهام التصدير من واجهة برمجة التطبيقات باستخدام `GET /v1/receipt-exports/{id}` — راجع [تصدير الإيصالات](https://docs.truthlocks.com/ar/api-reference/receipts/export.md).

### تنزيل حزمة إثبات

افتح صفحة تفاصيل أي إيصال وانقر على **تنزيل حزمة الإثبات** لحفظ حزمة تحقق مستقلة. تتضمن الحزمة مغلف الإيصال الموقع، وإثبات تضمين Merkle، ولقطة مفتاح المصدر — كل ما يلزم [للتحقق دون اتصال](#proof-bundles).

### إخفاء إيصال

من صفحة تفاصيل أي إيصال نشط، انقر فوق **إخفاء** لإزالة المعلومات الشخصية من الحمولة بشكل دائم. يشرح مربع حوار التأكيد أن الإخفاء لا رجعة فيه قبل المتابعة. الإخفاء متاح فقط للإيصالات ذات حالة `active`. بعد الإخفاء، يتم الاحتفاظ بالإثبات التشفيري وإدخال سجل الشفافية — يتم إزالة محتوى الحمولة فقط. راجع [إخفاء الإيصالات](#redacting-receipts) للحصول على تفاصيل حول ما يتغير.

## سياسة الاستبقاء

يتم تنظيف الإيصالات تلقائيًا بناءً على سياسة الاستبقاء المحددة وقت الإنشاء. يقوم عامل خلفي بمسح الإيصالات منتهية الصلاحية بانتظام.

عيّن `retention_policy` عند سك العملة:

| السياسة | المدة | الوصف |
| - | - | - |
| `standard` | سنتان | افتراضي. مناسب لمعظم إيصالات المعاملات. |
| `extended` | 7 سنوات | لحالات الاستخدام التي تتطلب الاحتفاظ بالبيانات لفترة أطول. |
| `permanent` | أبدًا | لا يتم حذفها تلقائيًا أبدًا. |

يمكن تنقيح الإيصالات التي تقترب من موعد الاحتفاظ بها بدلاً من حذفها إذا كنت بحاجة إلى الحفاظ على الإثبات التشفيري مع إزالة بيانات الحمولة.

## الخطوات التالية

> [card] [مواصفات حزمة الإثبات](https://docs.truthlocks.com/specification/proof-bundle.md)
>
> الهيكل الكامل وخطوات التحقق دون اتصال لحزم الإثبات.

> [card] [مرجع واجهة برمجة تطبيقات الإيصالات](https://docs.truthlocks.com/api-reference/receipts/mint.md)
>
> مرجع API كامل لسك، والبحث، والتصدير، وتنقيح الإيصالات.

> [card] [الويب هوكس](https://docs.truthlocks.com/guides/webhooks.md)
>
> اشترك في أحداث الاستلام ومعالجتها في الوقت الفعلي.

> [card] [سياسات الإصدار](https://docs.truthlocks.com/guides/issuance-policies.md)
>
> فرض سير عمل الموافقات والقيود على سك الإيصالات.


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