کنار دیوار بستری برای افزودن اطلاعات و خدمات به دیوار است. با ارائهٔ خدمات خود در کنار دیوار، به کاربران دیوار کمک کنید تجربهٔ خرید و فروش ساده‌تر، مطمئن‌تر و دلنشین‌تری را تجربه کنند. در کنار دیوار می‌توانید:
- به آگهی‌گذاران کمک کنید اطلاعات تکمیلی در آگهی‌های خود درج کنند.
- با همکاری آگهی‌گذاران خدمات تکمیلی روی آگهی‌ها ارائه دهید.
- با ارائهٔ خدمات در چت، تعامل کاربران را در راستای معاملهٔ سریع‌تر و مطمئن‌تر تسهیل کنید.
🚀 برای شروع کار در کنار دیوار، در پنل کنار دیوار ثبت‌نام کنید.
برخی از APIهای کنار دیوار در حال حاضر در مرحلهٔ آزمایشی هستند. در این مرحله ممکن است قواعد، سیاست‌ها و ابزارهای آزمایشی در بازه‌های زمانی کوتاه تغییر کنند. این تغییرات از طریق ایمیلی که در پنل کنار ثبت کرده‌اید به اطلاع شما می‌رسد. در صورت استفاده از این API ها، آمادگی به روزرسانی و تغییر در بازه‌های ۲ هفته‌ای را داشته باشید. آدرس APIهای آزمایشی در مستندات به جای نسخه‌بندی (مثلاً v2) با experimental شروع می‌شود.
به دلیل سرعت تغییرات، ممکن است در بازه‌های زمانی خاصی اطلاعات ارائه شده در مورد این APIها در این مخزن نیز ناقص یا نیازمند بروزرسانی باشند.
☎️ تماس با ما
- پاسخ سوالتان را در این مستندات پیدا نکرده‌اید؟ سوالات خود را اینجا بپرسید.
- برای افزونه‌ی خود درخواست تغییر یا انتشار دارید؟ در توسعه‌ی افزونه‌ی خود دچار مشکلی شده‌اید؟ درخواست خود را در پنل کنار دیوار ثبت کنید.
- برای طرح سایر مشکلات، موضوعات، نظرات، پیشنهادات، و ... با ما از طریق آدرس ایمیل kenar.support@divar.ir تماس بگیرید.
برای ارسال اولین درخواست به API های کنار دیوار این مراحل را بروید.
۱. در پنل کنار دیوار وارد شوید.
۲. یک برنامهٔ تستی بسازید، یا از مدیر یک برنامهٔ دیگر بخواهید شما را به برنامه‌اش اضافه کند.
۳. برای برنامهٔ مورد نظرتان کلید API بسازید.
۴. در قسمت آگهی‌های تستی یک آگهی بسازید تا بتوانید راحت‌تر تست کنید.
۵. می‌توانید فهرست درخواست‌ها را ببینید یا این کالکشن را دانلود کنید و در ابزارهایی مثل Postman وارد کنید و شروع کنید.
⏺ ریتینو
خدمات مختلف در کنار دیوار در قالب «برنامه» یا «اپلیکیشن» (Application) ها به کاربران ارائه می‌شوند. کاربران در نقاط مشخصی از دیوار مثل صفحهٔ آگهی یا چت، می‌توانند به درخواست خودشان با برنامهٔ شما در قالب یک برنامهٔ وب (Web Application)تعامل کنند، در صورت نیاز اجازه‌های لازم را به شما بدهند، خدمات مورد نظر را دریافت کنند و به دیوار برگردند.
برنامه‌های متصل به کنار دیوار با هر زبانی می‌توانند توسعه یابند، اما برقراری ارتباطشان با کنار دیوار از طریق درخواست‌های HTTP خواهد‌بود.
جزییات برنامه(ها)ی خود را در صفحهٔ اپ‌ها در پنل کنار دیوار می‌توانید ببینید. اطلاعات بیشتر در مورد مدیریت برنامه‌ها را اینجا بخوانید.
در حال حاضر خدماتی که از طریق صفحات مربوط به آگهی می‌توانید ارائه دهید، در قالب زیر است:
۱. برنامه‌های مرتبط با آگهی (از نظر دسته، شهر یا موارد دیگر) در قسمت مدیریت آگهی به کاربر پیشنهاد می‌شود.
۲. کاربر پس از انتخاب برنامهٔ شما، به آدرس مشخص شده هدایت می‌شود و وب‌اپلیکیشن شما در اپ دیوار باز خواهد شد.
۳. در صورت نیاز می‌توانید در وب‌اپ خود اطلاعات آگهی، اطلاعات کاربر یا آگهی‌های کاربر (با کسب اجازهٔ کاربر) را از دیوار دریافت کنید.
۴. به علاوه می‌توانید از کاربر اجازهٔ درج محتوا در آگهی مورد نظر را نیز بگیرید. این محتوا از ویجت‌های دیوار مثل متن، عکس، امتیاز و ... تشکیل می‌شود.
۵. پس از پایان کار، برنامه باید کاربر را به دیوار برگرداند.
۶. پس از انتشار، کاربران آگهی‌بیننده می‌توانند با محتوای درج‌شده تعامل داشته‌باشند (برای مثال، با استفاده از دکمه‌های اضافه شده، آدرس‌های مشخص شده در برنامهٔ شما را باز کرده و با وب‌اپلیکیشن شما تعامل کنند). دقت کنید که حتما بعد از پایان تعامل با کاربر، وی را به دیوار بازگردانید.
💡 مثال
یک سرویس پرداخت آنلاین، بعد از ثبت آگهی کالای نو، با فروشنده هماهنگ کرده، اطلاعات و مجوزهای لازم را از وی می‌گیرد، سپس با افزودن دکمهٔ پرداخت آنلاین به آگهی، به آگهی‌‌بینندگان امکان پرداخت سریع و از طریق درگاه را فراهم می‌آورد.
در این حالت سرویس شما به عنوان سرویس سمت بیننده آگهی ثبت می‌شود، در هنگام بازدید آگهی به کاربر معرفی خواهد شد و اگر کاربر بیننده انتخاب کند به سایت شما منتقل خواهد شد و اطلاعات مورد نیاز بیندده آگهی را در اختیار او قرار می‌دهید
برای اطلاعات دقیق تر اینجا را مطالعه کنید
💡 مثال
یک سرویس ارزیابی قیمت خودرو تحت عنوان ارزیابی قیمت در دسته‌های خودرو به بیننده های آگهی نمایش داده می‌شود، کاربر در صورت انتخاب کردن این سرویس به سایت آن ریدایرکت خواهد شد. سرویس مذکور اطلاعات آگهی را دریافت کرده و درباره مناسب بودن یا نبودن قیمت به کاربر اطلاعات می‌دهد.
📖 اطلاعات بیشتر در مورد افزونه‌های آگهی‌ها را اینجا بخوانید.
ارائهٔ خدمات در چت دیوار به طور کلی در قالب زیر انجام می‌شود:
۱. برنامه‌های مرتبط با آگهی و چت کاربران به آنها پیشنهاد داده‌می‌شود.
۲. پس از انتخاب برنامهٔ شما توسط کاربر، درخواستی از طرف دیوار به آدرسی که از قبل توسط شما در پنل مشخص شده ارسال می‌شود و کاربر به آدرسی که در پاسخ به درخواست دیوار می‌دهید، هدایت می‌شود.
۳. در این مرحله شما می‌توانید اطلاعات آگهی یا اطلاعات کاربر را (با اجازهٔ کاربر) از دیوار بگیرید.
۴. به علاوه، در این مرحله می‌توانید با اجازهٔ کاربر، در چت پیام ارسال کنید.
۵. شما می‌توانید به پیام‌های ارسالی در چت، دکمه‌هایی برای طرفین چت ضمیمه کنید که کاربران با استفاده از آنها، با برنامهٔ شما تعامل نمایند.
۶. بعد از پایان تعامل، برنامهٔ شما باید کاربر را به دیوار برگرداند.
💡 مثال
برنامهٔ پرداخت به کاربر خریدار پیشنهاد شده و وی برنامه را باز کرده، به آدرس ارسالی هدایت می‌شود. برنامه اطلاعات آگهی و شمارهٔ کاربر را دریافت کرده و از طریق درگاه بانکی، مبلغ را از وی دریافت می‌کند. برنامهٔ پرداخت سپس پیامی در چت ارسال می‌کند که ذیل آن دکمه‌ای برای فروشنده قرار گرفته تا از طریق آن، مبلغ را دریافت کند. فروشنده با زذ دکمه به آدرس مشخص شده هدایت می‌شود، برنامه شمارهٔ تماس وی را از دیوار دریافت کرده و سپس با دریافت اطلاعات بانکی، مبلغ را به فروشنده منتقل می‌کند.
💡 مثال
برنامهٔ تنظیم قرارداد به کاربر پیشنهاد می‌شود. وی از طریق برنامه نمونهٔ قرارداد دلخواه را انتخاب کرده، اطلاعات مربوط به خویش را وارد کرده و به شکل دیجیتال امضاء می‌کند. برنامه لینک مربوط به این قرارداد را به همراه پیامی در چت برای طرف دیگر ارسال می‌کند، کاربر دیگر با باز کردن لینک مشخص شده قرارداد را پر نموده و به صورت دیجیتال امضاء می‌کند، سپس برنامه نسخهٔ امضاء شده را برای طرفین در چت ارسال می‌کند.
📖 اطلاعات بیشتر در مورد افزونه‌های چت را اینجا بخوانید.
برای استفاده از قابلیت‌های کنار دیوار باید درخواست‌های HTTP به آدرس مربوطه ارسال کنید. هر درخواست باید شامل یک کلید API متعلق به برنامهٔ شما باشد تا دیوار از طریق آن هویت شما را احراز کند. برای ایجاد کلید برای برنامهٔ خود به [صفحهٔ کلیدها در پنل کنار][پنل کنار » کلیدها] مراجعه کنید.
🔒 نکات امنیتی
🔑 کلید را در هدرx-api-keyقرار دهید. درخواست‌های بدون کلید رد خواهند شد.
🙈 در پنل کنار، کلید API را فقط در زمان ساخت می‌توانید ببینید. در نگهداری از آن دقت کنید.
🤹 یک اپلیکیشن می‌تواند کلیدهای مختلف با دسترسی‌های متفاوت داشته باشد.
🛂 مطمئن شوید که هر کلید کمینهٔ دسترسی‌های مورد نیاز را دارد.
🕰️ کلیدها را به شکل دوره‌ای و منظم پاک کرده و با کلیدهای جدید جایگزین کنید.
🔥 هر اپلیکیشن می‌تواند فقط یک کلید برای دریافت اجازه‌های مختلف از کاربر داشته باشد.
📖 برای اطلاعات بیشتر در مورد امنیت کلیدها اینجا را بخوانید. برای اطلاعات بیشتر در مورد کلیدهای API اینجا را بخوانید.
برخی قابلیت‌ها، مثل دریافت اطلاعات شخصی کاربران یا افزودن محتوا به آگهی، نیازمند دریافت اجازه از کاربر هستند. در کنار دیوار، این فرآیند بر مبنای استاندارد OAuth 2.0 انجام می‌شود. برای کار با این استاندارد، در زبان‌ها و فریم‌ورک‌های مختلف، ابزارهای متنوعی وجود دارند که برخی از آنها را می‌توانید اینجا ببینید. برای اطلاعات بیشتر در این مورد، اینجا را بخوانید.
- برای تست خدمات روی آگهی‌ها اینجا را بخوانید.
- برای تست خدمات در چت [اینجا را بخوانید][راهنما » افزونه‌های چت » تست].
- برای اتصال یک آدرس عمومی و قابل دسترس در اینترنت به localhost خود، می‌توانید از سرویس‌هایی مثل ngrok یا Pinggy یا Loophole استفاده کنید.
در این قسمت فهرست درخواست‌ها، پارامترها و دسترسی‌های لازم برای هر کدام را می‌بینید. جزییات بیشتر در مورد هر درخواست را در صفحهٔ جزییات مربوط به درخواست مورد نظر می‌توانید بیابید.\
همهٔ آدرس‌های زیر با https://api.divar.ir/v${v}/open-platform شروع می‌شوند.
| v | endpoint | method | توضیحات | دسترسی‌های لازم برای اپ | دسترسی‌های احراز باز لازم | مستندات |
|---|---|---|---|---|---|---|
| 1 | /finder/post/{{token}} | GET | دریافت اطلاعات یک آگهی | GET_POST | - | اطلاعات آگهی |
| 1 | /finder/user-posts | GET | دریافت آگهی‌های یک کاربر | GET_USER_POSTS | USER_POSTS_GET | آگهی‌های کاربر |
| 2 | /finder/posts | POST | جستجوی آگهی بر اساس شهر و محله، دسته، کلیدواژه | SEARCH_POST | - | جستجو در آگهی‌ها |
| 1 | /users | POST | دریافت اطلاعات تماس یک کاربر | USER_RETRIEVE | USER_PHONE | اطلاعات کاربر |
| 2 | /addons/user/{{phone}} | POST | درج افزونه برای همهٔ آگهی‌های یک کاربر | USER_ADDON_CREATE | USER_ADDON_CREATE | درج افزونه‌ی کاربر |
| 1 | /addons/user/{{id}} | DELETE | حذف یک افزونهٔ درج شده از همهٔ آگهی‌های یک کاربر | USER_ADDON_CREATE | USER_ADDON_CREATE | حذف افزونه کاربر |
| 1 | /semantic/user/{{phone}} | POST | درج اطلاعات احراز به یک کاربر | USER_SEMANTIC_CREATE | USER_VERIFICATION_CREATE | درج اطلاعات معنایی کاربر |
| 1 | /semantic/user/{{phone}} | DELETE | حذف اطلاعات احراز درج شده برای یک کاربر | USER_SEMANTIC_DELETE | - | حذف اطلاعات معنایی کاربر |
| 1 | /payment-ticket/validate | POST | بررسی معتبر بودن تیکت پرداخت | - | - | بررسی صحت تیکت پرداخت |
| 2 | /events/subscriptions | POST | ایجاد هوک مطلع شدن از رویدادها | EVENTS_REGISTER_SUBSCRIPTION | - | رویدادها |
| 2 | /conversations/{{conversation-id}}/messages | POST | ارسال پیام در یک چت | CHAT_SEND_MESSAGE_OAUTH | CONVERSATION_SEND_MESSAGE CHAT_SUPPLIER_ALL_CONVERSATIONS_MESSAGE_SEND | ارسال پیام در چت |
| 1 | /assets/category | GET | فهرست دسته‌ها | - | - | مقادیر |
| 1 | /assets/city | GET | فهرست شهرها | - | - | مقادیر |
| 1 | /assets/district/{{city}} | GET | فهرست همهٔ محله‌ها یا محله‌های یک شهر با تنظیم شهر در آدرس | - | - | مقادیر |
| 1 | /assets/brand-model/light | GET | فهرست برندمدل‌ها در دستهٔ خودروی سواری | - | - | مقادیر |
| 1 | /assets/body-status | GET | فهرست نام‌های مربوط به وضعیت بدنه برای دستهٔ خودروی سواری | - | - | مقادیر |
| 1 | /assets/color/light | GET | فهرست رنگ‌ها در دستهٔ خودروی سواری | - | - | مقادیر |
| 1 | /assets/brand-model/mobile-phones | GET | فهرست برندمدل‌ها در دستهٔ گوشی موبایل | - | - | مقادیر |
| 1 | /assets/color/mobile-phones | GET | فهرست رنگ‌ها در دستهٔ گوشی موبایل | - | - | مقادیر |
| 1 | /assets/internal-storage | GET | فهرست نام‌ها و مقدار مربوط به حافظهٔ داخلی در دسته‌های مرتبط دیجیتال | - | - | مقادیر |
| 1 | /assets/ram-memory | GET | فهرست نام‌ها و مقدار مربوط به حافظهٔ RAM در دسته‌های مرتبط دیجیتال | - | - | مقادیر |
برای ارسال درخواست‌هایی که نیاز به دریافت مجوز از کاربر دارد از OAuth استفاده کنید. فرایند در یافت کلید دسترسی را در ادامه می‌بینید. جزییات اسکو‌پ‌های دسترسی را در مستندات هر درخواست و همچنین صفحهٔ اسکوپ‌ها می‌توانید ببینید
Redirect https://api.divar.ir/oauth2/auth
| نام پارامتر | مقدار | توضیحات |
|---|---|---|
| response_type | code | مقدار بازگشتی بعد از ریدایرکت کاربر از صفحهٔ احراز باز دیوار به صفحهٔ شما که در پارامتر redirect_uri مشخص می‌کنید |
| client_id | نام یکتای برنامهٔ شما که در قسمت مدیریت برنامهٔ پنل کنار دیوار می‌توانید ببینید | |
| redirect_uri | آدرسی از برنامهٔ شما که کاربر بعد از صدور (یا رد) اجازه‌های درخواستی به آن هدایت شود. (این آدرس باید URL encoded باشد، در فهرست آدرس‌های مجاز برنامهٔ شما در پنل کنار ثبت شده‌باشد و هیچ پارامتری در آن نباشد.) | |
| scope | جازه‌های مورد نیاز برای دریافت از کاربر که با اسپیس (" ") از هم جدا شدند. |
|
| state | ک مقدار دلخواه که در بازگشت کاربر به اپلیکیشن شما مجدد در پارامترهای URL قرار می‌گیرد. |
کاربر به آدرس redirect_uri که در گام اول مشخص کردید با پارامترهای زیر ریدایرکت می‌شود.
| نام پارامتر | مقدار | توضیحات |
|---|---|---|
| code | code | اگر کاربر با درخواست اجازهٔ شما موافقت کرده‌باشد، این مقدار را خواهید داشت. در غیر این صورت می‌توانید خطای متناسب به کاربر نمایش دهید. |
| state | مقداری که در پارامتر state در بخش قبل قرار دادید را عیناً این قسمت دریافت می‌کنید. |
در صورت موافقت کاربر و دریافت code در هنگام بازگشت به برنامه، می‌توانید با درخواست زیر access token دریافت کنید.
دقت شود در این درخواست هدر Content-Type حتما باید application/x-www-form-urlencoded باشد.
POST https://api.divar.ir/oauth2/token
{
"code": "c87sDtaqmWwgis7dYyukMqy6KAArNUFkukAPW8O90GmiEJkdmSTWH4KjSkNUP6FZ",
"client_id": "{{app_slug}}",
"client_secret": "{{client_secret}}",
"grant_type": "authorization_code",
"redirect_uri": "your redirect_uri"
}| نام پارامتر | مقدار | توضیحات |
|---|---|---|
| code | code | اگر کاربر با درخواست اجازهٔ شما موافقت کرده‌باشد، این مقدار را خواهید داشت. در غیر این صورت می‌توانید خطای متناسب به کاربر نمایش دهید. |
| redirect_uri | <redirect_uri> | با همان مقداری که برای ریکوئست اول (گرفتن کد در گام اول) قرار داده شده است پر شود. |
- پنل کنار
- اطلاعات آگهی
- افزونه‌های آگهی
- ویجت‌ها
- افزونه‌های چت
- افزونه‌های چت » ارسال پیام
- [افزونه‌های چت » محیط تست][راهنما » افزونه‌های چت » تست]
- احراز باز
- افزونه‌های کاربر
- تیکت پرداخت
