خطاها

کدهای پاسخ API، شکل پیام خطا و اینکه با هر کدام چه کنید.

پیام‌های خطا فارسی و برای نمایش به کاربر پنل سایت مناسب‌اند. خطای مربوط به یک فیلد، زیر نام همان فیلد می‌آید؛ بقیه زیر detail:

{ "items": ["ردیف 1: کالایی با کد «NOPE» در حسابداری نیست. کد کالا (SKU) سایت باید با کد کالا در نمو یکی باشد."] }

{ "detail": "کلید API نامعتبر یا باطل‌شده است." }

کدها و کار درست

کد	یعنی	چه کنید	دوباره بفرستید؟
`200`	انجام شد (یا قبلاً انجام شده بود: `"duplicate": true`)	—	—
`201`	سفارش تازه ثبت شد	`status` را بخوانید؛ `needs_review` هم موفق است.	—
`400`	دادهٔ ارسالی مشکل دارد	پیام را بخوانید و داده یا تنظیمات را اصلاح کنید.	فقط بعد از اصلاح
`401`	کلید نفرستاده‌اید، نامعتبر یا باطل است، یا IP مجاز نیست	کلید را بررسی کنید.	خیر
`403`	کلید این دسترسی را ندارد، اشتراک سازمان فعال نیست، یا ماژول «اتصال فروشگاه آنلاین» فعال نیست	پیام دقیق را بخوانید.	پس از رفع
`404`	سفارش پیدا نشد (برای پرداخت، برگشت یا خواندن)	`external_id` و `source` را بررسی کنید؛ شاید سفارش هنوز فرستاده نشده.	—
`429`	بیش از ۱۲۰ درخواست در دقیقه	یک دقیقه صبر کنید.	بله
`5xx` یا قطع اتصال	مشکل موقت	با فاصلهٔ رو به افزایش (۱، ۵، ۲۵ دقیقه…) دوباره بفرستید.	بله، بی‌خطر

پیام	علت و راه حل
کالایی با کد «…» در حسابداری نیست	SKU سایت با کد کالا در نمو یکی نیست. کالا را در نمو با همان کد تعریف یا کد را اصلاح کنید.
مشتری مشخص نیست	موبایل معتبر نفرستاده‌اید و «مشتری پیش‌فرض» هم در تنظیمات اتصال انتخاب نشده.
سال مالی‌ای که این تاریخ را دربر بگیرد … تعریف نشده	تاریخ سفارش در هیچ سال مالی نمو نیست؛ حسابدار سال مالی را بسازد.
تاریخ باید به شکل YYYY-MM-DD (میلادی) باشد	تاریخ شمسی یا با قالب دیگر فرستاده‌اید.
تخفیف سفارش از جمع آن بیشتر است	`discount` از جمع ردیف‌ها و هزینهٔ ارسال بیشتر است.

پاسخ 201 با "status": "needs_review" یعنی سفارش پذیرفته شده و فاکتورش پیش‌نویس ساخته شده، اما حسابدار باید کاری بکند — علتش در error است:

این سفارش را دوباره نفرستید؛ بعد از رفع مشکل در پنل، وب‌هوک وضعیت تازه را خبر می‌دهد.

در پنل نمو، صفحهٔ اتصال فروشگاه ← سفارش‌های رسیده، هر ارسال — حتی ناموفق — با وضعیت و پیام خطایش ثبت است. اگر چیزی نرسیده، اول آن‌جا را ببینید.