مرجع یکپارچه‌سازی‌های خارجی

تمام یکپارچه‌سازی‌های خروجی: کاربرد، زمان فعال‌شدن، نحوه احراز هویت، رفتار retry، fallbackها و تمام متغیرهای محیطی. سرویس‌های داخلی (کپچا، داده‌های پرس‌وجوی آفلاین) برای کامل‌بودن گنجانده شده‌اند.

فهرست
  1. درخت تصمیم مسیریابی پرس‌وجو
  2. فناوران — پلتفرم خسارت بیمه
  3. SandHub — درگاه پرس‌وجوی قدیمی
  4. پرس‌وجوی تجارت — درگاه block-inquiry (V2+)
  5. ESG — ارائه‌دهنده پرس‌وجوی تنانت پارسیان
  6. پیامک — درگاه‌های کاوه‌نگار و پارسیان
  7. سرویس هوش مصنوعی — تشخیص خسارت خودرو
  8. سرویس قیمت خودرو — جستجوی ارزش بازار
  9. پرس‌وجوی آفلاین — داده‌های fallback
  10. مرجع متغیرهای محیطی

۱ — درخت تصمیم مسیریابی پرس‌وجو

هر فایل تقصیر با فراخوانی "run-inquiries" آغاز می‌شود که بیمه‌نامه طرف مقصر را از یک ارائه‌دهنده خارجی دریافت می‌کند. اینکه کدام ارائه‌دهنده واقعاً فراخوانی می‌شود به سه عامل بستگی دارد: تنانت (CLIENT_ID)، نوع فایل (THIRD_PARTY در مقابل CAR_BODY) و اینکه آیا حالت API زنده در تنظیمات سیستم فعال است یا خیر. لایه داده‌های پرس‌وجوی آفلاین در جلوی هر سه ارائه‌دهنده قرار دارد.

انتخاب ارائه‌دهنده

برای هر پرس‌وجوی مبتنی بر پلاک:
  • درخواست همیشه با پلاک فعلی ارسال‌شده و بیمه‌گذار نهایی همان نوع بیمه انجام می‌شود. متادیتای انتقال اخیر هیچ استعلامی برای پلاک یا بیمه‌گذار قبلی ایجاد نمی‌کند.
  • ۱. بررسی داده‌های آفلاین (MongoDB) — اگر داده مطابق یافت شد، آن را برگردانده و تمام HTTP را رد کن.
  • ۲. اگر CLIENT_ID=8 (تنانت پارسیان/ESG) → مسیریابی به ESG /inquiry/policyByPlate یا /inquiry/policyByChassis.
  • ۳. در غیر این صورت → مسیریابی به پرس‌وجوی تجارت /block-inquiry-tejarat (THIRD_PARTY) یا /block-inquiry-tejarat/badane (CAR_BODY).
  • ۴. اگر system_settings.externalApis.sandHubUseLiveApi = false (پیش‌فرض) → پاسخ mock برگردانده شود به جای انجام فراخوانی‌های HTTP.

برای بررسی‌های هویت شخصی، گواهینامه، مالکیت و شبا:
  • اگر CLIENT_ID=8 → ESG /inquiry/person و /inquiry/sheba.
  • در غیر این صورت → تجارت/SandHub /personal-inquiry/tejarat-no، /driver-license-check، /ownership، /sheba/sheba-tejaratno.

تفاوت کلیدی — فرمت تاریخ تولد: SandHub/تجارت تاریخ تولد میلادی انتظار دارند (داخلی از جلالی تبدیل می‌شود). ESG مستقیماً تاریخ جلالی انتظار دارد.

اندپوینت‌های SandHub فقط در مسیرهای قدیمی کد استفاده می‌شوند. تمام جریان‌های فعال تقصیر V2+ از طریق ارائه‌دهندگان تجارت یا ESG می‌روند.

۲ — فناوران فعال

