Limit Durumu

Bu uçları kim çağırır?Dış API (s2s)

Taban yol: /api/v1/wallet
Kimlik: Ed25519 istek imzası — X-Key-Id, X-Date, X-Nonce, Digest (body varsa), X-Signature. Zaman penceresi ±5 dk, nonce tek kullanımlık, anahtarda IP allow-list olabilir.
Yetki: Anahtarınız cüzdan ürününü ve çağrının gerektirdiği cüzdan iznini taşımalıdır; izni olmayan çağrı 403 WALLET_INSUFFICIENT_SCOPE alır. Uç başına izinler: Anahtar izinleri.
Çapraz yüzey: Aynı okuma merchant panelde de vardır; son kullanıcı kendi limitini portaldan okur. Limit şemalarının tanımı yalnız paneldedir. Bu uç için anahtarınızda bir cüzdan okuma izni (wallet:enduser:read) gerekir.

GET /api/v1/wallet/end-users/{id}/limits

Kullanıcının o anki limit kullanımını döner: hangi tavan uygulanıyor, ne kadarı kullanıldı, ne kadarı kaldı. Limitlerin nasıl tanımlandığı ve nasıl sayıldığı Limitler sayfasındadır; bu sayfa yalnız okuma ucunu anlatır.

Sorgu parametreleri

Parametre	Tip	Kural ve anlamı
`operationType`	string	En fazla 32 karakter; harf, rakam ve `_`. Büyük/küçük harf fark etmez. Verilirse yalnız bu işlem tipini bağlayan sayaçlar döner (aşağıya bakın). Verilmezse şemanızdaki tüm satırlar döner.
`currency`	string	3–8 harf. Gönderilmezse `TRY`.

operationType olarak işlem tipi adlarını gönderirsiniz; örneğin W2W_TRANSFER, W2IBAN_WITHDRAW, WITHDRAW_BANK, PAYMENT_BUY, BILL_PAY, TOPUP_CARD. Şemanızdaki cüzdan toplamı satırını (*) görmek için parametreyi göndermeyin; * bu parametrede kabul edilmez.

Hangi satırlar döner

Satırlar, programınıza atanmış limit şemasından, kullanıcının geçerli KYC seviyesi ve istenen para birimi için seçilir.

operationType olmadan: şemanızda bu seviye ve para birimi için tanımlı her işlem tipinin kendi satırı (bucket: OPERATION_TYPE) ve cüzdan toplamı satırı varsa iki satır daha döner: para çıkışı toplamı (WALLET_TOTAL_OUTFLOW) ve para girişi toplamı (WALLET_TOTAL_INFLOW). Bu iki satırda operationType değeri *'dır.
operationType ile: o tipin kendi satırı (tanımlıysa) ve o tipi bağlayan cüzdan toplamı satırı (tanımlıysa) döner. Bir işlemin geçebilmesi için dönen satırların hepsinde yer olmalıdır.

Para girişi sayılan tipler TOPUP_CARD, TOPUP_TRANSFER, TOPUP_AGENT, TOPUP_REFUND ve REFUND_CREDIT'tir; bunlar WALLET_TOTAL_INFLOW toplamına yazılır. Diğer tüm tipler para çıkışıdır ve WALLET_TOTAL_OUTFLOW toplamına yazılır.

Örnek

curl "https://api-gateway.lunixi.com/api/v1/wallet/end-users/8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34/limits?operationType=W2W_TRANSFER&currency=TRY" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "X-Signature: …"

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "statuses": [
      {
        "operationType": "W2W_TRANSFER",
        "bucket": "OPERATION_TYPE",
        "currency": "TRY",
        "kycLevel": "LOW",
        "schemeId": "a41c7e2b-9d3f-4b8a-8e5c-2f1d6b9a0c37",
        "singleMax": "500000",
        "daily": {
          "amountLimit": "1000000",
          "amountUsed": "125000",
          "amountRemaining": "875000",
          "countLimit": 20,
          "countUsed": 3,
          "countRemaining": 17
        },
        "monthly": {
          "amountLimit": "3000000",
          "amountUsed": "410000",
          "amountRemaining": "2590000",
          "countLimit": null,
          "countUsed": 11,
          "countRemaining": null
        }
      },
      {
        "operationType": "W2W_TRANSFER",
        "bucket": "WALLET_TOTAL_OUTFLOW",
        "currency": "TRY",
        "kycLevel": "LOW",
        "schemeId": "a41c7e2b-9d3f-4b8a-8e5c-2f1d6b9a0c37",
        "singleMax": null,
        "daily": {
          "amountLimit": "2000000",
          "amountUsed": "180000",
          "amountRemaining": "1820000",
          "countLimit": null,
          "countUsed": 5,
          "countRemaining": null
        },
        "monthly": {
          "amountLimit": "5000000",
          "amountUsed": "650000",
          "amountRemaining": "4350000",
          "countLimit": null,
          "countUsed": 19,
          "countRemaining": null
        }
      }
    ],
    "sharedCaps": []
  },
  "requestId": "…"
}

