نمونه کد API استعلام شبا: پیاده‌سازی production-ready با cURL، Python و Node.js

برای پیاده‌سازی سریع نمونه کد API استعلام شبا کافی است درخواست GET را به آدرس https://api.novin.one/v1/ibans بفرستید، توکن را در هدر Authorization با قالب Bearer قرار دهید و در ادرس درخواست پارامتر value را با شماره شبا کامل پر کنید. بلوک cURL زیر همان درخواست production-ready است و بعد از آن نسخه Python و Node.js با مدیریت خطا و خواندن توکن از متغیر محیطی آمده است تا همان روز بتوانید اتصال واقعی بزنید.

curl --request GET 'https://api.novin.one/v1/ibans?value=IR5201500000001234567891' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

endpoint و نمونه cURL آماده اجرا برای استعلام شبا

آدرس سرویس ثابت است: GET https://api.novin.one/v1/ibans. دو هدر الزامی دارید؛ یکی Authorization: Bearer YOUR_ACCESS_TOKEN و دیگری Content-Type: application/json. در ادامه آدرس یک پارامتر string ساده با کلید value است که شماره شبا را به‌صورت کامل، با پیشوند IR، می‌گیرد.

نمونه کد cURL استعلام شبا بالا برای smoke test روی سرور توسعه یا ترمینال محلی کافی است. توکن واقعی را جایگزین placeholder کنید، یک شبا معتبر بگذارید و پاسخ را ببینید. اگر وضعیت HTTP برابر ۲۰۰ باشد و فیلد success مقدار true داشته باشد، بدنه شامل اطلاعات بانک، شماره حساب، وضعیت حساب و صاحبان است. خطاهای احراز هویت، اعتبارسنجی شبا یا محدودیت نرخ درخواست با کدهای HTTP و پیام‌های مشخص برمی‌گردند که در بخش مدیریت خطا پوشش داده شده‌اند.

این الگوی REST برای پیاده‌سازی API استعلام شبا در هر زبانی یکسان می‌ماند: همان URL، همان هدرها، همان بدنه. تفاوت فقط در کتابخانه HTTP و نحوه خواندن پاسخ است.

مرجع فنی درخواست: هدرها، بدنه و فیلدهای Endpoint

قرارداد درخواست برای کد اتصال API شبا کوتاه و صریح است. بدون حدس زدن پارامترهای اضافه، همین سه جزء را درست بفرستید.

فیلد value تنها ورودی بدنه در این قرارداد است و باید شماره شبا کامل باشد. خالی گذاشتن آن یا فرستادن مقدار نامعتبر به خطاهای اعتبارسنجی مثل الزامی بودن شبا یا نامعتبر بودن شبا منجر می‌شود. پارامتر اختیاری دیگری در بدنه این endpoint تعریف نشده؛ بنابراین اضافه کردن کلیدهای ناشناخته کمکی به پاسخ نمی‌کند و فقط پیچیدگی بی‌مورد می‌سازد.

جزئیات معماری، معیارهای انتخاب سرویس و جایگاه این API در فلوهای فین‌تک و PSP را در مرجع تصمیم‌گیری فنی وب‌سرویس استعلام شماره شبا ببینید. این مقاله روی نمونه درخواست، پاسخ و کد اجرا تمرکز دارد.

نمونه پاسخ JSON موفق از سرویس واقعی

پاسخ موفق شکل ثابتی دارد. ریشه شامل success برابر true و شیء data است. تیم بک‌اند معمولاً همین ساختار را به مدل داخلی map می‌کند.

{
  "success": true,
  "data": {
    "bank": "SEPAH",
    "depositNumber": "1234568791",
    "iban": "IR5201500000001234567891",
    "status": "ACTIVE",
    "owners": [
      {
        "firstName": "محمد",
        "lastName": "محمدی"
      }
    ],
    "bankName": "بانک سپه",
    "statusName": "فعال"
  }
}

در آرایه owners هر عضو firstName و lastName دارد. برای احراز مالکیت حساب در onboarding یا قبل از پرداخت، معمولاً نام برگشتی با داده ثبت‌نام کاربر مقایسه می‌شود و وضعیت حساب هم برای جلوگیری از واریز به حساب مسدود یا راکد بررسی می‌گردد.

اگر درخواست از نظر ساختار یا اعتبار شبا رد شود، با پاسخ validation-error طرف هستید، نه با همین شیء data. کدهای HTTP و پیام‌های خطای سرویس را جدا از مسیر موفق parse کنید تا UI یا worker شما روی فیلدهای ناموجود نشکند.

نمونه کد Python استعلام شبا با requests