فناوران (apimanager.iraneit.com) پلتفرم ملی پرونده خسارت بیمه است. پس از اینکه کارشناس خسارت ارزیابی خود را ارسال می‌کند، سیستم به‌صورت خودکار یک خسارت ساختاریافته را از طریق یک پروتکل چهار مرحله‌ای به فناوران ارسال می‌کند. فناوران همچنین به‌عنوان منبع جستجوی code-listها (انواع تصادف، اجزای خودرو، کدهای شهر و غیره) در سراسر پلتفرم عمل می‌کند.

چرخه حیات احراز هویت

۱
GET AppToken — POST /EITAuthentication/GetAppToken با هدرهای appname + secret. هدر apptoken را برمی‌گرداند.
۲
Login — POST /EITAuthentication/Login با هدرهای appToken + userName + password. هدر authenticationToken را برمی‌گرداند.
۳
Cache — توکن در حافظه و پایدار در MongoDB (fanavaran_auth_tokens) ذخیره می‌شود. تا نیمه‌شب Asia/Tehran معتبر است — اولین فراخوانی پس از ۰۰:۰۰ یک توکن تازه دریافت می‌کند.
۴
تمام فراخوانی‌های بعدی چهار هدر شامل می‌شوند: authenticationToken، CorpId، ContractId، Location — مختص تنانت، hardcoded به ازای هر کلید FANAVARAN_CLIENT.

یک اثر انگشت پیکربندی (هش appName + secret + username + password + corpId + contractId + location) یک ورود تازه را زمانی که هر مدرکی تغییر کند، حتی قبل از نیمه‌شب، مجبور می‌کند.

پروتکل ارسال خسارت (۴ مرحله)

۱
خسارت پایه (GEN.03) — POST /car/third-party-car-financial-claims. داده‌های مالک، راننده، بیمه، وسیله نقلیه و تصادف را ارسال می‌کند. یک claimId و claimNo فناوران برمی‌گرداند. پیامک با هر دو شناسه برای مالک ارسال می‌شود.
۲
موارد خسارت (GEN.05) — POST /car/third-party-car-financial-claims/{claimId}/dmg-cases. یک ورودی به ازای هر قطعه آسیب‌دیده با شناسه کامپوننت، شدت و قیمت. سقف: کل ≤ ۵۳،۰۰۰،۰۰۰ تومان.
۳
پیوست‌ها (GEN.07) — POST /car/third-party-car-financial-claims/{claimId}/files. اسناد، تصاویر car-capture و ویدیوها که با شناسه فایل ارجاع داده شده‌اند.
۴
کارشناسی (GEN.08) — POST /car/third-party-car-financial-claims/{claimId}/expertise. متادیتای ارزیابی کارشناس (نقش کارشناس، تاریخ، نتیجه). ارسال را نهایی می‌کند.

هر چهار مرحله در مجموعه fanavaran_audit_logs با بدنه کامل درخواست/پاسخ، وضعیت HTTP، مدت زمان و کد ردیابی برای اشکال‌زدایی ثبت می‌شوند.

اندپوینت‌های Lookup

همه زیر https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/. نتایج روی دیسک (به ازای کلید مشتری) و در مجموعه MongoDB lookups کش می‌شوند. تنانت پارسیان قبل از درخواست API از DB می‌خواند؛ دیگران ابتدا به API می‌روند.

