Updated text and file names

divar-ir · Oct 1, 2023 · c421b4a · c421b4a
1 parent c445765
commit c421b4a
Show file tree

Hide file tree

Showing 10 changed files with 326 additions and 217 deletions.
diff --git a/ReadMe.md b/ReadMe.md
@@ -1,15 +1,58 @@
 # کنار دیوار
 
-**راهنمای برنامه‌نویسانه استفاده از کنار دیوار**
+مجموعه‌ای از ابزارها برای اضافه کردن امکانات، خدمات یا اطلاعات بیشتر به قسمت‌هایی از مسیر کاربر در دیوار
+## شروع
+برای استفاده از امکانات کنار باید در [پنل کنار دیوار](https://kenar.divar.ir/admin) حساب داشته‌باشید. 
+در پنل کنار، اپلیکیشن مورد نظر خود را اضافه و کلید مورد نیاز را برای صدا زدن APIها دریافت و شروع کنید.
+> در حال حاضر امکان ثبت نام عمومی وجود ندارد.
 
-> ⚠️ دردست نوشتار
+## اپلیکیشن
+هر حساب کاربری می‌تواند اپلیکیشن‌های متفاوتی تعریف کند و از طریق آنها خدمات خود را به کاربران دهد. هر اپلیکیشن می‌تواند نام، تصویر نمایه و نوع خدمت متفاوتی ارائه دهد. 
 
-## فهرست مطالب
+## کلید API
+هر اپلیکیشن می‌تواند کلید‌های API با دسترسی‌های متفاوتی داشته‌باشد و از طریق آن‌ها به کنار دیوار درخواست ارسال کند.
+این کلید همراه همهٔ درخواست‌ها که به کنار ارسال می‌شود باید در هدر `x-api-key` ارسال شود. 
 
-1. مدیریت دسترسی
-    - [داکیومنت فنی](./access/apikeys.md)
-2. است ها
-    - [داکیومنت فنی](./assets/assets.md)
-3. افزونه ها
-    - [داکیومنت فنی](widgets/index.md)
-    - [لینک فیگمای ویجت های افزونه ها](https://www.figma.com/file/ZhhSihwKTjiER1VUDX4ovh/%F0%9F%93%92-Kenar-Docs-(WIP)?type=design&node-id=2-4&mode=design&t=QGrDdUp5agET6as9-0)
+برای ساخت کلید جدید یا ویرایش اجازه‌نامه‌های کلیدهای موجود، پس از ورود به پنل، به [صفحهٔ API Keys](https://kenar.divar.ir/admin/info/apikeys) بروید.
+
+از دکمهٔ `New` برای  ساخت کلید جدید استفاده کنید. با انتخاب اپلیکیشن خود و انتخاب دسترسی‌های لازم، یک کلید جدید بسازید. 
+* از هدر `x-api-key` برای ارسال کلید استفاده کنید.
+* کلید API را فقط در زمان ساخت می‌توانید ببینید، پس در نگهداری آن دقت کنید.
+* فقط دسترسی‌های لازم را به یک کلید دهید. (مسئولیت استفادهٔ نادرست از API و دسترسی‌ها با صاحب اپلیکیشن است)
+* هر اپلیکیشن فقط یک کلید با قابلیت استفاده به عنوان کلید OAuth دارد که در قسمت [احرازِ باز](#احرازِ-باز-oauth) توضیح داده‌شده است.
+
+## افزونه‌ها
+به اجزایی که توسط سرویس‌دهنده‌های بیرونی به دیوار اضافه می‌شود افزونه یا Add-on می‌گوییم. در حال حاضر امکان توسعهٔ افزونه برای صفحهٔ آگهی و چت در دسترس است.
+### افزونه‌های آگهی
+در قسمت‌های مشخصی از صفحهٔ آگهی یا صفحهٔ مدیریت آگهی، می‌توان افزونه درج کرد. جزییات درخواست‌های مربوط به این افزونه‌ها را در صفحهٔ [افزونه‌های صفحهٔ آگهی](addons) ببینید.
+### افزونه‌های چت 
+افزونه‌های چت دیوار بر اساس شرایط (دستهٔ آگهی، شهر آگهی) به کاربران ارائه می‌شود و کاربران هنگام استفاده از یک نوع خدمات (مثلاً ارسال کالا) می‌توانند به اپ یا سایت شما هدایت شوند و خدمت مورد نظر را دریافت کرده و ادامه دهند.
+جزییات اتصال سرویس به چت دیوار را در [صفحهٔ افزونه‌های چت](chat) ببینید.
+## ویجت‌های دیوار
+ویجت‌ها اجزای تشکیل دهندهٔ صفحات در دیوار هستند، که بعضی از آنها را همانطور که در بالا اشاره شد می‌توانید به وسیلهٔ تعریف افزونه، در قسمت‌های مشخصی درج کنید. جزییات ویجت‌ها و روش استفاده از آنها را در [صفحهٔ ویجت‌های دیوار](widegts) ببینید.
+
+مثال از قراردادن ویجت در درخواست درج افزونه به یک آگهی
+```JSON
+{
+    "widgets": {
+        "widget_list": [
+            {
+                "widget_type": "LEGEND_TITLE_ROW",
+                "data": {
+                    "@type": "type.googleapis.com/widgets.LegendTitleRowData",
+                    "title": "ماشین‌باز",
+                    "subtitle": "کارشناسی سریع خودرو"
+                }
+            },
+            ...moreWidgets
+        ]
+    }
+}
+```
+
+## احرازِ باز (OAuth)
+برای درخواست اطلاعات یا دسترسی از کاربران دیوار استاندارد [OAuth 2.0](https://oauth.net/2/) ارائه می‌شود. کتابخانه‌های مرتبط برای استفاده از OAuth را [اینجا](https://oauth.net/code/) می‌توانید ببینید.
+
+برای اطلاع از APIها و روش استفاده از احراز باز، [صفحهٔ احراز باز (OAuth)](oauth) را ببینید.
+## منابع و مقادیر عمومی (Assets)
+برای دسترسی به مقادیر enum پرکاربرد و معمولاً ثابت دیوار مثل نام شهرها یا دسته‌ها، می‌توانید از API هایی که در [صفحهٔ Assets](assets) توضیح داده‌ایم استفاده کنید.
diff --git a/access/apikeys.md b/access/apikeys.md
diff --git a/addons/ReadMe.md b/addons/ReadMe.md
@@ -0,0 +1 @@
+# افزونه‌های صفحهٔ آگهی
diff --git a/assets/assets.md → assets/ReadMe.md b/assets/assets.md → assets/ReadMe.md
@@ -4,20 +4,20 @@
 منابعی که از دیوار دریافت میکنید کاربرد دارند. برای مثال در جستجوی آگهی برای
 فیلتر کردن روی مقادیر برند-مدل خودرو از است برند-مدل میتوانید گزینه‌های موجود را دریافت کنید.
 
-> اگرچه مقادیر است به ندرت تغییر میکنند، اما تضمینی برای ثابت ماندن ریسپانس نیست و هر زمان و بدون اطلاع تغییر خواهد کرد.
-> اما ساختمان داده دارای تغییر شکننده نخواهد بود.
+> اگرچه این مقادیر ثابت هستند و به ندرت تغییر میکنند، اما تضمینی برای ثابت ماندن پاسخ دریافتی نیست و ممکن است هر زمان و بدون اطلاع تغییر کنند.
+> البته ساختمان دادهٔ پاسخ، تغییری که باعث بروز خطا شود، نخواهد داشت.
 
-## دسته‌بندی‌ها
+## دسته‌ها
 
 درخواست
 
 ```http
 GET https://api.divar.ir/v1/open-platform/assets/category
 ```
 
-پاسخ
+نمونهٔ پاسخ
 
-```json5
+```JSON
 {
     "categories": [
         {
@@ -41,9 +41,9 @@ GET https://api.divar.ir/v1/open-platform/assets/category
 GET https://api.divar.ir/v1/open-platform/assets/city
 ```
 
-پاسخ
+نمونهٔ پاسخ
 
-```json5
+```JSON
 {
     "cities": [
         {
@@ -70,9 +70,9 @@ GET https://api.divar.ir/v1/open-platform/assets/city
 GET https://api.divar.ir/v1/open-platform/assets/district
 ```
 
-پاسخ
+نمونهٔ پاسخ
 
-```json5
+```JSON
 {
     "districts": [
         {
@@ -84,13 +84,8 @@ GET https://api.divar.ir/v1/open-platform/assets/district
 }
 ```
 
-برای دریافت محله‌های یک شهر خاص میتوان آنرا از طریق فانکشن زیر دریافت کرد
-
-```http request
-GET https://api.divar.ir/v1/open-platform/assets/district/tehran
-```
-
-لیست شهرهای دارای محله به شرح زیر است:
+### محله‌های یک شهر
+می‌توانید محله‌های شهرهای زیر را از آدرسی که در ادامه می‌بینید دریافت کنید:
 - shiraz
 - isfahan
 - rasht
@@ -100,20 +95,22 @@ GET https://api.divar.ir/v1/open-platform/assets/district/tehran
 - ahvaz
 - mashhad
 
+```http request
+GET https://api.divar.ir/v1/open-platform/assets/district/{{city}}
+```
 
-## برندمدل‌ها
 
-ریکوئست
+## برند-مدل‌ها
+
+در دسته‌های `light` برای خودرو و `mobile-phones` برای کالاهای دیجیتال می‌توانید از آدرس زیر لیست برند‌مدل‌ها را دریافت کنید:
 
 ```http request
 GET https://api.divar.ir/v1/open-platform/assets/brand-model/{{category}}
 ```
 
-فقط دسته‌بندی‌های `light` و `mobile-phones` دارای برندمدل هستند.
-
-ریسپانس
+نمونهٔ پاسخ
 
-```json5
+```JSON
 {
     "brand_models": [
         {
@@ -131,17 +128,14 @@ GET https://api.divar.ir/v1/open-platform/assets/brand-model/{{category}}
 
 ## رنگ‌ها
 
-درخواست
+مشابه برند-مدل، برای دسته‌بندی‌های `light` و `mobile-phones` می‌توانید لیست رنگ‌های موجود در دیوار را از آدرس زیر دریافت کنید.
 
 ```http request
 GET https://api.divar.ir/v1/open-platform/assets/color/{{category}}
 ```
+نمونه پاسخ
 
-فقط دسته‌بندی‌های `light` و `mobile-phones` دارای رنگ هستند.
-
-پاسخ
-
-```json5
+```JSON
 {
     "colors": [
         {
@@ -163,9 +157,9 @@ GET https://api.divar.ir/v1/open-platform/assets/color/{{category}}
 GET https://api.divar.ir//v1/open-platform/assets/internal-storage
 ```
 
-پاسخ
+نمونهٔ پاسخ
 
-```json5
+```JSON
 {
     "internal_storages": [
         {
@@ -188,9 +182,9 @@ GET https://api.divar.ir//v1/open-platform/assets/ram-memory
 ```
 
 
-پاسخ
+نمونهٔ پاسخ
 
-```json5
+```JSON
 {
     "ram_memories": [
         {
@@ -212,9 +206,9 @@ GET https://api.divar.ir//v1/open-platform/assets/ram-memory
 GET https://api.divar.ir//v1/open-platform/assets/body-status
 ```
 
-پاسخ
+نمونهٔ پاسخ
 
-```json5
+```JSON
 {
     "body_status": [
         {

diff --git a/chat/ReadMe.md b/chat/ReadMe.md
@@ -0,0 +1 @@
+# افزونه‌های چت دیوار