# المحافظ الثابتة

> عناوين إيداع دائمة مرتبطة بطلب أو مستخدم معيّن، مثالية للمدفوعات المتكررة وطويلة الأمد.

المحافظ الثابتة هي عناوين دائمة لاستلام مدفوعات العملات المشفرة. ترتبط بـ `order_id` معيّن وتكون فريدة بمجموع `project_id + order_id + currency + network`.

استخدم المحافظ الثابتة من أجل:

- الإيداعات المتكررة من نفس المستخدم
- عناوين دفع طويلة الأمد تُعرض على الملف الشخصي للمستخدم
- تدفقات إيداع كبيرة الحجم حيث تريد عنوانًا ثابتًا لكل مستخدم

## إنشاء محفظة ثابتة

`POST /v1/static-wallet`

### معاملات الطلب

| الحقل | النوع | مطلوب | الوصف |
|-------|------|----------|-------------|
| `currency` | string | نعم | العملة المشفرة (USDT، BTC، ETH، إلخ.) |
| `network` | string | نعم | رمز الشبكة |
| `order_id` | string | نعم | معرّف الطلب/المستخدم الخاص بك (حتى 255 حرفًا) |
| `label` | string | لا | تسمية المحفظة (حتى 255 حرفًا) |
| `url_callback` | string | نعم | عنوان URL لإشعارات webhook |
| `invite_code` | string | لا | رمز المُحيل |

### مثال على الطلب

```json
{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}
```

### مثال على الاستجابة

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

## معلومات المحفظة

احصل على معلومات المحفظة الثابتة بواسطة `uuid` أو `address`.

`POST /v1/static-wallet/info`

### معاملات الطلب

| الحقل | النوع | مطلوب | الوصف |
|-------|------|----------|-------------|
| `uuid` | string | نعم* | معرّف المحفظة الثابتة UUID |
| `address` | string | نعم* | عنوان البلوكتشين للمحفظة |

> **INFO:** يجب توفير واحد على الأقل من `uuid` أو `address`.

### مثال على الاستجابة

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

- `total_received` — مجموع جميع الإيداعات المستلمة بهذه المحفظة، بـ `currency`.
- `transactions_count` — عدد الإيداعات المستلمة حتى الآن.
- `qr` — رمز QR مُرمَّز بـ Base64 (data URI) لعنوان الإيداع (موجود دائمًا للمحافظ الثابتة، حيث يتم تعيين العنوان عند الإنشاء).

## قائمة المحافظ

`POST /v1/static-wallet/list`

### معاملات الطلب

| الحقل | النوع | مطلوب | الوصف |
|-------|------|----------|-------------|
| `status` | string | لا | تصفية حسب الحالة (`active`، `inactive`) |
| `currency` | string | لا | تصفية حسب العملة |
| `network` | string | لا | تصفية حسب الشبكة |
| `order_id` | string | لا | تصفية حسب order_id |
| `page` | int | لا | رقم الصفحة (الافتراضي: 1) |
| `per_page` | int | لا | عدد العناصر لكل صفحة (الافتراضي: 20، الحد الأقصى: 100) |

### مثال على الاستجابة

```json
{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}
```

## تفعيل / تعطيل المحفظة

تبديل ما إذا كانت المحفظة الثابتة تقبل مدفوعات جديدة.

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### الطلب

تأخذ كلتا نقطتي النهاية معاملًا واحدًا:

```json
{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}
```

### مثال على الاستجابة

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}
```

بالنسبة لـ `enable`، تكون `status` هي `"active"` وتكون `message` هي `"Static wallet enabled successfully"`.

## معاملات المحفظة

احصل على قائمة بجميع الإيداعات المستلمة بمحفظة ثابتة.

`POST /v1/static-wallet/transactions`

### معاملات الطلب

| الحقل | النوع | مطلوب | الوصف |
|-------|------|----------|-------------|
| `uuid` | string | نعم | معرّف المحفظة الثابتة UUID |
| `date_from` | date | لا | تاريخ البداية (YYYY-MM-DD) |
| `date_to` | date | لا | تاريخ النهاية (YYYY-MM-DD) |
| `page` | int | لا | رقم الصفحة (الافتراضي: 1) |
| `per_page` | int | لا | عدد العناصر لكل صفحة (الافتراضي: 15، الحد الأقصى: 5000) |

### مثال على الاستجابة

```json
{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}
```

- `fee_amount` — رسوم المنصة المخصومة من هذا الإيداع، بـ `currency`.
- `net_amount` — المبلغ المُضاف إلى رصيد التاجر بعد الرسوم.

## webhooks المحافظ الثابتة

عند استلام دفعة على محفظة ثابتة، يرسل النظام webhook إلى `url_callback`.

> **WARNING:** يختلف تنسيق webhook للمحافظ الثابتة عن webhooks المدفوعات العادية. الجدير بالذكر أن webhooks المحافظ الثابتة تتضمن حقل `merchant_amount` الذي يجب استخدامه للإيداع.

### محتوى webhook

```json
{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}
```

> **INFO:** webhooks المحافظ الثابتة **لا تتضمن** `url` أو `expires_at` (لأن العنوان دائم، وليس جلسة). لكنها **تتضمن** `exchange_rate` و`created_at`.

### مرجع الحقول

| الحقل | النوع | الوصف |
|-------|------|-------------|
| `uuid` | string | معرّف المعاملة (الفاتورة) UUID لهذا الإيداع |
| `order_id` | string | `order_id` الخاص بمحفظتك الثابتة |
| `amount` | decimal (8 dp) | مبلغ العملة المشفرة المستلم |
| `currency` | string | العملة المشفرة المستلمة (تطابق `currency` للمحفظة) |
| `amount_usd` | decimal (8 dp) | القيمة بالدولار الأمريكي وقت الاستلام |
| `exchange_rate` | decimal | سعر صرف العملة المشفرة / الدولار المستخدم |
| `payer_currency` | string | نفس `currency` للمحافظ الثابتة |
| `payer_amount` | decimal (8 dp) | نفس `amount` للمحافظ الثابتة |
| `network` | string | شبكة البلوكتشين |
| `address` | string | عنوان المحفظة الثابتة |
| `payment_status` | string | دائمًا `paid` للمحافظ الثابتة |
| `txid` | string | هاش معاملة البلوكتشين |
| `payment_amount` | decimal (8 dp) | نفس `amount` |
| `merchant_amount` | decimal (18 dp) | **المبلغ بعد خصم الرسوم** — استخدمه للإيداع |
| `created_at` | string (ISO 8601) | متى تم استلام الإيداع |
| `sign` | string (hex) | توقيع HMAC-SHA256 للمحتوى |

## أفضل الممارسات

- **`order_id` فريد** — استخدم `order_id` فريدًا لكل مستخدم أو طلب
- **Idempotency** — تحقق من `txid` قبل المعالجة لتجنب الإيداعات المكررة
- **التحقق من التوقيعات** — تحقق دائمًا من توقيع `sign` قبل إيداع الأموال
- **استخدم `merchant_amount`** — أضف للمستخدمين على أساس `merchant_amount`، وليس `payment_amount`