کاربردمسیر
گزینه‌های dropdown برای accidentReason (نگاشت شده به شناسه‌های محلی)/car/base-info/accident-causes
گزینه‌های accidentWay/car/code-list/accident-report-type
طبقه‌بندی استفاده از وسیله نقلیه/car/base-info/vehicle-use-types
روش پرداخت خسارت/car/code-list/dmg-pay-method
گزینه‌های نوع گواهینامه/car/base-info/driving-licence-types
طبقه‌بندی طرف مقصر/car/code-list/accident-culprit-type
گزینه‌های محل بازرسی/car/code-list/inspection-place
کدهای وضعیت کاهش قیمت/car/code-list/drop-amount-status
کاتالوگ کامپوننت (نگاشت به قطعات بیرونی/داخلی)/car/base-info/car-components
گزینه‌های شدت تصادف/car/code-list/accident-level
تطبیق INSURANCE_CORP_ID ← corpId فناوران/common/code-list/insurance-corp
انتخابگرهای شهر/استان/common/base-info/cities، /common/base-info/Provinces
دریافت بیمه‌نامه کامل بر اساس شناسه پس از استعلام/car/third-party-car-policies/{policyId}
جستجوی وسیله نقلیه بر اساس VIN/car/vehicles/inquiry-by-vin?vin=…
فهرست بیمه‌نامه‌ها برای یک کد ملی/common/Policies/inquiry-my-policies
دریافت رکورد مشتری بر اساس شناسه/common/customers/{customerId}
جستجوی طرف بر اساس کد ملی + تاریخ تولد/common/parties/inquiry-by-unique-identifier

مدیریت خطا و انعطاف‌پذیری

توضیحمکانیزم
۳ تلاش، ۵۰۰ ms ← ۱۰۰۰ ms backoff نمایی در تمام فراخوانی‌های HTTP.Retry
وقتی فناوران پیام فارسی "دوباره تلاش کنید" (یا tracking-code 500) برمی‌گرداند، یک مکث ۵ دقیقه‌ای در سطح تنانت فعال می‌شود. تمام فراخوانی‌ها در این پنجره بلافاصله 503 ServiceUnavailable دریافت می‌کنند — بدون فشار.Backoff گذرا
در ۴۰۱، توکن از حافظه و MongoDB پاک می‌شود؛ فراخوانی بعدی GetAppToken + Login تازه را فعال می‌کند.ابطال توکن
درخواست‌های همزمان ورود برای همان تنانت به یک Promise در حال پرواز جمع می‌شوند.حذف تکراری Inflight
هر مرحله (GET_APP_TOKEN، LOGIN و هر چهار مرحله ارسال) در fanavaran_audit_logs با وضعیت STARTED / SUCCESS / FAILURE، هدرهای کامل، بدنه و مدت زمان نوشته می‌شود.لاگ Audit
۲۰–۳۰ ثانیه به ازای هر فراخوانی HTTP.Timeout

پروفایل‌های تنانت (FANAVARAN_CLIENT)

سه پروفایل تنانت از پیش تعیین‌شده وجود دارد. پروفایل فعال توسط متغیر محیطی FANAVARAN_CLIENT انتخاب می‌شود. هر پروفایل appName، secret، username، password، CorpId، ContractId و Location هدرهای خود را به علاوه پیش‌فرض‌های payload (AccidentCityId و غیره) دارد.

شرکت بیمهکلید
بیمه پارسیانparsian
بیمه تجارت نوtejaratno
بیمه معلمmoallem

INSURANCE_CORP_ID یک رشته عنوان نمایشی است (مثلاً "بیمه پارسیان") که در برابر فهرست زنده فناوران insurance-corp تطبیق داده می‌شود تا corpId عددی مورد استفاده در ارسال‌ها را تولید کند. شناسه تطبیق‌یافته روی دیسک کش می‌شود.

۳ — SandHub قدیمی

SandHub درگاه پرس‌وجوی اصلی است. هنوز در کدبیس حضور دارد اما تمام جریان‌های فعال تقصیر (V2+) به ارائه‌دهنده پرس‌وجوی تجارت منتقل شده‌اند. اندپوینت‌های SandHub قابل فراخوانی هستند اما فقط از طریق مسیرهای قدیمی کد قابل دسترسی هستند. حالت mock آن توسط همان تنظیم سیستم sandHubUseLiveApi کنترل می‌شود.

احراز هویت