نسخه زیر برای بک‌اند Python آماده است: توکن از محیط خوانده می‌شود، timeout تنظیم شده، وضعیت HTTP بررسی می‌شود و بدنه JSON برمی‌گردد. هاردکد توکن در سورس عمداً حذف شده است.

import os
import sys
import requests

url = "https://api.novin.one/v1/ibans"
token = os.environ.get("ACCESS_TOKEN")
if not token:
    sys.exit("ACCESS_TOKEN در محیط تنظیم نشده است")

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}
params = { "value": "IR5201500000001234567891", }

try:
    response = requests.get(url, headers=headers, params=params, timeout=30)
except requests.RequestException as exc:
    # خطای شبکه یا timeout؛ توکن را لاگ نکنید
    raise SystemExit(f"خطای ارتباط: {exc}") from exc

if response.status_code == 200:
    data = response.json()
    print(data)
elif response.status_code == 401:
    print("توکن نامعتبر یا منقضی است")
elif response.status_code == 400:
    print("درخواست بدساخت است", response.text)
elif response.status_code == 422:
    print("اعتبارسنجی شبا رد شد", response.text)
elif response.status_code == 429:
    print("محدودیت نرخ درخواست؛ بعداً با backoff محدود تلاش کنید")
else:
    print("پاسخ غیرمنتظره", response.status_code, response.text)

همین تابع را می‌توانید در سرویس داخلی یا worker یکپارچه‌سازی بپیچید و فقط value را از لایه دامنه بگیرید. الگوی هدر Bearer و خواندن توکن از env برای بقیه استعلام‌های مشابه در همان codebase قابل تکرار است.

نمونه کد Node.js استعلام شبا با axios یا fetch

برای تیم‌های Node.js دو مسیر رایج وجود دارد. ابتدا نسخه axios با async/await و همان قرارداد درخواست:

const axios = require("axios");

async function inquireIban(iban) {
  const token = process.env.ACCESS_TOKEN;
  if (!token) {
    throw new Error("ACCESS_TOKEN در محیط تنظیم نشده است");
  }

  try {
    const { data, status } = await axios.get(
      "https://api.novin.one/v1/ibans",
      { 
        params: { value: iban },
        headers: {
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json",
        },
        timeout: 30000,
        validateStatus: () => true, // مدیریت دستی کدها
      }
    );

    if (status === 200) return data;
    if (status === 401) throw new Error("توکن نامعتبر یا منقضی");
    if (status === 400) throw new Error(`درخواست بدساخت: ${JSON.stringify(data)}`);
    if (status === 422) throw new Error(`validation شبا: ${JSON.stringify(data)}`);
    if (status === 429) throw new Error("rate limit؛ retry محدود با backoff");
    throw new Error(`وضعیت غیرمنتظره ${status}`);
  } catch (err) {
    // پیام exception را بدون توکن و بدون داده حساس لاگ کنید
    throw err;
  }
}

inquireIban("IR5201500000001234567891")
  .then((res) => console.log(res))
  .catch((err) => console.error(err.message));

اگر وابستگی axios نمی‌خواهید، معادل fetch به‌صورت زیر است و برای میکروسرویس یا worker سبک مناسب است:

async function inquireIbanFetch(iban) {
  const token = process.env.ACCESS_TOKEN;
  if (!token) throw new Error("ACCESS_TOKEN تنظیم نشده");

const url = new URL("https://api.novin.one/v1/ibans");
url.searchParams.set("value", iban);

const response = await fetch(url, {
     method: "GET",
     headers: {
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json",
     },
});

  const data = await response.json().catch(() => ({}));

  if (response.status === 200) return data;
  if (response.status === 401) throw new Error("توکن نامعتبر یا منقضی");
  if (response.status === 400) throw new Error("درخواست بدساخت");
  if (response.status === 422) throw new Error("شبا نامعتبر یا ناقص");
  if (response.status === 429) throw new Error("محدودیت نرخ درخواست");
  throw new Error(`وضعیت ${response.status}`);
}

ماژول را export کنید تا در چند سرویس داخلی reuse شود و فراخوانی مستقیم از مرورگر انجام نشود.

مدیریت خطاهای رایج ۴۰۱، ۴۰۰، ۴۲۲ و ۴۲۹ در هر زبان

تفاوت کد خام با اتصال production در همین branching است. معنای عملی کدها را این‌طور در نظر بگیرید:

• ۴۰۱: توکن نامعتبر، منقضی یا حساب غیرفعال؛ معادل عملی پیام‌هایی مثل Forbidden در سمت سرویس.
• ۴۰۰: بدنه خالی یا ساختار نامعتبر درخواست.
• ۴۲۲: اعتبارسنجی شماره شبا رد شده؛ مثلاً شبا الزامی است یا شبا نامعتبر است.
• ۴۲۹: محدودیت نرخ یا سقف روزانه فراخوانی؛ فقط اینجا retry محدود با backoff منطقی است.

