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

مرور یکپارچه‌سازی سازمانی

این بخش، مستندات فنی «زربان سازمانی» است: راهنمای اتصال سرور شما به API زربان برای ساخت حساب، دریافت آدرس واریز، اجرای تراکنش و ارائه محصولات مالی به کاربران خودتان.

کدام API؟ زربان دو API مجزا دارد و این دو یکی نیستند.

  • زربان سازمانی روی https://hd.zarban.io — همین بخش. احراز هویت با clientId و clientSecret سازمان.
  • کیف پول زربان روی https://api.zarban.io — بخش کیت توسعه نرم‌افزار. احراز هویت با رایانامه و گذرواژه کاربر نهایی.

اگر قرارداد سازمانی با زربان دارید و clientId دریافت کرده‌اید، مستندات شما همین بخش است.

پیش‌نیاز: سازمان فعال​

زربان سازمانی ثبت‌نام خودکار ندارد. پیش از شروع باید سازمان شما ساخته شده و این سه مورد را در اختیار داشته باشید:

  1. شناسه سازمان — رشته‌ای کوتاه مانند PLN که هم شناسه سازمان است و هم clientId شما.

  2. کلید مخفی — clientSecret، از داشبورد سازمانی.

  3. دسترسی‌های فعال — سازمان شما زیرمجموعه‌ای از دسترسی‌هاست، نه همه آن‌ها. نگاه کنید به دسترسی‌ها.

سازمان‌ها را به‌صورت دستی می‌سازیم؛ درخواست خود را از صفحه کسب‌وکار ثبت کنید.

محیط اجرا و خشک‌اجرا​

https://hd.zarban.io تنها میزبان API است و همه فراخوانی‌ها روی محیط عملیاتی اجرا می‌شوند. هر فراخوانی اجراکننده که موفق شود، روی دارایی واقعی اثر می‌گذارد.

برای آزمودن یک مسیر پیش از اجرای واقعی، API دو سازوکار خشک‌اجرا1 دارد. همه نمونه‌های این راهنما بر پایه همین دو نوشته شده‌اند:

  • POST /transactions/simulate — تراکنش را کامل اعتبارسنجی می‌کند و نتیجه را برمی‌گرداند، بدون جابه‌جایی دارایی.
  • فیلد intent با مقدار Preview — در ساخت و بازپرداخت وام، به‌جای اجرا، اثر عملیات را برمی‌گرداند.

گردش کار پیشنهادی: هر مسیر جدید را اول با simulate یا Preview بنویسید؛ وقتی خروجی همان بود که انتظار داشتید، فراخوانی را به شکل اجراکننده تغییر دهید. اولین اجرای واقعی هر مسیر را با کوچک‌ترین مبلغ ممکن انجام دهید.

مفاهیم پایه​

پیش از رفتن به شروع سریع، چهار واژه که در تمام این مستندات تکرار می‌شوند:

واژهیعنی چه
سازمان2شما. شناسه‌ای مانند PLN که همه چیز زیر آن ساخته می‌شود و clientId شماست.
حساب3یک کاربر شما در سمت زربان. با POST /accounts ساخته می‌شود و با externalId — شناسه‌ای که خودتان می‌دهید — به کاربر شما وصل می‌شود.
دسترسی4مجوز استفاده از یک محصول. سازمان شما زیرمجموعه‌ای از شش دسترسی را دارد.
توکن5کلید مخفی مستقیماً روی هیچ درخواستی نمی‌رود؛ آن را با یک توکن یک‌ساعته تعویض می‌کنید.

مدل امانی​

زربان سازمانی امانی6 است: زربان کلیدهای خصوصی را در سرویس HD نگه می‌دارد و در پاسخ هیچ فراخوانی برنمی‌گرداند. کاربر نهایی شما کیف پول شخصی ندارد و چیزی امضا نمی‌کند — شما از طرف او با API کار می‌کنید.

این مسیر با مسیر غیرامانیِ پروتکل روی زنجیره فرق دارد. برای مقایسه این دو نگاه کنید به زربان سازمانی.

مسیر مطالعه​

اگر تازه شروع کرده‌اید، به همین ترتیب پیش بروید:

  1. شروع سریع: از صفر تا اولین واریز — کوتاه‌ترین مسیر کامل، با curl.

  2. احراز هویت و توکن‌ها — چرخه عمر توکن و نگهداری کلید مخفی.

  3. دسترسی‌ها — بفهمید سازمان شما چه چیزی را می‌تواند فراخوانی کند.

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

  5. تراکنش‌ها و ایدمپوتنسی — مهم‌ترین صفحه برای جلوگیری از پرداخت دوباره.

  6. وب‌هوک‌ها

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

و پیش از رفتن به تولید: خطاها و رفتن به تولید.

قواعد مشترک همه درخواست‌ها​

  • میزبان: https://hd.zarban.io
  • احراز هویت: هدر Authorization: Bearer <accessToken> روی همه مسیرها، به‌جز /oauth/token و مسیرهای عمومی گواهی وثیقه.
  • قالب بدنه: JSON، با هدر Content-Type: application/json.
  • قالب خطا: همیشه یکسان — { "msg": "...", "reasons": [...] }. نگاه کنید به خطاها.
  • مبالغ: همیشه رشته اعشاری، نه عدد. "100.5" نه 100.5 — تا دقت اعشار در گذر از JSON از دست نرود.

Footnotes​

  1. Dry run ↩

  2. Tenant ↩

  3. Account ↩

  4. Scope ↩

  5. Token ↩

  6. Custodial ↩