مفاهیم اولیه

1تعاریف

2شروع کار

برای استفاده از این سامانه باید پس از ورود به کنسول، مراحل زیر را طی کنید:

ساخت کلاینت

قبل از هر چیز شما باید یک کلاینت در کنسول توسعه دهندگان ایجاد نمایید. برای این منظور در منوی اپلیکیشن‌ها بر روی علامت (+) یا به اضافه کلیک کنید و اطلاعات خواسته شده را به شرح زیر وارد نمایید:

پس از ثبت درخواست شما منتظر تایید راهبر سامانه فینوتک است و تا قبل از تایید راهبر میتوانید درخواست خود را در صفحه اپلیکیشنها ویرایش کنید.

تایید کلاینت

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

دریافت توکن و فراخوانی سرویس

پس از تایید برنامه شما قادر خواهید بود با استفاده از روش های زیر سرویس های فینوتک را فراخوانی کنید:

3گرفتن توکن با رویکرد Client_Credential بدون حساب

رویکرد Client_Credential

فراخوانی سرویس‌های غیرحسابی از طریق این رویکرد انجام خواهد شد و رویکرد client credential برای این دسته از سرویس‌ها معتبر است.

در این رویکرد برنامه قادر خواهد بود با استفاده از یک رمز (token) سرویس‌های فینوتک را فراخوانی کند. از آنجا که این سرویس به منابع (resource) خود کلاینت نیاز دارد احتیاجی به دریافت اجازه دسترسی از کاربر بیرونی نخواهد بود.

برای فراخوانی این سرویس ها پس از وارد شدن به کنسول توسعه دهندگان فینوتک، وارد جزییات کلاینت شوید. در تب توکن‌ها و قسمت Client_Credential Token، اسکوپ(های) مورد نظر خود را انتخاب کرده و بر روی دکمه افزودن توکن کلیک کنید. اکنون می‌توانید مقدار توکن و رفرش توکن را مشاهده نمایید.

دریافت توکن

برای دریافت توکن با فراخوانی سرویس، می‌توانید به مستند دریافت توکن client_credential مراجعه نمایید و یا مراحل زیر را طی کنید: ابتدا باید یک درخواست POST به آدرس زیر ارسال شود.

https://api.finnotech.ir/dev/v2/oauth2/token

محیط سندباکس: https://sandboxapi.finnotech.ir/dev/v2/oauth2/token

درخواست باید شامل پارامتر های زیر در قسمت body به صورت JSON باشد:

• nid: کد ملی ۱۰ رقمی شخص فراخوانی کننده که باید به کلاینت دسترسی داشته باشد
• grant_type: این مقدار باید برابر client_credentials قرار گیرد
• scopes: اسکوپ‌(ها)یی که قصد فراخوانی آن را دارید.

"grant_type": "client_credentials"
, "nid": "0123456789"
, "scopes": "oak:deposit-to-iban:get"

همچنین درخواست باید شامل پارامتر های زیر در قسمت Header‌ باشد:

• Content-type: این مقدار باید برابر application/json قرار گیرد
• Authorization: این فیلد باید برابر رشته زیر فرستاده شود (بر اساس استاندارد Basic Authentication)

  Basic AuthenticationString

  مقدار AuthenticationString باید برابر Base64 از اطلاعات برنامه شما به صورت YOURCLIENTID:YOURCLIENTSECRET باشد. برای مثال اگر شناسه برنامه شما برابر firstapp باشد و رمز برنامه شما که در قسمت جزییات برنامه در کنسول قابل مشاهده است برابر 6932dddb927b76e54997 باشد، شما باید Base64 مقدار firstapp:6932dddb927b76e54997 را تولید کنید. در این صورت مقدار این هدر باید برابر مقدار زیر قرار گیرد

  Basic Zmlyc3RhcHA6NjkzMmRkZGI5MjdiNzZlNTQ5OTc=

پاسخ موفق از این سرویس شامل فیلد های زیر به صورت JSON خواهد بود:

• result که شامل پارامترهای زیر است:
  • value: توکنی که برای فراخوانی سرویس ها استفاده می‌شود
  • scopes: آرایه‌ای از اسکوپ‌(ها)یی که قصد فراخوانی آن را دارید.
  • lifeTime: عمر توکن به میلی ثانیه
  • creationDate: زمان ساخت توکن به صورت تاریخ شمسی YYYYMMDDHHmmss
  • refreshToken: اگر عمر توکن تمام شود با استفاده از این توکن و فراخوانی سرویس تمدید توکن قادر خواهید بود توکن جدید دریافت نمایید
