سازمانی

API محتوای سوداگاه

داده مزایده، مناقصه و استعلام را مستقیم در محصول خودتان استفاده کنید. API نسخه اول فقط محتوا و جست‌وجو را برمی‌گرداند؛ برآورد قیمت و چت هوشمند در API ارائه نمی‌شوند.

احراز هویت

کلید را از صفحه اشتراک بسازید و در هدر بفرستید. کلید فقط یک‌بار نمایش داده می‌شود.

Authorization: Bearer sg_...

سهمیه

۱۰٬۰۰۰ درخواست در ماه و حداکثر ۵ درخواست در ثانیه برای هر کلید.

دسترسی

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

فعال‌سازی پلن سازمانی

نقاط انتهایی

متدمسیرتوضیح
GET
/api/v1/ext/auctions

جست‌وجوی مزایده‌ها با q، category، province، limit و offset

GET
/api/v1/ext/auctions/{id}

جزئیات کامل یک مزایده شامل attributes و doc

GET
/api/v1/ext/facets

شمارش دسته‌بندی‌ها و استان‌ها

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

curl -H "Authorization: Bearer sg_your_key" \
  "https://api.sodagah.ir/api/v1/ext/auctions?q=پژو&category=خودرو&limit=20"

نمونه پاسخ

{
  "total": 1240,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "id": "…",
      "title": "مزایده پژو 207 …",
      "category": "خودرو",
      "province": "تهران",
      "base_price": 1200000000,
      "deadline": "1405/09/01 - 12:00",
      "source_url": "https://…"
    }
  ]
}
GET
/api/v1/ext/auctions

جست‌وجوی آگهی‌ها

پارامترها: q (متن آزاد)، category، province، limit (حداکثر ۱۰۰) و offset. فقط آگهی‌های فعال برمی‌گردند.

درخواست

curl -H "Authorization: Bearer sg_your_key"   "https://api.sodagah.ir/api/v1/ext/auctions?q=پژو&category=خودرو&province=تهران&limit=20"

پاسخ ۲۰۰

{
  "total": 1240,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "id": "auc_8f21c",
      "source_id": "setad",
      "source_name": "سامانه ستاد",
      "source_url": "https://…",
      "kind": "auction",
      "title": "مزایده پژو 207 مدل 1402",
      "category": "خودرو",
      "organizer": "اجرای احکام مدنی تهران",
      "province": "تهران",
      "city": "تهران",
      "base_price": 1200000000,
      "deadline": "1405/09/01 - 12:00",
      "status": "active",
      "tags": ["پژو", "خودرو"],
      "risk_flags": []
    }
  ]
}
GET
/api/v1/ext/auctions/{id}

جزئیات کامل یک آگهی

شناسه را از پاسخ جست‌وجو بردارید. description، attributes، doc و terms (واژه‌نامه همان آگهی) اضافه می‌شوند.

درخواست

curl -H "Authorization: Bearer sg_your_key"   "https://api.sodagah.ir/api/v1/ext/auctions/auc_8f21c"

پاسخ ۲۰۰

{
  "id": "auc_8f21c",
  "title": "مزایده پژو 207 مدل 1402",
  "organizer": "اجرای احکام مدنی تهران",
  "base_price": 1200000000,
  "description": "خودرو توقیفی، بدون گارانتی…",
  "attributes": {"مدل": "1402", "رنگ": "سفید"},
  "doc": {"url": "https://…/notice.pdf"},
  "terms": [
    {"key": "deposit", "term": "مبلغ تضمین", "short": "…"}
  ]
}
GET
/api/v1/ext/facets

شمارش دسته‌ها و استان‌ها

برای ساخت فیلتر در محصول شما. فقط آگهی‌های فعال شمرده می‌شوند.

درخواست

curl -H "Authorization: Bearer sg_your_key"   "https://api.sodagah.ir/api/v1/ext/facets"

پاسخ ۲۰۰

{
  "categories": [
    {"key": "خودرو", "count": 820},
    {"key": "املاک", "count": 614}
  ],
  "provinces": [
    {"key": "تهران", "count": 932},
    {"key": "اصفهان", "count": 210}
  ]
}

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

  • هر درخواست باید کلید معتبر و فعال داشته باشد.
  • محدودیت ۵ درخواست در ثانیه؛ در صورت عبور، پاسخ 429 برمی‌گردد.
  • سهمیه ماهانه در ابتدای هر ماه شمسی بازنشانی می‌شود.
  • بازنشر داده باید با ذکر منبع سوداگاه و لینک آگهی اصلی باشد.
  • برای استفاده تجاری سنگین یا ویجت اختصاصی با پشتیبانی تماس بگیرید.

کدهای خطا

کدمعنا
401

کلید ارسال نشده یا نامعتبر/غیرفعال است.

403

پلن فعلی دسترسی API ندارد (نیازمند پلن سازمانی).

429

عبور از محدودیت ۵ درخواست در ثانیه برای همان کلید.