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

مقدمه

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

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

توضیحات

برای تمامی درخواست های ارسالی باید مقادیر زیر در هدر ارسال شوند: توکن همان کلید 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": "شماره شبا با موفقیت حذف شد."
     }
}