# Statik Cüzdanlar

> Belirli bir siparişe veya kullanıcıya bağlı kalıcı yatırma adresleri; tekrarlayan ve uzun vadeli ödemeler için ideal.

Statik cüzdanlar, kripto para ödemeleri almak için kalıcı adreslerdir. Belirli bir `order_id`'ye bağlıdırlar ve `project_id + order_id + currency + network` kombinasyonuyla benzersizdirler.

Statik cüzdanları şunlar için kullanın:

- Aynı kullanıcıdan tekrarlayan yatırımlar
- Bir kullanıcı profilinde gösterilen uzun vadeli ödeme adresleri
- Kullanıcı başına stabil bir adres istediğiniz yüksek hacimli yatırım akışları

## Statik cüzdan oluştur

`POST /v1/static-wallet`

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama |
|------|-----|---------|----------|
| `currency` | string | evet | Kripto para (USDT, BTC, ETH vb.) |
| `network` | string | evet | Ağ kodu |
| `order_id` | string | evet | Sipariş/kullanıcı ID'niz (en fazla 255 karakter) |
| `label` | string | hayır | Cüzdan etiketi (en fazla 255 karakter) |
| `url_callback` | string | evet | Webhook bildirimleri için URL |
| `invite_code` | string | hayır | Yönlendiren kodu |

### İstek örneği

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

### Yanıt örneği

```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..."
  }
}
```

## Cüzdan bilgisi

Statik cüzdan bilgisini `uuid` veya `address` ile alın.

`POST /v1/static-wallet/info`

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama |
|------|-----|---------|----------|
| `uuid` | string | evet* | Statik cüzdan UUID'si |
| `address` | string | evet* | Blockchain cüzdan adresi |

> **INFO:** `uuid` veya `address`'ten en az biri gereklidir.

### Yanıt örneği

```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` — bu cüzdan tarafından alınan tüm yatırımların toplamı, `currency` cinsinden.
- `transactions_count` — şu ana kadar alınan yatırım sayısı.
- `qr` — yatırma adresinin Base64 ile encode edilmiş QR data URI'si (statik cüzdanlar için her zaman mevcuttur, adres oluşturma sırasında atanır).

## Cüzdan listesi

`POST /v1/static-wallet/list`

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama |
|------|-----|---------|----------|
| `status` | string | hayır | Duruma göre filtre (`active`, `inactive`) |
| `currency` | string | hayır | Para birimine göre filtre |
| `network` | string | hayır | Ağa göre filtre |
| `order_id` | string | hayır | order_id'ye göre filtre |
| `page` | int | hayır | Sayfa numarası (varsayılan: 1) |
| `per_page` | int | hayır | Sayfa başına öğe (varsayılan: 20, en fazla: 100) |

### Yanıt örneği

```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
    }
  }
}
```

## Cüzdanı etkinleştir / devre dışı bırak

Bir statik cüzdanın yeni ödemeleri kabul edip etmeyeceğini değiştirin.

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### İstek

Her iki endpoint de tek bir parametre alır:

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

### Yanıt örneği

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

`enable` için `status` `"active"`'tir ve `message` `"Static wallet enabled successfully"` olarak okunur.

## Cüzdan işlemleri

Bir statik cüzdan tarafından alınan tüm yatırımların listesini alın.

`POST /v1/static-wallet/transactions`

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama |
|------|-----|---------|----------|
| `uuid` | string | evet | Statik cüzdan UUID'si |
| `date_from` | date | hayır | Başlangıç tarihi (YYYY-MM-DD) |
| `date_to` | date | hayır | Bitiş tarihi (YYYY-MM-DD) |
| `page` | int | hayır | Sayfa numarası (varsayılan: 1) |
| `per_page` | int | hayır | Sayfa başına öğe (varsayılan: 15, en fazla: 5000) |

### Yanıt örneği

```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` — bu yatırımdan düşülen platform ücreti, `currency` cinsinden.
- `net_amount` — ücret düşüldükten sonra merchant bakiyesine yansıtılan tutar.

## Statik cüzdan webhook'ları

Bir statik cüzdana ödeme alındığında, sistem `url_callback` adresine bir webhook gönderir.

> **WARNING:** Statik cüzdanlar için webhook formatı, normal ödeme webhook'larından farklıdır. Özellikle, statik cüzdan webhook'ları alacaklandırma için kullanmanız gereken bir `merchant_amount` alanı içerir.

### Webhook payload'u

```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",
  "tx_explorer_url": "https://tronscan.org/#/transaction/8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}
```

> **INFO:** Statik cüzdan webhook'ları `url` veya `expires_at` **içermez** (çünkü adres kalıcıdır, bir oturum değil). `exchange_rate` ve `created_at` **içerir**.

### Alan referansı

