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

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

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

احراز هویت

دریافت توکن

import requests

data = {
    'username': 'store name',
    'password': 'store password'
}

response = requests.post('https://api.baloan.ir/api/v1/merchant/token/', data=data)

curl -X POST -d username=store_name -d password=store_password \
   https://api.baloan.ir/api/v1/merchant/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

مقدار accesskey را به access دریافتی از قسمت دریافت توکن تغییر دهید.

وام های قابل اعطا

در این سرویس لیست وام های قابل اعطا و همچنین تمامی اطلاعات وام ارایه شده است

curl --location 'https://api.baloan.ir/api/v1/merchant/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/merchant/loan-policies', headers=headers)

You must replace accesstoken with your access key in token request.

Successful response:

[
  {
    "stores": [
      {
        "id": 37,
        "title_fa": "فروشگاه تست۱",
        "logo": "https://store1.url/?blahblah=True"
      }
    ],
    "amount": {
      "lower": 30,
      "upper": 50,
      "bounds": "[)"
    },
    "possible_loan_dues": [18],
    "bank_effected_interest_rate": 18,
    "installment_formula": "(amount * (bank_effected_interest_rate / 1200) * ((bank_effected_interest_rate / 1200) + 1) ^ loan_due) / ((((bank_effected_interest_rate / 1200) + 1) ^ loan_due) - 1)"
  },
  {
    "stores": [
      {
        "id": 38,
        "title_fa": "فروشگاه تست۲",
        "logo": "https://store2.url/?blahblah=True"
      }
    ],
    "amount": {
      "lower": 10,
      "upper": 30,
      "bounds": "[)"
    },
    "possible_loan_dues": [6, 12],
    "bank_effected_interest_rate": 18,
    "installment_formula": "(amount * (bank_effected_interest_rate / 1200) * ((bank_effected_interest_rate / 1200) + 1) ^ loan_due) / ((((bank_effected_interest_rate / 1200) + 1) ^ loan_due) - 1)"
  }
]

آپلود فایل

این سرویس برای آپلود فایل استقاده میشود و در ریسپانس برای فایل آپلود شده آدرس و uuid را میدهد. برای ارسال مدارک اشاره شده دراین سند برای ارسال مدارک از این سرویس استفاده شود

curl --location 'https://api.baloan.ir/api/v1/utility/file-upload/' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer {accesstoken}'\
--form 'file=@"/example/file.pdf"'

import requests

url = "https://api.baloan.ir/api/v1/utility/file-upload/"

payload = {}
files=[
  ('file',('example.pdf',open('/example/file.pdf','rb'),'application/x-sh'))
]
headers = {}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

You must replace accesstoken with your access key in token request.

Successful response:

{
  "status": "ok",
  "message": "",
  "message_code": "",
  "data": {
    "uuid": "d4c22af9-3676-4c6e-ab72-2a7b5b22afc5",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/d4f2ea9d-b09a-47b6-b269-17a0b55af871/cebcbd1f-5b7e-45cc-b4ce-2ddeb18310c6.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=bPkVTGsrPutYLgCyOWBOSxufopw%3D&Expires=1730123744"
  }
}


size limitation	10 MB
acceptable file formats	pdf, jpg, png

سرویس call back

در این سرویس تمامی تغییرات در وضعیت پرونده وام با استفاده از سرویس ارایه شده توسط شما با uuid وام اطلاع رسانی خواهد شد.

Successful response samples:

{
  "uuid": "d4c22af9-3676-4c6e-ab72-2a7b5b22afc5",
  "state": "loan_filled"
}

{
  "uuid": "d4c22af9-3676-4c6e-ab72-2a7b5b22afc5",
  "state": "blocked",
  "reason": "reason of blocked"
}

{
  "uuid": "d4c22af9-3676-4c6e-ab72-2a7b5b22afc5",
  "state": "user_need_correction",
  "need_to_correct_fields": [
    "amount",
    "loan_due",
    "residence_address.postal_code"
  ],
  "reason": "support comment for user guidance and correction instructions"
}

