حساب‌ها و آدرس واریز

«حساب» واحد پایه زربان سازمانی است. هر کاربر شما یک حساب دارد، و هر چیز دیگری — موجودی، تراکنش، وام، سپرده، موقعیت وثیقه — به یک حساب وصل است.

ساخت حساب

curl -sS -X POST "https://hd.zarban.io/accounts" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "PLN",
    "externalId": "user_8412"
  }'

{
  "id": 1234,
  "entityId": "PLN",
  "externalId": "user_8412"
}

فقط دو فیلد لازم است: entityId (شناسه سازمان شما) و externalId.

externalId مهم‌ترین تصمیم شماست

externalId تنها پلی است که کاربر شما را به حساب زربان وصل می‌کند. زربان چیز دیگری از کاربر شما نمی‌داند — نه نامی، نه ایمیلی، نه شماره‌ای.

⚠

شناسه پایدار و داخلی انتخاب کنید، مانند کلید اصلی کاربر در پایگاه داده خودتان (user_8412).

از ایمیل، شماره تلفن یا نام کاربری استفاده نکنید: این‌ها تغییر می‌کنند، و وقتی تغییر کردند شما حسابی در زربان دارید که دیگر به کاربرتان وصل نیست — و راهی برای اصلاحش ندارید، چون externalId پس از ساخت قابل تغییر نیست.

ضمناً این‌ها داده شخصی‌اند و فرستادنشان به سرویس بیرونی، وقتی یک شناسه بی‌معنی هم همان کار را می‌کند، بی‌دلیل است.

id بازگشتی را کنار کاربر خود ذخیره کنید. بقیه API با همان id عددی کار می‌کند، نه با externalId.

یافتن حساب

اگر id را گم کردید، با externalId پیدایش کنید:

curl -sS "https://hd.zarban.io/accounts?entityId=PLN&externalId=user_8412" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

فهرست همه حساب‌های سازمان، صفحه‌به‌صفحه:

curl -sS "https://hd.zarban.io/accounts?entityId=PLN&limit=50" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

{
  "data": [ { "id": 1234, "entityId": "PLN", "externalId": "user_8412" } ],
  "hasMore": true,
  "nextCursor": 1500
}

تا وقتی hasMore برابر true است، nextCursor را در پارامتر cursor بفرستید:

curl -sS "https://hd.zarban.io/accounts?entityId=PLN&limit=50&cursor=1500" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

و یک حساب مشخص:

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

آدرس واریز

آدرس واریز برای هر ترکیب حساب، ارز و شبکه جداگانه است:

curl -sS "https://hd.zarban.io/accounts/1234/coindepositaddress?symbol=USDT&network=arbitrum" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

{
  "addresses": [
    {
      "address": "0x3a1f9c2e7b8d4056a9c1e2f3b4d5e6f7a8b9c0d1",
      "network": "arbitrum",
      "symbol": "USDT",
      "version": "v1",
      "memo": "",
      "accountId": 1234,
      "isDeprecated": false,
      "isActive": true
    }
  ]
}

شبکه‌های پذیرفته‌شده: arbitrum، tron، bnb، ton.

سه قاعده پیش از نمایش آدرس به کاربر

1. پاسخ آرایه است. یک حساب می‌تواند بیش از یک آدرس برای همان ارز داشته باشد، چون آدرس‌ها نسخه دارند. همیشه آدرسی را نشان دهید که isActive آن true و isDeprecated آن false است.

2. memo را نادیده نگیرید. اگر خالی نبود، کاربر باید آن را همراه واریز بفرستد؛ وگرنه واریز به حساب او نسبت داده نمی‌شود. رابط کاربری شما باید memo را به همان برجستگی آدرس نشان دهد.

3. ارز و شبکه را ثابت ننویسید. فهرست را از GET /coins بگیرید؛ آنجا مشخص است که برای هر ترکیب، واریز و برداشت فعال است یا نه.

ℹ

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

موجودی

همه ارزهای یک حساب:

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

{
  "balances": [
    {
      "symbol": "USDT",
      "balance": { "values": { "USDT": "25.000000" } },
      "locked":  { "values": { "USDT": "0" } }
    }
  ]
}

یک ارز مشخص:

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

⚠

locked را از balance کم کنید. balance کل موجودی است و locked بخشی از آن که رزرو شده — برای برداشتی که در صف است یا وثیقه‌ای که در وامی فعال قفل‌شده. آنچه کاربر می‌تواند خرج کند تفاضل این دو است. نمایش balance به‌عنوان «موجودی قابل برداشت» یکی از رایج‌ترین اشتباهات در یکپارچه‌سازی است.

مبالغ همیشه رشته هستند، نه عدد. آن‌ها را با کتابخانه اعشار دقیق پردازش کنید؛ تبدیلشان به float در هر زبانی، دیر یا زود به خطای گردکردن در گزارش مالی می‌رسد.

حساب اصلی (master account)

سازمان شما می‌تواند یکی از حساب‌هایش را «حساب اصلی» تعیین کند — حسابی متعلق به خود سازمان، نه به کاربران، که معمولاً برای نگهداری موجودی عملیاتی استفاده می‌شود:

curl -sS "https://hd.zarban.io/tenants/PLN/master-account" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

تعیین یا تغییر آن از داشبورد سازمانی انجام می‌شود:

حساب اصلی بالای فهرست، با موجودی و آخرین تراکنش‌هایش، جدا از زیرحساب‌ها نشان داده می‌شود. زیرحساب‌ها همان حساب‌هایی‌اند که با POST /accounts می‌سازید؛ «شناسه خارجی» هر ردیف همان externalId است که خودتان فرستاده‌اید.

مطالب مرتبط

• تراکنش‌ها و ایدمپوتنسی — جابه‌جا کردن موجودی این حساب‌ها
• وب‌هوک‌ها — باخبر شدن از تغییر موجودی