مستندات وندار | ارایه دهنده راهکارهای پرداخت

آخرین تغییرات: ۱۴۰۰/۰۷/۰۸

مقدمه

سرویس مشتریان چیست:

سرویس مشتریان جهت مدیریت طرف‌حساب‌های پذیرندگان وندار ارائه شده است که توسط این سرویس، پذیرندگان می‌توانند اطلاعات هویتی، کیف پول، شبا، اشتراک‌ها و تراکنش‌های مشتریان خود را مدیریت کنند.

توضیحات

برای تمامی درخواست های ارسالی باید مقادیر زیر در هدر ارسال شوند: توکن همان کلید API یی است که از وندار دریافت کرده اید.

Accept: application/json
Authorization Bearer {Token}

مشتریان

در این بخش سرویس‌های ثبت مشتری، مشاهده لیست مشتریان، ویرایش اطلاعات مشتری، حذف مشتری و مشاهده اطلاعات یک مشتری ارائه می‌شوند.

۱. لیست مشتریان:

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

Method: GET
Address: https://api.vandar.io/v2/business/{business}/customers

پارامتر {business} نام انگلیسی کسب و کار است.

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

HTTP/1.1 200
{
    "data": [
        {
            "id": "394dd280-210f-11ec-96d5-95b80dce5a5a",
            "name": "تست",
            "balance": 0,
            "created_at": "13:53 - 1400/07/07",
            "mobile": null
        },
        {
            "id": "35e431e0-210c-11ec-9200-79b42496d8e0",
            "name": "الناز نوروزی",
            "balance": 0,
            "created_at": "13:31 - 1400/07/07",
            "mobile": "09121234567"
        }
    ],
    "links": {
        "first": "https://customer.vandar.io/v2/business/{business}/customers?page=1",
        "last": "https://customer.vandar.io/v2/business/{business}/customers?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://customer.vandar.io/v2/business/{business}/customers",
        "per_page": 10,
        "to": 2,
        "total": 2
    }
}

status: ما http response را مطابق آن‌چه که واقعاً اتفاق افتاده برای شما ارسال می‌کنیم؛ درخواست‌های موفقیت‌آمیز با ۲۰۰، خطاهای اعتبارسنجی را با ۴۲۲، خطای ۴۰۴ برای عدم یافتن منبعی خاص، خطاهای سمت سرور با ۵۰۰ و غیره.
data:
- id: شناسه یکتای مشتری
- name: نام مشتری که برای مشتری حقیقی نام و نام خانوادگی مشتری و برای مشتری حقوقی نام نماینده می‌باشد.
- balance: موجودی کیف پول مشتری
- created_at: تاریخ ثبت مشتری
- mobile: شماره موبایل مشتری
links:
- first: آدرس اولین صفحه
- last: آدرس آخرین صفحه
- prev: آدرس صفحه قبل
- next: آدرس صفحه بعد
meta:
- current_page: آدرس همین صفحه
- from: شماره اولین آیتمی که در این صفحه آمده است
- last_page: تعداد کل صفحات
- path: آدرس خالص بدون صفحه بندی
- per_page: تعداد آیتم در هر صفحه
- to: شماره آخرین آیتمی که در این صفحه آمده است
- total: تعداد کل آیتم ها

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

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

۲. ثبت مشتری جدید

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

METHOD: POST
URL: https://api.vandar.io/v2/business/{business}/customers

پارامتر {business} نام انگلیسی کسب و کار است.

پارامترهای مجاز

name	Type	Status
business_id	string	required
first_name	string	optional
last_name	string	optional
legal_name	string	optional
agent_name	string	optional
type	string	required in:INDIVIDUAL,LEGAL
mobile	string	required if type=INDIVIDUAL
agent_mobile	string	required if type=LEGAL
telephone	string	optional
individual_national_code	string	required if type=INDIVIDUAL
legal_national_code	string	required if type=LEGAL
province_id	string	optional
city_id	string	optional
address	string	optional
postal_code	string	optional
mcc_code	string	optional

توضیحات

business_id (اجباری): آیدی کسب و کار
first_name (اختیاری): نام مشتری در صورتی که نوع مشتری حقیقی باشد.
last_name (اختیاری): نام خانوادگی مشتری در صورتی که نوع مشتری حقیقی باشد.
legal_name (اختیاری): نام حقوقی در صورتیکه مشتری حقوقی باشد.
agent_name (اختیاری): نام نماینده شرکت در صورتی که مشتری حقوقی باشد.
type (اجباری): نوع مشتری که شامل حقیقی (INDIVIDUAL) و حقوقی (LEGAL) می‌باشد.
mobile (اجباری برای مشتری حقیقی): شماره موبایل مشتری در صورتی که نوع مشتری حقیقی باشد.
agent_mobile (اجباری برای مشتری حقوقی): شماره موبایل مشتری در صورتی که نوع مشتری حقوقی باشد.
telephone (اختیاری): شماره تلفن ثابت.
individual_national_code (اجباری برای مشتری حقیقی): کد ملی مشتری در صورتی که نوع مشتری حقوقی باشد.
legal_national_code (اجباری برای مشتری حقوقی): کد ملی مشتری در صورتی که نوع مشتری حقوقی باشد.
province_id (اختیاری): آیدی استان محل سکونت مشتری.
city_id (اختیاری): آیدی شهر محل سکونت مشتری.
address (اختیاری): آدرس محل سکونت مشتری.
postal_code (اختیاری): کدپستی محل سکونت مشتری.
mcc_code (اختیاری برای مشتری حقوقی): کد صنف مشتری.

نکته

برای دریافت آیدی استان و شهر از سرویس زیر استفاده نمایید:

https://api.vandar.io/v2/information/cities
برای دریافت آیدی اصناف از سرویس زیر استفاده نمایید:

https://api.vandar.io/v2/information/mccs

نمونه json برای ثبت نام مشتری حقیقی

{
    "business_id": "20",
    "first_name": "الناز",
    "last_name": "نوروزی",
    "type": "INDIVIDUAL",
    "mobile": "09121234567",
    "telephone": "",
    "individual_national_code": "1234567890",
    "province_id": "8",
    "city_id": "6",
    "address": "تهران...",
    "postal_code": ""
}

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

HTTP/1.1 200
{
    "status": "1",
    "message": "مخاطب با موفقیت ثبت گردید.",
    "result": {
        "customer": {
            "id": "35e431e0-210c-11ec-9200-79b42496d8e0"
        }
    }
}

نمونه json برای ثبت نام مشتری حقوقی

{
    "business_id": "20",
    "legal_name": "تست",
    "agent_name": "نوروزی",
    "type": "LEGAL",
    "agent_mobile": "09121234567",
    "telephone": "",
    "legal_national_code": "1234567890",
    "province_id": "8",
    "city_id": "6",
    "address": "تهران",
    "postal_code": ""
    "mcc_code": ""
}

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

HTTP/1.1 200
{
    "status": "1",
    "message": "مخاطب با موفقیت ثبت گردید.",
    "result": {
        "customer": {
            "id": "394dd280-210f-11ec-96d5-95b80dce5a5a"
        }
    }
}

۳. ویرایش اطلاعات مشتری

با استفاده از این سرویس می‌توانید اطلاعات مشتری را ویراش نمایید.

 METHOD: PUT
 URL: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}

پارامتر {business} نام انگلیسی کسب و کار است.

پارامتر {customer_uuid} شناسه یکتای مشتری می‌باشد که از طریق سرویس مشاهده لیست مشتریان قابل دسترسی می‌باشد.

پارامترهای مجاز

name	Type	Status
business_id	string	required
first_name	string	optional
last_name	string	optional
legal_name	string	optional
agent_name	string	optional
type	string	required in:INDIVIDUAL,LEGAL
mobile	string	optional
agent_mobile	string	optional
telephone	string	optional
individual_national_code	string	optional
legal_national_code	string	optional
province_id	string	required if city_id is set
city_id	string	required if province_id is set
address	string	optional
postal_code	string	optional
mcc_code	string	optional

توضیحات

business_id (اجباری): آیدی کسب و کار
first_name (اختیاری): نام مشتری در صورتی که نوع مشتری حقیقی باشد.
last_name (اختیاری): نام خانوادگی مشتری در صورتی که نوع مشتری حقیقی باشد.
legal_name (اختیاری): نام حقوقی در صورتیکه مشتری حقوقی باشد.
agent_name (اختیاری): نام نماینده شرکت در صورتی که مشتری حقوقی باشد.
type (اجباری): نوع مشتری که شامل حقیقی (INDIVIDUAL) و حقوقی (LEGAL) می‌باشد.
mobile (اختیاری برای مشتری حقیقی): شماره موبایل مشتری در صورتی که نوع مشتری حقیقی باشد.
agent_mobile (اختیاری برای مشتری حقوقی): شماره موبایل مشتری در صورتی که نوع مشتری حقوقی باشد.
telephone (اختیاری): شماره تلفن ثابت.
individual_national_code (اختیاری برای مشتری حقیقی): کد ملی مشتری در صورتی که نوع مشتری حقوقی باشد.
legal_national_code (اختیاری برای مشتری حقوقی): کد ملی مشتری در صورتی که نوع مشتری حقوقی باشد.
province_id (اختیاری): آیدی استان محل سکونت مشتری.
city_id (اختیاری): آیدی شهر محل سکونت مشتری.
address (اختیاری): آدرس محل سکونت مشتری.
postal_code (اختیاری): کدپستی محل سکونت مشتری.
mcc_code (اختیاری): کدپستی محل سکونت مشتری.

نکته

برای دریافت آیدی استان و شهر از سرویس زیر استفاده نمایید:

https://api.vandar.io/v2/information/cities
برای دریافت آیدی اصناف از سرویس زیر استفاده نمایید:

https://api.vandar.io/v2/information/mccs

نمونه json برای ثبت نام مشتری حقیقی

 {
     "business_id": "20",
     "first_name": "الناز",
     "last_name": "نوروزی",
     "type": "INDIVIDUAL",
     "mobile": "09121234567",
     "telephone": "",
     "individual_national_code": "1234567890",
     "province_id": "8",
     "city_id": "6",
     "address": "تهران...",
     "postal_code": "1234567890"
 }

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

 HTTP/1.1 200
 {
  "message": "مخاطب با موفقیت به‌روزرسانی شد.",
  "customer": {
      "name": "الناز نوروزی",
      "first_name": "الناز",
      "last_name": "نوروزی",
      "legal_name": null,
      "agent_name": null,
      "type": "INDIVIDUAL",
      "mobile": "09121234567",
      "agent_mobile": null,
      "telephone": null,
      "balance": 0,
      "legal_national_code": null,
      "individual_national_code": "1234567890",
      "province_id": "8",
      "province": "تهران",
      "city_id": "6",
      "city": "تهران",
      "address": "تهران...",
      "postal_code": "1234567890",
      "mcc_code": null,
      "mcc_name": "-"
  }
}

نمونه json برای ثبت نام مشتری حقوقی

 {
     "business_id": "20",
     "legal_name": "تست",
     "agent_name": "نوروزی",
     "type": "LEGAL",
     "agent_mobile": "09121234567",
     "telephone": "",
     "legal_national_code": "1234567890",
     "province_id": "8",
     "city_id": "6",
     "address": "تهران",
     "postal_code": ""
 }

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

 HTTP/1.1 200
 {
  "message": "مخاطب با موفقیت به‌روزرسانی شد.",
  "customer": {
      "name": "تست",
      "first_name": null,
      "last_name": null,
      "legal_name": "تست",
      "agent_name": "نوروزی",
      "type": "LEGAL",
      "mobile": null,
      "agent_mobile": "09121234567",
      "telephone": null,
      "balance": 0,
      "legal_national_code": "1234567890",
      "individual_national_code": null,
      "province_id": "8",
      "province": "تهران",
      "city_id": "6",
      "city": "تهران",
      "address": "تهران",
      "postal_code": "1234567890",
      "mcc_code": null,
      "mcc_name": "-"
  }
}

۴. حذف مشتری

در صورت نیاز به حذف یک مشتری از این سرویس استفاده نمایید.

METHOD: DELETE
URL: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}

پارامتر {business} نام انگلیسی کسب و کار است.

پارامتر {customer_uuid} شناسه یکتای مشتری می‌باشد که از طریق سرویس مشاهده لیست مشتریان قابل دسترسی می‌باشد.

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

HTTP/1.1 200
{
  "status": 1,
  "message": "مخاطب با موفقیت حذف گردید."
}

۵. نمایش اطلاعات مشتری

در این بخش امکان مشاهده اطلاعات یک مشتری را خواهید داشت.

Method: GET
Address: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}

پارامتر {business} نام انگلیسی کسب و کار است.

پارامتر {customer_uuid} شناسه یکتای مشتری می‌باشد که از طریق سرویس مشاهده لیست مشتریان قابل دسترسی می‌باشد.

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

HTTP/1.1 200
{
  "customer": {
      "name": "تست",
      "first_name": null,
      "last_name": null,
      "legal_name": "تست",
      "agent_name": "نوروزی",
      "type": "LEGAL",
      "mobile": null,
      "agent_mobile": "09121234567",
      "telephone": null,
      "balance": 0,
      "legal_national_code": "1234567890",
      "individual_national_code": null,
      "province_id": 8,
      "province": "تهران",
      "city_id": 6,
      "city": "تهران",
      "address": "تهران",
      "postal_code": "1234567890",
      "mcc_code": null,
      "mcc_name": "-"
  }
}