لیست status پرونده وام به شکل زیر قابل مشاهده است

state_slug	وضعیت	توضیحات
created	ایجاد شده	وام تازه ایجاد شده و در انتظار بررسی است.
user_need_correction	نیاز به اصلاح کاربر	اطلاعات وارد شده توسط کاربر نیاز به اصلاح دارند.
loan_filled	وام تکمیل شده	تمام اطلاعات وام تکمیل شده و توسط تیم اعتبارسنجی مورد بررسی قرار میگیرد.
user_verified	کاربر تایید شده	هویت کاربر تایید شده و ادامه مراحل بررسی وام امکان‌پذیر است.
cheque_image_need_verification	نیاز به تایید تصویر چک	تصویر چک ارسال شده و در انتظار تایید میباشد.
cheque_need_correction	نیاز به اصلاح چک	اطلاعات چک نیاز به اصلاح دارند.
cheque_uploaded	چک آپلود شده	تصویر چک با موفقیت آپلود شده است.
cheque_verified	چک تایید شده	تصویر چک تایید شده و آماده ارسال به بانک است.
send_loan_to_bank	ارسال وام به بانک	وام به بانک جهت بررسی واریز ارسال شده است.
loan_paid	وام پرداخت شده	وام به طور کامل پرداخت شده و فرآیند تکمیل شده است.
blocked	مسدود شده	وام به دلایل مختلف مسدود شده است.

:(در این حالت ها یادداشت کاربر اعتبارسنجی به همراه need_to_correct_fields ارسال میشود)وضعیت هایی که به وام باید ویرایش شود

user_need_correction
cheque_need_correction

فیلد هایی که ممکن اس درneed_to_correct_fields بضورت لیست برمیگردند:

amount
loan_due
store
residence_address.postal_code
income_amount
occupation_type
occupation_title
monthly_cost
monthly_installments
income_account_print
occupation_proof
income_cheque
cheque_number
cheque_image

در صورتی که در خواست وام رد شود وضعیت blocked به همراه دلیل رد شدن ارسال میشود

تشکیل پرونده وام

این سرویس برای ازسال اطلاعات هویتی افراد و همچنین اطلاعات مورد نیاز برای تشکیل پرونده ی فرد استفاده میشود

تشکیل پرونده

این سرویس اولین قدم برای تشکیل پرونده میباشد که در آن اطلاعات فرد گرفته میشود

curl --location 'https://api.baloan.ir/api/v1/merchant/loan/' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accesstoken}' \
--data '{
    "phone_number": "09123456780",
    "national_identifier": "62249140564",
    "birth_date": "1999-02-14",
    "amount": 35000000,
    "loan_due": 18,
    "referralfamily_set": [
        {
            "first_name": "John",
            "last_name": "Doe",
            "phone": "09123456781",
            "national_code": "07148143380",
            "relation_type": "FRIEND"
        },
        {
            "first_name": "Jane",
            "last_name": "Doe",
            "phone": "09123456782",
            "national_code": "01639654781",
            "relation_type": "FAMILY"
        }
    ],
    "residence_address": {
        "province": "تهران",
        "city": "تهران",
        "address": "دست چپ",
        "postal_code": "1234567890"
    },
    "residency_type": "rental",
    "home_phone_number": "02112345678",
    "income_amount": 5000,
    "occupation_type": "employee",
    "occupation_title": "Engineer",
    "monthly_cost": 200,
    "monthly_installments": 100,
    "income_account_print": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "occupation_proof": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "income_cheque": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "store": 3
}'

import requests
import json

