Skip to main content
#P1382

POST /api/v2/colleagues/billing

Route Info

این متد برای دریافت اطلاعات مالی کلی یک همکار (Colleague) یا پرسنل (Personnel) استفاده می‌شود. مسیر (Route) و میان‌افزارهای امنیتی آن به شرح زیر است:
Method
HTTPMethod Endpoint RouteController ControllerMiddleware FunctionPurpose Middlewareدسته‌بندی عملکردی
POST /api/v2/colleagues/billingauth/connect/branch ColleaguesControllerUserController@connectBranch general_billingV2ندارد domainAccess,اتصال ipTrustو معتبرسازی شعبه بر اساس کد ورودی برای پایان‌دامنه مرتبطAuthentication / Branch Connection

Request(Analysis) Parametersتحلیل عملکرد

این متدEndpoint یکبرای پارامترشناسایی ورودیو اصلیاعتبارسنجی شعبه است. هدف آن بارگزاری دامنه محیط (Unauthenticated) به عنوان نقطه ورود اولیه بدون نیاز به احراز هویت است. این درخواست با نامدریافت idکد شعبه ورودی، هویت دامنه مرتبط با آن دفتر را از بدنه‌ی درخواست دریافتبازگردانی می‌کند.

مکانیسم کدگذاری شعبه

سیستم از فرمول زیر برای استخراج شناسه واقعی شعبه از کد ارسالی استفاده می‌کند:
Actual Office ID = Input Branch Code - 1000
برای مثال اگر کد ورودی 1050 باشد، شناسه واقعی شعبه 50 خواهد بود.

منطق اعتبارسنجی

پس از استخراج شناسه واقعی، سیستم پارامتر زیر را بررسی می‌کند:
  • در جدول offices جستجو انجام می‌شود تا مطمئن شود شعبه فعال است.
  • در صورت یافت نشدن یا غیرفعال بودن، پاسخ خطا بازگردانده می‌شود.
  • اگر شعبه معتبر باشد، شناسه و اطلاعات دامنه مرتبط (domain) بازگردانده می‌شود.

(Inputs) ورودی‌ها

نام پارامترفیلد نوع داده الزامی توضیحاتتوضیح
idbranch stringInteger بله کد شعبه (شناسه مربوطواقعی به+ همکار یا پرسنل. اگر مقدار شامل - باشد، نوع از مقدار استخراج می‌گردد، در غیر این صورت مقدار نوع برابر colleague فرض می‌شود.1000)
نمونه

Processing Logic

منطق عملکرد متد بر اساس کد موجود در کنترلر به شرح زیر می‌باشد:
  • ابتدا مقدار $request->id بررسی می‌شود.
  • اگر این مقدار شامل خط تیرهدرخواست (-)Request باشد، نوع (type) و شناسه (id) از آن استخراج می‌شود؛ در غیر این صورت نوع پیش‌فرض colleague در نظر گرفته می‌شود.
  • در صورتی که نوع برابر با colleague باشد، تابع CronController:Body):colleaguesGeneralBilling($id) فراخوانی شده تا مانده سال جاری حساب محاسبه گردد.
  • خروجی برای نوع colleague به‌صورت زیر است:
{
  "CreditLimit"branch": {credit_amount},
  "CreditBalance": {credit_amount - balance}1050
}
در صورتی که type = personnel باشد:

(Outputs) 
{
  "CreditLimit": false,
  "CreditBalance": false
}

Error Handlingخروجی‌ها

در صورتیهمه که شرکت (همکار) یافت نشود یا اطلاعات نادرست باشد،حالات پاسخ زیرHTTP بازگردانده200 می‌شود:برمی‌گردد.

خروجی موفق:

HTTP{
  200"status": OKtrue,
  "office": {
    "id": 50,
    "domain": "example.domain.ir",
    "title": "دفتر مرکزی"
  }
}

خروجی ناموفق:

{
  "status": false,
  "message": "اطلاعاتکد شرکتشعبه بدرستیمعتبر ارسالنیست نشدهیا است.یافت نشد."
}

Response(Dependencies) Exampleوابستگی‌ها

  • UserController::connectBranch(Request
    • $request)OfficeDomainتستباPostman:

    (Typical

    ErrorCases)خطا
    نوع
  • مدل‌ها: درخواست
    		•  کدو وضعیت

    (Testing & Usage) تست و استفاده

    نمونه پاسخ
    موفق (Colleague)200 OK 
    POST /api/auth/connect/branch
Content-Type: application/json

{
  "CreditLimit"branch": 5000000,
  "CreditBalance": 27500001050
}
    پرسنل 200موارد OK
    • کد شعبه کوچکتر از 1000 یا غیرعددی
    • شعبه غیرفعال در جدول offices
    • عدم تعریف دامنه برای دفتر مربوطه

    (Implementation Details) جزئیات پیاده‌سازی

    public function connectBranch(Request $request)
{
    "CreditLimit"$branchCode = $request->branch;
    $actualId = $branchCode - 1000;
    $office = Office::find($actualId);

    if (!$office) {
        return response()->json(['status' => false, "CreditBalance":'message' false=> 'کد شعبه معتبر نیست یا یافت نشد.']);
    }

    return response()->json([
        'status' => true,
        'office' => [
            'id' => $office->id,
            'domain' => $office->domain,
            'title' => $office->title,
        ]
    ]);
}

    Notes(Conclusion) نتیجه‌گیری

    - پاسخ همواره با وضعیت HTTP 200 بازگردانده می‌شود، حتی در حالت خطا.
    - این متدEndpoint صرفاًیک جهتنقطه خواندنورود وضعیتکاربردی مالیبرای کللاگین سالدامنه‌ها جاریبدون طراحینیاز شدهبه احراز هویت اولیه است و هیچفرایند تغییریتشخیص دامنه بر اساس کد شعبه را ساده می‌کند.

    (Appendix) پیوست: نگهداری و امنیت

    • احراز ورودی قبل از تبدیل نوع: اطمینان از عددی بودن branch.
    • عدم نیاز به تزریق احراز JWT در داده‌هایاین اصلیمرحله ایجاد(unauthenticated).
      • نمی‌کند.
      -
    • پیشنهاد محاسبهبه ماندهمحدود وکردن سقفنرخ اعتباردرخواست‌ها برجهت مبنایجلوگیری اطلاعاتاز ثبت‌شدهSpam.
      • در
    حسابداری داخلی سیستم انجام می‌شود.
    Back to top