POST {SANHUB_BASE_URL}/user/login با بدنه JSON نام کاربری + رمز عبور. توکن در حافظه برای ۵۵ دقیقه کش می‌شود. در ۴۰۱، توکن پاک می‌شود و یک تلاش مجدد انجام می‌شود. ۳ تلاش با ۱۰۰۰ ms ← ۲۰۰۰ ms backoff نمایی.

اندپوینت‌ها

متدمسیرتوضیح
POST/block-inquiry-tejaratپرس‌وجوی بیمه‌نامه مبتنی بر پلاک (THIRD_PARTY). بدنه: leftTwoDigits، serialLetter، threeDigits، rightTwoDigits، nationalCode.
POST/block-inquiry-tejarat/badaneپرس‌وجوی بیمه‌نامه CAR_BODY. Timeout ۵۰ ثانیه (طولانی‌تر از استاندارد).
POST/personal-inquiry/tejarat-noبررسی هویت شخصی. بدنه: nationalCode + birthDate میلادی (داخلی از جلالی تبدیل می‌شود).
POST/driver-license-checkاعتبارسنجی گواهینامه. پرچم IsSucceed را برمی‌گرداند.
POST/ownershipبررسی مالکیت وسیله نقلیه. پرچم IsSuccess را برمی‌گرداند.
POST/sheba/sheba-tejaratnoاعتبارسنجی شبا / حساب بانکی. ReturnValue + HasError را برمی‌گرداند.

تمام اندپوینت‌ها پاسخ‌های mock کامل را زمانی که sandHubUseLiveApi=false در تنظیمات سیستم (پیش‌فرض) پشتیبانی می‌کنند. داده‌های mock قطعی هستند و به‌صورت محلی بدون هیچ فراخوانی HTTP تولید می‌شوند.

۴ — پرس‌وجوی تجارت فعال

درگاه فعال block-inquiry برای تمام تنانت‌های غیر ESG. در هر فراخوانی V2+ run-inquiries که CLIENT_ID ≠ 8 استفاده می‌شود. URL پایه قابل پیکربندی است؛ در تولید به همان هاست SandHub اشاره می‌کند اما از اعتبارنامه‌های جداگانه استفاده می‌کند.

احراز هویت

POST {TEJARAT_INQUIRY_BASE_URL}/user/login با بدنه JSON ایمیل + رمز عبور. توکن برای ۵۵ دقیقه کش می‌شود. ۲ تلاش با ۵۰۰ ms ← ۱۰۰۰ ms backoff. جدا از اعتبارنامه‌های SandHub — از TEJARAT_INQUIRY_EMAIL / TEJARAT_INQUIRY_PASSWORD استفاده می‌کند.

اندپوینت‌ها

متدمسیرتوضیح
POST/block-inquiry-tejaratپرس‌وجوی پلاک THIRD_PARTY. بدنه: فیلدهای پلاک + nationalCode. ابتدا داده آفلاین بررسی می‌شود.
POST/block-inquiry-tejarat/badaneپرس‌وجوی پلاک CAR_BODY. بدنه: part1–part4 (عددی) + nationalCode. همیشه زنده می‌شود (mock برای مسیر badane وجود ندارد).

وقتی sandHubUseLiveApi=false، مسیر THIRD_PARTY یک پاسخ mock بدون HTTP برمی‌گرداند. مسیر CAR_BODY همیشه API زنده را صرف‌نظر از این پرچم فراخوانی می‌کند.

۵ — ESG فعال (CLIENT_ID=8)

ESG یک درگاه API بیمه داخلی است که منحصراً توسط تنانت پارسیان (CLIENT_ID=8) استفاده می‌شود. برای تمام انواع پرس‌وجو زمانی که این تنانت فعال است، جایگزین تجارت/SandHub می‌شود. شکل پاسخ متفاوتی دارد، TTL توکن پویا دارد و تاریخ تولد را در فرمت جلالی انتظار دارد (نه میلادی، برخلاف SandHub/تجارت).

