شروع کار با API دیدار

پیش از استفاده از Endpointهای دیدار، لازم است API Key خود را بسازید، روش ارسال آن را بدانید و با ساختار کلی Request و Response آشنا شوید. این صفحه اطلاعات عمومی و مشترک بین APIهای دیدار را توضیح می‌دهد. جزئیات هر عملیات، فیلدهای قابل‌ارسال و نمونه کامل Request و Response در صفحه همان Endpoint در بخش API Reference قرار دارد.

پیش‌نیازها

برای شروع کار با APIهای دیدار به موارد زیر نیاز دارید:

یک حساب فعال در دیدار
دسترسی ادمین برای ساخت و مدیریت API Key
یک API Key معتبر
ابزاری برای ارسال Request، مانند Postman، cURL یا کد Backend
آشنایی با HTTP و JSON

آدرس پایه API

تمام Requestهای API دیدار از آدرس پایه زیر ارسال می‌شوند:

https://app.didar.me

مسیر هر Endpoint به این آدرس اضافه می‌شود. برای مثال:

POST https://app.didar.me/api/product/save

احراز هویت با API Key

احراز هویت در APIهای دیدار با استفاده از API Key انجام می‌شود. API Key باید با پارامتر Query به نام apikey در URL درخواست ارسال شود:

?apikey={{API_KEY}}

نمونه یک URL کامل:

POST https://app.didar.me/api/product/save?apikey={{API_KEY}}

اگر API Key ارسال نشود یا مقدار آن نامعتبر باشد، API خطای 401 و خطای احراز هویت برمی‌گرداند.

ساخت و مدیریت API Key در دیدار

برای ساخت یا مدیریت API Key، کاربری که دسترسی ادمین دارد باید مسیر زیر را در دیدار طی کند:

وارد بخش تنظیمات شوید.
از منو، گزینه اتصال به سرورهای دیگر را انتخاب کنید.
در صفحه بازشده وارد تب اتصال به دیدار شوید.

در این بخش می‌توانید:

فهرست کلیدهایی را که قبلاً ایجاد کرده‌اید مشاهده کنید.
هر کلید را فعال یا غیرفعال کنید.
نام کلید را ویرایش کنید.
نوع دسترسی کلید را ویرایش کنید.
یک کلید دسترسی جدید بسازید.

به‌جز نام کلید و نوع دسترسی، سایر اطلاعات کلید قابل‌ویرایش نیستند.

نکته مهم هنگام ایجاد کلید جدید، مقدار API Key را همان لحظه در یک محل امن ذخیره کنید. پس از ایجاد کلید، دیگر امکان مشاهده مجدد مقدار API Key در دیدار وجود ندارد.

API Key را با API ID اشتباه نگیرید مقداری که برای احراز هویت و ارسال Request به APIهای دیدار نیاز دارید، API Key است. مقدار API ID برای احراز هویت قابل‌استفاده نیست.

تست APIها با Postman

برای شروع سریع‌تر می‌توانید Postman Collection دیدار را دانلود و در Postman وارد کنید.

دانلود Postman Collection

پس از دریافت فایل JSON:

در Postman روی گزینه Import کلیک کنید.
فایل JSON کالکشن را انتخاب کنید.
یکی از Requestهای موجود در Collection را باز کنید.
مقدار API Key خود را در محل مشخص‌شده قرار دهید.
Request را اجرا کنید.

ساختار کلی Requestها

متد، مسیر، پارامترها و بدنه هر Request در صفحه همان Endpoint مشخص شده است. در Requestهایی که بدنه دارند، اطلاعات معمولاً با فرمت JSON ارسال می‌شوند و Header زیر باید در Request قرار بگیرد:

Content-Type: application/json

نام فیلدها، Type آن‌ها و ساختار Objectها و Arrayها را دقیقاً مطابق مستندات همان Endpoint ارسال کنید. فیلدهایی که با عنوان الزامی مشخص شده‌اند باید حتماً در Request وجود داشته باشند. نمونه عمومی:

{
  "Entity": {
    "Title": "Sample title"
  }
}

ساختار کلی Responseها

Response APIهای دیدار با فرمت JSON برگردانده می‌شود. در بسیاری از Endpointها، داده اصلی پاسخ داخل پراپرتی Response قرار می‌گیرد. ساختار دقیق این مقدار براساس نوع Endpoint می‌تواند یک Object، Array یا مقدار دیگری باشد. نمونه پاسخ شامل یک Object:

{
  "Response": {
    "Id": "412c14f0-aef9-41b7-b186-53032c8e1e2b",
    "Title": "Sample title"
  }
}

نمونه پاسخ شامل یک Array:

{
  "Response": []
}

ساختار کامل Response، فیلدها و مقادیر احتمالی آن در صفحه اختصاصی هر Endpoint نمایش داده می‌شود.

ادامه مسیر

برای ادامه کار می‌توانید از بخش‌های زیر استفاده کنید:

​پیش‌نیازها

​آدرس پایه API

​احراز هویت با API Key

​ساخت و مدیریت API Key در دیدار

​تست APIها با Postman

​دانلود Postman Collection

​ساختار کلی Requestها

​ساختار کلی Responseها

​ادامه مسیر