Finnotech API Proxy

این پروژه یک پروکسی API برای سرویس‌های فینوتک است که امکان استفاده راحت‌تر از API های فینوتک را فراهم می‌کند.

اندپوینت‌ها

1. دریافت اطلاعات کارت

GET /cards/:card

پارامترها:

• card: شماره کارت 16 رقمی
• trackId (اختیاری): کد پیگیری (حداکثر 40 کاراکتر الفبا-عددی)

مثال:

GET /cards/6037991123456789?trackId=card-info-123

پاسخ موفق:

{
  "result": {
    "destCard": "6037991123456789",
    "name": "نام دارنده کارت",
    "bankName": "نام بانک",
    "result": "SUCCESS",
    "description": "توضیحات",
    "doTime": "2024-03-14T10:30:00"
  },
  "status": "DONE",
  "trackId": "card-info-123"
}

2. تبدیل شماره کارت به شبا

GET /cards/:card/iban

پارامترها:

• card: شماره کارت 16 رقمی
• trackId (اختیاری): کد پیگیری (حداکثر 40 کاراکتر الفبا-عددی)

مثال:

GET /cards/6037991123456789/iban?trackId=card-to-iban-123

پاسخ موفق:

{
  "result": {
    "IBAN": "IR123456789123456789123456",
    "bankName": "نام بانک",
    "deposit": "1234567890",
    "card": "6037991123456789",
    "depositStatus": "02",
    "depositOwners": "نام صاحب حساب"
  },
  "status": "DONE",
  "trackId": "card-to-iban-123"
}

3. ارسال پیامک شاهکار

GET /kyc/shahkar/sms

پارامترها:

• mobile: شماره موبایل (11 رقم، شروع با 09)
• nationalCode: کد ملی (10 رقم)
• trackId (اختیاری): کد پیگیری (حداکثر 40 کاراکتر الفبا-عددی)

مثال:

GET /kyc/shahkar/sms?mobile=09123456789&nationalCode=1234567890&trackId=shahkar-sms-123

پاسخ موفق:

{
  "responseCode": "FN-KCAT-20000100000",
  "trackId": "shahkar-sms-123",
  "result": {
    "smsSent": true
  },
  "status": "DONE"
}

4. تایید پیامک شاهکار

GET /kyc/shahkar/verify

پارامترها:

• otp: رمز یکبار مصرف (6 رقم)
• inquiryTrackId: کد پیگیری دریافتی از مرحله ارسال پیامک
• trackId (اختیاری): کد پیگیری جدید (حداکثر 40 کاراکتر الفبا-عددی)

مثال:

GET /kyc/shahkar/verify?otp=123456&inquiryTrackId=shahkar-sms-123&trackId=shahkar-verify-123

پاسخ موفق:

{
  "responseCode": "FN-KCAT-20004500000",
  "trackId": "shahkar-verify-123",
  "result": {
    "isValid": true
  },
  "status": "DONE"
}

5. تطبیق کد ملی و شماره موبایل

GET /shahkar/verify

پارامترها:

• mobile: شماره موبایل (11 رقم، شروع با 09)
• nationalCode: کد ملی (10 رقم)
• trackId (اختیاری): کد پیگیری (حداکثر 40 کاراکتر الفبا-عددی)

مثال:

GET /shahkar/verify?mobile=09123456789&nationalCode=1234567890&trackId=shahkar-verify-123

پاسخ موفق:

{
  "responseCode": "FN-FYVR-20001000000",
  "trackId": "shahkar-verify-123",
  "result": {
    "isValid": true
  },
  "status": "DONE"
}

6. تطبیق شماره شبا و کدملی

GET /kyc/iban-owner-verification

پارامترها:

• nid: کد ملی صاحب حساب (10 رقم)
• iban: شماره شبا (26 کاراکتر، شروع با IR)
• trackId (اختیاری): کد پیگیری (حداکثر 40 کاراکتر الفبا-عددی)

مثال:

GET /kyc/iban-owner-verification?nid=6661111111&iban=IR111111111111111111111111&trackId=iban-nid-verify-123

پاسخ موفق:

{
  "responseCode": "FN-KCFH-20002800000",
  "trackId": "iban-nid-verify-123",
  "result": {
    "isValid": "yes"
  },
  "status": "DONE"
}

پاسخ ناموفق:

{
  "status": "FAILED",
  "error": {
    "code": "ERROR_CODE",
    "message": "توضیحات خطا"
  }
}

کدهای وضعیت depositStatus در پاسخ تبدیل کارت به شبا

• 02: حساب فعال است
• 03: حساب مسدود با قابلیت واریز
• 04: حساب مسدود بدون قابلیت واریز
• 05: حساب راکد است
• 06: بروز خطا در پاسخ دهی
• 07: سایر موارد

مدیریت خطاها

تمام اندپوینت‌ها در صورت بروز خطا، پاسخی با این ساختار برمی‌گردانند:

{
  "status": "FAILED",
  "error": {
    "code": "ERROR_CODE",
    "message": "توضیحات خطا"
  }
}

نکات مهم

1. تمام درخواست‌ها باید با متد GET ارسال شوند
2. همه پارامترهای trackId اختیاری هستند
3. در سرویس شاهکار، inquiryTrackId مرحله دوم باید همان trackId دریافتی از مرحله اول باشد
4. اعتبارسنجی‌های زیر انجام می‌شود:
   • شماره کارت: دقیقاً 16 رقم
   • شماره موبایل: 11 رقم، شروع با 09
   • کد ملی: دقیقاً 10 رقم
   • OTP: دقیقاً 6 رقم
   • trackId: حداکثر 40 کاراکتر الفبا-عددی
   • inquiryTrackId: حداکثر 40 کاراکتر الفبا-عددی

راه‌اندازی

1. فایل env.example را به .env کپی کنید
2. مقادیر متغیرهای محیطی را در فایل .env تنظیم کنید:

   # Finnotech API Configuration
   FINNOTECH_BASE_URL=https://sandboxapi.finnotech.ir # یا https://api.finnotech.ir برای پروداکشن
   FINNOTECH_CLIENT_ID=YOUR_CLIENT_ID
   FINNOTECH_CLIENT_SECRET=YOUR_CLIENT_SECRET
   FINNOTECH_NID=YOUR_NATIONAL_ID
   
   # Server Configuration
   PORT=3000
   HOST=0.0.0.0

3. نصب وابستگی‌ها:

   npm install

4. اجرای برنامه:

   # برای محیط توسعه
   npm run dev
   
   # برای محیط پروداکشن
   npm run build
   npm start