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

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

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

تفاوتهای کلیدی نسخه ۲

احراز هویت نسخه ۲

دریافت توکن

import requests

data = {
    'username': 'store_uuid',
    'password': 'store_password'
}

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

curl --location 'https://api.baloan.ir/api/v2/merchant/token/' \
--header 'Content-Type: application/json' \
--data '{
    "username": "store_uuid",
    "password": "store_password"
}'

Successful response:

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTc4NzQ4Nzk3MCwiaWF0IjoxNzcwMjA3OTcwLCJqdGkiOiJkNTJhYmQwOTY2Nzg0MmI1OTQ0OGI1YTVkN2Y0ZGQ0OCIsInVzZXJfaWQiOjUxNjc5fQ.64RV1zFqpTB09gv7j7G4v2O_VB5-M_tMe2-Rolfxu_A",
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzcwMjk0MzcwLCJpYXQiOjE3NzAyMDc5NzAsImp0aSI6IjYzMDk5YWVkMWUyMDRmMTU5MDkxN2ZiOTBmZGViZDJlIiwidXNlcl9pZCI6NTE2Nzl9.ztvTy1POnT5UXyEqsTVuDz3O7nsRv81t49rlLTVUnko"
}

در نسخه ۲، فرایند احراز هویت مشابه نسخه ۱ است، اما endpoint به /api/v2/merchant/token/ تغییر کرده است.

HTTP Request

POST https://api.baloan.ir/api/v2/merchant/token/

Data Parameters

Parameter Required Description
username true Store UUID received after contract agreement
password true Store password received after contract agreement

اعتبار نسخه ۲

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

import requests

data = {
    'national_identifier': '4311204302'
}
response = requests.post(
    'https://api.baloan.ir/api/v2/merchant/check-credit/',
    headers={'Authorization': 'Bearer access_token'},
    json=data
)

curl --location 'https://api.baloan.ir/api/v2/merchant/check-credit/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
    "national_identifier": "4311204302"
}'

The above command returns JSON structured like this:

{
    "status": "ok",
    "message": "",
    "message_code": "",
    "data": {
        "national_identifier": "4311204302",
        "user_credit": 40000000
    }
}

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

HTTP Request

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

Data Parameters

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

ارسال otp

import requests

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

curl --location 'https://api.baloan.ir/api/v2/merchant/send-credit-otp/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
    "national_identifier": "0012345678"
}'

The above command returns JSON structured like this:

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

در صورتی که کاربر اعتبار داشته باشد، کد OTP برای کاربر پیامک شده و برای مرحله بعد آماده می‌شود.

HTTP Request

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

Data Parameters

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

اعتبارسنجی otp

import requests

data = {
    'national_identifier': '0012345678',
    'otp': '11111'
}
response = requests.post(
    'https://api.baloan.ir/api/v2/merchant/validate-credit-otp/',
    headers={'Authorization': 'Bearer access_token'},
    json=data
)

curl --location 'https://api.baloan.ir/api/v2/merchant/validate-credit-otp/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
    "national_identifier": "0012345678",
    "otp": "11111"
}'

The above command returns JSON structured like this:

{
  "status": "ok",
  "message": "",
  "message_code": "",
  "data": {
    "token": "44f83431-77a8-40d7-9556-2fe43f95ab4b"
  }
}

مرحله جدید در نسخه ۲: پس از ارسال OTP، این endpoint برای اعتبارسنجی کد OTP استفاده می‌شود. در صورت موفقیت، توکن تراکنش برگردانده می‌شود که برای مرحله تسویه حساب ضروری است.

HTTP Request

POST https://api.baloan.ir/api/v2/merchant/validate-credit-otp/

Data Parameters

Parameter Required Description
national_identifier true Store's customer national identifier that has baloan credit.
otp true OTP code received by user's phone number.

تایید واریز اعتبار نسخه ۲

import requests

url = "https://api.baloan.ir/api/v2/merchant/settle-confirm/"
files = [
  ('file', ('invoice.pdf', open('/path/to/invoice.pdf', 'rb'), 'application/pdf'))
]
data = {
    'national_identifier': '0012345678',
    'data': '{"code":"TLC-111111", "bill":{"total":60000000}}',
    'token': '44f83431-77a8-40d7-9556-2fe43f95ab4b'
}
headers = {
    'Authorization': 'Bearer access_token'
}

response = requests.post(url, headers=headers, data=data, files=files)

curl --location 'https://api.baloan.ir/api/v2/merchant/settle-confirm/' \
--header 'Authorization: Bearer access_token' \
--form 'national_identifier="0012345678"' \
--form 'data="{\"code\":\"TLC-111111\", \"bill\":{\"total\":60000000}}"' \
--form 'file=@"/path/to/invoice.pdf"' \
--form 'token="44f83431-77a8-40d7-9556-2fe43f95ab4b"'

The above command returns JSON structured like this:

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

بهبود در نسخه ۲: این endpoint اکنون نیاز به توکن تراکنش از مرحله اعتبارسنجی OTP دارد. پس از تسویه موفق، موجودی باقی‌مانده کاربر برگردانده می‌شود.

HTTP Request

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

Data Parameters

Parameter Required Description
national_identifier true Store's customer national identifier
data true JSON field containing transaction code and bill info
file true PDF invoice file
token true Transaction token from validate-credit-otp endpoint

فرایند کامل نسخه ۲

  1. دریافت توکن احراز هویت: /api/v2/merchant/token/
  2. استعلام اعتبار: /api/v2/merchant/check-credit/ (جدید)
  3. ارسال OTP: /api/v2/merchant/send-credit-otp/
  4. اعتبارسنجی OTP: /api/v2/merchant/validate-credit-otp/ (جدید)
  5. تایید تسویه: /api/v2/merchant/settle-confirm/ (با توکن تراکنش)

خطاها

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

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