احراز هویت

POST {ESG_URL}/auth/login با بدنه JSON { username, password }. TTL توکن از فیلد expiresIn پاسخ خوانده می‌شود (پیش‌فرض ۱۴ دقیقه). ۲ تلاش با ۵۰۰ ms ← ۱۰۰۰ ms backoff. در ۴۰۱، توکن پاک و یک تلاش مجدد. URL پیش‌فرض: http://192.168.20.22:8085 (شبکه داخلی).

اندپوینت‌ها

متدمسیرتوضیح
POST/inquiry/policyByPlateجستجوی بیمه‌نامه مبتنی بر پلاک (THIRD_PARTY). بدنه: nationalCode، plk1–plk4. پاسخ قبل از ذخیره به فرمت قدیمی تجارت نگاشت می‌شود.
POST/inquiry/policyByChassisجایگزین مبتنی بر VIN/شاسی برای پرس‌وجوی پلاک. توسط اندپوینت‌های run-inquiries-vin فراخوانی می‌شود. از جستجوی شاسی ESG استفاده می‌کند (نه مسیر SandHub). بدنه: nationalCode، chassis.
POST/inquiry/personبررسی هویت شخصی. بدنه: nationalCode، birthDate (جلالی، نه میلادی).
POST/inquiry/shebaاعتبارسنجی شبا / حساب بانکی.

ESG هر پاسخ را به صورت { success: boolean, data: … } می‌پیچد. در envelope نرمال‌شده خطا، بک‌اند مقدار error.messageFa را بدون تغییر به فراخواننده برمی‌گرداند؛ فیلدهای فنی مانند message، providerMessage و providerCode برای ثبت لاگ و دسته‌بندی حفظ می‌شوند. خطای کسب‌وکاری «یافت نشد» به‌عنوان قطعی سرویس گزارش نمی‌شود. بررسی داده آفلاین-پرس‌وجو هنوز ابتدا اجرا می‌شود، قبل از هر فراخوانی HTTP ESG.

۶ — پیامک فعال

دو ارائه‌دهنده پیامک پشتیبانی می‌شوند: کاوه‌نگار (پیش‌فرض) و درگاه پیامک پارسیان. ارائه‌دهنده فعال توسط متغیر محیطی SMS_PROVIDER (یا SMS) انتخاب می‌شود. هر دو ارائه‌دهنده رابط درگاه داخلی یکسانی را پیاده‌سازی می‌کنند بنابراین لایه ارکستراسیون مستقل از ارائه‌دهنده است.

انتخاب ارائه‌دهنده

ارائه‌دهنده فعالمقدارمتغیر محیطی
کاوه‌نگار — api.kavenegar.comkavenegar (پیش‌فرض)SMS_PROVIDER (یا SMS)
درگاه پیامک پارسیان — PARSIAN_SMS_URLparsianSMS_PROVIDER (یا SMS)

اندپوینت‌های کاوه‌نگار

URL پایه: https://api.kavenegar.com/v1/{SMS_API_KEY}/

متدمسیرزمان استفاده
POSTsms/send.jsonپیام‌های متن ساده (مثلاً متن‌های اطلاع‌رسانی مبتنی بر کلید ذخیره‌شده در مجموعه sms_texts).
GETverify/lookup.jsonتمام پیام‌های مبتنی بر قالب (OTPها، لینک‌های دعوت، اطلاع‌رسانی کارشناس). پارامترها: receptor، token[، token2، token3، token10]، template.

درگاه پیامک پارسیان

URL پایه از PARSIAN_SMS_URL. احراز هویت: هدر X-PACKAGE-API-KEY + Authorization: Basic {PARSIAN_BASIC_TOKEN}. به‌صورت GET با پارامترهای URL-encoded ReceiverNumbers و Message ارسال می‌کند. پیام‌های قالب قبل از ارسال به یک بدنه متن ساده پیش‌رندر می‌شوند (معادل verify/lookup ندارد).

