NAV
shell python

مستند درگاه ارتباطی

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

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

احراز هویت

دریافت توکن

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 accesstoken with 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 accesstoken with 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"
    }
]
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 accesstoken with 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
    }
}
field description
phone_number شماره تماس کاربر
national_identifier کد ملی کاربر
birth_date تاریخ تولد کاربر بصورت میلادی در قالب YYY-MM-DD
amount مبلغ وام درخواستی بصورت تومان
loan_due مدت بازپرداخت وام
store id فروشگاه
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 accesstoken with your access key in token request.

Be sure to replace loan-uuid with 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
}
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 accesstoken with your access key in token request.

Be sure to replace loan-uuid with 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 accesstoken with your access key in token request.

Be sure to replace loan-uuid with 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 accesstoken with 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.