در cURL وضعیت را با -w "%{http_code}" یا بررسی خروجی اسکریپت بخوانید و برای غیر از ۲۰۰ مسیر جدا تعریف کنید. در Python مثل نمونه بالا بعد از requests.getروی status_code شاخه بزنید و متن پاسخ را بدون چاپ هدر Authorization نگه دارید. در Node.js یا axios، response.status را چک کنید و برای ۴۰۱ و ۴۲۲ هرگز حلقه retry کور نگذارید؛ اول توکن یا ورودی را درست کنید.

کدهای منطقی سرویس که ممکن است در بدنه خطا دیده شوند شامل مواردی مثل یافت نشدن شبا، یافت نشدن صاحب، الزامی بودن شبا، نامعتبر بودن شبا، بدنه نامعتبر، غیرمجاز بودن توکن، رسیدن به محدودیت روزانه، در دسترس نبودن سرویس‌دهنده و خطای داخلی سرور است. لاگ را طوری بنویسید که توکن، شبا کامل در محیط‌های غیرضروری و جزئیات حساس کاربر در CI دیده نشود.

امنیت توکن، متغیر محیطی و مرز بک‌اند و فرانت‌اند

هرگز access token را در کد فرانت‌اند، اپ موبایل یا ریپازیتوری عمومی قرار ندهید. نمونه کد Bearer Token استعلام شبا فقط روی سرور معنا دارد: مقدار ACCESS_TOKEN را در env یا secret manager بگذارید و هنگام اجرای فرایند به هدر تزریق کنید.

فراخوانی باید پشت BFF یا سرویس داخلی شما باشد. مرورگر کاربر نباید مستقیم به endpoint استعلام شبا با توکن سازمانی شما وصل شود. محیط dev، stage و prod را جدا کنید، سطح دسترسی توکن را حداقل نگه دارید و چرخش دوره‌ای توکن را در عملیات امنیتی تیم بگنجانید.

در pipeline و exception messageها هم مراقب نشت باشید. چاپ کامل headers، dump کردن process.env و الصاق توکن به URL از اشتباهات پرتکرار هستند. اگر لاگ درخواست لازم است، فقط شناسه همبستگی داخلی، کد وضعیت و نوع خطا را نگه دارید.

از نمونه کد تا اتصال واقعی: چک‌لیست یکپارچه‌سازی

قبل از wire کردن در production این ترتیب را طی کنید: دریافت توکن معتبر، تست cURL روی همان endpoint، پیاده‌سازی زبان هدف با خواندن env، پوشش شاخه‌های ۴۰۱ و ۴۰۰ و ۴۲۲ و ۴۲۹، حذف هر هاردکد، و مانیتورینگ نرخ ۴۲۹ به‌همراه ۵xx. بعد از پایدار شدن پاسخ ۲۰۰، mapping فیلدهای data را در دامنه کسب‌وکار قفل کنید تا تغییر UI باعث شکستن قرارداد نشود.

برای تصمیم معماری، قابلیت اطمینان و مقایسه جایگاه سرویس در فین‌تک و PSP به وب سرویس API استعلام شماره شبا: مرجع تصمیم‌گیری فنی رجوع کنید. صفحه سرویس و مستندات عملیاتی نیز از مسیر hub در دسترس است. این کلاستر پیاده‌سازی در کنار موضوعاتی مثل تبدیل کارت به شبا معنا پیدا می‌کند، اما endpoint، بدنه و پاسخ آن سرویس‌ها با استعلام مشخصات از روی شبا یکی نیست و نباید کد را جابه‌جا کپی کرد.

اگر همین مسیر را تا انتها بروید، تیم بک‌اند می‌تواند بدون بازنویسی boilerplate، سرویس را در محیط واقعی به سیستم onboarding، پرداخت یا احراز حساب وصل کند.

سوالات متداول

جمع‌بندی

با نمونه کد API استعلام شبا ارائه‌شده، مسیر عملی روشن است: یک GET به endpoint مشخص همراه با پارامتر Query به نام value، هدر Bearer، سه بلوک cURL و Python و Node.js، و مدیریت خطاهای رایج بدون هاردکد توکن. امنیت را روی مرز بک‌اند نگه دارید، پاسخ موفق را روی فیلدهای data مپ کنید و قبل از انتشار، چک‌لیست یکپارچه‌سازی را کامل کنید. برای شروع عملی و دریافت دسترسی سرویس، صفحه وب سرویس api استعلام شماره شبا را ببینید و اتصال را از محیط کنترل‌شده سرور آغاز کنید.