قالب‌های پیامک در حال استفاده

توکن‌هاماشهنام قالب
token = کد OTPورود OTP کاربر / اکتور، فراموشی رمز، OTPهای طرفAUTH_SMS_TEMPLATE (محیطی)
token = publicId، token2 = لینکطرف دوم لینک دعوت تقصیر را از طریق پیامک دریافت می‌کندyara724-invite-link
token = نوع فایل، token2 = نام خانوادگی کارشناس، token3 = لینککارشناس میدانی لینک را برای یک طرف ارسال می‌کندyara-field-expert-link
token = publicId، token2 = لینکاطلاع به طرف که طرف دیگر با رأی کارشناس موافقت کرده استyara-blame-agreement
token = publicId، token2 = لینکطرف زیان‌دیده مطلع می‌شود که جریان خسارت را پس از تکمیل تقصیر باز کندyara-claim-link
token = "تصادف"/"خسارت"، token2 = publicId، token3 = نام خانوادگی کارشناسکارشناس یک فایل تقصیر یا خسارت را قفل می‌کندyara-expert-lock
token = نوع فایل، token2 = publicId، token3 = لینککارشناس درخواست ارسال مجدد اسناد می‌دهدyara-resend-documents
token = نوع فایل، token2 = publicId، token3 = نام خانوادگی کارشناس، token10 = لینکطرف مطلع می‌شود که ارزیابی خسارت کارشناس را امضا کندyara-signature
token = publicId، token2 = claimId فناوران، token3 = claimNo فناورانارسال فناوران تأیید شد — با شماره و شناسه خسارت فناوران برای مالک خسارت ارسال می‌شودyara-fanavaran-claim

تمام فراخوانی‌های پیامک fire-and-forget هستند — هرگز throw نمی‌کنند. شکست‌ها log می‌شوند اما جریان اصلی را مسدود نمی‌کنند. یک مجموعه MongoDB sms_send_logs هر پیام خروجی را با نوع آن (OTP در مقابل TEMPLATE)، ارائه‌دهنده، نام قالب و وضعیت موفقیت/شکست ثبت می‌کند. پیام‌های متنی اطلاع‌رسانی (اختلاف طرفین، امضای یک طرف و غیره) در راه‌اندازی در مجموعه sms_texts seed می‌شوند و در زمان اجرا قابل ویرایش هستند.

۷ — سرویس هوش مصنوعی غیرفعال (کد موجود)

یک سرویس تشخیص خسارت خودرو مبتنی بر تصویر در کدبیس یکپارچه‌سازی شده است اما فراخوانی‌های HTTP آن کاملاً comment شده‌اند. ماژول در راه‌اندازی مقداردهی اولیه می‌شود، تلاش برای ورود می‌کند (در صورت شکست به صورت خاموش بلعیده می‌شود)، و یک متد aiRequestImage را expose می‌کند — اما فراخوانی‌های axios زیرین غیرفعال هستند. سرویس هیچ جریان تولیدی را تحت تأثیر قرار نمی‌دهد.

رابط مورد نظر (زمانی که دوباره فعال شود)

متدمسیرتوضیح
POST{AI_URL_V2}/auth/loginاحراز هویت با نام کاربری + رمز عبور. accessToken را برمی‌گرداند.
GET{AI_URL_V2}/auth/profileدریافت apiKey.key مورد نیاز به‌عنوان هدر درخواست gateway-api-key.
POST{AI_URL_V2}/services/car-damage/detector?version=ai-v7ارسال تصویر قطعه خودرو (multipart). downloadLink با نتیجه حاشیه‌نویسی‌شده را برمی‌گرداند.

