ثبت سفارش

هر سفارش سایت با یک درخواست، فاکتور فروش در حسابداری نمو می‌شود — و اگر پرداخت شده، دریافت وجه هم.

POST/api/v1/orders/

دسترسی لازم: orders.write

نمونه

curl https://panel.nemosystem.ir/api/v1/orders/ \
  -H "Authorization: Bearer $NEMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "site:shop.example.com",
    "external_id": "10452",
    "date": "2026-10-01",
    "customer": { "name": "مینا صدری", "mobile": "09124445566", "email": "mina@example.com" },
    "items": [
      { "sku": "3101", "name": "ساعت مچی کلاسیک", "quantity": 2, "unit_price": 2500000 },
      { "sku": "3207", "quantity": 1, "unit_price": 1200000, "discount": 100000 }
    ],
    "shipping": 450000,
    "discount": 300000,
    "payment": { "method": "online", "reference": "ZP-000222", "date": "2026-10-01" }
  }'

پاسخ 201 Created:

{
  "source": "site:shop.example.com",
  "external_id": "10452",
  "status": "paid",
  "status_display": "پرداخت‌شده",
  "total": "6250000",
  "invoice_number": 84,
  "invoice_status": "posted",
  "receipt_number": 37,
  "return_number": null,
  "error": null,
  "duplicate": false
}

فیلدها

customer

اگر موبایل نفرستید، سفارش به «مشتری پیش‌فرض» تنظیمات اتصال ثبت می‌شود؛ اگر آن هم انتخاب نشده باشد، خطای 400 برمی‌گردد.

items[]

payment

وجه به «حساب دریافت وجه سفارش‌ها» در تنظیمات اتصال واریز می‌شود. اگر آن حساب صندوق باشد، دریافت «نقد» ثبت می‌شود؛ اگر بانک باشد، «انتقال» (یا «کارت‌خوان» برای card/pos).

سفارشی که هنوز پرداخت نشده (مثلاً پرداخت در محل) را بدون payment بفرستید و بعداً پرداختش را جدا ثبت کنید.

مالیات

نمو نرخ مالیاتی را که در تنظیمات اتصال انتخاب شده روی همهٔ ردیف‌ها (و هزینهٔ ارسال) می‌گذارد:

• «قیمت‌های سایت شامل مالیات است» خاموش: قیمت‌ها بدون مالیات فرض می‌شوند و مالیات به آن‌ها اضافه می‌شود.
• روشن: مالیات از دل قیمت‌ها جدا می‌شود؛ جمع فاکتور با جمع سایت یکی می‌ماند.

وضعیت سفارش

needs_review خطا نیست — سفارش پذیرفته شده و دوباره فرستادنش لازم نیست. دلیل‌های معمول: موجودی کالا کافی نیست، «قطعی‌سازی خودکار» خاموش است، یا حساب دریافت وجه انتخاب نشده. وقتی حسابدار مشکل را رفع کند و «تلاش دوباره» بزند، اگر وب‌هوک ثبت کرده باشید خبرش به شما می‌رسد.

ارسال تکراری

یک سفارش (همان source و external_id) فقط یک بار ثبت می‌شود. اگر دوباره بفرستید — مثلاً چون پاسخ اول به‌خاطر timeout نرسید — پاسخ 200 OK با همان نتیجهٔ اول و "duplicate": true برمی‌گردد و هیچ سندی ساخته نمی‌شود. بدنهٔ ارسال دوم نادیده گرفته می‌شود؛ برای تغییر سفارش ثبت‌شده باید در پنل اقدام شود.

پس قاعدهٔ ساده این است: هر وقت مطمئن نیستید سفارش رسیده، دوباره بفرستید.

استثنا: اگر ارسال قبلی با خطای 400 رد شده بود (مثلاً SKU ناشناخته)، چیزی ثبت نشده؛ بعد از اصلاح، ارسال دوباره سفارش را از نو ثبت می‌کند.

خواندن وضعیت یک سفارش

GET/api/v1/orders/{external_id}/?source={source}

همان پاسخ بالا (بدون duplicate) را برمی‌گرداند. اگر سفارش ثبت نشده باشد، 404.

curl "https://panel.nemosystem.ir/api/v1/orders/10452/?source=site:shop.example.com" \
  -H "Authorization: Bearer $NEMO_KEY"

گام بعد

پرداخت و برگشت ←