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

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

مقدمه

سرویس معاملات امن چیست:

میاندو برای خریدار هویت فروشنده و برای فروشنده، پرداخت مبلغ از سوی خریدار را تضمین می‌کند. خریدار مبلغ معامله را نزد میاندو به امانت می‌گذارد تا پس از ارائه کالا یا خدمت و تایید خریدار، این مبلغ برای فروشنده آزاد شود.

نحوه فعالسازی:

شما برای استفاده از سرویس پرداخت امن میاندو نیاز دارید که در ابتدا برای کسب و کار خود درخواست فعالسازی ابزار پرداخت امن را ثبت کنید تا پشتیبانی بعد از تایید آن را برای شما فعال کند. در غیر این صورت شما نمیتوانید از سرویس پرداخت امن در کسب و کار خود استفاده کنید.

پس از فعالسازی به دو مقدار 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"
}

نکته! توکن دریافت شده یکسال اعتبار دارد که درصورت منقضی شدن آن میتوانید مجددا نسبت به دریافت آن اقدام کنید (زمان انقضای توکن متغیر است و بسته به مقدار expires_in ممکن است تغییر کند).

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

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
deposit_price	integer	required
payer	string	required
payment_method	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.*.price	string	required
items.*.quantity	integer	required
items.*.attachments	array	optional

توضیحات

trace_id (اجباری): شناسه یکتا سمت کسب و کار.
currency_code (اجباری): واحد پول مورد استفاده در معامله (in:IRR).
redirect_url (اجباری): لینک بازگشت به کسب و کار پس از پرداخت موفق.
description (اجباری): توضیحات مربوط به توافق نامه.
creator (اجباری): نقش ایجاد کننده معامله (in:buyer,seller).
deposit_price (اجباری): مبلغ پرداختی معامله.
payer (اجباری): نقش پرداخت‌کننده هزینه مربوط به کالا (in:buyer,seller).
payment_method (اجباری): نوع پرداخت: پرداخت کامل، پیش پرداخت (in:full-pay,pre-pay).
parties.*.role (اجباری): نقش طرف معامله (in:buyer,seller).
parties.*.mobile (اجباری): موبایل طرف معامله.
کاربر باید از قبل توسط شما به لیست مشتری ها اضافه شده باشد.
parties.*.iban (اجباری): شماره شبا طرف معامله.
items.*.title (اجباری): عنوان کالا.
items.*.category (اجباری): دسته‌بندی کالا.

اسلاگ‌های مجاز جهت انتخاب دسته‌بندی:
general: عمومی
digital: دیجیتال
items.*.description (اختیاری): توضیحات کالا.
items.*.link (اختیاری): لینک توضیحات مربوط به کالا.
items.*.price (اجباری): مبلغ بیعانه کالا.
items.*.quantity (اجباری): تعداد کالا.
items.*.attachments (اختیاری): عکس‌های مربوط به کالا.

نمونه درخواست با فرمت صحیح:

{
  "trace_id": "89fa2150-c976-44ed-87d1-2037abf51821",
  "currency_code": "IRR",
  "redirect_url": "http://redirect.url",
  "description": "موبایل y8s",
  "creator": "buyer",
  "deposit_price": "200000",
  "payer": "buyer",
  "payment_method": "full-pay",
  "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",
      "price": "200000",
      "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
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 مربوط به قرار داد را دریافت خواهید کرد.

در این قسمت درصورت موفقیت آمیز بودن وبهوک شما باید HTTP Status Code 200 را خروجی دهید، در غیر این صورت وبهوک مربوطه ناموفق تلقی میشود و مجددا سعی در ارسال آن میشود.

احراز هویت وبهوک های دریافتی:

بدلیل مسائل امنیتی تمامی وبهوک های ارسالی بهتر است از سمت دریافت کننده نیز احراز هویت شوند، به همین دلیل تمامی وبهوک های ارسالی از سمت میاندو دارای هدر 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",
}