وضعیت: هر سه فراخوانی در بلوک‌های axios.request(…) comment-شده پیچیده شده‌اند. CW_URL در .env.example نیست. برای فعال‌سازی مجدد، فراخوانی‌های axios login، getApiKey و aiRequestImage را uncomment کنید و AI_URL_V2، AI_USERNAME، AI_PASSWORD را پیکربندی کنید.

۸ — سرویس قیمت خودرو نیمه‌فعال

فقط در طول محاسبه کاهش قیمت کارشناس-خسارت استفاده می‌شود. وقتی یک کارشناس مقادیر شدت برای هر قطعه ارائه می‌دهد، سیستم قیمت‌های بازار بلادرنگ برای مدل خودروی آسیب‌دیده را دریافت می‌کند، سپس کاهش قیمت را با استفاده از فرمول محاسبه می‌کند: قیمت خودرو × ضریب سال × مجموع ضرایب قطعات ÷ ۴۰۰. سرویس دو منبع داده (اندپوینت) دارد که به‌صورت موازی امتحان می‌شوند.

اندپوینت‌ها

متدمسیرتوضیح
GET{CW_URL}price?akharinدریافت قیمت‌های بازار خودرو از منبع "آخرین". آرایه { carName, marketPrice } را برمی‌گرداند.
GET{CW_URL}price?hamrahدریافت قیمت‌های بازار خودرو از منبع "همراه". همان شکل پاسخ.

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

CW_URL در .env.example مستندسازی نشده است. این سرویس در صورت تنظیم نشدن متغیر، به‌صورت خاموش هیچ کاهش قیمتی تولید نخواهد کرد.

۹ — پرس‌وجوی آفلاین داخلی / fallback

لایه پرس‌وجوی آفلاین فراخوانی‌های پرس‌وجوی مبتنی بر پلاک را قبل از اینکه هر HTTP خارجی انجام شود رهگیری می‌کند. عمدتاً برای توسعه و تست (پلاک‌های شناخته‌شده از پیش seed شده) استفاده می‌شود اما همچنین به‌عنوان fallback انعطاف‌پذیری زمانی که سرویس‌های پرس‌وجوی زنده در دسترس نیستند عمل می‌کند. توسط یک پرچم پایگاه‌داده زمان اجرا کنترل می‌شود، نه یک متغیر محیطی.

نحوه کار

جزئیاتجنبه
مجموعه MongoDB offline-inquiries. اسناد شامل clientKey، فیلدهای نرمال‌شده پلاک، nationalCode و پاسخ از پیش ساخته‌شده raw + mapped برای برگرداندن هستند.ذخیره‌سازی
system_settings.offlineInquiry.enabled — پیش‌فرض true. تغییر از طریق PATCH /super-admin/system-settings/offline-inquiry.سوئیچ اصلی
پلاک نرمال‌شده (فقط ارقام، عربی→فارسی) + کد ملی + کلید مشتری فناوران باید همه مطابقت داشته باشند. اگر پیدا شد، بلافاصله برگردانده می‌شود؛ هیچ فراخوانی HTTP انجام نمی‌شود.ترتیب جستجو
فقط برای پرس‌وجوی block مبتنی بر پلاک (THIRD_PARTY) اعمال می‌شود. پرس‌وجوی CAR_BODY (/badane) همیشه API زنده را می‌زند.محدوده
system_settings.externalApis.sandHubUseLiveApi — وقتی false (پیش‌فرض)، حتی اگر هیچ داده آفلاینی مطابقت نداشته باشد، یک پاسخ mock داخلی برگردانده می‌شود به جای فراخوانی تجارت/ESG.پرچم API زنده

۱۰ — مرجع متغیرهای محیطی

تمام متغیرهای محیطی در سراسر تمام یکپارچه‌سازی‌ها، گروه‌بندی‌شده بر اساس سرویس. متغیرهای علامت‌گذاری‌شده با * در .env.example وجود ندارند.

فناوران