url = 'https://api.baloan.ir/api/v1/merchant/loan/'
headers = {
    'Accept-Language': 'en',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {accesstoken}'
}
data = {
    "phone_number": "09123456780",
    "national_identifier": "62249140564",
    "birth_date": "1999-02-14",
    "amount": 35000000,
    "loan_due": 18,
    "referralfamily_set": [
        {
            "first_name": "John",
            "last_name": "Doe",
            "phone": "09123456781",
            "national_code": "07148143380",
            "relation_type": "FRIEND"
        },
        {
            "first_name": "Jane",
            "last_name": "Doe",
            "phone": "09123456782",
            "national_code": "01639654781",
            "relation_type": "FAMILY"
        }
    ],
    "residence_address": {
        "province": "تهران",
        "city": "تهران",
        "address": "دست چپ",
        "postal_code": "1234567890"
    },
    "residency_type": "rental",
    "home_phone_number": "02112345678",
    "income_amount": 5000,
    "occupation_type": "employee",
    "occupation_title": "Engineer",
    "monthly_cost": 200,
    "monthly_installments": 100,
    "income_account_print": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "occupation_proof": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "income_cheque": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "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": "09123456780",
  "national_identifier": "62249140564",
  "birth_date": "1999-02-14",
  "residency_type": "rental",
  "home_phone_number": "02112345678",
  "referralfamily_set": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "phone": "09123456781",
      "national_code": "07148143380",
      "relation_type": "FRIEND"
    },
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "09123456782",
      "national_code": "01639654781",
      "relation_type": "FAMILY"
    }
  ],
  "uuid": "700c7ce5-959e-4c01-b031-0f144aa9df6b",
  "plan_detail": {
    "monthly_installment_amount": 2691588,
    "total_payback": 48448589
  },
  "residence_address": {
    "province": "تهران",
    "city": "تهران",
    "address": "دست چپ",
    "postal_code": "1234567890"
  },
  "income_amount": 5000,
  "occupation_type": "employee",
  "occupation_title": "Engineer",
  "income_account_print": {
    "uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/b2c5a6a1-98a4-4256-b686-447698e7b494/499336ba-5469-4ebf-b146-c375a27dc482.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=4etcO8J1UBycGeUAZNRAeSFDkYA%3D&Expires=1735549692"
  },
  "occupation_proof": {
    "uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/b2c5a6a1-98a4-4256-b686-447698e7b494/499336ba-5469-4ebf-b146-c375a27dc482.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=4etcO8J1UBycGeUAZNRAeSFDkYA%3D&Expires=1735549692"
  },
  "income_cheque": {
    "uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/b2c5a6a1-98a4-4256-b686-447698e7b494/499336ba-5469-4ebf-b146-c375a27dc482.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=4etcO8J1UBycGeUAZNRAeSFDkYA%3D&Expires=1735549692"
  },
  "amount": 35000000,
  "loan_due": 18,
  "monthly_cost": 200,
  "monthly_installments": 100,
  "store": 3
}

دریافت اطلاعات پرونده وام

برای دریافت اطلاعات پرونده وام از طریق این سرویس امکان پذیر است وضعیت وام در فیلد state_slug باز میگردد (لیست slug ها در قسمت callback قابل مشاهده است)

curl -X GET 'https://api-nw-qa-baloan.rahkar.team/api/v1/merchant/loan/700c7ce5-959e-4c01-b031-0f144aa9df6b/'

import requests

url = "https://api-nw-qa-baloan.rahkar.team/api/v1/merchant/loan/79b2f45e-cef5-4d15-a67b-c1e21db1e6cc/"

response = requests.request("GET", url, headers=headers, data=payload)

You must replace accesstoken with your access key in token request.

Successful response:

