مستند درگاه ارتباطی
در این مستند به معرفی سرویس های اعتباری بالون پرداخته میشود.
سرویس گیرندهگان میتوانند بعد از عقد قرارداد با بالون از طریق این درگاه اقدام به اعطای تسهیلات به کاربران خود کنند.
احراز هویت
دریافت توکن
import requests
data = {
'username': 'username',
'password': 'password'
}
response = requests.post('https://api.baloan.ir/api/v1/partnership/token/', data=data)
curl -X POST -d username=username -d password=password \
https://api.baloan.ir/api/v1/partnership/token/
Successful response:
{
"refresh":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0bmVzaCIsImV42ODM5MDU5MSwiaWF0IjoxNjY4M",
"access":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.6Xg5lfYhy5DqJbHNT2XZ_crZrv8QmXyrNqN4RG-Q-pU"
}
سرویس گیرنده برای ورود به درگاه اعتباری بالون باید از username و password دریافت شده بعد از عقد قرارداد استفاده کنند.
احراز هویت
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
-H "Authorization: Bearer {accesstoken}"
response = requests.post('your_endpoint', headers={'Authorization': f'Bearer {accesstoken}'})
You must replace
accesstokenwith your access key in token request.
برای تمام درخواستهای بعدی باید این مقدار در هدر درخواست ست شده باشد:
Authorization: Bearer accesstoken
وام های قابل اعطا
در این سرویس سیاست های وام دهی به همراه لیست فروشگاه ها ارائه شده است
curl --location 'https://api.baloan.ir/api/v1/partnership/loan-policies' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer {accesskey}'
import requests
headers = {
'Accept-Language': 'en',
'Authorization': 'Bearer {accesskey}',
}
response = requests.get('https://api.baloan.ir/api/v1/partnership/loan-policies', headers=headers)
You must replace
accesstokenwith your access key in token request.Successful response:
[
{
"stores": [
{
"id": 1,
"title_fa": "فروشگاه اول",
"logo": "https://first-store.logo.sample"
},
{
"id": 2,
"title_fa": "فروشگاه دوم",
"logo": "https://second-store.logo.sample"
},
],
"amount": {
"lower": 10,
"upper": 30,
"bounds": "[)"
},
"possible_loan_dues": [
12
],
"bank_effected_interest_rate": 22,
"installment_formula": "(amount+(amount*bank_effected_interest_rate)/100)/loan_due"
}
]
- Response fields:
| field | description |
|---|---|
| stores | لیستی از فروشگاه ها به همراه نام، id و لوگو |
| amount | بازه وام بصورت میلیون تومان |
| possible_loan_dues | لیستی از مدت های بازپرداخت |
| bank_effected_interest_rate | درصد سود بانکی |
| installment_formula | فرمول مصاحبه افساط ماهانه |
تشکیل پرونده وام
تشکیل پرونده
این سرویس برای ازسال اطلاعات هویتی مورد نیاز برای تشکیل پرونده ی فرد استفاده میشود که ضمانت نیز قفل میشود
curl --location 'https://api.baloan.ir/api/v1/partnership/loan/' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accesstoken}' \
--data '{
"phone_number": "09123456789",
"national_identifier": "07148143380",
"birth_date": "1999-02-14",
"amount": 10000000,
"loan_due": 12,
"store": 1
}'
import requests
import json
url = 'https://api.baloan.ir/api/v1/partnership/loan/'
headers = {
'Accept-Language': 'en',
'Content-Type': 'application/json',
'Authorization': 'Bearer {accesstoken}'
}
data = {
"phone_number": "09123456789",
"national_identifier": "07148143380",
"birth_date": "1999-02-14",
"amount": 10000000,
"loan_due": 12,
"store": 1
}
response = requests.post(url, headers=headers, data=json.dumps(data))
You must replace
accesstokenwith your access key in token request.Successful response:
{
"phone_number": "09123456789",
"national_identifier": "07148143380",
"birth_date": "1999-02-14",
"amount": 10000000,
"loan_due": 12,
"store": 1,
"uuid": "a71b93c4-b1a9-4868-9cb2-310757422af1",
"plan_detail": {
"monthly_installment_amount": 1057616,
"total_payback": 12691397
}
}
- Request fields:
| field | description |
|---|---|
| phone_number | شماره تماس کاربر |
| national_identifier | کد ملی کاربر |
| birth_date | تاریخ تولد کاربر بصورت میلادی در قالب YYY-MM-DD |
| amount | مبلغ وام درخواستی بصورت تومان |
| loan_due | مدت بازپرداخت وام |
| store | id فروشگاه |
- Response fields:
| field | description |
|---|---|
| phone_number | شماره تماس کاربر |
| national_identifier | کد ملی کاربر |
| birth_date | تاریخ تولد کاربر بصورت میلادی در قالب YYY-MM-DD |
| amount | مبلغ وام درخواستی بصورت تومان |
| loan_due | مدت بازپرداخت وام |
| store | id فروشگاه |
| uuid | uuid وام |
| monthly_installment_amount | مبلغ اقساط ماهانه |
| total_payback | مبلغ بازپرداخت نهایی |
دریافت قرارداد
پس از تایید چک قرار داد وام کاربر ایجاد شده و در این سرویس ارسال میشود.
curl -X GET --location 'https://api.baloan.ir/api/v1/partnership/loan/{loan-uuid}/contract/' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer {accesstoken}'
import requests
import json
url = 'https://api.baloan.ir/api/v1/partnership/loan/{loan-uuid}/contract/'
headers = {
'Accept-Language': 'en',
'Authorization': 'Bearer {accesstoken}'
}
response = requests.get(url, headers=headers)
You must replace
accesstokenwith your access key in token request.Be sure to replace
loan-uuidwith the unique identifier of the desired loan.Successful response:
{
"contract_pdf_file": {
"uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
"file": "https://contract-file.sample"
},
"is_agreed_by_user": false
}
- Response fields:
| field | description |
|---|---|
| contract_pdf_file | فایل قرارداد |
| is_agreed_by_user | قرارداد توسط کاربر تایید شده یا خیر |
صدور otp و ارسال برای کاربر
پس از در یافت قرارداد از این سرویس برای صدور otp برای کاربران استفاده میشود.
curl -X POST --location 'https://api.baloan.ir/api/v1/partnership/loan/{loan-uuid}/contract/' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer {accesstoken}'
import requests
import json
url = 'https://api.baloan.ir/api/v1/partnership/loan/{loan-uuid}/contract/'
headers = {
'Accept-Language': 'en',
'Authorization': 'Bearer {accesstoken}'
}
response = requests.post(url, headers=headers)
You must replace
accesstokenwith your access key in token request.Be sure to replace
loan-uuidwith the unique identifier of the desired loan.
ارسال otp جهت امضای قرارداد
در این سرویس otp ارسالی برای کاربر دیافت شده و پرونده کاربر تایید نهایی میشود.
curl -X PATCH --location 'https://api.baloan.ir/api/v1/partnership/loan/{loan-uuid}/contract/' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer {accesstoken}' \
--data '{
"otp": "12345",
}'
import requests
import json
url = 'https://api.baloan.ir/api/v1/partnership/loan/{loan-uuid}/contract/'
headers = {
'Accept-Language': 'en',
'Authorization': 'Bearer {accesstoken}'
}
data = {
"otp": "12345",
}
response = requests.patch(url, headers=headers, data=json.dumps(data))
You must replace
accesstokenwith your access key in token request.Be sure to replace
loan-uuidwith the unique identifier of the desired loan.
سرویس call back
در این سرویس تمامی تغییرات در وضعیت پرونده وام با استفاده از سرویس ارایه شده توسط شما با uuid وام اطلاع رسانی خواهد شد.
Successful response samples:
{
"uuid": "d4c22af9-3676-4c6e-ab72-2a7b5b22afc5",
"state": "cheque_verified"
}
{
"uuid": "d4c22af9-3676-4c6e-ab72-2a7b5b22afc5",
"state": "blocked/canceld",
"reason": "reason of blocked or cancled"
}
لیست status پرونده وام به شکل زیر قابل مشاهده است
| status_slug | نام فارسی | توضیحات |
|---|---|---|
| created | ایجاد شده | وام تازه ایجاد شده و در انتظار بررسی است. |
| cheque_verified | وام تکمیل شد | وام تکمیل شد و آماده ارسال به بانک است. |
| send_loan_to_bank | ارسال وام به بانک | وام به بانک جهت بررسی واریز ارسال شده است. |
| loan_paid | وام پرداخت شده | وام به طور کامل پرداخت شده و فرآیند تکمیل شده است. |
| blocked | مسدود شده | وام به دلایل مختلف مسدود شده است. |
| canceled | لغو شده | وام توسط کاربر یا سیستم لغو شده است. |
لیست خطاهای سرویس وام
خطاهای احتمالی در فرایند دریافت وام (با استتوس کد 400)
| پیام خطا | کد خطا |
|---|---|
| ورود نامعتبر | unauthorized_partnership |
| شماره تماس ارسالی قبلاً در سیستم ما با کد ملی دیگری ثبت شده است. لطفاً شماره تماس جدیدی وارد کنید تا بتوانیم حساب کاربری شما را ایجاد کنیم. | phone_number_exist_with_another_national_id |
| کد ملی ارسالی پیش از این در سامانه با شماره تماس {phone_number} ثبت شده است. لطفا با شماره تماس صحیح درخواست را ثبت کنید. | national_id_exists_with_another_phone_number |
| تاریخ تولد وارد شده در بازه سنی مجاز نیست. لطفاً اطمینان حاصل کنید که سن شما بین ۱۸ تا ۷۰ سال باشد. | age_not_in_valid_range |
| تاریخ تولد وارد شده نامعتبر است. لطفاً اطمینان حاصل کنید که تاریخ تولد به فرمت صحیح (YYYY-MM-DD) میلادی وارد شده باشد. | invalid_date_format |
| مبلغ یا مدت تسهیلات اعلامی خارج از بازه مجاز سیاستهای فروشگاه شما است. لطفاً مبلغ تسهیلات را با توجه به سیاستهای وامگیری فروشگاه انتخاب کنید | loan_due_or_amount_not_match_store_policies |
| کاربر گرامی، متاسفانه بهدلیل عدم تطابق اطلاعات شما در سامانه شاهکار (مغایرت شماره تلفن با کدملی) درخواست وام شما غیر قابل بررسی میباشد. | national_phone_verification_failed |
| استعلام سرویس {service_name} با خطا مواجه شد. | service_inquiry_failed |
| امکان تغییر فیلد در این وضعیت وجود ندارد. لطفا دوباره وضعیت وام را چک کنید. | can_not_update |
| لغو وام با مشکل مواجه شد. | failed_to_cancel_loan |
| در این وضعیت امکان ندارد. لطفا دوباره وضعیت وام را چک کنید. | not_allowed_in_state |
| قرارداد درحال حاضر توسط کاربر امضا شده است. | already_agreed_by_user |
| درخواست تکراری | duplicate_request |
| درخواستی برای تایید وجود ندارد | no_request_to_verify |
| کد اشتباه است. | incorrect_otp_code |
| دوباره درخواست دهید. | throttled_otp_code |
| مبلغ درخواستی بیشتر از حد اعتبار مجاز کاربر است. | loan_amount_exceed_user_credit |
لغو پرونده وام
این سرویس برای لغو درخواست می باشد که در صورت موفق بودم ضمانت قفل شده آزاد میگردد
curl --location 'https://api.baloan.ir/api/v1/partnership/loan/{loan-uuid}/cancel/' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accesstoken}'
import requests
import json
url = 'https://api.baloan.ir/api/v1/partnership/loan/{loan-uuid}/cancel/'
headers = {
'Accept-Language': 'en',
'Content-Type': 'application/json',
'Authorization': 'Bearer {accesstoken}'
}
response = requests.post(url, headers=headers)
You must replace
accesstokenwith your access key in token request.
خطاها
درگاه اعتباری بالون به صورت کلی شامل ارور های زیر است:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 404 | Not Found -- The specified api could not be found. |
| 429 | Too Many Requests -- You're requesting too many! Slow down! |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |