NAV
shell python

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

در این مستند به معرفی درگاه اعتباری بالن پرداخته میشود. نسخه حاضر 1.0.0 است که فایل Postman برای API ها از اینجا قابل دسترسی است.

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

احراز هویت

دریافت توکن

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

آپلود فایل

این سرویس برای آپلود فایل استقاده میشود و در ریسپانس برای فایل آپلود شده آدرس و 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

اعتبار

استعلام اعتبار

data = {
    'national_identifier': '0012345678'
}
response = requests.post(
    'https://api.baloan.ir/api/v1/merchant/check-credit/',
    headers={'Authorization': 'Bearer accesstoken'},
    data=data
)

curl "https://api.baloan.ir/api/v1/merchant/check-credit/" \
  -H "Authorization: Bearer accesstoekn" -X POST \
  -d national_identifier=0012345678

The above command returns JSON structured like this:

{
  "status": "ok",
  "message": "",
  "message_code": "",
  "data": {
    "national_identifier": "0012345678",
    "amount": 100000000
  }
}

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

HTTP Request

POST https://api.baloan.ir/api/v1/merchant/check-credit/

Data Parameters

Parameter Required Description
national_identifier true Store's customer national identifier that has baloan credit.

ارسال otp

data = {
    'national_identifier': '0012345678'
}
response = requests.post(
    'https://api.baloan.ir/api/v1/merchant/send-credit-otp/',
    headers={'Authorization': 'Bearer accesstoken'},
    data=data
)

curl "https://api.baloan.ir/api/v1/merchant/send-credit-otp/" \
  -H "Authorization: Bearer accesstoekn" -X POST \
  -d national_identifier=0012345678

The above command returns JSON structured like this:

{
  "status": "ok",
  "message": "",
  "message_code": "",
  "data": {}
}

در صورتی که کاربر اعتبار داشته باشد کد otp برای کاربر پیامک شده و برای تایید واریز اعبتار به حساب فروشگاه ارسال otp در مرحله بعد توسط کاربر الزامی است.

HTTP Request

POST https://api.baloan.ir/api/v1/merchant/send-credit-otp/

Data Parameters

Parameter Required Description
national_identifier true Store's customer national identifier that has baloan credit.

تایید واریز اعتبار

data = {
    'national_identifier': '0012345678',
    'otp': '11111',
    'file': "import file with python"
}

response = requests.post(
    'https://api.baloan.ir/api/v1/merchant/settle-confirm/',
    headers={'Authorization': 'Bearer accesstoken'}
)

در صورت استفاده از نرم افزار پستمن دیتا را از طریق form-data ارسال کنید

فایل ارسال شده فرمت pdf باشد.

curl --location 'https://api.baloan.ir/api/v1/merchant/settle-confirm/' \
--header 'Authorization: Bearer accesstoken' \
--form 'national_identifier="0012345678"' \
--form 'otp="11111"' \
--form 'data="{\"code\":\"TLC-111111\", \"bill\":{\"total\":500000000}}"' \
--form 'file=@"/path/file.pdf"'

The above command returns JSON structured like this:

{
  "status": "ok",
  "message": "",
  "message_code": "",
  "data": {}
}

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

در ضمن ارسال پارامتر data الزامی می باشد و پارامتر های ذکر شده در آن فیلد های اجباری میباشند.

HTTP Request

POST https://api.baloan.ir/api/v1/merchant/settle-confirm/

URL Parameters

Parameter Required Description
national_identifier true Store's customer national identifier
otp true received otp in previous step by user's phone number.
file true
data true json field

خطاها

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

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.
shell python