{
  "phone_number": "09123456780",
  "national_identifier": "62249140564",
  "birth_date": "1999-02-14",
  "residency_type": "rental",
  "home_phone_number": "02112345678",
  "referralfamily_set": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "phone": "09123456781",
      "national_code": "07148143380",
      "relation_type": "FRIEND"
    },
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "09123456782",
      "national_code": "01639654781",
      "relation_type": "FAMILY"
    }
  ],
  "uuid": "700c7ce5-959e-4c01-b031-0f144aa9df6b",
  "plan_detail": {
    "monthly_installment_amount": 2691588,
    "total_payback": 48448589
  },
  "residence_address": {
    "province": "تهران",
    "city": "تهران",
    "address": "دست چپ",
    "postal_code": "1234567890"
  },
  "income_amount": 5000,
  "occupation_type": "employee",
  "occupation_title": "Engineer",
  "income_account_print": {
    "uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/b2c5a6a1-98a4-4256-b686-447698e7b494/499336ba-5469-4ebf-b146-c375a27dc482.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=4etcO8J1UBycGeUAZNRAeSFDkYA%3D&Expires=1735549692"
  },
  "occupation_proof": {
    "uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/b2c5a6a1-98a4-4256-b686-447698e7b494/499336ba-5469-4ebf-b146-c375a27dc482.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=4etcO8J1UBycGeUAZNRAeSFDkYA%3D&Expires=1735549692"
  },
  "income_cheque": {
    "uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/b2c5a6a1-98a4-4256-b686-447698e7b494/499336ba-5469-4ebf-b146-c375a27dc482.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=4etcO8J1UBycGeUAZNRAeSFDkYA%3D&Expires=1735549692"
  },
  "amount": 35000000,
  "loan_due": 18,
  "monthly_cost": 200,
  "monthly_installments": 100,
  "store": 3,
  "state_slug": "created",
  "defective_fields": []
}

اعتبارسنجی ایران

پس از تشکیل پرونده موفق نیاز به دریافت اعتبار سنجی ایران می باشد.

curl -X POST --location 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/iranian-credit-query' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer {accesstoken}'

import requests

url = 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/iranian-credit-query'
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.

Successful response:

{
  "report_status": "otp_verify_wait"
}

ارسال کد otp اعتبار سنجی ایران

در این سرویس کد otp ارسالی توسط اعتبار ستجی ایران که برای کاربر ارسال میشود

curl -X PATCH --location 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/iranian-credit-query' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accesstoken}' \
--data '{
    "otp": "1234"
}'

import requests
import json

url = 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/iranian-credit-query'
headers = {
    'Accept-Language': 'en',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {accesstoken}'
}
data = {
    "otp": "1234"
}

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.

Successful response:

{
  "report_status": "otp_verify_wait"
}

دریافت وضعیت otp اعتبار سنجی ایران

از طریق این سرویس امکان دریافت وضعیت گزارش اعتبارسنجی امکان پذیر میباشد

curl -X GET --location 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/iranian-credit-query' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accesstoken}' \

import requests
import json

url = 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/iranian-credit-query'
headers = {
    'Accept-Language': 'en',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {accesstoken}'
}
data = {
    "otp": "1234"
}

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.

Successful response:

{
  "report_status": "otp_verify_wait"
}

وضعیت گزارش	توضیحات	action
otp_verify_wait	در انتظار ارسال کد otp	ارسال کد otp
requested	ساخت گزارش درخواست داده شد	-
report_generated	گزارش ساخته شده	-
report_received	گزارش دریافت شده است	وام به وضعیت loan_filled (اطلاع رسانی از طریق کالبک)میرود
kaput	دریافت گزارش با مشکل روبرو شد	درخواست دوباره گزارش

ارسال مدارک مورد نیاز (ویرایش وام)

زمانی که وام در استیت user_need_correction قرار بگیره از طریق

curl -X PATCH --location 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accesstoken}' \
--data '{
    "amount": 25000000,
    "loan_due": 12,
    "residence_address": {
        "postal_code": "0987654321"
    }
}'

import requests
import json

url = 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/'
headers = {
    'Accept-Language': 'en',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {accesstoken}'
}
data = {
    "amount": 25000000,
    "store":3
    "loan_due": 12,
    "residence_address": {
        "postal_code": "0987654321"
    }
}

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.

Successful response:

{
  "phone_number": "09123456780",
  "national_identifier": "62249140564",
  "birth_date": "1999-02-14",
  "residency_type": "rental",
  "home_phone_number": "02112345678",
  "referralfamily_set": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "phone": "09123456781",
      "national_code": "07148143380",
      "relation_type": "FRIEND"
    },
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "09123456782",
      "national_code": "01639654781",
      "relation_type": "FAMILY"
    }
  ],
  "uuid": "700c7ce5-959e-4c01-b031-0f144aa9df6b",
  "plan_detail": {
    "monthly_installment_amount": 1691588,
    "total_payback": 38448589
  },
  "residence_address": {
    "province": "تهران",
    "city": "تهران",
    "address": "دست چپ",
    "postal_code": "0987654321"
  },
  "income_amount": 5000,
  "occupation_type": "employee",
  "occupation_title": "Engineer",
  "income_account_print": {
    "uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/b2c5a6a1-98a4-4256-b686-447698e7b494/499336ba-5469-4ebf-b146-c375a27dc482.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=4etcO8J1UBycGeUAZNRAeSFDkYA%3D&Expires=1735549692"
  },
  "occupation_proof": {
    "uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/b2c5a6a1-98a4-4256-b686-447698e7b494/499336ba-5469-4ebf-b146-c375a27dc482.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=4etcO8J1UBycGeUAZNRAeSFDkYA%3D&Expires=1735549692"
  },
  "income_cheque": {
    "uuid": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/b2c5a6a1-98a4-4256-b686-447698e7b494/499336ba-5469-4ebf-b146-c375a27dc482.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=4etcO8J1UBycGeUAZNRAeSFDkYA%3D&Expires=1735549692"
  },
  "amount": 35000000,
  "loan_due": 18,
  "monthly_cost": 200,
  "monthly_installments": 100,
  "store": 3,
  "state_slug": "created",
  "defective_fields": []
}

سرویس دریاقت ضمانت

پس از تایید پرونده وام توسظ کارشناسان اعتبار سنجی وام در وضعیت user_verified قرار میگیرد حال بایستی اطلاعات ضمانت لازم برای این وام داده شود. در این سرویس اطلاعات مورد نیاز برای ضمانت وام که شامل چک میشود مشخص میکند تا کاربر متقاضی وام بر این اساس چک مورد نیاز را آماده کند.

curl -X GET --location 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/collateral/' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer {accesstoken}'

import requests

url = 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/collateral/'
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:

{
  "cheque_amount": "250000000",
  "cheque_date": "2024-11-09",
  "pay_to": {
    "name": "شرکت راه‌کار‌های مالی هوشمند سامان",
    "national_identifier": "14008499833"
  },
  "address": {
    "province": "تهران",
    "city": "تهران",
    "address": "جنت آباد مرکزی بلوار مخبری بین ۱۶ متری اول و دوم پلاک ۲۱۹ طبقه ۴ واحد ۷",
    "postal_code": "1475714941"
  }
}

سرویس ارسال ضمانت

اطلاعات ضمانت نامه چک به همراه تصویر آن در این سرویس ارسال میشود.

curl -X POST --location 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/collateral/' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accesstoken}' \
--data '{
    "cheque_number": "1234567890123456",
    "cheque_image": "sdc7883b-0cd7-47e4-82c6-66544720e0d7"
}'

import requests
import json

url = 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/collateral/'
headers = {
    'Accept-Language': 'en',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {accesstoken}'
}
data = {
    "cheque_number": "1234567890123456",
    "cheque_image": "sdc7883b-0cd7-47e4-82c6-66544720e0d7"
}

response = requests.post(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.

Successful response:

{
  "cheque_number": "250000000",
  "cheque_image": {
    "uuid": "sdc7883b-0cd7-47e4-82c6-66544720e0d7",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/d4f2ea9d-b09a-47b6-b269-17a0b55af871/cebcbd1f-5b7e-45cc-b4ce-2ddeb18310c6.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=zxWqb3n0fogb1s5p4OrXWGsWvMA%3D&Expires=1730139419"
  }
}

سرویس ویرایش ضمانت

فیلد هایی که در وضعیت نیاز به ویرایش دارند را ارسال کنید

curl -X PATCH --location 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/collateral/' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accesstoken}' \
--data '{
    "cheque_number": "1234567890123457",
    "cheque_image": "sdc7883b-0cd7-47e4-82c6-66544720e0d6"
}'

import requests
import json

url = 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/collateral/'
headers = {
    'Accept-Language': 'en',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {accesstoken}'
}
data = {
    "cheque_number": "1234567890123457",
    "cheque_image": "sdc7883b-0cd7-47e4-82c6-66544720e0d6"
}

response = requests.post(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.

Successful response:

{
  "cheque_number": "1234567890123457",
  "cheque_image": {
    "uuid": "sdc7883b-0cd7-47e4-82c6-66544720e0d6",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/d4f2ea9d-b09a-47b6-b269-17a0b55af871/cebcbd1f-5b7e-45cc-b4ce-2ddeb18310c6.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=zxWqb3n0fogb1s5p4OrXWGsWvMA%3D&Expires=1730139419"
  }
}

دریافت قرارداد

پس از تایید چک قرار داد وام کاربر ایجاد شده و در این سرویس ارسال میشود.

curl -X GET --location 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/contract/' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer {accesstoken}'

import requests
import json

url = 'https://api.baloan.ir/api/v1/merchant/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": "d4c22af9-3676-4c6e-ab72-2a7b5b22afc5",
    "file": "https://s3.ir-thr-at1.arvanstorage.ir/staging-baloan-user-uploads/users/d4f2ea9d-b09a-47b6-b269-17a0b55af871/cebcbd1f-5b7e-45cc-b4ce-2ddeb18310c6.pdf?AWSAccessKeyId=71337362-374e-40e6-850a-27de1397d3e2&Signature=zxWqb3n0fogb1s5p4OrXWGsWvMA%3D&Expires=1730139419"
  },
  "is_agreed_by_user": true
}

صدور otp و ارسال برای کاربر

پس از در یافت قرارداد از این سرویس برای صدور otp برای کاربران استفاده میشود.

curl -X POST --location 'https://api.baloan.ir/api/v1/merchant/loan/{loan-uuid}/contract/' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer {accesstoken}'

import requests
import json

url = 'https://api.baloan.ir/api/v1/merchant/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/merchant/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/merchant/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.

لیست خطاهای سرویس وام