• status: وضعیت فراخوانی سرویس
• error: جزییات خطا (در صورت بروز خطا)

به عنوان مثال پاسخ دریافتی از سرویس توکن به صورت زیر خواهد بود:

"result": {
    "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZyZXNoVG9rZW4iOiJVNWx0eGV1M3BuYm90UERHOXFQRlVFeTFoTGg5WmVmTHJNb2tQS29qc1AxajBjU0JQNEJLOFZJNkZVNjVzRGNTbjdwVk96UWFQOUVpaDQ1SzNDYnZwbnVERU5oY3BFQ1p0aEZWkh3Um9EVkk4cWNOMkE1NWxvODNSYXlWZncwWEdSTHloUWxXY2VwTE9vWHJ3VjJhMVhIUFZNeHhWYjdIZzJVWDQ1WURIaElkVTlGNjBiQThGeENhZzI0WXBHd2pCSE1jSVJwUjFXM052dTdyWERmUnc4blJ4uMnZHbGJiZThnRVF0Z1djZUNYZVRCeFhRQ1lpRThwMVZjWXNOSVI1IiwiY3JlYXRpb25EYXRlIjoiMTM5NzA3MzAxMTEzNTUiLCJsaWZlVGltZSI6ODY0MDAwMDAwLCJjbGllbnRJZCI6IjU4YTE3YzA3MzZhNjBlNWM2NTI3NGM2OCIsInVzZXJJZCI6IjAxMjM0NTY3ODkiLCJhY3RpdmUiOnRydWUsInNjb3BlcyI6WyJvYWs6ZGVwb3NpdC10by1pYmFuOmdldCJdLCJkZXBvc2l0cyI6W10sIm1vbnRobHlDYWxsTGltaXRhdGlvbiI6bnVsbCwibWF4QW1vdW50UGVyVHJhbnNhY3Rpb24iOm51bGwsImRlc3RpbmF0aW9uIjpudWxsLCJ0eXBlIjoiQ0xJRU5ULUNSRURFTlRJQUwiLCJpYXQiOjE1NDAxOTQyMzV9.ZplbUfe2De7r8RqpbyZ8Pbbf3lqzHoGi0esTXBJM6tM"
    , "scopes": [
        "oak:deposit-to-iban:get"
    ]
    , "lifeTime": 864000000
    , "creationDate": "13970720135334"
    , "refreshToken": "U5ltxeu3pnbotPDG9qPFUEy1hLh9ZefLrMokPKojsP1j0cSBP4BK8VI6FU6kds3FpVOzQaPZHwRoDVI8qcN2A55lo83RayVfw0XGRLyhQlWcepLOoXrwV2a1XHPVMxxVb7Hg2UX45YDHhIdU9F60bA8FxCag24YpGwjBHMcIRpR1W3Nvu7rXDfRw8nRx9Eih45K3CbvpnuDENhcpECZthFn2vGlbbe8gEQtgWceCXeTBxXQCYiE8p1VcYsNIR5"
}
, "status": "DONE"

4گرفتن توکن با رویکرد Authorization_Code

رویکرد authorization_code

در این رویکرد برنامه احتیاج به منابع (resource) سایر کاربران دارد (برای مثال صورتحساب بانکی کاربر)، بنابراین باید برای دسترسی به این منابع از کاربر اجازه بگیرد.

فرض کنید شما قصد دارید برنامه ای بسازید که به صورتحساب بانکی کاربرانتان احتیاج دارد. نمودار گردش کار برنامه شما برای دریافت این صورتحساب به صورت زیر خواهد بود.

1. کاربر از برنامه شما درخواست میکند که صورتحساب وی را از فینوتک دریافت کند.
2. سرور شما کاربر را به صفحه درخواست دسترسی (Authorization) فینوتک هدایت (Redirect) میکند.
3. کاربر به حساب کاربری بانک درخواستی وارد شده و به برنامه شما اجازه دسترسی به حسابهایش را میدهد.
4. فینوتک کاربر را به آدرس بازگشتی شما به همراه یک کد هدایت میکند.
5. سرور شما کد را دریافت میکند.
6. سرور برنامه با کد دریافت شده، از فینوتک درخواست توکن میکند.
7. سرور بانک در صورت صحیح بودن کد، توکن را برمی گرداند.
8. سرور شما با استفاده از توکن دریافت شده، سرویس صورتحساب را فراخوانی میکند.
9. سرور فینوتک پس از چک کردن توکن توسط بانک و اطلاع رسانی به فینوتک، صورتحساب کاربر را به سرور شما ارسال مینماید.
10. در صورت نیاز برنامه شما میتواند صورتحساب را در اختیار کاربر قرار دهد.