شرحمتغیر
کلید پروفایل تنانت فعال: parsian | tejaratno | moallemFANAVARAN_CLIENT
عنوان نمایشی شرکت بیمه‌گر (مثلاً "بیمه پارسیان") — در راه‌اندازی در برابر فهرست insurance-corp فناوران به یک corpId عددی تطبیق داده می‌شود.INSURANCE_CORP_ID

اعتبارنامه‌های هر تنانت (appName، secret، username، password، CorpId، ContractId، Location) در src/core/config/fanavaran-client.config.ts زیر SEED_FANAVARAN_CLIENT_PROFILES hardcoded شده‌اند.

SandHub (قدیمی)

شرحمتغیر
URL پایه برای SandHub. پیش‌فرض: http://82.99.202.245:3027SANHUB_BASE_URL
URL کامل ورود (معمولاً base + /user/login)SANHUB_URL_LOGIN
ایمیل ورود SandHubSANHUB_USERNAME
رمز عبور ورود SandHubSANHUB_PASSWORD

پرس‌وجوی تجارت

شرحمتغیر
URL پایه. پیش‌فرض: http://82.99.202.245:3027TEJARAT_INQUIRY_BASE_URL
ایمیل ورودTEJARAT_INQUIRY_EMAIL
رمز عبور ورودTEJARAT_INQUIRY_PASSWORD

ESG (فقط CLIENT_ID=8)

شرحمتغیر
به 8 تنظیم کنید تا ارائه‌دهنده پرس‌وجوی ESG برای تنانت پارسیان فعال شود.CLIENT_ID
URL پایه ESG. پیش‌فرض: http://192.168.20.22:8085 (شبکه داخلی)ESG_URL
نام کاربری ورود ESGESG_USERNAME
رمز عبور ورود ESGESG_PASSWORD

پیامک

شرحمتغیر
kavenegar (پیش‌فرض) یا parsianSMS_PROVIDER (یا SMS)
کلید API کاوه‌نگار (الزامی وقتی provider = kavenegar)SMS_API_KEY
نام قالب کاوه‌نگار برای پیام‌های OTP (مثلاً yara-otp)AUTH_SMS_TEMPLATE
URL پایه درگاه پیامک پارسیان (الزامی وقتی provider = parsian)PARSIAN_SMS_URL
مقدار هدر پیامک پارسیان X-PACKAGE-API-KEYPARSIAN_API_KEY
اعتبارنامه‌های رمزگذاری‌شده Base64 برای هدر Authorization: Basic …PARSIAN_BASIC_TOKEN
URL پایه فرانت‌اند — برای ساخت تمام لینک‌های دعوت + خسارت تعبیه‌شده در پیام‌های پیامک استفاده می‌شودURL

سرویس هوش مصنوعی

شرحمتغیر
URL پایه درگاه هوش مصنوعی. پیش‌فرض: https://ai-gw.ittalie.ir (استفاده نشده — سرویس غیرفعال است)AI_URL_V2
نام کاربری ورود سرویس هوش مصنوعی (استفاده نشده)AI_USERNAME
رمز عبور ورود سرویس هوش مصنوعی (استفاده نشده)AI_PASSWORD

سرویس قیمت خودرو

شرحمتغیر
URL پایه برای API قیمت بازار خودرو (مثلاً https://…/). در .env.example نیست. کاهش قیمت به‌صورت خاموش رد می‌شود اگر تنظیم نشده باشد.CW_URL *

عمومی / برنامه

شرحمتغیر
پورت HTTP (پیش‌فرض ۳۰۰۰). توسط fallback insurance-corp فناوران برای فراخوانی اندپوینت جستجوی محلی خودش استفاده می‌شود.PORT
true / false — چالش کپچای ورود را فعال/غیرفعال می‌کند. داخلی، بدون سرویس خارجی.CAPTCHA_ENABLED
TTL چالش کپچا به دقیقه.EXP_CAPTCHA_TIME
TTL کد یکبار مصرف به دقیقه.EXP_OTP_TIME