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

مقدمه

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

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

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

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

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