برای دریافت این نوع توکن، پس از وارد شدن به کنسول توسعه دهندگان فینوتک، وارد جزییات کلاینت شوید. در تب توکن‌ها و قسمت Authorization_Code Token اسکوپ(های) مورد نظر خود و آدرس بازگشتی را از منو انتخاب نمایید و برروی درخواست کد کلیک کنید. یک رشته کد به آدرس بازگشتی شما فرستاده می‌شود. کد را در قسمت مربوطه کپی کنید. با کلیک برروی دریافت توکن، توکن و رفرش توکن برای شما تولید می‌شود.

همچنین می‌توانید مراحل زیر را انجام دهید:

• درخواست دسترسی
• دریافت کد
• درخواست توکن
• فراخوانی سرویس ها

درخواست دسترسی

اولین قدم برای استفاده از این سرویس ها درخواست دسترسی از کاربر است. به این معنی که کاربر به برنامه‌ی شما اجازه فراخوانی سرویس ها را بدهد. به این منظور باید کاربر را به صفحه authorize فینوتک هدایت کنید. آدرس پایه سرویس authorize به صورت زیر است:

https://api.finnotech.ir/dev/v2/oauth2/authorize

شما باید پارامتر های زیر را مشخص کنید:

• client_id: شناسه ثبت شده برای کلاینت در سامانه فینوتک
• redirect_uri: آدرس بازگشتی کلاینت، دامنه این آدرس باید با دامنه ثبت شده به ازای آدرس بازگشتی کلاینت در فینوتک برابر باشد،‌ در غیر این صورت با خطا مواجه خواهید شد. لازم به ذکر است آدرسی که در این قسمت فرستاده میشود باید با آدرس بازگشتی ارسال شده در مرحله دریافت توکن برابر باشد.
• scope: اسکوپ (دسترسی) هایی که کاربر باید مجوز دسترسی به آنها را بدهد به صورت جدا شونده با کاما انگلیسی (comma separated). در صورتی که اسکوپ درخواستی شامل اسکوپ برداشت وجه از (oak:withdrawal-from:execute) یا مسدودی و رفع مسدودی (oak:block:*) باشد فیلد های limit و count باید ارسال شوند. نکته مهم: مقدار فیلد اسکوپ باید شامل اسکوپ های پایه بانک و یا شامل اسکوپ های سامانه های جنبی (مانند کیلید) باشد،‌ به عبارت دیگر نباید اسکوپ های پایه و اسکوپ های کیلید با هم ارسال شوند. در صورتی که نیاز به هر دو گروه اسکوپ هست باید اجازه دسترسی آنها جداگانه از کاربر اخذ شود. درباره جزییات سرویس‌هایی که در هر دسته (پایه و سامانه های جنب) قابل فراخوانی هستند در ادامه و در بخش فراخوانی سرویس توضیح داده شده است.
• response_type: نوع پاسخ که باید برابر code باشد
• limit: رشته عددی مشخص کننده حداکثر مبلغ انتقال وجه، این فیلد در صورتی لازم است که اسکوپ های درخواستی شامل اسکوپ برداشت وجه از یا مسدودی باشد. مقدار این فیلد باید کمتر یا مساوی مقدار حداکثر ثبت شده برای کلاینت در هنگام ثبت نام اولیه کلاینت باشد.
• count: رشته عددی مشخص کننده تعداد درخواست های انتقال وجه، این فیلد در صورتی لازم است که اسکوپ های درخواستی شامل اسکوپ برداشت وجه از یا مسدودی باشد. مقدار این فیلد باید کمتر یا مساوی مقدار حداکثر ثبت شده برای کلاینت در هنگام ثبت نام اولیه کلاینت باشد.
• destination: رشته عددی مشخص کننده شماره حساب مقصد انتقال وجه. این فیلد در صورتی لازم است که اسکوپ های درخواستی شامل اسکوپ برداشت وجه از یا مسدودی باشد. این حساب باید از بین حسابهای مقصدی باشد که در هنگام ثبت نام کلاینت تعیین شده بود.
• bank: کد بانک مقصد کاربر که قصد دسترسی به حساب آن را دارید. برای بانک اقتصاد نوین این مقدار برابر "en" می‌باشد و در صورت ارسال نکردن این پارامتر مقدار پیش فرض یعنی بانک آینده در نظر گرفته خواهد شد.
• state (اختیاری): این کد برای ردگیری درخواست توسط کلاینت استفاده می‌شود و در صورت ارسال به همراه کد به آدرس بازگشتی کلاینت برگردانده می‌شود

