راهنمای مدیر محصول
این صفحه توضیح میدهد که ساختن یک محصول روی زربان سازمانی چه دامنهای دارد، مسئولیتها چگونه تقسیم میشوند و کدام پارامترها را باید در طراحی تعیین کنید. شکل درخواستها، فیلدها و نمونههای curl را در راهنمای یکپارچهسازی سازمانی آوردهایم.
مدل کار
زربان سازمانی یک API روی hd.zarban.io است. سرویس شما برای هر کاربر یک حساب میسازد و آن را با شناسه داخلی خودتان (externalId) به کاربر گره میزند؛ از آن پس واریز، برداشت، وام، سپرده و وثیقه را با فراخوانی API روی همان accountId انجام میدهید.
این مسیر امانی1 است: زربان کلیدهای خصوصی را در سرویس HD نگه میدارد و از هیچ مسیری در API برنمیگرداند. در مقابلِ آن پروتکل غیرامانی قرار دارد که کاربر تراکنش را با کیف پول خودش امضا میکند.
هویت کاربر نهایی در سیستم شما میماند: زربان حساب را تنها با externalId میشناسد و هیچ اطلاعات هویتی از کاربر شما نگه نمیدارد.
دامنه محصولات و دسترسیها
| محصول | رفتار سیستم | دسترسی لازم | مستندات فنی |
|---|---|---|---|
| واریز و برداشت رمزارز | آدرس واریز اختصاصی برای هر حساب، برداشت به آدرس بیرونی، انتقال داخلی میان حسابهای همان سازمان | «واریز کوین» (CoinDepositScope)، «برداشت کوین» (CoinWithdrawalScope)، «انتقال داخلی» (InternalTransferScope) | تراکنشها |
| سپردهگذاری | قرار دادن موجودی در استخر وامدهی؛ سود از کارمزد وامگیرندگان میآید و پیوسته انباشته میشود | «سپردهگذاری» (SavingScope) | سپردهگذاری (API) |
| وام | قفل شدن وثیقه رمزارزی و ایجاد بدهی ریالی، با تعداد و فاصله اقساط قابل پیکربندی | «وام» (LoanScope) | وام (API) |
| گواهی وثیقه | لینکی که گیرنده با آن بدون حساب کاربری وثیقه میگذارد و کسبوکار در برابرش بدهی ریالی میگیرد؛ وضعیت موقعیت با همان لینک دیده میشود | «موقعیت بدهی» (DebtPositionScope) | موقعیت وثیقه (API) |
دسترسیها در سطح سازمان و مستقل از هم فعال میشوند و برای شروع، یک محصول کافی ا ست. فهرست دسترسیهای فعالِ سازمان خود را از GET /tenants/{id} بخوانید — نگاه کنید به دسترسیها.
تقسیم مسئولیت
زربان لایه اجرای مالی است و در نقاط زیر با سیستم شما مرز دارد. این تقسیم را در برنامه تیم خود در نظر بگیرید:
| موضوع | زربان | سرویس شما |
|---|---|---|
| هویت و احراز هویت کاربر | حساب را با externalId میشناسد | هویت، ورود و نگاشت externalId را نگه میدارد |
| اطلاع از رویدادها | وبهوک امضاشده میفرستد | رویداد را طوری مصرف میکند که تکرارش مشکلی نسازد و وضعیت داخلی را بهروز میکند |
| موجودی و مانده | مانده معتبر را روی API عرضه میکند | بهصورت دورهای آن را با مانده داخلی خودش مغایرتگیری میکند |
| سلامت وثیقه | مقادیر collateralizationRatio و liquidationPrice را برمیگرداند | وضعیت و هشدار را در رابط کاربری نشان میدهد |
| پشتیبانی | از تیم شما پشتیبانی سازمانی میکند | از کاربر نهایی پشتیبانی میکند |
جزئیات هر ردیف را در حسابها، وبهوکها و رفتن به تولید بخوانید.
سه پارامتر طراحی
محیط اجرا و پیشنمایش
فراخوانیها روی محیط عملیاتی اجرا میشوند. برای اینکه پیش از اجرای واقعی بتوانید یک مسیر را بیازمایید، زربان دو سازوکار خشکاجرا2 در اختیارتان میگذارد:
intent: "Preview"روی وام — همان بدنه ساخت را میفرستید، بیآنکه اثری واقعی بگذارد؛ پاسخ، مقادیر نهایی را برمیگرداند: بدهی، وثیقه، نرخ و قیمت نقد شدن.simulateروی تراکنشها — همان مسیر اعتبارسنجی و برآورد را طی میکند، بدون آنکه تراکنشی ثبت شود.
برای هر مسیر تازه، این ترتیب را پیشنهاد میکنیم: اول پیشنمایش بگیرید، بعد یک بار با کوچکترین مبلغ ممکن و زیر نظر یک نفر واقعاً اجرا کنید، و در پایان آن را به جریان خودکار بسپارید.
رفتار نرخها
سود سپرده و کارمزد وام از عرضه و تقاضای استخر به دست میآیند و پیوسته تغییر میکنند. API نرخ لحظهای را برمیگرداند: GET /savings/rates و فیلد fee هر طرح وام. رابط کاربری خود را بر این پایه طراحی کنید که نرخ نمایشدادهشده لحظهای است، و این مقادیر را تنها کوتاهمدت کش کنید.
رفتار نقد شدن وثیقه
اگر نسبت ارزش وثیقه به بدهی از حد تعیینشده در طرح پایینتر برود، قرارداد هوشمند بخشی از وثیقه را به مزایده میگذارد تا بدهی تسویه شود؛ کارمزد نقد شدن و پاداش مصادرهکننده را از همان وثیقه کم میکند و باقیمانده را به حساب برمیگرداند.
این رفتار خودکار است، به قیمت بازار وابسته است و از مسیر API نمیتوان جلویش را گرفت. پس اگر محصولی میسازید که وام یا وثیقه عرضه میکند، از همان ابتدا collateralizationRatio را رصد کنید، پیش از رسیدن به آستانه به کاربر هشدار دهید و متن و مسیر پشتیبانی این حالت را هم آماده داشته باشید. نگاه کنید به شاخص سلامت و نقد شدن.
مسیر راهاندازی
- دسترسی بگیرید. سازمانها را بهصورت دستی میسازیم؛ درخواست خود را از صفحه کسبوکار ثبت کنید.
- اعتبارنامه بگیرید. یک شناسه سازمان (
clientId) و کلید (clientSecret) در اختیارتان میگذاریم و دسترسیهای موردنیازتان را روی سازمان فعال میکنیم. - مسیر بدون جابهجایی وجه را طی کنید. چهار گام نخست شروع سریع — گرفتن توکن، ساخت حساب، گرفتن آدرس واریز و ثبت وبهوک — هیچکدام تراکنش مالی نمیسازند.
- نخستین تراکنش واقعی را با کوچکترین مبلغ ممک ن انجام دهید.
- سیاهه بررسی تولید را کامل کنید — هشدارها، مغایرتگیری و مسیر پشتیبانی؛ نگاه کنید به رفتن به تولید.
تصمیمهای پیکربندی پیش از شروع
- کدام شناسه داخلی را به
externalIdنگاشت میکنید؟ این مقدار پس از ساخت حساب دیگر تغییر نمیکند، پس شناسهای را انتخاب کنید که در تمام عمر حساب کاربر ثابت میماند — نه نشانی رایانامه، نه شماره تلفن و نه نام کاربری. - با کدام محصول شروع میکنید و کدام دسترسیها را لازم دارید؟
- مغایرتگیری روزانه بر عهده کدام تیم است و خروجی آن را کجا ثبت میکنید؟
- نقد شدن وثیقه را از کدام کانال و با چه متنی به کاربر اطلاع میدهید؟
مطالب مرتبط
- زربان سازمانی — توضیح محصول
- راهنمای یکپارچهسازی سازمانی — مستندات فنی با نمونههای
curl - پرسشهای متداول