۱ چه چیزی در دسترس است

دسترسی توسعه‌دهندگان بر پایهٔ همان حساب یکپارچهٔ کراپلود است؛ حساب جداگانه لازم نیست. امکانات فعلی و مسیر توسعهٔ آن‌ها:

هویت و حساب

شناسایی کاربر، خواندن پروفایل عمومی و وضعیت حساب از طریق نشست یا کلید دسترسی.

محتوا و مقالات

دسترسی به فهرست و جزئیات مطالب منتشرشدهٔ پلاس برای نمایش یا تحلیل.

جست‌وجوی سراسری

جست‌وجو در مقالات، محصولات و صفحات عمومی با پاسخ سریع.

کیف پول

مشاهدهٔ وضعیت و سابقهٔ تراکنش‌های حساب؛ عملیات مالی نیازمند مجوز صریح است.

اعلان‌ها

دریافت رویدادهای حساب از طریق نقاط پایانی یا وب‌هوک.

مستندات

مرجع فنی، نمونهٔ درخواست‌ها و تغییرات نسخه‌ها در مرکز مستندات.

۲ احراز هویت

دو مسیر برای احراز هویت وجود دارد و انتخاب آن به نوع کاربرد بستگی دارد:

  • نشست کاربر (Session): برای درخواست‌هایی که از طرف خود کاربر و با ورود او انجام می‌شود. مناسب ویجت‌ها و یکپارچه‌سازی درون‌مرورگری.
  • کلید دسترسی (API Key): برای ارتباط سرور به سرور. کلید باید فقط در محیط سرور نگهداری شود و هرگز در کد سمت کلاینت یا مخزن عمومی قرار نگیرد.
کلید دسترسی را مثل رمز عبور بدانید: در متغیر محیطی نگه دارید، دوره‌ای بچرخانید و در صورت افشا فوراً باطل کنید.

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

برای پایداری سرویس، هر کلید سقف درخواست دارد. اگر از سقف بگذرید، پاسخ 429 دریافت می‌کنید و باید با تأخیر پلکانی دوباره تلاش کنید.

  • 200 — موفق
  • 400 — درخواست نامعتبر یا پارامتر ناقص
  • 401 — احراز هویت انجام نشده یا کلید نامعتبر
  • 403 — دسترسی به این منبع مجاز نیست
  • 404 — منبع یافت نشد
  • 429 — عبور از سقف نرخ درخواست
  • 5xx — خطای موقت سرویس؛ تلاش مجدد با تأخیر منطقی
در خطاهای 5xx هرگز درخواست را در حلقهٔ بی‌پایان تکرار نکنید؛ تأخیر پلکانی و سقف تلاش تعیین کنید.

۴ نمونهٔ درخواست

ساختار درخواست‌ها ساده و قابل پیش‌بینی است. نمونهٔ خواندن فهرست مطالب:

curl -X GET "https://croplod.com/api/..." \
  -H "Authorization: Bearer <ACCESS_KEY>" \
  -H "Accept: application/json"

پاسخ‌ها همیشه JSON هستند و در خطا، ساختاری یکنواخت با پیام قابل فهم برمی‌گردانند تا مدیریت خطا در سمت شما ساده باشد.

۵ وب‌هوک‌ها

برای رویدادهای مهم، به‌جای نظرسنجی مکرر می‌توانید وب‌هوک دریافت کنید. اصول پیاده‌سازی:

  • نقطهٔ پایانی شما باید پاسخ سریع با کد 2xx بدهد.
  • پردازش سنگین را به صف پس‌زمینه منتقل کنید.
  • رویدادها ممکن است بیش از یک بار ارسال شوند؛ پردازش باید تکرارپذیر (idempotent) باشد.
  • امضای رویداد را پیش از اعتماد به محتوا اعتبارسنجی کنید.

۶ محیط آزمایشی

پیش از اتصال به دادهٔ واقعی، رفتار درخواست‌ها و مدیریت خطا را در محیط توسعه بررسی کنید. در صورت ارائهٔ محیط آزمایشی، نشانی و محدودیت‌های آن در مستندات همان بخش ذکر می‌شود.

۷ مسیر شروع در سه گام

  1. مطالعهٔ مستندات: از مرکز مستندات شروع کنید و مسیر مناسب نقش خود را انتخاب کنید.
  2. ساخت حساب و دریافت دسترسی: با حساب کراپلود وارد شوید و کلید دسترسی را در محیط سرور تنظیم کنید.
  3. آزمون و اتصال: با درخواست‌های ساده شروع کنید، مدیریت خطا را کامل کنید و سپس به محیط عملیاتی بروید.

۸ قواعد استفاده

  • استخراج انبوه داده بدون اجازهٔ کتبی مجاز نیست.
  • احترام به robots.txt و محدودیت نرخ الزامی است.
  • استفاده از نام و لوگوی کراپلود نیازمند مجوز است.
  • دادهٔ کاربران را تنها با مبنای قانونی معتبر پردازش کنید.
  • کلیدهای دسترسی را با دیگران به اشتراک نگذارید.

چارچوب کامل در شرایط استفاده آمده است.

۹ کمک و پشتیبانی

برای پرسش فنی، مشکل در یکپارچه‌سازی یا درخواست دسترسی جدید، از مسیرهای زیر استفاده کنید:

در پیام خود، نام سرویس، نقطهٔ پایانی و کد خطا را ذکر کنید تا بررسی سریع‌تر انجام شود.