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

موقعیت وثیقه و گواهی عمومی

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

موقعیت وثیقه با وام یک تفاوت مهم دارد: سازمان شما موقعیت را بدون آنکه کاربر حسابی نزد شما داشته باشد می‌سازد و لینکی می‌گیرد که هر کس بازش کند، می‌تواند وثیقه بگذارد و وضعیت لحظه‌ای را ببیند.

برای درک مفهومی، کاربردها و تصاویر صفحه‌ای که گیرنده لینک می‌بیند، نگاه کنید به گواهی وثیقه.

دو نیمه این محصول​

نیمهمخاطباحراز هویت
مسیرهای /debt-positions/…سرور شماتوکن سازمان
مسیرهای /public/debt-positions/…مرورگر گیرنده لینکبدون احراز هویت

شناسه موقعیت خودش مجوز دسترسی است. هر کس uuid را داشته باشد می‌تواند صفحه عمومی را باز کند. پس با آن مانند یک راز رفتار کنید: از کانال امن به گیرنده برسانیدش، در لاگ ننویسیدش، و نگذارید در پارامتر نشانی صفحات دیگر یا در ارجاع‌دهنده نشت کند.

ساخت موقعیت​

curl -sS -X POST "https://hd.zarban.io/debt-positions" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": 1234,
    "debt": "1000"
  }'
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "debt": "1000",
  "expiresAt": "2026-09-02T12:00:00Z",
  "createdAt": "2026-08-03T12:00:00Z"
}

id هم شناسه موقعیت است و هم لینک قابل اشتراک.

پس از expiresAt، هر کس لینک عمومی را باز کند پاسخ 410 Gone می‌گیرد. اگر لینک را با رایانامه یا پیامک می‌فرستید، زمان انقضا را در همان پیام بنویسید و در سمت خودتان هم پیش از انقضا یادآوری بگذارید تا گیرنده بداند لینک تا کی پاسخ می‌دهد.

صفحه عمومی​

گیرنده لینک، بدون هیچ حسابی، این‌ها را می‌بیند و انجام می‌دهد:


# طرح‌های وثیقه پیشنهادی برای این موقعیت
curl -sS "https://hd.zarban.io/public/debt-positions/550e8400-e29b-41d4-a716-446655440000/open"

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

سپس وضعیت را می‌خواند:

curl -sS "https://hd.zarban.io/public/debt-positions/550e8400-e29b-41d4-a716-446655440000/state"

پاسخ شامل وضعیت کاربرپسند موقعیت است و — تا وقتی منتظر وثیقه است — اینکه چقدر واریز شده، چقدر باقی‌مانده و آدرس واریز کدام است.

جریان رویداد زنده​

curl -sS -N "https://hd.zarban.io/public/debt-positions/550e8400-e29b-41d4-a716-446655440000/state/stream"

این مسیر همان بدنه state را با هر تغییر، به‌صورت SSE می‌فرستد.

الگوی درست در رابط کاربری: برای نمایش اولیه از state استفاده کنید، سپس به state/stream وصل شوید. اگر جریان قطع شد یا در دسترس نبود، به فراخوانی دوره‌ای state برگردید. جریان جایگزین نمایش اولیه نیست، مکمل آن است.

وضعیت‌ها​

status واژگان کوچک و پایداری است که رابط کاربری شما می‌تواند رویش شاخه بزند؛ ماشین حالت داخلی هیچ‌وقت بیرون نمی‌آید:

وضعیتیعنی چه
DebtPositionStatusOpenساخته شده، هنوز طرحی انتخاب نشده
DebtPositionStatusWaitingForDepositمنتظر واریز وثیقه
DebtPositionStatusInProgressدر حال اجرا روی زنجیره
DebtPositionStatusActiveفعال
DebtPositionStatusUpdatingدر حال تغییر وثیقه یا بدهی
DebtPositionStatusRefunding / Refundedدر حال بازگرداندن / بازگردانده شد
DebtPositionStatusFailedناموفق
DebtPositionStatusLiquidatedنقد شد
DebtPositionStatusExpiredلینک منقضی شد
DebtPositionStatusUnknownنامشخص

شاخه default را در کد خود فراموش نکنید.

داشبورد سازمانی همین وضعیت‌ها را با متن فارسی آماده‌ی status.title نشان می‌دهد — همان متنی که خود API برمی‌گرداند، پس رابط کاربری شما هم می‌تواند بدون نگاشت جداگانه از آن استفاده کند:

تب موقعیت‌های بدهی در داشبورد زربان سازمانی
سه مرحله از چرخه عمر، پشت سر هم: «لینک باز» هنوز طرحی انتخاب نشده، «در انتظار واریز وثیقه» بخشی از وثیقه رسیده، و «فعال» موقعیتی است که وثیقه‌اش قفل و بدهی‌اش ساخته شده.

تغییر وثیقه و بدهی​

چهار عملیات، همه با همان ساختار بدنه:

curl -sS -X POST "https://hd.zarban.io/debt-positions/550e8400-e29b-41d4-a716-446655440000/collateral/increase" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": 1234,
    "amount": "100"
  }'
مسیراثر
collateral/increaseافزودن وثیقه — موقعیت را امن‌تر می‌کند
collateral/decreaseبرداشت وثیقه — موقعیت را پرخطرتر می‌کند
debt/increaseایجاد بدهی ریالی بیشتر
debt/decreaseبازپرداخت بدهی

در debt/decrease می‌توانید به‌جای amount، فیلد repayAll را true بگذارید تا کل بدهی باقی‌مانده تسویه شود.

پاسخ هر عملیات، kind و amount و مقادیر پس از عملیات را برمی‌گرداند — همان چیزی که باید به کاربر نشان دهید.

پیگیری​

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

curl -sS "https://hd.zarban.io/debt-positions/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

رویدادها​

پنج رویداد وب‌هوک به این محصول مربوط است: WebhookDebtPositionCreated، Activated، Adjusted، Failed و Liquidated.

WebhookDebtPositionLiquidated خبر می‌دهد که وثیقه یک حساب نقد شده است. برای این رویداد در سرویس خود مسیر مشخصی بگذارید — دست‌کم به کاربر اطلاع دهید و وضعیت داخلی را به‌روز کنید — چون پس از آن، مقادیر وثیقه و بدهی همان موقعیت عوض شده‌اند.

جزئیات در وب‌هوک‌ها.