خطا	کد خطا
شماره تماس ارسالی قبلاً در سیستم ما با کد ملی دیگری ثبت شده است. لطفاً شماره تماس جدیدی وارد کنید تا بتوانیم حساب کاربری شما را ایجاد کنیم.	phone_number_exist_with_another_national_id
کد ملی ارسالی پیش از این در سامانه با شماره تماس {phone_number} ثبت شده است. لطفا با شماره تماس صحیح درخواست را ثبت کنید.	national_id_exists_with_another_phone_number
تاریخ تولد وارد شده در بازه سنی مجاز نیست. لطفاً اطمینان حاصل کنید که سن شما بین ۱۸ تا ۷۰ سال باشد.	age_not_in_valid_range
نمیتوانید برای فروشگاه غیر آنلاین، درخواست وام آنلاین بدهید.	not_allowed_to_create_online_loan_for_not_online_store
نمیتوانید برای فروشگاه آنلاین، درخواست وام غیر آنلاین بدهید	not_allowed_to_create_not_online_loan_for_online_store
مبلغ یا مدت تسهیلات اعلامی خارج از بازه مجاز سیاست‌های فروشگاه شما است. لطفاً مبلغ تسهیلات را با توجه به سیاست‌های وام‌گیری فروشگاه انتخاب کنید	loan_due_or_amount_not_match_store_policies
تاریخ تولد وارد شده نامعتبر است. لطفاً اطمینان حاصل کنید که تاریخ تولد به فرمت صحیح (YYYY-MM-DD) میلادی وارد شده باشد.	invalid_date_format
اطلاعات وارد شده برای آشنایان نامعتبر است. لطفاً اطمینان حاصل کنید که کد ملی و شماره تماس آشنایان با اطلاعات خود متقاضی و همچنین با یکدیگر متفاوت باشد.	invalid_referral_family_data
استان وارد شده نامعتبر است. لطفاً اطمینان حاصل کنید که استان انتخابی در لیست استان‌های مورد قبول سیستم ما باشد	invalid_province
شهر وارد شده نامعتبر است. لطفاً اطمینان حاصل کنید که شهر انتخابی در لیست شهرهای مورد قبول سیستم ما باشد	invalid_city
وضعیت سکونت وارد شده نامعتبر است. لطفاً اطمینان حاصل کنید که یکی از گزینه‌های معتبر وضعیت سکونت را انتخاب کرده‌اید.	invalid_residency_type_choice
نوع شغل وارد شده نامعتبر است. لطفاً اطمینان حاصل کنید که یکی از گزینه‌های معتبر نوع شغل را انتخاب کرده‌اید.	invalid_occupation_type_choice
استعلام سرویس {service_name} با خطا مواجه شد.	service_inquiry_failed
استعلام کد پستی با خطا مواجه شد. لطفاً اطمینان حاصل کنید که کد پستی به درستی وارد شده باشد.	postal_code_verification_failed
کاربر گرامی، متاسفانه به‌دلیل عدم تطابق اطلاعات شما در سامانه شاهکار (مغایرت شماره تلفن با کدملی) درخواست وام شما غیر قابل بررسی می‌باشد.	national_phone_verification_failed
متأسفانه اطلاعات وارد شده معتبر نیست و نمی‌توان درخواست را ثبت کرد. لطفاً بررسی کنید که کد ملی و تاریخ تولد به درستی وارد شده باشند	registry_info_verification_failed
درخواست تکراری	duplicate_request
{ارور سرویس ایران}	iranian_service_error
درخواستی برای تایید وجود ندارد	no_request_to_verify
درخواست شما منقضی شد. لطفا دوباره درخواست ارسال پیامک بدید	expired_request
مشکلی در تایید کد رخ داده است. دوباره سعی کنید.	failed_to_verify
دریافت گزارش اعتبار سنجی ایران با مشکل روبرو شد.لطفا دوباره درخواست گزارش کنید.	icq_record_is_is_not_valid
قرارداد درحال حاضر توسط کاربر امضا شده است.	already_agreed_by_user
کد اشتباه است.	incorrect_otp_code
دوباره درخواست دهید.	throttled_otp_code
امکان تغییر فیلد در این وضعیت وجود ندارد. لطفا دوباره وضعیت وام را چک کنید.	can_not_update
در این وضعیت امکان ندارد. لطفا دوباره وضعیت وام را چک کنید.	not_allowed_in_state
شماره صیاد معتبر نیست. شماره صیاد باید 16 رقم و در قالب اعداد انگلیسی باشد.	cheque_number_is_not_valid
لغو وام با مشکل مواجه شد.	failed_to_cancel_loan
پارامتر ضروری. مبلغ باید عدد انگلیسی و به صورت query_param ارسال شود.	invalid_amount
مبلغ تسهیلات خارج از بازه مجاز سیاست‌های فروشگاه شما است. لطفاً مبلغ را بصورت تومان ارسال کنید.	amount_not_match_store_policies
امکان ساخت وام برای کاربر بلاک شده از سمت بالون وجود ندارد.	can_not_request_loan_for_blocked_user
شما یک وام در جریان دارید. امکان درخواست جدید وام وجود ندارد.	can_not_request_for_new_loan
یک یا چند تا از فیلد های ارسالی مشکل دارد	invalid_input / invalid
فیلد ویرایش نشده است	missed_defective_field
مفدار جدید با قبلی یکسان است. باید ویرایش شود	same_value_for_defective_field
درخواست شما یافت نشد (معمولا در فایل های آپلودی)	does_not_exist

لیست پارامتر های استقاده شده در سرویس ها

occupation_type

مقدار	نام فارسی
employee	کارمند
employer/freelancer	کارفرما / شغل آزاد
retired	بازنشسته

residency_type

مقدار	نام فارسی
RENTAL	اجاره‌ای
OWNERSHIP	مالک

refferalfamily.relation_type

مقدار	نام فارسی
FAMILY	خانواده
FRIEND	دوست

لغو پرونده وام

