آخرین تغییرات: 1400/07/06

سرویس تسویه گروهی

مقدمه

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

لیست تسویه های گروهی ثبت شده

در این بخش شما می‌توانید لیست تسویه‌های گروهی را که تا به حال ثبت کرده‌اید، مشاهده نمایید.

METHOD: GET
URL: https://batch.vandar.io/api/v1/business/{business}/batches
                      

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد مشاهده‌ی لیست تسویه های گروهی آن را دارید.

page(اختیاری): صفحه مورد نظر را مشخص می‌کند.

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200
{
  "data": [
    {
      "batch_id": "900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640",
      "status": {
        "total_count": 1,
        "init_count": 0,
        "submitted_count": 1,
        "failed_count": 0
      },
      "total_amount": 50000,
      "created_at": 1629672276
    }
  ],
  "links": {
    "first": "http:\/\/batch.vandar.io\/api\/v1\/business\/{business}\/batches?page=1",
    "last": "http:\/\/batch.vandar.io\/api\/v1\/business\/{business}\/batches?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http:\/\/batch.vandar.io\/api\/v1\/business\/{business}\/batches",
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}
                      
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره.
  • data:
    • batch_id: شناسه تسویه گروهی ثبت شده
    • status: در این بخش جزییات کلی تسویه گروهی مشخص می شود.
      • total_count: تعداد کل تسویه گروهی ثبت شده
      • init_count: تعداد تسویه هایی که در حال ارسال هستند
      • submitted_count: تعداد تسویه هایی که ارسال شده اند
      • failed_count: تعداد تسویه هایی که با خطا مواجه شده اند
    • total_amount: مبلغ کلی تسویه های گروهی
    • created_at: تاریخ ایجاد تسویه گروهی (timestamp)
    • links:
      • first: آدرس اولین صفحه
      • last: آدرس آخرین صفحه
      • prev: آدرس صفحه قبل
      • next: آدرس صفحه بعد
    • meta:
      • current_page: آدرس همین صفحه
      • from: شماره اولین آیتم تسویه ای که در این صفحه آمده است
      • last_page: تعداد کل صفحات تسویه
      • path: آدرس خالص بدون صفحه بندی
      • per_page: تعداد آیتم در هر صفحه
      • to: شماره آخرین آیتم تسویه ای که در این صفحه آمده است
      • total: تعداد کل آیتم های تسویه

نمونه پاسخ دریافتی ناموفق:

HTTP/1.1 4xx
{
"status": 0,
"error": "Unauthenticated"
}
                      


جزییات یک تسویه گروهی

در این بخش شما می‌توانید جزییات یک تسویه‌ ی گروهی و تسویه های ثبت شده در آن مشاهده نمایید.

METHOD: GET
URL: https://batch.vandar.io/api/v1/business/{business}/batch-settlements/{batch_id}?per_page=20&page=1&status=SUBMITTED
                      

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد مشاهده‌ی لیست تسویه های گروهی آن را دارید.

پارامتر {batch_id} شناسه تسویه گروهی که در ثبت آن ارسال کرده اید.

per_page(اختیاری): تعداد رکورد اطلاعاتی درخواست تسویه را مشخص میکند

  • INIT: در حال ارسال
  • SUBMITTED: ارسال شده
  • FAILED: ناموفق

status(اختیاری): یکی از پارامتر های زیر را قبول می کند. و مشخص می کند چه نوع تسویه هایی در لیست جزییات تسویه گروهی نمایش داده شود. عدم ارسال این پارامتر باعث می شود تمام وضعیت ها در پاسخ نمایش داده شود.

page(اختیاری): صفحه مورد نظر را مشخص می‌کند.

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200
{
  "data": [
    {
      "id": "8736c960-039a-11ec-8171-334dd8b08284",
      "track_id": "10000000",
      "payment_number": "2",
      "amount": "50000",
      "iban": "IR150620000000203214109001",
      "status": "SUBMITTED",
      "transaction_id": 162967221235,
      "error_message": null
    }
  ],
  "links": {
    "first": "http:\/\/batch.vandar.io\/api\/v1\/business\/vandario\/batch-settlements\/900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640?page=1",
    "last": "http:\/\/batch.vandar.io\/api\/v1\/business\/vandario\/batch-settlements\/900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http:\/\/batch.vandar.io\/api\/v1\/business\/vandario\/batch-settlements\/900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640",
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}
                      
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره.
  • data:
    • id: شناسه تسویه
    • track_id: شناسه یکتای ارسالی
    • payment_number: شناسه پرداخت ارسالی
    • amount: مبلغ
    • iban: شماره شبا
    • status: در این بخش جزییات کلی تسویه گروهی مشخص می شود.
    • links:
      • INIT: در حال ارسال
      • SUBMITTED: ارسال شده
      • FAILED: ناموفق
    • transaction_id: شناسه یکتای ونداری
    • error_message: در صورت وضعیت خطا متن خطا در این پارامتر بر می گردد.
    • links:
      • first: آدرس اولین صفحه
      • last: آدرس آخرین صفحه
      • prev: آدرس صفحه قبل
      • next: آدرس صفحه بعد
    • meta:
      • current_page: آدرس همین صفحه
      • from: شماره اولین آیتم تسویه ای که در این صفحه آمده است
      • last_page: تعداد کل صفحات تسویه
      • path: آدرس خالص بدون صفحه بندی
      • per_page: تعداد آیتم در هر صفحه
      • to: شماره آخرین آیتم تسویه ای که در این صفحه آمده است
      • total: تعداد کل آیتم های تسویه

نمونه پاسخ دریافتی ناموفق:

HTTP/1.1 4xx
{
"status": 0,
"error": "Unauthenticated"
}
                      


ثبت درخواست تسویه گروهی

در این بخش شما می‌توانید یک درخواست تسویه گروهی را ثبت نمایید.

METHOD: POST
URL: https://batch.vandar.io/api/v1/business/{business}/batches-settlement
                      

پارامتر {business} همان نام انگلیسی کسب و کاری است که قصد ثبت تسویه برای آن را دارید.

HTTP/1.1
{
	"batch_id": "900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640",
	"batches_settlement": [
        {
			"track_id": "10000000",
			"iban": "IR150620000000203214109001",
			"amount": 50000,
			"payment_number": "2",
        },
        {
			"track_id": "10000000",
			"iban": "IR150620000000203214109001",
			"amount": 50000,
			"payment_number": "2",
        }
	]
}
                        
  • status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره.
  • batch_id: شناسه یکتایی که برای ثبت هر تسویه گروهی ارسال می گردد. این مقدار از256 Hash اطلاعات آرایه ارسالی batches_settlement ایجاد می شود. نمونه از ساخت این مقدار را می توانید در نمونه کد زیر که به زبان php است مشاهده کنید.
    hash('sha256', json_encode([
            {
    			"track_id": "10000000",
    			"iban": "IR150620000000203214109001",
    			"amount": 50000,
    			"payment_number": "2",
            },
            {
    			"track_id": "10000000",
    			"iban": "IR150620000000203214109001",
    			"amount": 50000,
    			"payment_number": "2",
            }
    ])
                                
  • batches_settlement: لیستی از تسویه ها که همزمان ارسال می شوند.
    • amount (اجباری): مبلغ تراکنش به ریال و بزرگتر یا مساوی 50,000 و کوچکتر یا مساوی 500,000,000
    • iban (اجباری): شماره شبا ای که می خواد پول به آن واریز شود
    • track_id (اجباری): رشته پیگیری که به ازای هر درخواست تسویه بایستی یکتا باشد. پیشنهاد ما استفاده از uuid برای این پارامتر است.
    • payment_number (اختیاری): شناسه واریز شماره ای اختیاری است تا حداکثر 30 رقم.

نمونه پاسخ دریافتی موفق:

HTTP/1.1 200
{
      "batch_id": "900e69c676f67008de9bed005a014fb6e604222bb5e824ab65fc4153757cb640",
      "status": {
        "total_count": 1,
        "init_count": 0,
        "submitted_count": 1,
        "failed_count": 0
      },
      "total_amount": 50000,
      "created_at": 1629672276
}
                      
  • با ثبت موقث تسویه گروهی خورجی بالا با جزییات زیر نمایش داده می شود.
    • batch_id: شناسه تسویه گروهی ثبت شده
    • status: در این بخش جزییات کلی تسویه گروهی مشخص می شود.
      • total_count: تعداد کل تسویه گروهی ثبت شده
      • init_count: تعداد تسویه هایی که در حال ارسال هستند
      • submitted_count: تعداد تسویه هایی که ارسال شده اند
      • failed_count: تعداد تسویه هایی که با خطا مواجه شده اند
    • total_amount: مبلغ کلی تسویه های گروهی
    • created_at: تاریخ ایجاد تسویه گروهی (timestamp)

نمونه پاسخ دریافتی ناموفق:

HTTP/1.1 4xx
{
    "status": 0,
    "error": "Unauthenticated"
}