راهنمای API برای فروشندگان

API برای کسب‌وکارهایی است که پلنشان «API» دارد. با آن، نرم‌افزار خودتان آگهی می‌سازد، قیمت را به‌روز می‌کند، عکس می‌فرستد و سرنخ‌ها را می‌خواند. همه‌ی قانون‌های سایت و همان بررسی ناظر برقرار است.

کلید

• کلید را در «حساب من › کلید API» بسازید. کلید فقط همان یک بار نمایش داده می‌شود؛ آن را در جای امنی بگذارید.
• کلید «فقط خواندن» فقط می‌خواند. برای ساختن و ویرایش آگهی، تیک «اجازه‌ی نوشتن» را بزنید.
• کلید را در سرآیند هر درخواست بفرستید، نه در نشانی:

Authorization: Bearer sg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• هر کلید سقف درخواست در دقیقه دارد. پاسخ‌ها سرآیندهای X-RateLimit-Limit و X-RateLimit-Remaining دارند. اگر سقف پر شود، پاسخ 429 با Retry-After می‌آید.
• اگر کلید لو رفت، همان‌جا «باطل کردن» را بزنید و کلید تازه بسازید.

نشانی‌ها

همه‌ی نشانی‌ها زیر /api/v1 هستند و پاسخ JSON است.

روش	نشانی	کار
GET	/me	نام کسب‌وکار، پلن و سهمیه
GET	/categories	زیردسته‌ها با خانه‌های فنی هر کدام (specs)
GET	/options	برندها، وضعیت دستگاه، تحویل، استان‌ها
GET	/listings?status=draft	آگهی‌های خودتان، ۵۰ تا در هر صفحه (page)
GET	/listings/{id}	یک آگهی، با فهرست آنچه هنوز کم است (missing)
POST	/listings	ساخت پیش‌نویس
PATCH	/listings/{id}	ویرایش؛ فقط خانه‌هایی که می‌فرستید عوض می‌شوند
POST	/listings/{id}/photos	فرستادن یک عکس (photo، multipart)
POST	/listings/{id}/submit	فرستادن برای بررسی
POST	/listings/{id}/reserve · unreserve · sold · archive	رزرو، برداشتن رزرو، فروخته‌شده، بایگانی
GET	/leads?since=2026-11-01	آخرین ۱۰۰ سرنخ

نمونه: ساخت پیش‌نویس

POST /api/v1/listings
Content-Type: application/json

{
  "title": "تراش CNC هاس ST-20 سال ۲۰۱۸",
  "category": "lathes",
  "brand": "haas",
  "condition": "used",
  "price": 2400000000,
  "province": "تهران",
  "specs": { "swing": 400, "length": 1000 }
}

• category شناسه یا slug زیردسته است، از /categories.
• brand نام یا slug برند است. برندی که در فهرست نیست همان‌طور که نوشته شود ثبت می‌شود.
• price به تومان است. برای قیمت توافقی، price را نفرستید و "price_negotiable": true بفرستید.
• خانه‌های specs همان کلیدهای /categories هستند. خانه‌ی ناشناخته نادیده گرفته می‌شود.

خطاها

خطای فیلدها با کد 422 و همان پیام‌های فارسی فرم سایت برمی‌گردد:

{ "message": "...", "errors": { "title": ["عنوان دست‌کم 8 نویسه می‌خواهد."] } }

کد	یعنی
401	کلید نیست، نادرست است یا باطل شده
403	پلن API ندارد، کلید فقط خواندنی است، یا حساب معلق است
404	آگهی پیدا نشد. آگهی کسب‌وکار دیگر هم همین را برمی‌گرداند.
422	داده‌ی فرستاده درست نیست، یا آگهی برای ارسال کامل نیست
429	سقف درخواست پر شد

حریم خریدار

سرنخ‌ها نام خریدار، آگهی، منبع (دیدن شماره یا گفتگو) و وضعیت پیگیری را دارند. موبایل خریدار هیچ‌وقت فرستاده نمی‌شود.