نمونه ی یک درخواست authorize در زیر آمده است:

https://api.finnotech.ir/dev/v2/oauth2/authorize?
client_id=drops&
response_type=code&
redirect_uri=https://www.drops.com/return&
scope=oak:withdrawal-from:execute&
limit=10000000&
count=10&
bank=062&
state=15467287

در صورتی که پارامتر ها به درستی مشخص شوند کاربر به صفحه‌ی دسترسی هدایت خواهد شد. برای مثال در نمونه زیر کاربر به صفحه دسترسی هدایت شده تا اجازه دسترسی به اسکوپ دریافت حساب ها را برای کلاینت اسموکی اپ اعطا کند.

دریافت کد

در صورتی که کاربر بر روی دکمه دسترسی دارد در صفحه authorize بانک کلیک کند، فینوتک کاربر را به آدرس برگشتی که در درخواست دسترسی ارسال کرده‌ است به همراه یک code هدایت میکند. به عنوان نمونه:

https://www.yourapplication.com/return?code=C49w1bza5brPU6ed&state=15467287

و در صورتی که کاربر بر روی دکمه دسترسی ندارد کلیک کند فینوتک کاربر را به آدرس برگشتی با پارامتر error برمیگرداند. به عنوان نمونه:

https://www.yourapplication.com/return?error=access_denied&state=15467287

دریافت توکن

پس از دریافت کد از سرویس بالا، سرور شما باید سرویس درخواست توکن را فراخوانی کند. برای این منظور باید یک درخواست POST به آدرس زیر ارسال شود.

https://api.finnotech.ir/dev/v2/oauth2/token

درخواست باید شامل پارامتر های زیر در قسمت body به صورت JSON باشد:

• code: کد دریافت شده در قسمت قبل
• grant_type: این مقدار باید برابر authorization_code‌ قرار گیرد
• redirect_uri: آدرس برگشت برنامه شما. نکته مهم: این آدرس باید با آدرس برگشتی که در سرویس authorize یا دسترسی ارسال شده برابر باشد
• bank: کد بانک مقصد (که از جدول بالا انتخاب کردید)

"grant_type": "authorization_code"
, "code": "C49w1bza5brPU6ed"
, "redirect_uri": "https://www.drops.com/return"
, "bank": "062"

همچنین درخواست باید شامل پارامتر های زیر در قسمت Header‌ باشد:

• Content-type: این مقدار باید برابر application/json قرار گیرد
• Authorization: این فیلد باید برابر رشته زیر فرستاده شود (بر اساس استاندارد Basic Authentication)

  Basic AuthenticationString

  مقدار AuthenticationString باید برابر Base64 از اطلاعات برنامه شما به صورت YOURCLIENTID:YOURCLIENTSECRET باشد. برای مثال اگر شناسه برنامه شما برابر firstapp باشد و رمز برنامه شما که در قسمت جزییات برنامه در کنسول قابل مشاهده است برابر 6932dddb927b76e54997 باشد، شما باید Base64 مقدار firstapp:6932dddb927b76e54997 را تولید کنید. در این صورت مقدار این هدر باید برابر مقدار زیر قرار گیرد

  Basic Zmlyc3RhcHA6NjkzMmRkZGI5MjdiNzZlNTQ5OTc=

پاسخ موفق از این سرویس شامل فیلد های زیر به صورت JSON خواهد بود:

