###POST /keylead/v2/clients/{clientId}/users/{nid}/deposits/{deposit}/requests * **شرح: ** یک درخواست انتقال وجه (تکی یا گروهی) در سامانه [کیـ.لید](https://key.ba24.ir) ایجاد میکند * **اسکوپ: ** ```kilid:request:create``` * **رویکرد: ** ```Authorization_Code``` ```````````````` {address}/keylead/v2/clients/{clientId}/users/{nid}/deposits/{deposit}/requests?trackId={trackId} ```````````````` <div class="sandboxaddress sandbox" id="sandbox" style="float:right" style="display: none" > https://sandboxapi.finnotech.ir<b><span class="finnotech-sandbox-address-text"> :address </span></b> </div> <div class="production-address production" style="float:right" style="display: block"> https://apibeta.finnotech.ir <b> :address </b> </div> <br><br> * سرویس‌های مرتبط : <table> <thead> <tr> <th style="text-align: center; vertical-align: middle;">ررویکرد CLIENT CREDENTIAL</th> <th style="text-align: center; vertical-align: middle;">رویکرد AUTHORIZATION CODE</th> <th style="text-align: center; vertical-align: middle;">حساب کاربر نهایی باید در بانک همکار باشد</th> <th style="text-align: center; vertical-align: middle;">حساب کاربر نهایی حقوقی است</th> <th style="text-align: center; vertical-align: middle;">حساب کاربر نهایی حقیقی است</th> <th style="text-align: center; vertical-align: middle;">نام سرویس</th> <th style="text-align: center; vertical-align: middle;">شماره ردیف</th> </tr> </thead> <tbody> ‪<tr> <td style="text-align: center; vertical-align: middle; "><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;">[مشاهده لیست دستور پرداخت‌ها](/kilid-requests.html?sandbox=+sandbox) </td> <td style="text-align: center; vertical-align: middle;">۱</td> </tr> <tr> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;">[مشاهده یک دستور پرداخت](/kilid-request.html?sandbox=+sandbox) </td> <td style="text-align: center; vertical-align: middle;">۲</td> </tr> <tr> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;">[ویرایش دستور پرداخت](/kilid-editRequest.html?sandbox=+sandbox) </td> <td style="text-align: center; vertical-align: middle;">۳</td> </tr> <tr> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;">[حذف یک دستور پرداخت](/kilid-deleteRequest.html?sandbox=+sandbox) </td> <td style="text-align: center; vertical-align: middle;">۴</td> </tr> <tr> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;">[مشاهده لیست حساب‌های فعال](/kilid-deposits.html?sandbox=+sandbox) </td> <td style="text-align: center; vertical-align: middle;">۵</td> </tr> <tr hidden> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;">[صورتحساب حساب‌های فعال](/kilid-statement.html?sandbox=+sandbox) </td> <td style="text-align: center; vertical-align: middle;">۶</td> </tr> <tr hidden> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;"><img src="png/checkCircle.png"></td> <td style="text-align: center; vertical-align: middle;">[استعلام مشتری](/kilid-user.html?sandbox=+sandbox) </td> <td style="text-align: center; vertical-align: middle;">۷</td> </tr> </tbody> </table> <div class="sandbox-address" id="sandbox" style="display: none"> درصورتی که از سندباکس استفاده میکنید: https://sandboxapi.finnotech.ir </div> #### Headers مقادیر زیر باید در هدر قرار بگیرد ```````````````` Authorization : Bearer {Token} Content-Type : application/json ```````````````` * برای فراخوانی این سرویس لازم است به اپلیکیشن خود، حساب یکی از بانک های همکار فینوتک را اضافه کنید و روی حساب افزوده شده توکن بگیرید. #### URI Parameters * **clientId: ** (اجباری) شناسه کلاینت * **nid :** بر اساس رویکرد * Authorization_Code: (اجباری) کد ملی کاربر صاحب حساب مبدا که برای برداشت از او اجازه گرفته اید و باید رشته عددی به طول ۱۰ رقم باشد * Client_Credential: (اجباری) کد ملی ایجاد کننده توکن ,کسی که در پنل توسعه دهندگان لاگین کرده , باید رشته عددی به طول ۱۰ رقم باشد * **deposit:** (اجباری) شماره حساب معتبر که باید رشته عددی به طول ۱۳ کاراکتر باشد #### Query Parameters * **trackId:** (اجباری) &#x202b; رشته ای با طول حداکثر ۴۰ کاراکتر شامل حرف و عدد. پیشنهاد ما برای trackId تولید کردن UUID است. در صورت نیاز به نتیجه یک فراخوانی میتوانید با trackId آن را فیلتر کنید. در گزارش فراخوانی سرویس فراخوانی مورد نظر را با همین کد پیگیری پیدا میکنید. * example: ```create-req-9603030098``` #### Body #####Example: ```````````````` { "destinations": [{ "amount": "12000" , "description": "توضیحات تراکنش" , "number": "IR120620000000203899754000" , "reference_code": "548201" , "name": "سیما نیمایی" }, { "amount": "185000" , "description": "پرداخت قبض" , "number": "02010707872221" , "reference_code": "100023" }] , "ceremonies": [ {"nid": "0012354541","order":1} , {"nid": "0070355699","order":2} ] , "note":"پرداخت آذر‌ماه" , "nationalCode":"0012457895" } ```````````````` * **destinations:** (اجباری) &#x202b; لیست گیرندگان انتقال وجه که پارامتر های آن در زیر شرح داده شده است * **amount:** (اجباری) &#x202b; مبلغ تراکنش، مقدار این فیلد اجباری است و باید یک عدد باشد * **name:** (اختیاری) &#x202b;نام دارنده‌ی حساب مقصد. در صورتی‌که مقصد شماره شبا باشد نام اجباری است. * **description:** &#x202b; شرح تراکنش، مقدار این فیلد باید رشته ای با حداکثر طول ۳۰ کاراکتر باشد. در صورتی‌که مقصد شبا باشد توضیحات اجباری است. * **number:** (اجباری) &#x202b; شماره حساب مقصد، این فیلد اجباری است و می‌تواند شماره حساب آینده با طول ۱۳ کاراکتر و یا شبای بانک‌های دیگر باشد * **reference_code:** &#x202b; کد پیگیری، مقدار این فیلد باید رشته ای عددی با حداکثر طول ۱۵ کاراکتر باشد * **ceremonies:** تشریفات درخواست، این فیلد اختیاری است و تعیین میکند افراد مجاز به چه ترتیبی درخواست را مشاهده و امضا کنند * **nid:** کد ملی امضادار یا کسی که اجازه مشاهده درخواست را دارد * **order:** ترتیب دیده شدن درخواست برای کد ملی که میتواند ۱، ۲ و یا ۳ باشد و مقدار پیش فرض آن برای همه ۲ است * **note:** یاداشت، مقدار این فیلد توضیحاتی در مورد دستور پرداخت می‌باشد * **nationalCode:** کد ملی شخصی که دسترسی ایجاد کننده روی حساب مربوطه در کیلید را داشته باشد ###Results Format #### Successful result format (status code 200) ```````````````` { "result": { "request": 75333, "number": "0201648361000", "created_date": "13950918112816", "status": "created", "last_update": "13950918112816", "ceremonies": [ { "nid": "0013977801", "order": 2 } ], "note": "پرداخت آذر‌ماه", "attachment": null, "destinations": [ { "id": 47562151, "request": 75333, "number": "02010707872221", "amount": 185000, "name": "سیما نیمایی", "description": "پرداخت قبض", "reference_code": "100023", "state": "ready", "failure_message": null, "transfer_type": "paya", "ref_code": null, "trackId": null, "payment_number": "100023", "pay_date": null, } { "id": 47562147, "request": 75333, "number": "IR120620000000203899754000", "amount": 12000, "name": "سیما نیمایی", "description": "توضیحات تراکنش", "reference_code": "548201", "state": "ready", "failure_message": null, "transfer_type": "internal", "ref_code": null, "trackId": null, "payment_number": "548201", "pay_date": null } ], "id": 75333 }, "status": "DONE" } ```````````````` * **request:** شناسه درخواست * **created_date:** تاریخ ساخته شدن درخواست * **last_update:** آخرین تاریخ به روز رسانی درخواست * **status:** وضعیت درخواست است که میتواند مقادیر زیر را داشته باشد * **done:** دستور پرداخت با موفقیت پرداخت شده و وضعیت آن پایان یافته است * **signed:** دستور پرداخت امضا شده و منتظر پرداخت شدن است * **deleted:** دستور پرداخت حذف شده است * **created:** دستور پرداخت ایجاد شده است * **pending:** دستور پرداخت حداقل یک امضا دارد و منتظر سایر امضا هاست * **inprogress:** دستور پرداخت پرداخت شده ولی هنوز جوابی نیامده است * **number:** شماره حساب مبدا که دستور پرداخت روی آن ایجاد شده است * **ceremonies:**&#x202b; تشریفات دستور پرداخت که مشخص کننده ترتیب افراد امضادار و یا افرادی که روی حساب دسترسی دارند است, به صورت آرایه ای از Object زیر است * **nid:** کد ملی فرد * **order:** ترتیب دسترسی که عدد ۱ بیانگر بالاترین دسترسی است * **note:** توضیحات دستور پرداخت * **attachment:** فایل پیوست دستور پرداخت * **destinations:** &#x202b; ردیف های دستور پرداخت که آرایه ای از Object با فیلد های زیر است * **number:** شماره حساب آینده و یا شبای مقصد * **amount:** مبلغ تراکنش * **state:** وضعیت * **description:** شرح * **reference_code:** شناسه پرداخت * **name:** نام صاحب حساب مقصد * **failure_message:** پیام خطا * **transfer_type:** نوع انتقال * **internal:** داخلی * **paya:** انتقال وجه پایا * **ref_code:** کد پیگیری * **pay_date:** تاریخ پرداخت * **note:** توضیحات دستور پرداخت * **history:**&#x202b; تاریخچه دستور پرداخت, که آرایه ای از action ها روی دستور پرداخت است * **nid:** کد ملی فردی که عملیات روی دستور پرداخت انجام داده است * **date:** تاریخی که عملیات روی دستور پرداخت انجام شده * **description:** شرح * **action:**&#x202b; عملیاتی که باعث ثبت history شده است * **create** * **sign** * **edit** * **pay** * **unsign** * **delete** * **first_name:** نام فردی که عملیات روی دستور پرداخت انجام داده است * **last_name:** نام خانوادگی فردی که عملیات روی دستور پرداخت انجام داده است * **signs:** آرایه ای از امضا های دستور پرداخت است * **trackId:** کد پیگیری که در فراخوانی سرویس فرستاده شده * **status: ** وضعیت فراخوانی سرویس * DONE: فراخوانی موفق سرویس * FAILED: فراخوانی ناموفق سرویس * **error:** جزییات خطا (در صورت بروز خطا) #### UnSuccessful result format ```````````````` { "result": { "code": 1 , "message": "invalid destination deposit" , "farsi_message": "حساب مقصد نامعتبر است" , "invalidParameter": { "amount": 1 , "description": "45216941584" , "number": "00201070797001" , "reference_code": "45216941584" } } , "status": "DONE" , "trackId": "create-req-9603030098" } ```````````````` * در صورتی که با خطای ۴۰۰ مواجه شوید،‌ پارامتر invalidParameter شامل سطر دارای خطا خواهد بود * برای مشاهده خطاهای عمومی میتوانید به صفحه [لیست خطاها](/generic-errors.html) مراجعه کنید