ورود و دسترسی‌ها

مخاطب: هر برنامه‌نویسی که اولین بار به API سلر ۳۶۰ وصل می‌شود.

🔑 کلید API

هر درخواست با یک کلید API شناسایی می‌شود. کلید را فروشنده در پنل سلر ۳۶۰ می‌سازد («تنظیمات پنل ← API و وب‌هوک ← ساخت کلید») و هنگام ساخت، دسترسی‌های آن را انتخاب می‌کند.

هر کلید فقط به یک پنل تعلق دارد. برای چند پنل، برای هر پنل یک کلید بسازید.
کلید فقط یک بار نمایش داده می‌شود. سلر ۳۶۰ خود کلید را نگه نمی‌دارد و فقط اثر رمزنگاری‌شده‌ی آن را ذخیره می‌کند؛ اگر کلید گم شد، کلید تازه بسازید.
کلید را هر وقت بخواهید باطل کنید؛ باطل شدن همان لحظه اعمال می‌شود.
در پنل، زمان و نشانی آی‌پی آخرین استفاده‌ی هر کلید نمایش داده می‌شود.

ارسال کلید

کلید را در سرآیند Authorization و به شکل Bearer بفرستید:

curl https://api.seller360.ir/v1/me \
  -H "Authorization: Bearer s360_live_aB3dE5fG7hJ9kL2mN4pQ6rS8tU0vW1xY"

نشانی همیشه با https:// شروع می‌شود. اگر پیام خام درخواست را ببینید (مثلا در ابزار عیب‌یابی)، خط اول آن GET /v1/me HTTP/1.1 است؛ «HTTP/1.1» نام قالب پیام است، نه نوع اتصال، و همین پیام داخل اتصال رمزنگاری‌شده‌ی HTTPS فرستاده می‌شود.

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

کلید آزمایشی و واقعی

شکل کلید	پنل	نوشتن در دیجی‌کالا
`s360_live_…`	پنل واقعی شما	انجام می‌شود
`s360_test_…`	پنل نمایشی سلر ۳۶۰	انجام نمی‌شود؛ نتیجه شبیه‌سازی می‌شود

با کلید آزمایشی کل اتصال را بدون خطر آزمایش کنید و فقط در پایان سراغ کلید واقعی بروید. رویدادهای کلید آزمایشی livemode: false دارند.

دسترسی‌ها (Scope)

هر مسیر دقیقا یک دسترسی لازم دارد (در مرجع مسیرها کنار هر مسیر آمده است). کلید را با کمترین دسترسی لازم بسازید؛ مثلا نرم‌افزار حسابداری فقط finance:read و reports:read می‌خواهد و هرگز نمی‌تواند قیمت یا موجودی را تغییر دهد.

حوزه	دسترسی	اجازه
کالا و موجودی	`catalog:read`	خواندن کاتالوگ کالا
کالا و موجودی	`catalog:write`	تغییر کاتالوگ و جفت کردن کد کالا
کالا و موجودی	`stock:read`	خواندن موجودی و رزرو
کالا و موجودی	`stock:write`	تغییر موجودی فروشنده
کالا و موجودی	`warehouse:read`	خواندن انبار دیجی‌کالا و هزینه‌ی ماندگاری
کالا و موجودی	`kardex:read`	خواندن کاردکس و انبارگردانی
کالا و موجودی	`kardex:write`	ثبت در کاردکس و انبارگردانی
کالا و موجودی	`purchasing:read`	خواندن پیشنهاد خرید و سفارش خرید
کالا و موجودی	`purchasing:write`	ثبت سفارش خرید
کالا و موجودی	`stock_split:read`	خواندن تقسیم موجودی
کالا و موجودی	`stock_split:write`	تنظیم و اجرای تقسیم موجودی
قیمت و رقابت	`prices:read`	خواندن قیمت
قیمت و رقابت	`prices:write`	تغییر قیمت فروش
قیمت و رقابت	`bot:read`	خواندن ربات قیمت‌گذاری
قیمت و رقابت	`bot:write`	کنترل ربات قیمت‌گذاری و استراتژی‌ها
قیمت و رقابت	`competition:read`	خواندن بای‌باکس و رقبا
قیمت و رقابت	`competition:write`	تنظیم پایش رقبا
قیمت و رقابت	`promotions:read`	خواندن تخفیف و کمپین
قیمت و رقابت	`promotions:write`	تغییر تخفیف و کمپین
سفارش و ارسال	`orders:read`	خواندن سفارش‌ها و تعهد ارسال
سفارش و ارسال	`shipping:read`	خواندن محموله و نوبت انبار
سفارش و ارسال	`shipping:write`	ساخت محموله و تنظیم ارسال
مالی و گزارش	`finance:read`	خواندن تراکنش و تسویه
مالی و گزارش	`finance:write`	تغییر شرایط تسویه و هزینه‌ها
مالی و گزارش	`reports:read`	خواندن گزارش‌ها
عمومی	`webhooks:manage`	مدیریت وب‌هوک‌ها
عمومی	`events:read`	خواندن رویدادها

مسیر GET /v1/me با هر کلیدی پاسخ می‌دهد و دسترسی‌ها و سقف‌های همان کلید را نشان می‌دهد.

خطاهای ورود

کد HTTP	خطا	معنی
`401`	`missing_api_key`	سرآیند `Authorization` ارسال نشده یا شکل آن `Bearer` نیست.
`401`	`invalid_api_key`	کلید نامعتبر است یا باطل شده است.
`403`	`https_required`	درخواست با HTTP ارسال شده است؛ کلید را باطل کنید.
`403`	`scope_missing`	کلید دسترسی لازم این مسیر را ندارد.
`403`	`module_inactive`	ماژول «API و وب‌هوک» برای این پنل فعال نیست.
`403`	`panel_unavailable`	پنل حذف شده یا پنل دیجی‌کالا نیست.
`403`	`subscription_inactive`	اشتراک پنل فعال نیست؛ خواندن ممکن است ولی تغییر در دیجی‌کالا نه.