• result: این فیلد دارای فیلد های زیر خواهد بود:
  • scopes — آرایه ای از اسکوپ‌های مجاز توکن
  • monthlyCallLimitation — حداکثر تعداد تراکنش ماهانه به ازای یک توکن
  • maxAmountPerTransaction — حداکثر مبلغ هر تراکنش به ریال
  • userId — کد ملی کاربر
  • creationDate — زمان ساخت توکن به صورت تاریخ شمسی YYYYMMDDHHmmss
  • type — نوع توکن (در اینجا CODE)
  • bank — کد بانک فرستاده شده
  • lifeTime — عمر توکن به میلی ثانیه
  • deposits — آرایه از شماره حساب های کاربر که توکن اجازه دسترسی به آن را دارد
  • clientId — نام اپلیکیشن
  • value — توکنی که برای فراخوانی سرویس ها استفاده میشود
  • refreshToken — اگر عمر توکن تمام شود با استفاده از این توکن و فراخوانی سرویس توکن قادر خواهید بود توکن جدید دریافت نمایید
• status: وضعیت فراخوانی سرویس
• error: جزییات خطا (در صورت بروز خطا)

به عنوان مثال پاسخ دریافتی از سرویس توکن به صورت زیر خواهد بود:

"result": {
    "scopes": [
        "oak:statement:get"
    ]
    , "monthlyCallLimitation": null
    , "maxAmountPerTransaction": null
    , "userId": "0012345678"
    , "creationDate": "13970720135334"
    , "type": "CODE"
    , "bank": "062"
    , "lifeTime": 864000000
    , "deposits": [
        "0202879784005"
    ]
    , "clientId": "smokey"
    , "randomUUID": "702EU5ZURmw4NeWV"
    , "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6Iko9VCJ9.eyJ0b2tlbklkIjoiYVI3aTZEeXhNc05MZkdCM2dDV0RM2YwKR3l5NzB1TWEiLCJzY29wZXMiOlsib2FrOnN3hXRlbWVudDpnZXQiXSwibW9udGhseUNhbGxMaW1pdGF0aW9uIjpudWxsLCJtYXhBbW91bnRLZXJUcmFuc2FjdGlvbiI6bnVsbCwidXNlcklkIjoiMDAxNTE0NzE2OSIsImNyZWF0aW9uRGF0ZSI6IjEzOTcwNzI1MTM1MzM0IiwidHlwZSI6IkNPREUiLCJiYW5rIjoiMDYyIiwibGlmZVRpbWUiOjg2NDAwMDAwMCwiZGVwb3NpdHMiOlsiMDIwMjg3OTc4NDAwNSJdLCJjbGllbnRJZCI6InNtb2tleSIsInJfumRvbVVVSUQiOiI3MDJFVTVaVVJtdzROZVdWIiwiaWF0IjoxNTM5NzcxODE0fQ.2oZIycxOxDRC5RNQvgtj4B2BT9-Zyh_tMmCiTBUpWbY",
    , "refreshToken": "sI2t91Bm7zwuORlHDIcdVAw4Ewal7Pz86xpT0w3URx9KQIk3NyWcYxkkzpiLemDWqsGihsc2wIuFvimjHHFXna33KDquF7SJYO8s7OorI5awCFoLu4crJuhqLyIviTje38AuN9TxQKFrzcf2v1yJgtstDTe4QJhRtTq3wzvPGEq8buwE5M1fWSw0Ekenf15h280Rm68oFG9G7qS8A0VUlfplcqwgwvpCD7jCQkTjNF6ZrItGt1KYuv5cS5DsPCwIPGmVxcUxW"
}
, "status": "DONE"

5تمدید توکن - Refresh Token

از آنجاییکه عمر توکن ها محدود است و مقدار آن در فیلد lifeTime همراه توکن ارسال شده است،‌ باید قبل از منقضی شدن توکن با ارسال رفرش توکن، توکن جدید را دریافت کنید. یک درخواست POST به آدرس زیر ارسال شود.

https://api.finnotech.ir/dev/v2/oauth2/token

درخواست باید شامل پارامتر های زیر در قسمت body به صورت JSON باشد:

• grant_type: این مقدار باید برابر refresh_token قرار گیرد
• refresh_token: رفرش توکن
• token_type: نوع توکن (CLIENT-CREDENTIAL یا CODE)
• bank: کد بانک (کد مربوط به هر بانک در جدول بالاتر- گرفتن توکن با رویکرد Authorization_Code - موجود است). در صورتی که توکن از نوع CLIENT_CREDENTIAL باشد نیازی به فرستادن این پارامتر نیست.

