قالب درخواست و پاسخ

📦 پاسخ موفق

همه‌ی پاسخ‌های موفق یک شکل دارند:

{ "status": "ok", "data": { } }

فهرست‌ها یک بخش pager هم دارند؛ نام فیلدهای آن همان نام‌های دیجی‌کالاست تا اگر با API دیجی‌کالا کار کرده‌اید، آشنا باشد:

{
  "status": "ok",
  "data": [ ],
  "pager": { "page": 1, "item_per_page": 50, "total_pages": 12, "total_rows": 587 }
}

پارامتر	پیش‌فرض	بیشینه
page	1	—
size	50	500

❌ پاسخ خطا

{
  "status": "error",
  "error": {
    "code": "variant_not_found",
    "message": "تنوعی با این شناسه در این پنل یافت نشد.",
    "detail": "variant 84780448",
    "doc_url": "https://docs.seller360.ir/errors#variant_not_found",
    "request_id": "c41f0d2a9b7e4f1a"
  }
}

• برنامه‌ی خود را روی code بنویسید، نه روی message. کدها هرگز تغییر نام نمی‌دهند؛ پیام‌ها ممکن است بهتر شوند.
• detail می‌گوید دقیقا چه چیزی نادرست بود (مثلا نام پارامتر) و همیشه وجود ندارد.
• doc_url به ردیف همین کد در فهرست خطاها پیوند دارد.

سرآیندهای هر پاسخ

سرآیند	معنی
X-Request-Id	کد پیگیری درخواست؛ هنگام تماس با پشتیبانی اعلام کنید.
X-RateLimit-Limit	سقف درخواست این نوع (خواندن یا نوشتن) در هر دقیقه برای این کلید.
X-RateLimit-Remaining	درخواست‌های باقی‌مانده تا پایان دقیقه‌ی جاری.
X-RateLimit-Reset	زمان شروع دقیقه‌ی بعد، به ثانیه از ۱۹۷۰.
Retry-After	فقط در پاسخ‌های 429 و 503: چند ثانیه صبر کنید.

💰 پول، عدد و تاریخ

• همه‌ی مبالغ به ریال و عدد صحیح‌اند؛ هیچ مبلغی اعشار ندارد.
• مبالغ مالی علامت‌دار هستند: مثبت یعنی پول به حساب شما، منفی یعنی پول از حساب شما.
• درصدها عدد اعشاری با یک رقم اعشارند (7.5 یعنی ۷٫۵ درصد).
• زمان‌ها با قالب ISO 8601 و منطقه‌ی زمانی‌اند (2026-11-12T10:15:03+03:30). روزها به وقت تهران حساب می‌شوند.
• شناسه‌ها (کد تنوع، کد سفارش، کد سریال) را عدد حساب نکنید و رقم صفر اولشان را نیندازید؛ بعضی شناسه‌ها رشته‌اند.

🔄 تازگی داده‌ها

سلر ۳۶۰ داده‌ها را از دیجی‌کالا می‌خواند و نسخه‌ای از آن‌ها نگه می‌دارد. هر منبع زمان آخرین خواندن را در synced_at (در موجودی: observed_at) دارد، و اگر از حد معمول عقب افتاده باشد، stale: true.

داده	به‌روزرسانی
موجودی و رزرو	با همگام‌سازی معمول سلر ۳۶۰؛ با افزونه‌ی «موجودی لحظه‌ای» حدود ۱۵ ثانیه
نوبت انبار	۳۰ ثانیه
تعهد ارسال و سفارش‌های باز	۵ دقیقه، و چند ثانیه پس از رویداد سفارش دیجی‌کالا
بای‌باکس و رقبا	با هر دور ربات؛ پایش رقبا حدود هر ۵ دقیقه
کاتالوگ	هر شب، و پس از هر تغییر
قیمت مرجع	روزانه
سفارش‌ها	هر شب، و پس از رویداد سفارش دیجی‌کالا
محموله‌ها	هر شب، و پس از رویداد محموله‌ی دیجی‌کالا
تراکنش‌ها و تسویه‌ها	هر شب
آمار رسمی دیجی‌کالا	هر بار زنده از دیجی‌کالا خوانده می‌شود (از سقف درخواست دیجی‌کالا مصرف می‌کند)

برای تغییرهای فوری به جای خواندن پیاپی، وب‌هوک دریافت کنید.

🧭 فازهای عرضه

هر مسیر یکی از سه فاز را دارد و در صفحه‌ها با نشان آن مشخص شده است:

فاز	شامل	نشان
۱	همه‌ی خواندن‌ها، رویدادها و وب‌هوک، و تغییرهایی که فقط در سلر ۳۶۰ ثبت می‌شوند (قیمت خرید، هزینه‌ها، کاردکس، تنظیمات)	«فاز ۱»
۲	تغییر در دیجی‌کالا: قیمت، موجودی، ربات قیمت‌گذاری، تخفیف	«فاز ۲»
۳	کارهای چندمرحله‌ای: ساخت کالا و تنوع، ساخت محموله، کمپین	«فاز ۳»

مسیرهایی که هم‌اکنون فعال‌اند، نشان «فعال» دارند.