کیف پول

در این بخش مدیریت کیف پول مشتریان که شامل واریز، برداشت و مشاهده موجودی کیف پول مشتری می‌باشد، صورت می‌گیرد.

۱. موجودی کیف پول

در این یخش امکان مشاهده موجدی کیف پول مشتری را خواهید داشت.

Method: GET
Address: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}/wallet

پارامتر {business} نام انگلیسی کسب و کار است.

پارامتر {customer_uuid} شناسه یکتای مشتری می‌باشد که از طریق سرویس مشاهده لیست مشتریان قابل دسترسی می‌باشد.

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

HTTP/1.1 200
{
  "status": 1,
  "balance": 0,
  "currency": "RIAL"
}

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

در صورتی که شناسه مشتری به اشتباه داده شود خطای ۴۰۴ دریافت می‌کنید.

HTTP/1.1 422
{
  "status": 0,
  "message": "خطای 404 رخ داده است."
}

۲. واریز به کیف پول

در صورت نیاز به بالا بردن موجودی کیف پول مشتری می‌توانید با استفاده از این سرویس، یک تراکنش واریز به حساب، برای مشتری ثبت نمایید.

Method: POST
Address: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}/wallet/deposit

پارامتر {business} نام انگلیسی کسب و کار است.

پارامتر {customer_uuid} شناسه یکتای مشتری می‌باشد که از طریق سرویس مشاهده لیست مشتریان قابل دسترسی می‌باشد.

پارامترهای مجاز

name	Type	Status
amount	integer	required min=1
comment	string	optional
track_id	string	required

توضیحات:
- amount (اجباری): مبلغی که می‌خواهید به کیف پول مشتری اضافه شود.
- comment (اختیاری): توضیحات مربوط به تراکنش واریزی
- track_id (اجباری): شماره پیگیری غیرتکراری

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

HTTP/1.1 200
{
  "id": "0cf235d0-d48b-11ea-86cd-298ec898a9bd",
  "track_id": "123456",
  "status": 1,
  "message": "واریز با موفقیت انجام شد",
  "balance": 1000,
  "currency": "RIAL",
  "comment": "comment",
}

۲. برداشت از کیف پول

در صورت نیاز به پایین آرودن موجودی کیف پول مشتری می‌توانید با استفاده از این سرویس، یک تراکنش برداشت از کیف پول مشتری ثبت نمایید.

Method: POST
Address: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}/wallet/withdraw

پارامتر {business} نام انگلیسی کسب و کار است.

پارامتر {customer_uuid} شناسه یکتای مشتری می‌باشد که از طریق سرویس مشاهده لیست مشتریان قابل دسترسی می‌باشد.

پارامترهای مجاز

name	Type	Status
amount	integer	required min=1
comment	string	optional
track_id	string	required

توضیحات:
- amount (اجباری): مبلغی که می‌خواهید از کیف پول مشتری کم شود.
- comment (اختیاری): توضیحات مربوط به تراکنش برداشتی
- track_id (اجباری): شماره پیگیری غیرتکراری

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

HTTP/1.1 200
{
  "id": "0cf235d0-d48b-11ea-86cd-298ec898a9bd",
  "track_id": "123456",
  "status": 1,
  "message": "برداشت با موفقیت انجام شد",
  "balance": 1000,
  "currency": "RIAL",
  "comment": "comment"
}

تراکنش

در این بخش اطلاعات تراکنش‌های مشتریان قابل مشاهده می‌باشد.

۱. لیست تراکنش‌ها

با استفاده از این سرویس، لیست همه تراکنش های مشتری شامل واریز و برداشت را مشاهده می‌کنید.

Method: GET
Address: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}/transactions

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

HTTP/1.1 200
{
  "data": [
      {
          "uuid": "7641090d-41f4-48dd-8908-ce06560ffde3",
          "type": "withdraw",
          "amount": -1000,
          "comment": "کاهش کیف پول مشتری",
          "balance": "1000",
          "created_at": 1633082125,
          "updated_at": 1633082125
      },
      {
          "uuid": "f47f9242-968e-4cbf-902f-0e38ac9c3a3f",
          "type": "deposit",
          "amount": 1000,
          "comment": "افزایش کیف پول مشتری",
          "balance": "2000",
          "created_at": 1633081476,
          "updated_at": 1633081476
      },
      {
          "uuid": "7e86df2a-2870-47a7-aece-9d3e63bc5e73",
          "type": "deposit",
          "amount": 1000,
          "comment": "افزایش کیف پول مشتری",
          "balance": "1000",
          "created_at": 1633081255,
          "updated_at": 1633081255
      }
  ],
  "links": {
      "first": "https://customer.vandar.io/v2/business/{business}/customers/394dd280-210f-11ec-96d5-95b80dce5a5a/transactions?page=1",
      "last": "https://customer.vandar.io/v2/business/{business}/customers/394dd280-210f-11ec-96d5-95b80dce5a5a/transactions?page=1",
      "prev": null,
      "next": null
  },
  "meta": {
      "current_page": 1,
      "from": 1,
      "last_page": 1,
      "path": "https://customer.vandar.io/v2/business/{business}/customers/394dd280-210f-11ec-96d5-95b80dce5a5a/transactions",
      "per_page": 20,
      "to": 3,
      "total": 3
  },
  "status": 1
}