"grant_type": "refresh_token"
, "refresh_token": "sI2t91Bm7zwuORlHDIcdVAw4Ewal7Pz86xpT0w3URx9KQIk3NyWcYxkkzpiLemDWqsGihsc2wIuFvimjHHFXna33KDquF7SJYO8s7OorI5awCFoLu4crJuhqLyIviTje38AuN9TxQKFrzcf2v1yJgtstDTe4QJhRtTq3wzvPGEq8buwE5M1fWSw0Ekenf15h280Rm68oFG9G7qS8A0VUlfplcqwgwvpCD7jCQkTjNF6ZrItGt1KYuv5cS5DsPCwIPGmVxcUxW"
, "token_type": "CODE"
, "bank": "062"

همچنین درخواست باید شامل پارامتر های زیر در قسمت Header‌ باشد:

• Content-type: این مقدار باید برابر application/json قرار گیرد
• Authorization: این فیلد باید برابر رشته زیر فرستاده شود

  Basic AuthenticationString

  مقدار AuthenticationString باید برابر Base64 از اطلاعات برنامه شما به صورت YOURCLIENTID:YOURCLIENTSECRET باشد. برای مثال اگر شناسه برنامه شما برابر firstapp باشد و رمز برنامه شما که در قسمت جزییات برنامه در کنسول قابل مشاهده است برابر 6932dddb927b76e54997 باشد، شما باید Base64 مقدار firstapp:6932dddb927b76e54997 را تولید کنید. در این صورت مقدار این هدر باید برابر مقدار زیر قرار گیرد

  Basic Zmlyc3RhcHA6NjkzMmRkZGI5MjdiNzZlNTQ5OTc=

پاسخ درخواست بالا همانند درخواست دریافت توکن است.

6فراخوانی سرویس ها

اکنون که توکن را دریافت کرده اید، می توانید با استفاده از آن سرویس مورد نظر خود را فراخوانی کنید.

سرویس های فینوتک که با استفاده از oAuth قابل فراخوانی است در دو دسته اصلی زیر قرار می گیرد: سرویس های پایه بانکی و سرویس های سامانه های جنبی.

برای اطلاع از جزییات فراخوانی این سرویس ها به مستندات فنی سرویس‌های فینوتک مراجعه کنید.

7ساختار Response Code

در تمام ریسپانس‌ها، فیلد responseCode دارای یک الگوی ثابت است. ۵ رقم انتهایی این کد نشان‌دهنده وضعیت نهایی درخواست است.

اگر ۵ رقم آخر 00000 باشد، به معنای موفق بودن فراخوانی است.

هر مقدار دیگری به جز 00000 نشان‌دهنده ناموفق یا خطا در پردازش می‌باشد.

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

{
    "responseCode": "FN-FYVH-20001000000",
    "status": "DONE",
    "trackId": "trackId",
    "result": {}
}

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

{
    "responseCode": "FN-BRFH-40001000001",
    "status": "FAILED",
    "trackId": "trackId",
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "error"
    }
}

8شرایط و محدودیت‌های سرویس

به منظور رعایت مسائل امنیتی در سرویس‌های فینوتک و قوانین مربوطه در بانک مرکزی و بازار سرمایه شرایط و محدودیت‌هایی برای برخی از سرویس‌های فینوتک در نظر گرفته شده که در ادامه به آن‌ها اشاره شده است:

سقف پیش فرض بانکی

در فینوتک هر تراکنشی که منجر به انتقال پول شود، باید از سقف پیش فرض بانک کمتر باشد. برای مثال سقف انتقال وجه بین بانکی پایا در هر تراکنش برابر ۵۰۰ میلیون ریال است. در نتیجه هر تراکنش مالی که در فینوتک صورت میگیرد باید از این مقدار کمتر باشد، در غیر این صورت با خطا مواجه خواهد شد.

سقف روزانه پیش فرض برنامه (client)

در فینوتک هر برنامه قادر خواهد بود روزانه تا میزان خاصی که توسط راهبر بومرنگ مشخص میشود انتقال وجه مالی داشته باشد. در صورتی که میزان انتقال وجه ها در روز از این مقدار تجاوز کند با خطا مواجه خواهید شد.

محدودیت‌های سرویس واریز وجه

