مقدمه
سرویس مشتریان چیست:
سرویس مشتریان جهت مدیریت طرفحسابهای پذیرندگان وندار ارائه شده است که توسط این سرویس، پذیرندگان میتوانند اطلاعات هویتی، کیف پول، شبا، اشتراکها و تراکنشهای مشتریان خود را مدیریت کنند.
توضیحات
برای تمامی درخواست های ارسالی باید مقادیر زیر در هدر ارسال شوند: توکن همان کلید 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": "شماره شبا با موفقیت حذف شد."
}
}