مقدمه
سرویس معاملات امن چیست:
میاندو برای خریدار هویت فروشنده و برای فروشنده، پرداخت مبلغ از سوی خریدار را تضمین میکند. خریدار مبلغ معامله را نزد میاندو به امانت میگذارد تا پس از ارائه کالا یا خدمت و تایید خریدار، این مبلغ برای فروشنده آزاد شود.
نحوه فعالسازی:
شما برای استفاده از سرویس پرداخت امن میاندو نیاز دارید که در ابتدا برای کسب و کار خود درخواست فعالسازی ابزار پرداخت امن را ثبت کنید تا پشتیبانی بعد از تایید آن را برای شما فعال کند. در غیر این صورت شما نمیتوانید از سرویس پرداخت امن در کسب و کار خود استفاده کنید.
پس از فعالسازی به دو مقدار client_id و client_secret دسترسی پیدا خواهید کرد که با استفاده از این مقادیر میتوانید جهت دریافت توکن کسب و کار خود اقدام کنید.
احراز هویت درخواست ها:
همانطور که گفته شد تمامی درخواست های ارسالی به OpenAPI ابزار پرداخت امن وندار نیازمند یک توکن است که مربوط به کسب و کار شماست.
برای دریافت توکن شما میتوانید درخواست زیر را به سرویس SSO وندار ارسال کنید تا توکن مربوطه را دریافت کنید.
Method: POST Address: https://api.vandar.io/sso/oauth/token
پارامترهای مجاز
name | Type | Status |
---|---|---|
grant_type | string | required |
client_id | int | required |
client_secret | string | required |
نمونه درخواست با فرمت صحیح:
{ "grant_type" : "client_credentials", "client_id": 1, "client_secret": "orFFZ7314ufiYt1D1bqJ0aJxO2AL2e8IKAjQG1iW" }
نمونه پاسخ دریافتی موفق:
HTTP/1.1 201
{
"token_type": "Bearer",
"expires_in": 31536000,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI3NSIsImp0aSI6ImEyYmQzY2Y5MDAxZDMwMGUyY2VhNzAxMjBhZTYzMjVlYmE1MmU2OTlhNmY1MzJiY2Q4OTFjMTk3OThjNGFmZjYxMjZjYTZmY2QwMDhhNTRkIiwiaWF0IjoxNjY2NTQ2NTY0LjA4NTY4OSwibmJmIjoxNjY2NTQ2NTY0LjA4NTY5MiwiZXhwIjoxNjk4MDgyNTY0LjA3NjQ4LCJzdWIiOiIiLCJzY29wZXMiOlsicGFydG5lciJdfQ.PWInLbjoC2MkhXxgGsqA5LfQkSnQEVXEARw2nJGEiFlz3a-c7pi12UVe-1hNm0IOcSW6NZXd7oKOyFxqhBl5WgAWPaAbM3WEy4R3Va-fo7ikmr77Xu1RcPqJwqRS3Dkyf4Ug-8sd9FSabGafCt6jfG163b-5bdqwV9WQJIbbSNuXMuQmuil2qK5F4kBLgUQaWGC170cNBSQCWVcyuFRc7-qYLYQqz08y2a6rcC2xkR7F3UmjSqU35eWGyhqRsy5iijtEZ-mZlVs2OSEbyNSylkKPSE0Z2r4gwKVbw-Qbx1iZchhSfalLhlbJGvNIcOhXGqYQCJyru2PVeP4zaG34TRccGwTmAR-Yx1hat2VBclK3Tzc6f9wqzSkhaTDwkLKGVwNrrKALf84fbGz14yC_LY6PL-atdS1RbHHkDb_Gl0WuPNeW4aNbpxHIqflOJjh6pVPuejAYIi-fomiRt7SQwwSFxeEKlvHNjIBZqecIKmfAYYNTdHTq4k91kH8LxKo4U4lXMIsvhh9uDszX9yMXwAivRX4F8AzI4sERrx51cosZ0vzrJUdg_nlKMIOGW2hIM9pCxZSekEr7PDgq5dKqDbcjnUegnPLJcc-1UdnUlOtwa005VRrs-2NdkdEAWy7oTSDFjqd3D5ItZ7sLhCZLnjtOPJ_fbpk4Ov95zwrgidsao"
}
برای تمامی درخواست های ارسالی باید مقادیر زیر در هدر ارسال شوند.
Accept: application/json Authorization: Bearer {access_token}
نمونه پاسخ دریافتی در صورت عدم احراز هویت:
HTTP/1.1 401
{
"error": "Unauthenticated"
}
مشتریان
مشریان در میاندو به اشخاصی اطلاق میشود که به عنوان طرفین معامله (خریدار، فروشنده) به خرید و فروش میپردازند.
۱. ایجاد مشتری:
در این بخش میتوانید یک مشتری ایجاد کنید که بتواند در یک معامله شرکت کند.
Method: POST Address: https://api.vandar.io/miando/api/v1/customers
پارامترهای مجاز
name | Type | Status |
---|---|---|
first_name | string | required |
last_name | string | required |
national_code | string | required |
mobile | string | required |
birth_date | string | required |
نمونه درخواست با فرمت صحیح:
{ "first_name" : "رضا", "last_name": "رضایی", "national_code": "1271234567", "mobile": "09123456789", "birth_date": "13700502" }
نمونه پاسخ دریافتی موفق:
HTTP/1.1 201
{
"message": "اطلاعات شما با موفقیت ثبت شد و در دست بررسی است."
}
نمونه پاسخ دریافتی ناموفق:
HTTP/1.1 422
{
"message": "مقادیر ورودی صحیح نیستند.",
"code": "validation_error",
"errors": {
"first_name": "فیلد نام الزامی است",
"last_name": "فیلد نام خانوادگی الزامی است",
"national_code": "فیلد کدملی الزامی است",
"mobile": "فیلد موبایل الزامی است",
"birth_date": "فیلد تاریخ تولد الزامی است"
}
}
۲. نمایش مشتری
با استفاده از این سرویس میتوانید اطلاعات یک مشتری را مشاهده نمایید.
METHOD: GET URL: https://api.vandar.io/miando/api/v1/customers/{customer_uid}
پارامتر {customer_uid} شناسه مشتری میباشد.
نمونه پاسخ دریافتی موفق:
HTTP/1.1 200
{
"message": "نمایش موفق اطلاعات مشتری",
"data": {
"uid": 152790245,
"first_name" : "رضا",
"last_name": "رضایی",
"national_code": "1271234567",
"mobile": "09123456789",
}
}
نمونه پاسخ دریافتی ناموفق:
HTTP/1.1 400
{
"message": "اطلاعات کاربر در سیستم موجود نیست.",
"code": "user_not_found"
}
۳. لیست مشتریان
با استفاده از این سرویس میتوانید لیست مشتریهای ساخته شده را مشاهده نمایید.
METHOD: GET URL: https://api.vandar.io/miando/api/v1/customers
نمونه پاسخ دریافتی موفق:
HTTP/1.1 200
{
"data": [
{
"uid": 152777442,
"first_name" : "رضا",
"last_name": "رضایی",
"national_code": "1271234567",
"mobile": "09123456789"
},
{
"uid": 1633644556,
"first_name": "محمد",
"last_name": "محمدی",
"national_code": "1167723051",
"mobile": "09023456789"
}
],
"links": {
"first": "http://escrow.vandar.local/api/v1/customers?page=1",
"last": "http://escrow.vandar.local/api/v1/customers?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"links": [
{
"url": null,
"label": "pagination.previous",
"active": false
},
{
"url": "http://escrow.vandar.local/api/v1/customers?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "pagination.next",
"active": false
}
],
"path": "http://escrow.vandar.local/api/v1/customers",
"per_page": 15,
"to": 2,
"total": 2
},
"message": "نمایش موفق اطلاعات مشتریان"
}
معاملات
پیش نویسی است که پس از تایید طرفین به یک قرارداد بین فروشنده و خریدار در میاندو ثبت میشود.
۱. ایجاد معامله:
در این بخش میتوانید یک پیشنویس معامله ایجاد کنید.
پیشنویس معامله به این معناست که فقط طرف سازنده معامله را تایید کرده است و دیگر اشخاص حاضر در معامله هنوز معامله را تایید نکرده اند.
Method: POST Address: https://api.vandar.io/miando/api/v1/agreements
پارامترهای مجاز
name | Type | Status |
---|---|---|
trace_id | string | required |
currency_code | string | required |
redirect_url | string | required |
description | string | required |
creator | string | required |
settlement_type | string | required |
parties | array | required |
parties.*.role | string | required |
parties.*.mobile | string | required |
parties.*.iban | string | required |
items | array | required |
items.*.title | string | required |
items.*.category | string | required |
items.*.description | string | optional |
items.*.link | string | optional |
items.*.item_price | string | required |
items.*.price | string | required |
items.*.payer | string | required |
items.*.payment_method | string | required |
items.*.quantity | integer | required |
items.*.attachments | array | optional |
توضیحات
- trace_id (اجباری): شناسه یکتا سمت کسب و کار.
- currency_code (اجباری): واحد پول مورد استفاده در معامله (in:IRR).
- redirect_url (اجباری): لینک بازگشت به کسب و کار پس از پرداخت موفق.
- description (اجباری): توضیحات مربوط به توافق نامه.
- creator (اجباری): نقش ایجاد کننده معامله (in:buyer,seller).
- settlement_type (اختیاری):
نوع تسویه حساب معامله در صورت نهایی شدن (in:wallet,wallet_iban).
wallet: شارژ کیف پول ونداری کاربر
wallet_iban: شارژ کیف پول و سپس انتقال به شبای کاربر - parties.*.role (اجباری): نقش طرف معامله (in:buyer,seller).
-
parties.*.mobile (اجباری):
موبایل طرف معامله.
کاربر باید از قبل توسط شما به لیست مشتری ها اضافه شده باشد.
- parties.*.iban (اجباری): شماره شبا طرف معامله.
- items.*.title (اجباری): عنوان کالا.
-
items.*.category (اجباری):
دستهبندی کالا.
اسلاگهای مجاز جهت انتخاب دستهبندی:
general: عمومی
digital: دیجیتال - items.*.description (اختیاری): توضیحات کالا.
- items.*.link (اختیاری): لینک توضیحات مربوط به کالا.
- items.*.item_price (اجباری): مبلغ کل کالا.
- items.*.price (اجباری): مبلغ بیعانه کالا.
- items.*.payer (اجباری): نقش پرداختکننده هزینه مربوط به کالا (in:buyer,seller).
- items.*.payment_method (اجباری): نوع پرداخت: پرداخت کامل، پیش پرداخت (in:full-pay,pre-pay).
- items.*.quantity (اجباری): تعداد کالا.
- items.*.attachments (اختیاری): عکسهای مربوط به کالا.
نمونه درخواست با فرمت صحیح:
{ "trace_id": "89fa2150-c976-44ed-87d1-2037abf51821", "currency_code": "IRR", "redirect_url": "http://redirect.url", "description": "موبایل y8s", "creator": "buyer", "parties": [ { "role": "buyer", "mobile": "09123456789", "iban": "IR670120020000002353697200" }, { "role": "seller", "mobile": "09023456789", "iban": "IR040120020000002343697300" } ], "items": [ { "title": "موبایل y8s", "category": "digital", "description": "در حد نو", "link": "https://divar.ir/v/gYoSNB1z", "item_price": "200000", "price": "200000", "payer": "buyer", "payment_method": "full-pay", "quantity": 1, "attachments": [ "https://vandar.io/assets/img/home/dashboard-full.png", "https://vandarpay.github.io/docs/images/token-step1.png" ] } ] }
نمونه پاسخ دریافتی موفق:
HTTP/1.1 201
{
"message": "معامله با موفقیت ایجاد شد",
"data": {
"tracking_code": "2075222800",
"trace_id": "408ce627-d220-4658-9fca-0403ed46f1a7",
"description": "موبایل y8s",
"parties": [
{
"role": "buyer",
"state": "accepted",
"national_code": "1271234567",
"mobile": "09123456789"
},
{
"role": "seller",
"state": "pending",
"national_code": "1167723051",
"mobile": "09023456789"
}
],
"state": "draft",
"created_at": "2022-09-26T08:32:51.000000Z"
}
}
۲. تعیین وضعیت معامله
با استفاده از این سرویس میتوانید یک معامله را تایید یا رد کنید.
پس از تایید معامله توسط خریدار/فروشنده، لینک پرداخت جهت پرداخت مبلغ معامله توسط خریدار برگشت داده میشود که شما میتوانید از آن استفاده کنید.
METHOD: POST URL: https://api.vandar.io/miando/api/v1/agreements/{tracking_code}
پارامتر {tracking_code} کد رهگیری معامله میباشد.
پارامترهای مجاز
name | Type | Status |
---|---|---|
action | string | required |
applicant_mobile | string | required |
توضیحات
- action (اجباری): نوع عملیات (in:agree,reject).
- applicant_mobile (اجباری): موبایل کاربر درخواستدهنده.
نمونه درخواست با فرمت صحیح:
{ "action": "agree", "applicant_mobile": "09123456789" }
نمونه پاسخ دریافتی موفق به ازای تایید پیشنویس:
HTTP/1.1 200
{
"message": "درخواست ایجاد معامله تایید شد.",
"data": {
"web_view_link": "https://vandar.io/minado/payment/review/104148740"
}
}
نمونه پاسخ دریافتی موفق به ازای رد پیشنویس:
HTTP/1.1 200
{
"message": "درخواست ایجاد معامله رد شد."
}
نمونه پاسخ دریافتی ناموفق:
HTTP/1.1 422
{
"code": 422,
"message": "مقادیر ورودی صحیح نیستند",
"errors": {
"action": "فیلد نوع درخواست الزامی است",
"applicant_mobile": "فیلد موبایل تایید کننده الزامی است"
}
}
نمونه پاسخ دریافتی ناموفق به ازای وضعیت نامعتبر قرارداد:
HTTP/1.1 400
{
"message": "وضعیت قرارداد نامعتبر است!",
"code": "invalid_state_agreement"
}
۳. نهایی سازی معامله
شما با استفاده از این سرویس میتوانید معامله را نهایی کنید.
نهایی شدن معامله به این معناست که خریدار کالا را تحویل گرفته و مبلغ معامله باید به حساب فروشنده واریز شود.
تنها قراردادهایی که پرداخت آن ها با موفقیت انجام شده است قابلیت نهایی شدن را دارند.
METHOD: POST URL: https://api.vandar.io/miando/api/v1/agreements/{tracking_code}/finalize
پارامتر {tracking_code} کد رهگیری معامله میباشد.
پارامترهای مجاز
name | Type | Status |
---|---|---|
buyer_mobile | string | required |
توضیحات
- buyer_mobile (اجباری): موبایل کاربر درخواستدهنده.
نمونه درخواست با فرمت صحیح:
{ "buyer_mobile": "09123456789" }
نمونه پاسخ دریافتی موفق به ازای نهایی سازی معامله:
HTTP/1.1 200
{
"message": "معامله با موفقیت تکمیل شد.",
"data": {
"is_finalized": true,
}
}
نمونه پاسخ دریافتی ناموفق:
HTTP/1.1 422
{
"code": 422,
"message": "مقادیر ورودی صحیح نیستند",
"errors": {
"buyer_mobile": "فیلد موبایل خریدار الزامی است"
}
}
نمونه پاسخ دریافتی ناموفق به ازای وضعیت نامعتبر قرارداد:
HTTP/1.1 400
{
"message": "وضعیت قرارداد نامعتبر است!",
"code": "invalid_state_agreement"
}
۴. لغو معامله
شما با استفاده از این سرویس میتوانید یک معامله را لغو کنید.
خریدار فقط میتواند معامله ای را لغو کند که یا پیش نویس باشد یا طرفین معامله آن را تایید کرده باشند، این در صورتی است که فروشنده بعد از پرداخت خریدار یا در حالت ثبت مشکل نیز میتواند یک معامله را لغو کند.
در صورتی که خریدار مبلغی را پرداخت کرده باشد، بعد از لغو شدن معامله مبلغ معامله به حساب خریدار برگشت داده میشود.
METHOD: POST URL: https://api.vandar.io/miando/api/v1/agreements/{tracking_code}/cancel
پارامتر {tracking_code} کد رهگیری معامله میباشد.
پارامترهای مجاز
name | Type | Status |
---|---|---|
applicant_mobile | string | required |
توضیحات
- buyer_mobile (اجباری): موبایل کاربر درخواستدهنده.
نمونه درخواست با فرمت صحیح:
{ "applicant_mobile": "09123456789" }
نمونه پاسخ دریافتی موفق به ازای نهایی سازی معامله:
HTTP/1.1 200
{
"message": "معامله با موفقیت لغو شد.",
"data": {
"is_canceled": true,
}
}
نمونه پاسخ دریافتی ناموفق:
HTTP/1.1 422
{
"code": 422,
"message": "مقادیر ورودی صحیح نیستند",
"errors": {
"applicant_mobile": "فیلد موبایل درخواستدهنده الزامی است"
}
}
نمونه پاسخ دریافتی ناموفق به ازای وضعیت نامعتبر قرارداد:
HTTP/1.1 400
{
"message": "وضعیت قرارداد نامعتبر است!",
"code": "invalid_state_agreement"
}
۵. نمایش معامله
با استفاده از این سرویس میتوانید اطلاعات یک معامله را مشاهده نمایید.
METHOD: GET URL: https://api.vandar.io/miando/api/v1/agreements/{tracking_code}
پارامتر {tracking_code} کد رهگیری معامله میباشد.
نمونه پاسخ دریافتی موفق:
HTTP/1.1 200
{
"message": "نمایش موفق اطلاعات معامله",
"data": {
"tracking_code": "2051291079",
"trace_id": "ee6b9100-a0a4-478d-8535-9eecff8af4b6",
"description": "بنز s500",
"parties": [
{
"role": "buyer",
"state": "accepted"
"national_code": "1271234567",
"mobile": "09123456789"
},
{
"role": "seller",
"state": "accepted"
"national_code": "1167723051",
"mobile": "09023456789"
}
],
"items": [
{
"title": "بنز s500",
"description": "در حد نو",
"quantity": 1,
"link": "https://example.ir/v/gYoSNB1z",
"category": "digital"
}
],
"amount": 200000,
"state": "investigation",
"creator": "buyer",
"created_at": "2022-08-20T01:51:21.000000Z"
}
}
۶. لیست معاملات
با استفاده از این سرویس میتوانید لیست معاملات ساخته شده را مشاهده نمایید (اطلاعات در این صفحه بصورت صفحه بندی شده نمایش داده میشوند).
METHOD: GET URL: https://api.vandar.io/miando/api/v1/agreements
نمونه پاسخ دریافتی موفق:
HTTP/1.1 200
{
"data": [
{
"tracking_code": "896770185",
"trace_id": "68112b4f-9a93-4f2b-93db-070331fe3b74",
"description": "iphone 11",
"parties": [
{
"role": "buyer",
"state": "accepted"
"national_code": "1271234567",
"mobile": "09123456789"
},
{
"role": "seller",
"state": "accepted"
"national_code": "1167723051",
"mobile": "09023456789"
}
],
"items": [
{
"title": "phone 11",
"description": "در حد نو",
"quantity": 1,
"link": "https://example.ir/v/gYoSNB1z",
"category": "digital"
}
],
"amount": 418000,
"state": "draft",
"created_at": "2022-09-24T07:54:18.000000Z"
},
{
"tracking_code": "1678531126",
"trace_id": "d86452f4-9dcc-461d-aa0d-0542e0dbefda",
"description": "موبایل y8s",
"parties": [
{
"role": "buyer",
"state": "accepted"
"national_code": "1271234567",
"mobile": "09123456789"
},
{
"role": "seller",
"state": "accepted"
"national_code": "1167723051",
"mobile": "09023456789"
}
],
"items": [
{
"title": "موبایل y8s",
"description": "در حد نو",
"quantity": 1,
"link": "https://example.ir/v/gYoSNB1z",
"category": "digital"
}
],
"amount": 418000,
"state": "contract",
"created_at": "2022-09-24T11:18:13.000000Z"
}
],
"links": {
"first": "http://escrow.vandar.local/api/v1/agreements?page=1",
"last": "http://escrow.vandar.local/api/v1/agreements?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"links": [
{
"url": null,
"label": "pagination.previous",
"active": false
},
{
"url": "http://escrow.vandar.local/api/v1/agreements?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "pagination.next",
"active": false
}
],
"path": "http://escrow.vandar.local/api/v1/agreements",
"per_page": 15,
"to": 2,
"total": 2
},
"message": "نمایش موفق اطلاعات معاملات"
}
تیکتها
اگر در روند معامله مشکلی پیش آمد میتوانید با ثبت تیکت مشکل خود را بیان کنید.
۱. ایجاد تیکت:
در این بخش میتوانید تیکت ایجاد کنید.
Method: POST Address: https://api.vandar.io/miando/api/v1/tickets
پارامترهای مجاز
name | Type | Status |
---|---|---|
agreement_tracking_code | string | required |
reporter | string | required |
ticket_type_slug | string | required |
redirect_url | string | required |
callback | string | required |
description | string | required |
attachments | array | optional |
توضیحات
- agreement_tracking_code (اجباری): کد رهگیری معامله.
- reporter_mobile (اجباری): موبایل شخص.
- ticket_type_slug (اجباری):
نوع تیکت.
اسلاگهای مجاز جهت انتخاب نوع تیکت:
-
dont_access_to_seller: به فروشنده دسترسی ندارم
نقش ثبت کننده تیکت: buyer -
dispute_with_seller: با فروشنده اختلاف دارم
نقش ثبت کننده تیکت: buyer -
stop_buying: از خرید منصرف شدم
نقش ثبت کننده تیکت: buyer -
dont_access_to_buyer: به خریدار دسترسی ندارم
نقش ثبت کننده تیکت: seller -
dispute_with_buyer: با خریدار اختلاف دارم
نقش ثبت کننده تیکت: seller -
stop_selling: از فروش منصرف شدم
نقش ثبت کننده تیکت: seller -
commodity_delivered_buyer_not_end_transaction: کالا را تحویل دادهام ولی
خریدار پایان معامله را اعلام نمیکند
نقش ثبت کننده تیکت: seller -
other_cases: سایر موارد
نقش ثبت کننده تیکت: seller,buyer
-
dont_access_to_seller: به فروشنده دسترسی ندارم
- redirect_url (اجباری): لینک بازگشت به کسب و کار پس از ثبت مشکل.
- description (اجباری): توضیحات.
نمونه درخواست با فرمت صحیح:
{ "agreement_tracking_code": "1005544572", "ticket_type_slug": "dont_access_to_seller", "description": "توضیحات مربوط به شکایت", "reporter_mobile": "09123456789", "redirect_url": "http://redirect.url" }
نمونه پاسخ دریافتی موفق:
HTTP/1.1 201
{
"message": "تیکت با موفقیت ایجاد شد",
"data": {
"ticket_uid": 888143355,
"button": {
"type": "redirect_url",
"link": "http://redirect.url",
"text": "بازگشت"
}
}
}
وبهوک
شما با استفاده از سرویس وبهوک میاندو میتوانید در لحظه از اتفاقاتی که برای کاربرانتان در طول پروسهی پرداخت امن رخ میدهد مطلع شوید و از تغییرات اتفاق افتاده در سیستم آگاه باشید.
۱. ایجاد وبهوک:
در این قسمت شما میتوانید با معرفی آدرس وبهوک و لیست رویدادهای مورد نیازتان، وبهوکتان را ابجاد کنبد.
Method: POST Address: https://api.vandar.io/miando/api/v1/webhooks
پارامترهای مجاز
name | Type | Status |
---|---|---|
url | string | required |
events | array | required |
events.* | String | required |
توضیحات
- url (اجباری):
لینک به جهت ارسال وبهوک.
به جهت تامین امنیت وبهوک های ارسالی، لینک شما باید از نوع https باشد.
- events.* (اجباری):
لیست وبهوک های مورد نیاز.
جهت مشاهده اسلاگهای مجاز به لیست رویدادها مراجعه کنید
نمونه درخواست با فرمت صحیح:
{ "url" : "https://vandar.io/miando/webhook", "events" : [ "agreement_created", "agreement_finalized", "seller_agreed_agreement" ] }
نمونه پاسخ دریافتی موفق:
HTTP/1.1 201
{
"message": "اطلاعات وبهوک با موفقیت ثبت شد.",
"data": {
"id": 1,
"url": "https://vandar.io/miando/webhook",
"is_active": true,
"events": [
{
"slug": "agreement_created",
"title": "معامله جدید ساخته شد"
},
{
"slug": "agreement_finalized",
"title": "معامله با موفقیت به پایان رسید"
},
{
"slug": "seller_agreed_agreement",
"title": "فروشنده معامله را پذیرفت"
}
]
}
}
نمونه پاسخ دریافتی ناموفق:
HTTP/1.1 422
{
"message": "مقادیر ورودی صحیح نیستند.",
"code": "validation_error",
"errors": {
"url": "فیلد لینک الزامی است",
"events": "فیلد رویداد ها الزامی است"
}
}
۲. بروزرسانی وبهوک:
شما با استفاده از این درخواست میتوانید وضعیت را فعال و غیرفعال کنید، آدرس وبهوک و لیست رویدادهای مورد نیاز را نیز ویرایش کنید.
Method: PUT Address: https://api.vandar.io/miando/api/v1/webhooks/{webhook_id}
پارامتر {webhook_id} شناسه وبهوک میباشد.
پارامترهای مجاز
name | Type | Status |
---|---|---|
url | string | required |
is_active | bool | required |
events | array | required |
events.* | String | required |
توضیحات
- url (اجباری): لینک به جهت ارسال وبهوک.
- is_active (اجباری): وضعیت سیستم وبهوک.
- events.* (اجباری):
لیست وبهوک های مورد نیاز.
جهت مشاهده اسلاگهای مجاز به لیست رویدادها مراجعه کنید
نمونه درخواست با فرمت صحیح:
{ "url": "https://shyepoortest.ir/webhook", "events": [ "seller_agreed_agreement", "agreement_finalized" ], "is_active": true }
نمونه پاسخ دریافتی موفق:
HTTP/1.1 200
{
"url": "https://shyepoortest.ir/webhook",
"events": [
"seller_agreed_agreement",
"agreement_finalized"
],
"is_active": true
}
نمونه پاسخ دریافتی ناموفق:
HTTP/1.1 422
{
"message": "مقادیر ورودی صحیح نیستند.",
"code": "validation_error",
"errors": {
"url": "فیلد لینک الزامی است",
"is_active": "فیلد وضعیت فعالسازی الزامی است",
"events": "فیلد رویداد ها الزامی است"
}
}
۳. نمایش وبهوک
با استفاده از این درخواست میتوانید اطلاعات یک وبهوک را مشاهده نمایید.
METHOD: GET URL: https://api.vandar.io/miando/api/v1/webhooks/{webhook_id}
پارامتر {webhook_id} شناسه وبهوک میباشد.
نمونه پاسخ دریافتی موفق:
HTTP/1.1 200
{
"message": "نمایش اطلاعات وبهوک با موفقیت انجام شد.",
"data": {
"id": 1,
"url": "https://shyepoortest.ir/webhook",
"is_active": true,
"events": [
{
"slug": "seller_agreed_agreement",
"title": "فروشنده معامله را پذیرفت"
},
{
"slug": "agreement_finalized",
"title": "معامله با موفقیت به پایان رسید"
}
]
}
}
۴. لیست وبهوکها:
شما با استفاده از این درخواست میتوانید لیست وبهوکهای خود را دریافت کنید.
Method: GET Address: https://api.vandar.io/miando/api/v1/webhooks
نمونه پاسخ دریافتی موفق:
HTTP/1.1 200
{
"message": "نمایش اطلاعات وبهوک با موفقیت انجام شد.",
"data": [
{
"id": 1,
"url": "https://shyepoortest.ir/webhook",
"is_active": true,
"events": [
{
"slug": "seller_agreed_agreement",
"title": "فروشنده معامله را پذیرفت"
},
{
"slug": "agreement_finalized",
"title": "معامله با موفقیت به پایان رسید"
}
]
}
]
}
۳. حذف وبهوک
با استفاده از این درخواست میتوانید اطلاعات یک وبهوک را حذف نمایید.
METHOD: DELETE URL: https://api.vandar.io/miando/api/v1/webhooks/{webhook_id}
پارامتر {webhook_id} شناسه وبهوک میباشد.
نمونه پاسخ دریافتی موفق:
HTTP/1.1 200
{
"message": "وبهوک با موفقیت حذف شد."
}
نمونه پاسخ دریافتی ناموفق:
HTTP/1.1 404
{
"message": "موردی یافت نشد",
"code": "not_found_error"
}
دریافت وبهوک:
تمامی وبهوکهای ارسالی به سمت لینک تنظیم شده شما در قالب زیر به صورت یک درخواست POST ارسال خواهند شد.
{ "created": 1666468058, "type": "agreement_finalized", "data": { "tracking_code": 796638828 } }
در تمامی وبهوک های مربوط به قرار داد شما tracking_code مربوط به قرار داد را دریافت خواهید کرد.
احراز هویت وبهوک های دریافتی:
بدلیل مسائل امنیتی تمامی وبهوک های ارسالی بهتر است از سمت دریافت کننده نیز احراز هویت شوند، به همین دلیل تمامی وبهوک های ارسالی از سمت میاندو دارای هدر X-Signature هستند که از یک الگوی مشخص برای رمز نگاری استفاده میکند که شما نیز باید در سمت خود این رمزنگاری را بررسی کنید و درصورت صحیح بودن این الگو از وبهوک استفاده کنید.
نمونه هدر ارسالی:
"X-Signature": "nbSOn\/WUA6lvhrkxv+QsTi9iCxhLskr8i4yz2rikj9I="
شما نیاز است که در هر وبهوک ارسالی این مقدار را بررسی کنید، نمونه کد بررسی این مقدار:
$hmac_header = $_SERVER['X-Signature']; $data = file_get_contents('php://input'); $calculated_hmac = base64_encode(hash_hmac('sha256', $data, BUSINESS_SLUG, true)); if(hash_equals($hmac_header, $calculated_hmac)) { // Valid header } else { // It's invalid }
در این قسمت شما نیاز است که با استفاده از داده دریافتی از سمت میاندو با الگوریتم داده شده مقدار هش شده را بسازید و سپس با مقدار دریافتی از هدر بررسی کنید ، درصورت برابر بودن این دومقدار میتوان نتیجه گرفت که هدر ارسالی هدر درست و معتبری است.
در مرحله اول نیاز است که شما داده ارسالی از سمت میاندو را که در فرمت Json است را با استفاده از الگوریتم هش SHA256 تولید کنید، در این قسمت از اسلاگ بیزنس شما (BUSINESS_SLUG) به جهت اعتبارسنجی مطمئن تر استفاده شده که همان نام انگلیسی بیزنس شما در وندار است.
لیست رویدادها و دیتای ارسالی:
- agreement: کل وبهوک های مربوط به قرارداد
-
agreement_created: معامله ایجاد شد
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", "creator_role": "buyer", "created_at": "2022-11-05 18:08:43", "creator_mobile": "09123456789" }
-
seller_agreed_agreement: فروشنده معامله را پذیرفت
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", "applicant_mobile": "09123456789" }
-
seller_rejected_agreement: فروشنده معامله را رد کرد
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", }
-
buyer_agreed_agreement: خریدار معامله را پذیرفت
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", "applicant_mobile": "09123456789" }
-
buyer_rejected_agreement: خریدار معامله را رد کرد
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", }
-
agreement_change_state_from_investigation: تغییر وضعیت معامله از معامله دارای مشکل
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", "trace_id": "ee6b9100-a0a4-478d-8535-9eecff8af4b6", "state": "finalize", }
-
agreement_finalized: معامله نهایی شد.
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", }
-
agreement_cancelled: معامله لغو شد.
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", }
- payment: کل وبهوک های مربوط به پرداخت
-
buyer_paid_agreement: خریدار مبلغ را به حساب امانی میاندو واریز کرد
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", "trace_id": "ee6b9100-a0a4-478d-8535-9eecff8af4b6", "transaction_ref_id": "548784521254", "payer_mobile": "09123456789", "amount": "4000000", }
-
payment_refunded_to_buyer: میاندو مبلغ پرداخت شده توسط خریدار را به حساب او بازگرداند.
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", "amount": "4000000", }
-
seller_checked_out: مبلغ معامله به حساب فروشنده واریز شد
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", "amount": "4000000", }
- ticket: کل وبهوک های مربوط به تیکت
-
buyer_submitted_ticket: خریدار مشکل ثبت کرد
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", "trace_id": "ee6b9100-a0a4-478d-8535-9eecff8af4b6", "reporter_mobile": "09123456789", }
-
seller_submitted_ticket: فروشنده مشکل ثبت کرد
نمونه دیتای ارسالی:
{ "tracking_code": "87441125", "trace_id": "ee6b9100-a0a4-478d-8535-9eecff8af4b6", "reporter_mobile": "09123456789", }