• سرویس انتقال وجه حساب به حساب، حساب به کارت بانکی آینده و همینطور پایا از ساعت ۲۳:۵۰ تا ۴:۳۰ غیرفعال میباشد و در صورت فراخوانی خطا برگردانده می‌شود
• اگر شماره شبا به عنوان حساب مقصد ارسال شود تا مبلغ ۵۰۰,۰۰۰,۰۰۰ ریال، انتقال وجه پایا انجام می‌شود.

سقف سرویس انتقال وجه کارت به کارت

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

محدودیت سرویس‌های خرید

حداقل مبلغ لازم جهت انجام عملیات خرید در سرویس‌های خرید موبایلی، ۱۰۰۰۰ ریال می‌باشد. لازم به ذکر است در صورت استفاده از کارت ملت، حداقل مبلغ خرید ۱۰۰۰۰۰ ریال می‌باشد.

سقف سرویس برداشت وجه از و سرویس مسدودی و رفع مسدودی

(oak:withdrawal-from:execute و oak:block:*)

• سقف مجاز به ازای برنامه: هنگام انتخاب اسکوپ سرویس برداشت وجه از و مسدودی و رفع مسدودی امکان تعیین سقف برای انتقال وجه های مالی وجود دارد که باید توسط سازنده برنامه مشخص شود. این مقدار باید توسط راهبر تایید شود و پس از تایید در قسمت جزییات برنامه قابل مشاهده خواهد بود. بدیهی است مقدار هر تراکنش انجام شده با استفاده از این سرویس باید از مقدار تعیین شده در این قسمت کمتر بوده و همچنین تعداد تراکنش ماهانه برنامه از مقدار وارد شده در این قسمت تجاوز نکند.
• سقف مجاز به ازای توکن: هنگام هدایت کاربر برای گرفتن دسترسی به منابع وی (سرویس دسترسی یا authorize) میتوان مقادیری کمتر از مقادیر تعیین شده برای برنامه تعیین کرد. بنابراین انتقال وجه های انجام شده توسط این توکن باید علاوه بر اینکه از مقادیر پیش فرض برنامه کمتر باشد از میزان این مقادیر هم تجاوز نکند.

9ملاحظات امنیتی

کلاینت ملزم است ملاحظات امنیتی زیر را رعایت کند:

• در آدرس بازگشت کلاینت، نباید هیچ اسکریپت خارجی وجود داشته باشد. در غیر اینصورت امکان افشا شدن آدرس بازگشت و یا دیگر پارامترها وجود دارد. در صورتی که نیاز به استفاده از اسکریپتهای خارجی وجود دارد باید اسکریپتی قبل از آنها اجرا شود که مقادیر حساس را از URI حذف نماید.
• در پاسخ به مرورگر کاربر، کلاینت (آدرس بازگشت کلاینت) نباید هیچ اطلاعات حساسی– از قبیل ادرس بازگشت یا مشخصات کلاینت - را در قسمت آدرس باقی بگذارد. در واقع کلاینت پس از دریافت کد اعطای دسترسی باید اطلاعات لازم را برداشته سپس کاربر را به آدرس دیگری هدایت کند که در آن هیچ اطلاعات حساسی وجود نداشته باشد.
• کلاینت برای انتقال کدهای دسترسی حتما باید از کانالی امن استفاده کند. بدین منظور پیاده‌سازی TLS برای کلاینت ضروری است.
• کلاینت نباید بیشتر از یکبار از یک کد اعطای دسترسی استفاده کند.
• در صورتی که پارامترهایی به دست کلاینت رسید که برایش تعریف نشده یا نامفهوم یا نامعتبر بودند، باید آنها را کاملا نادیده گرفته و از آنها استفاده نکند. مثلا اگر نوع توکن دسترسی برای کلاینت قابل قبول یا مفهوم نیست نباید آن توکن را دریافت کند.
• کلاینت حتما باید صحت TLS Certificate سرور را بررسی کند.
• کلاینت باید برای مقابله با تزریق کد یا حملات مشابه مقادیر دریافتی را پاکسازی کرده و اعتبار آنها را مورد ارزیابی قرار دهد.
• کلاینت باید ملاحظات مربوط به نگهداری امن توکن ها را رعایت کند و از هرگونه انتقال توکن پرهیز کند. (مسئولیت هر گونه سوء استفاده از توکن در صورت افشای آن به عهده کلاینت میباشد.)
• کلاینت باید امکان ابطال توکن (revoke) را به کاربران اعطا کند تا در هر زمانی بتوانند توکن های خود را غیر فعال کنند.