`statuses[]` alanları

Alan	Tip	Anlamı
`operationType`	string	Satırın ait olduğu işlem tipi; cüzdan toplamı satırlarında `*` (`operationType` olmadan sorgulandığında) ya da sorguladığınız tip.
`bucket`	string	Sayacın türü: `OPERATION_TYPE` (tipe özel sayaç), `WALLET_TOTAL_OUTFLOW` (tüm para çıkışlarının ortak toplamı), `WALLET_TOTAL_INFLOW` (tüm para girişlerinin ortak toplamı).
`currency`	string	Sayacın para birimi.
`kycLevel`	string	Hesapta kullanılan geçerli KYC seviyesi (`NONE`, `LOW`, `SUBSTANTIAL`, `HIGH`).
`schemeId`	UUID	Uygulanan limit şeması.
`singleMax`	string \| null	Tek işlemde izin verilen en yüksek tutar (minor-unit). `null` = tek işlem tavanı yok.
`daily`, `monthly`	nesne	Günlük ve aylık pencere.
`….amountLimit`	string \| null	Penceredeki tutar tavanı (minor-unit). `null` = bu pencerede tutar tavanı yok.
`….amountUsed`	string	Pencerede kullanılan tutar (minor-unit).
`….amountRemaining`	string \| null	Kalan tutar. Tavan yoksa `null`.
`….countLimit`	sayı \| null	Penceredeki işlem adedi tavanı. `null` = adet tavanı yok.
`….countUsed`	sayı	Pencerede yapılan işlem adedi.
`….countRemaining`	sayı \| null	Kalan adet. Tavan yoksa `null`.

Kullanılan tutar ve adet, başlamış ama henüz sonuçlanmamış işlemlerin rezervasyonlarını da içerir; ayrıntı: Limitler — Rezervasyon ve işlem ömrü.

`sharedCaps[]` — kanal-üstü ortak tavan

Programınızda seçili çıkış kanallarının paylaştığı bir üst tavan açıksa, kullanımı sharedCaps listesinde döner. Açık değilse liste boştur.

Alan	Tip	Anlamı
`capCode`	string	Tavanın kodu.
`description`	string \| null	Açıklama.
`members`	string[]	Bu tavanı birlikte dolduran işlem tipleri.
`currency`, `kycLevel`, `schemeId`	string	`statuses[]` ile aynı anlamda.
`daily`, `monthly`	nesne	`statuses[]` ile aynı alanlar.

Kullanıcı tutarı girerken kalan limiti gösterin. Bir para hareketinden önce kesin sonuç için ilgili quote ucunu çağırın: quote yanıtındaki limitBlocked alanı, işlemin limit nedeniyle başlatılamayacağını bildirir.

Hatalar

HTTP	Kod	Ne zaman
400	`VALIDATION_ERROR`	`operationType` ya da `currency` biçime uymuyor
400	—	`{id}` UUID değil
403	`WALLET_INSUFFICIENT_SCOPE`	Anahtarda cüzdan okuma izni yok
404	`WALLET_NOT_FOUND`	Kullanıcı yok ya da size ait değil
503	`WALLET_LIMIT_UNAVAILABLE`	Limit sayaçları o an okunamadı; kısa bir süre sonra yeniden deneyin

Bakiyeler Cüzdan ve Hesap Açma