این سرویس برای لغو درخواست می باشد که استیت وام به blocked تغییر خواهد یافت. فقط در استیت های زیر وام قابل لغو هست: created, loan_filled, user_need_correction

curl --location 'https://api.baloan.ir/api/v1/merchant/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/merchant/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.

تغییرات نسخه ۲

تغییرات در دو سرویس زیر اتفاق افتاده و باقی سرویس ها در همان url با همان body قابل استفاده هستد. قابل ذکر است که url های قدیمی این دو سرویس از دسترس خارج خواهد شد

‍‍‍https://api.baloan.ir/api/v1/merchant/loan-policies->https://api.baloan.ir/api/v2/merchant/loan-policies
‍‍‍https://api.baloan.ir/api/v1/merchant/loan/->https://api.baloan.ir/api/v2/merchant/loan/ ‍

وام های قابل اعطا

curl --location 'https://api-nw-qa-baloan.rahkar.team/api/v2/merchant/loan-policies/' \
--header 'Authorization: Bearer {accesstoken}'

response:

[
  {
    "stores": [
      {
        "id": 37,
        "title_fa": "فروشگاه تست۱",
        "logo": "https://store1.url/?blahblah=True",
        "service_modes": ["online", "in_person"]
      }
    ],
    "amount": {
      "lower": 30,
      "upper": 50,
      "bounds": "[)"
    },
    "possible_loan_dues": [18],
    "bank_effected_interest_rate": 18,
    "installment_formula": "(amount * (bank_effected_interest_rate / 1200) * ((bank_effected_interest_rate / 1200) + 1) ^ loan_due) / ((((bank_effected_interest_rate / 1200) + 1) ^ loan_due) - 1)"
  },
  {
    "stores": [
      {
        "id": 38,
        "title_fa": "فروشگاه تست۲",
        "logo": "https://store2.url/?blahblah=True",
        "service_modes": ["online"]
      }
    ],
    "amount": {
      "lower": 10,
      "upper": 30,
      "bounds": "[)"
    },
    "possible_loan_dues": [6, 12],
    "bank_effected_interest_rate": 18,
    "installment_formula": "(amount * (bank_effected_interest_rate / 1200) * ((bank_effected_interest_rate / 1200) + 1) ^ loan_due) / ((((bank_effected_interest_rate / 1200) + 1) ^ loan_due) - 1)"
  }
]

تغییرات

url
اضافه شدن فیلد service_modes که یک لیست از نوع سرویس برای شما برمیگردد

service_modes

نام فارسی	مقدار
online	آنلاین
in_person	حضوری

تشکیل پرونده / دریافت اطلاعات پرونده وام / ویرایش پرونده / لغو پرونده وام

request:

curl --location 'https://api.baloan.ir/api/v2/merchant/loan/' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accesstoken}' \
--data '{
"phone_number": "09123456780",
"national_identifier": "62249140564",
"birth_date": "1999-02-14",
"amount": 35000000,
"loan_due": 18,
"referralfamily_set": [
{
"first_name": "John",
"last_name": "Doe",
"phone": "09123456781",
"national_code": "07148143380",
"relation_type": "FRIEND"
},
{
"first_name": "Jane",
"last_name": "Doe",
"phone": "09123456782",
"national_code": "01639654781",
"relation_type": "FAMILY"
}
],
"residence_address": {
"province": "تهران",
"city": "تهران",
"address": "دست چپ",
"postal_code": "1234567890"
},
"residency_type": "rental",
"home_phone_number": "02112345678",
"income_amount": 5000,
"occupation_type": "employee",
"occupation_title": "Engineer",
"monthly_cost": 200,
"monthly_installments": 100,
"income_account_print": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
"occupation_proof": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
"income_cheque": "9e99ba5e-dccd-46ca-babc-c089cc2b80f0",
"store": 3,
"is_online": true
}'

تغییرات :

url
اضافه شدن فیلد is_online که با توجه به نوع فروشگاه در سرویس loan policy‍‍و کاربر مقادیر boolean را قبول میکند

خطاها

درگاه اعتباری بالون به صورت کلی شامل ارور های زیر است:

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.