data:
- uuid: شناسه یکتای مشتری
- type: نوع تراکنش که شامل واریز(deposit) و برداشت (withdraw) می‌باشد
- amount: مبلغ تراکنش
- comment: توضیحات تکمیلی تراکنش
- balance: موجودی کیف پول مشتری بعد از انجام آن تراکنش
- created_at: تاریخ انجام تراکنش
- updated_at: تاریخ ویراش تراکنش
links:
- first: آدرس اولین صفحه
- last: آدرس آخرین صفحه
- prev: آدرس صفحه قبل
- next: آدرس صفحه بعد
meta:
- current_page: آدرس همین صفحه
- from: شماره اولین آیتمی که در این صفحه آمده است
- last_page: تعداد کل صفحات
- path: آدرس خالص بدون صفحه بندی
- per_page: تعداد آیتم در هر صفحه
- to: شماره آخرین آیتمی که در این صفحه آمده است
- total: تعداد کل آیتم ها

شبا

۱. ثبت شماره شبا

با اسفاده از این سوریس می‌توانید برای مشتری شماره شبا ثبت نمایید.

Method: POST
Address: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}/ibans

پارامتر {business} نام انگلیسی کسب و کار است.

پارامتر {customer_uuid} شناسه یکتای مشتری می‌باشد که از طریق سرویس مشاهده لیست مشتریان قابل دسترسی می‌باشد.

پارامترهای مجاز

name	Type	Status
iban	string	required

توضیحات:
- iban (اجباری): شماره شبا مشتری.

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

HTTP/1.1 200
{
    "status": 1,
    "data": {
        "account_number": "0001780000000",
        "resolved_account_owner": "الناز نوروزی",
        "account_description": "حساب فعال است",
        "id": "0f4b9c30-2360-11ec-bec5-fffd717e132a",
        "IBAN": "IR880620000000001780000000",
        "account_owner": [
            {
                "firstName": "الناز",
                "lastName": "نوروزی"
            }
        ],
        "bank_name": "آینده"
    }
}

۲. لیست شماره شباها

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

  Method: GET
  Address: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}/ibans

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

  HTTP/1.1 200
  {
    "current_page": 1,
    "data": [
        {
            "account_number": "0001780000000",
            "resolved_account_owner": "الناز نوروزی",
            "account_description": "حساب فعال است",
            "id": "0f4b9c30-2360-11ec-bec5-fffd717e132a",
            "IBAN": "IR880620000000001780000000",
            "account_owner": [
                {
                    "firstName": "الناز",
                    "lastName": "نوروزی"
                }
            ],
            "bank_name": "آینده"
        }
    ],
    "first_page_url": "https://customer.vandar.io/v2/business/{business}/customers/394dd280-210f-11ec-96d5-95b80dce5a5a/ibans?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://customer.vandar.io/v2/business/{business}/customers/394dd280-210f-11ec-96d5-95b80dce5a5a/ibans?page=1",
    "next_page_url": null,
    "path": "https://customer.vandar.io/v2/business/{business}/customers/394dd280-210f-11ec-96d5-95b80dce5a5a/ibans",
    "per_page": 20,
    "prev_page_url": null,
    "to": 1,
    "total": 1
}

۳. حذف شماره شبا

در صورت نیاز می‌توانید از این بخش شماره شبا مربوط به مشتری را حدف نمایید.

   METHOD: DELETE
   URL: https://api.vandar.io/v2/business/{business}/customers/{customer_uuid}/ibans/{iban_id}

پارامتر {business} نام انگلیسی کسب و کار است.

پارامتر {customer_uuid} شناسه یکتای مشتری می‌باشد که از طریق سرویس مشاهده لیست مشتریان قابل دسترسی می‌باشد.

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

   HTTP/1.1 200
{
    "status": 1,
    "data": {
        "message": "شماره شبا با موفقیت حذف شد."
     }
}