| Alan | Tip | Açıklama |
|------|-----|----------|
| `uuid` | string | Bu yatırım için işlem (fatura) UUID'si |
| `order_id` | string | Statik cüzdanınızın `order_id`'si |
| `amount` | decimal (8 dp) | Alınan kripto tutarı |
| `currency` | string | Alınan kripto (cüzdanın `currency`'si ile eşleşir) |
| `amount_usd` | decimal (8 dp) | Alındığı andaki USD değeri |
| `exchange_rate` | decimal | Kullanılan kripto / USD kuru |
| `payer_currency` | string | Statik cüzdanlarda `currency` ile aynı |
| `payer_amount` | decimal (8 dp) | Statik cüzdanlarda `amount` ile aynı |
| `network` | string | Blockchain ağı |
| `address` | string | Statik cüzdan adresi |
| `payment_status` | string | Mevcut depozito durumu; genellikle `paid`, ancak AML kontrol? otomatik kredilenmemesi gereken `aml_lock` ?retebilir |
| `txid` | string | Blockchain işlem hash'i |
| `tx_explorer_url` | string \| null | Blockchain gezginindeki işlem URL'si. `txid` yoksa veya transfer dahili P2P ise `null` olur. |
| `payment_amount` | decimal (8 dp) | `amount` ile aynı |
| `merchant_amount` | decimal (18 dp) | **Ücret düşümünden sonraki tutar** — alacaklandırma için bunu kullanın |
| `created_at` | string (ISO 8601) | Yatırımın alındığı zaman |
| `sign` | string (hex) | Payload'un HMAC-SHA256 imzası |

## En iyi uygulamalar

- **Benzersiz `order_id`** — Her kullanıcı veya sipariş için benzersiz bir `order_id` kullanın
- **Idempotency** — Yinelenen alacaklandırmaları önlemek için işlemden önce `txid`'yi kontrol edin
- **İmzaları doğrulayın** — Fonları alacaklandırmadan önce HER ZAMAN `sign` imzasını doğrulayın
- **`merchant_amount` kullanın** — Kullanıcıları `payment_amount`'a değil, `merchant_amount`'a göre alacaklandırın

## Yaşam döngüsü ve idempotency

Bir static wallet yeniden kullanılabilir bir depozit kimliğidir, invoice değil. Beklenen bir miktarı ve son kullanma tarihi yok. Bir adres, ömrü boyunca herhangi sayıda mevduat işlemi gerçekleştirebilir.

Aynı merchant projesi için oluşturulma idempotent olarak kullanılır: `order_id`, `currency` ve `network`: mevcut cüzdan geri döner. O tuple'ı sabit tutun ve geri dönen cüzdanı `uuid`'da tutun; Aynı müşteri depozito ekranını her açtığında yeni bir `order_id` kullanmayın.

Yatırma idempotency cüzdandan idempotency]'dan farklıdır:

- `order_id` yeniden kullanılabilir cüzdan/müşteri eşlemesini belirler;
- cüzdan `uuid` kalıcı cüzdan kaydını tanımlar;
- webhook `uuid` tespit edilen bir depozito işlemini tespit eder;
- `txid` zincir içi transferi tanımlar ve kredi için birincil deduplication anahtarıdır.

İşlenen zincir/ağ/txid kimliği için veritabanı benzersizliği kısıtlaması kullanın ve müşterinin iç bakiyesini krediye alan aynı işlemde talep edin.

## Semantik etkinleştir ve devre dışı bırak

Bir cüzdanı devre dışı bırakmak, uygulamanın onu aktif bir depozito hedefi olarak işlemesini engeller; Adresi veya geçmişini silmez ve bir kullanıcı tarafından zaten gönderilen blok zinciri transferini durduramaz.

> **DANGER:** Kullanıcılara, aktif olmayan bir adrese gönderilen paraların otomatik olarak geri döndüğünü asla söylemeyin. Blokzincir transferleri geri döndürülemezdir. Adresi arayüzünden kaldırdıktan sonra devre dışı bırakın ve geç depozitolar için operasyonel bir kurtarma prosedürünü koruyun.

Yeniden etkinleştirmek aynı cüzdan kimliğini ve adresini korur. Sadece etiketi değiştirmek için bir yedek oluşturma; Etiketler settlement tanımlayıcı değildir.

## Static wallet Uç durumlar

| Durum | Doğru yol tutuşu |
|-----------|------------------|
| Tekrarlayıcı oluşturma talebi | Geri dönen mevcut cüzdanı kabul edin ve yeni bir adres beklemek yerine kalıcı tuple'ını doğrulayın. |
| Bir adrese birden fazla depozito | Her işlem için ayrı bir yerel depozito satırı oluşturun `uuid`/`txid`; Cüzdanın kendisini asla "ödenmiş" olarak işaretleme. |
| Kopya webhook | Zaten işlenmiş txid bulununca HTTP 200 döndür; tekrar kredi yapma. |
| Onay gecikmesi veya zincir yeniden gözden geçirme | idempotent işlemlerine devam et ve `/v1/static-wallet/transactions` üzerinden mutabakat yap. |
| auto-convert minimumunun altında para yatırma | Tamamlanmış `convert` bloğu olmadan kaynak döviz kredisi bekle. |
| Auto-convert başarılı | Kaynak ödeme değerlerini ve hedef `convert` sonucunu ayrı ayrı sakla. |
| Yanlış token veya yanlış ağ | Kredi uydurma. Kanıtı kaydet ve destek/geri kazanım ekibine bildir çünkü geri kazanılabilirlik zincire özgüdür. |
| Memo/etiket tabanlı zincir | Platform tarafından döndürülen her hedef alanı göster ve doğrula; bir adres tek başına yeterli olmayabilir, memo gerekli olduğunda. |
| AML kilidi | Yetkili durum uyumluluk süreciyle serbest bırakılana kadar son kullanıcıya kredi verme. |
| Adres gösterildikten sonra cüzdan devre dışı | UI'dan hemen kaldır, ancak geç transferler için operasyonel uyarıları izlemeye devam et. |

## Reconciliation modeli

`/v1/static-wallet/transactions` üzerinden sayfa sayfa geçen, txid ile yatırmaları güncelleyen ve bunların `merchant_amount`, durumu ve isteğe bağlı dönüşüm sonucunu iç defterinle karşılaştıran periyodik bir iş çalıştır. Webhook teslimi reconciliation'yi hızlı yapmalı, ama reconciliation tamamlayıcı olmalı.