API محتوای سوداگاه
داده مزایده، مناقصه و استعلام را مستقیم در محصول خودتان استفاده کنید. API نسخه اول فقط محتوا و جستوجو را برمیگرداند؛ برآورد قیمت و چت هوشمند در API ارائه نمیشوند.
احراز هویت
کلید را از صفحه اشتراک بسازید و در هدر بفرستید. کلید فقط یکبار نمایش داده میشود.
Authorization: Bearer sg_...
سهمیه
۱۰٬۰۰۰ درخواست در ماه و حداکثر ۵ درخواست در ثانیه برای هر کلید.
نقاط انتهایی
| متد | مسیر | توضیح |
|---|---|---|
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://…"
}
]
}/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": []
}
]
}/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": "…"}
]
}/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 | عبور از محدودیت ۵ درخواست در ثانیه برای همان کلید. |