پرش به مطلب اصلی

وام (API)

دسترسی لازم: LoanScope

با این محصول به کاربرانتان وام با پشتوانه رمزارز می‌دهید: کاربر رمزارزش را به‌عنوان وثیقه قفل می‌کند و در برابرش وام ریالی می‌گیرد — یک‌جا یا در اقساط.

مبلغ وام، بدهی و اقساط همه ریالی‌اند؛ هر واحد برابر ده هزار ریال (هزار تومان) است. در پاسخ‌ها این واحد با شناسه داخلی ZAR کلید می‌خورد — آن را یک برچسبِ واحد حساب بدانید، نه چیزی که کاربر نهایی شما باید از آن سر دربیاورد.

برای درک مفهومی محصول، پیش از این صفحه وام را ببینید.

مسیر کامل​

طرح‌ها → پیکربندی اقساط → برآورد → پیش‌نمایش → ساخت → بازپرداخت

گام ۱ — طرح‌های موجود​

curl -sS "https://hd.zarban.io/loans/plans" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

هر طرح مشخص می‌کند چه ارزی را به‌عنوان وثیقه می‌پذیریم و با چه شرایطی:

[
  {
    "name": "ETH-A",
    "minCollateralizationRatio": "1.5",
    "fee": "0.05",
    "acceptableCoins": [ … ],
    "minDebt": { "values": { "ZAR": "…" } },
    "maxDebt": { "values": { "ZAR": "…" } },
    "loanToValueOptions": [ … ]
  }
]
  • fee نرخ سالانه به‌صورت رشته اعشاری است: "0.05" یعنی ۵ درصد.
  • minCollateralizationRatio حداقل نسبت ارزش وثیقه به بدهی است. "1.5" یعنی وثیقه باید دست‌کم ۱٫۵ برابر بدهی بیارزد.
  • minDebt و maxDebt مرزهای مبلغ وام‌اند. طرح‌ها را در کد خود ثابت ننویسید؛ همیشه از این مسیر بخوانید.

گام ۲ — پیکربندی اقساط​

curl -sS "https://hd.zarban.io/loans/installment-configs" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"
[
  { "numberOfInstallments": 12, "paymentInterval": 2592000 }
]

paymentInterval بر حسب ثانیه است. 2592000 یعنی ۳۰ روز.

گام ۳ — برآورد​

پیش از آنکه کاربر چیزی را تأیید کند، به او نشان دهید با این مقدار وثیقه چقدر وام می‌گیرد:

curl -sS "https://hd.zarban.io/loans/estimate?accountId=1234&planName=ETH-A&inputType=collateral&amount=1.5&symbol=ETH&loanToValueOption=Normal" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

برآورد از هر دو سو کار می‌کند و inputType تعیین می‌کند amount کدام است:

  • inputType=collateral — «کاربر این مقدار وثیقه دارد؛ چقدر وام می‌گیرد؟»
  • inputType=loan — «کاربر این مقدار وام می‌خواهد؛ چقدر وثیقه لازم است؟»

شکل دوم معمولاً همان چیزی است که کاربر واقعاً می‌پرسد.

symbol در این فراخوانی ارز وثیقه است. loanToValueOption یکی از سه مقدار Safe، Normal یا Risky است — هرچه تهاجمی‌تر، وام بیشتر و فاصله تا نقد شدن کمتر.

گام ۴ — پیش‌نمایش​

گردش کار پیشنهادی این است که هر ساخت وام را اول با intent: "Preview" فراخوانی کنید. بدنه دقیقاً همان بدنه ساخت است و تنها intent فرق می‌کند؛ پس پیش‌نمایش همان مسیر اجرا را بدون اثر واقعی طی می‌کند و مقادیر نهایی را برمی‌گرداند.

curl -sS -X POST "https://hd.zarban.io/loans/create" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Preview",
    "accountId": 1234,
    "planName": "ETH-A",
    "symbol": "ZAR",
    "collateral": "1.5",
    "loanToValueOption": "Normal",
    "withInstallments": true,
    "numberOfInstallments": 12,
    "paymentInterval": 2592000
  }'

در پاسخ، این‌ها را به کاربر نشان دهید:

فیلدیعنی چه
debtبدهی کل
collateralوثیقه‌ای که قفل می‌شود
apyنرخ مؤثر سالانه
collateralizationRatioنسبت وثیقه به بدهی
liquidationPriceقیمتی که در آن وثیقه نقد می‌شود

گام ۵ — ساخت​

همان بدنه، با intent برابر Create:

curl -sS -X POST "https://hd.zarban.io/loans/create" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Create",
    "accountId": 1234,
    "planName": "ETH-A",
    "symbol": "ZAR",
    "collateral": "1.5",
    "loanToValueOption": "Normal",
    "withInstallments": true,
    "numberOfInstallments": 12,
    "paymentInterval": 2592000
  }'

این فراخوانی وثیقه را قفل می‌کند و بدهی می‌سازد. پیش از اجرا، مقادیر پاسخ را با همان‌هایی بسنجید که در پیش‌نمایش به کاربر نشان داده‌اید و او تأییدشان کرده است.

برای وام یک‌جا (بدون قسط)، withInstallments را false بگذارید و numberOfInstallments و paymentInterval را نفرستید.

بازپرداخت​

پیش‌نمایش:

curl -sS -X POST "https://hd.zarban.io/loans/repay" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Preview",
    "loanId": "123e4567-e89b-12d3-a456-426614174000",
    "repayAll": false
  }'

اجرا، با intent برابر Repay:

curl -sS -X POST "https://hd.zarban.io/loans/repay" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Repay",
    "loanId": "123e4567-e89b-12d3-a456-426614174000",
    "repayAll": false
  }'

repayAll برابر false یعنی یک قسط، و true یعنی تسویه کامل بدهی باقی‌مانده.

پیگیری وام‌ها​

curl -sS "https://hd.zarban.io/loans?accountId=1234" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

curl -sS "https://hd.zarban.io/loans/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

بدون accountId، همه وام‌های سازمان برمی‌گردد.

داشبورد سازمانی همین فهرست را نشان می‌دهد؛ برای پشتیبانی از یک کاربر، یافتن وامش اینجا سریع‌تر از فراخوانی API است:

تب وام‌ها در داشبورد زربان سازمانی
ستون «نسبت وثیقه» همان collateralizationRatio است و نوار زیر آن فاصله تا مرز نقد شدن را نشان می‌دهد: وام دوم با نسبت ۱٫۴۱ به حداقلِ طرح خود (۱٫۳) نزدیک شده و وام تسویه‌شده بدهی صفر دارد.

سلامت وام و نقد شدن​

اگر نسبت ارزش وثیقه به بدهی از حد تعیین‌شده در طرح پایین‌تر برود، قرارداد هوشمند بخشی از وثیقه را به مزایده می‌گذارد تا بدهی تسویه شود؛ کارمزد نقد شدن و پاداش مصادره‌کننده را از همان وثیقه کم می‌کند و باقی‌مانده را به حساب برمی‌گرداند.

این رفتار خودکار است، به قیمت بازار وابسته است و از مسیر API نمی‌توان جلویش را گرفت. سازوکارش را در نقد شدن و شاخص سلامت توضیح داده‌ایم.

مسئولیت سرویس شما:

  • collateralizationRatio و liquidationPrice را رصد کنید و به کاربر نشان دهید.
  • پیش از رسیدن به مرز خطر به کاربر هشدار بدهید، نه بعد از آن.
  • برای هشدار خودکار، از هشدارهای سازمانی استفاده کنید.

مطالب مرتبط​