شروع سریع: از صفر تا اولین واریز

چهار فراخوانی، از هیچ تا لحظه‌ای که زربان واریز کاربرتان را به سرور شما خبر می‌دهد. همه نمونه‌ها را با curl نوشته‌ایم و همان‌طور که هستند اجرا می‌شوند.

ℹ

چهار گام اول هیچ تراکنش مالی نمی‌سازند. گرفتن توکن، ساخت حساب، گرفتن آدرس واریز و ثبت وب‌هوک همگی عملیات پیکربندی‌اند و روی محیط عملیاتی هم بدون اثر مالی اجرا می‌شوند. تنها گام پنجم — واریز کاربر — دارایی جابه‌جا می‌کند؛ اولین بار آن را با کوچک‌ترین مبلغ ممکن انجام دهید.

پیش از شروع، clientId و clientSecret سازمان خود را آماده داشته باشید. اگر ندارید، مرور یکپارچه‌سازی را ببینید.

export ZARBAN_HOST="https://hd.zarban.io"
export ZARBAN_CLIENT_ID="PLN"
export ZARBAN_CLIENT_SECRET="…"       # از داشبورد سازمانی

گام ۱ — گرفتن توکن دسترسی

کلید مخفی هرگز روی درخواست‌های عادی نمی‌رود. اول آن را با یک توکن یک‌ساعته تعویض کنید:

curl -sS -X POST "$ZARBAN_HOST/oauth/token" \
  -H "Content-Type: application/json" \
  -d "{
    \"clientId\": \"$ZARBAN_CLIENT_ID\",
    \"clientSecret\": \"$ZARBAN_CLIENT_SECRET\",
    \"grantType\": \"ClientCredentials\"
  }"

پاسخ:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "refreshToken": "rt_3a1f9c2e7b8d4056a9c1e2f3b4d5e6f7",
  "expiresIn": 3600
}

توکن را برای گام‌های بعد نگه دارید:

export ZARBAN_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

accessToken یک ساعت اعتبار دارد و refreshToken نود روز. در سرویس واقعی، توکن را کش کنید و پیش از انقضا تازه‌اش کنید — نه اینکه برای هر درخواست یکی بگیرید. جزئیات در احراز هویت و توکن‌ها.

گام ۲ — ساخت حساب برای کاربر شما

هر کاربر شما در سمت زربان یک «حساب» است. آن را با شناسه‌ای که خودتان می‌دهید به کاربرتان وصل می‌کنید:

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

پاسخ:

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

⚠

externalId شناسه کاربر در سیستم شماست و تنها پل میان کاربر شما و حساب زربان است. id بازگشتی را در پایگاه داده خود کنار کاربر ذخیره کنید؛ بقیه فراخوانی‌ها با همین id کار می‌کنند.

گام ۳ — گرفتن آدرس واریز

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

curl -sS "$ZARBAN_HOST/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
    }
  ]
}

سه نکته پیش از نمایش این آدرس به کاربر:

• پاسخ یک آرایه است. آدرسی را نشان دهید که isActive آن true و isDeprecated آن false است.
• اگر memo خالی نبود، کاربر باید آن را هم همراه واریز بفرستد، وگرنه واریز به حسابش نسبت داده نمی‌شود. بعضی شبکه‌ها مانند تون این را لازم دارند.
• ارزها و شبکه‌های در دسترس را از GET /coins بگیرید؛ آن‌ها را در کد خود ثابت ننویسید.

گام ۴ — ثبت وب‌هوک

تا اینجا کاربرتان می‌تواند واریز کند، اما شما خبردار نمی‌شوید. آدرس خود را ثبت کنید:

curl -sS -X POST "$ZARBAN_HOST/webhooks/PLN" \
  -H "Authorization: Bearer $ZARBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.shoma.com/webhooks/zarban"
  }'

پاسخ:

{
  "entityId": "PLN",
  "url": "https://api.shoma.com/webhooks/zarban",
  "signingKey": "whsec_8f2c1a9b3e7d4f60a1c2b3d4e5f60718"
}

⚠

signingKey فقط در همین پاسخ به‌صورت متن ساده برمی‌گردد؛ فراخوانی‌های بعدی تنها شکل ماسک‌شده آن (whsec_••••0718) را برمی‌گردانند. آن را در همین مرحله در محل نگهداری اسرار سرویس خود ذخیره کنید. اگر کلید را از دست بدهید، تنها راه بازیابی آن است که کلید را بچرخانید — و این کار کلید قبلی را باطل می‌کند.

گام ۵ — واریز، و رویدادی که می‌رسد

حالا کاربر مبلغی به آدرس گام ۳ می‌فرستد. وقتی واریز روی زنجیره تأیید شد، زربان یک POST به آدرس گام ۴ می‌زند:

{
  "type": "transaction_event",
  "name": "transaction.coin.deposit"
}

سرویس شما باید پیش از هر کاری امضای درخواست را بررسی کند و سپس با کد 200 پاسخ دهد. روش بررسی امضا و فهرست کامل رویدادها در وب‌هوک‌ها آمده است.

برای دیدن اینکه تحویل موفق بوده یا نه، بدون نیاز به لاگ سمت خودتان:

curl -sS "$ZARBAN_HOST/webhooks/PLN/logs?limit=5" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

و برای دیدن خود تراکنش در سمت زربان:

curl -sS "$ZARBAN_HOST/transactions?accountId=1234" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

بررسی موجودی

curl -sS "$ZARBAN_HOST/balance?accountId=1234" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

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

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

گام بعد

مسیر «تا اولین واریز» همین‌جا تمام می‌شود. از اینجا:

• می‌خواهید برداشت هم بزنید؟ تراکنش‌ها و ایدمپوتنسی — پیش از اولین برداشت واقعی، حتماً این صفحه را بخوانید.
• می‌خواهید محصول مالی ارائه دهید؟ وام، سپرده‌گذاری، موقعیت وثیقه.
• آماده تولید می‌شوید؟ رفتن به تولید.