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

آنچه یک فروشگاه، حسابداری یا CRM باید بدهد تا شیرین، مژده، آقا بهرام و جیمی کامل کار کنند

نسخه ۱

شیرین دستیار فروش موری روی سایت فروشگاه است: به خریدار محصول پیشنهاد می‌دهد، از موجودی و قیمت و ارسال جواب می‌دهد، وضعیت سفارش را می‌گوید و محصول را به سبد اضافه می‌کند. مژده دستیار فروشنده در تلگرام است: محصول، قیمت، موجودی، عکس، دسته و سفارش را با دستور فروشنده و فقط بعد از تأیید او ویرایش می‌کند. آقا بهرام حساب‌وکتاب را نگه می‌دارد: فروش، سود، طلب و بدهی و چک‌ها. جیمی پست و کمپین فروش را از روی محصول‌ها می‌سازد.

این سند برای سایت‌هایی است که خودشان برنامه‌نویسی شده‌اند، پلتفرم‌هایی که موری هنوز به آن‌ها وصل نیست، و کسب‌وکارهایی که حسابداری یا CRM خودشان را دارند. از روی کاری که امروز با میکسین، ووکامرس، شاپفا، سازیتو، باسلام و حسابفا می‌کنیم نوشته شده، نه فهرست آرزو.

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

حداقل برای شروع، فقط ۶ کارت ضروری است: خواندن محصولات (۱ و ۲)، ویرایش محصول (۸)، قیمت و موجودی هر تنوع (۹) و خواندن سفارش‌ها (۱۹ و ۲۰). برای حسابداری کارت‌های ۴۱ و ۴۲ و برای CRM کارت ۴۹ کافی است. بقیه اختیاری‌اند؛ اگر امکانی را ندارید (مثلاً وبلاگ یا دسته‌بندی)، لازم نیست بسازید. کارت‌های ۱ تا ۳۶ همان نسخه اول این سند است؛ کارت‌های ۳۷ به بعد بعداً اضافه شده‌اند و هر کدام در بخش خودش آمده، پس شماره‌ها در صفحه پشت سر هم نیستند.

#کارآدرسبرایاولویت
۱لیست محصولاتGET /productsشیرین، مژده، جیمیضروری
۲یک محصولGET /products/4854601شیرین، مژده، جیمیضروری
۳دسته‌بندی‌هاGET /categories · GET /categories/12شیرین، مژدهبهتر است
۴برندهاGET /brandsشیرین، مژدهبهتر است
۵ویژگی‌های استفاده‌شدهGET /attributesمژدهبهتر است
۶اطلاعات فروشگاهGET /storeشیرین، مژده، جیمیبهتر است
۷صفحه‌ها و نوشته‌های وبلاگGET /pages · GET /pages/17شیرین، مژدهبهتر است
۸ویرایش محصولPATCH /products/4854601مژدهضروری
۹ویرایش یک تنوعPATCH /products/4854601/variants/991مژدهضروری
۱۰ساخت محصولPOST /productsمژدهبهتر است
۱۱افزودن عکسPOST /products/4854601/imagesمژدهبهتر است
۱۲ترتیب و متن جایگزین عکسPATCH /products/4854601/images/23مژدهبهتر است
۱۳حذف عکسDELETE /products/4854601/images/23مژدهبهتر است
۱۴ویرایش گروهی قیمت و موجودیPATCH /products/bulkمژدهبهتر است
۱۵ساخت دستهPOST /categoriesمژدهبهتر است
۱۶ویرایش دستهPATCH /categories/12مژدهبهتر است
۱۷ساخت برندPOST /brandsمژدهبهتر است
۱۸ساخت و ویرایش صفحه یا نوشته وبلاگPOST /pages · PATCH /pages/17مژدهبهتر است
۵۲حذف دستهDELETE /categories/12مژدهبهتر است
۱۹یک سفارشGET /orders/9784051344شیرین، مژده، آقا بهرامضروری
۲۰لیست سفارش‌هاGET /ordersشیرین، مژده، آقا بهرامضروری
۲۱ثبت وضعیت و کد رهگیریPATCH /orders/9784051344مژدهبهتر است
۲۲ثبت سفارش دستیPOST /ordersمژدهبهتر است
۳۷خط مبلغ و یادداشت روی سفارشPOST /orders/9784051344/feesآقا بهرام، مژدهبهتر است
۳۸تغییر گروهی وضعیت سفارش‌هاPATCH /orders/bulkمژدهبهتر است
۲۳ساخت کد تخفیفPOST /discountsمژدهبهتر است
۲۴پایان کد تخفیفPATCH /discounts/551مژدهبهتر است
۲۵روشن و خاموش کردن روش ارسالPATCH /shipping-methods/postمژدهبهتر است
۲۶روشن و خاموش کردن درگاه پرداختPATCH /payment-methods/zarinpalمژدهبهتر است
۵۳ویرایش اطلاعات فروشگاهPATCH /storeمژدهبهتر است
۵۴ساخت روش ارسالPOST /shipping-methodsمژدهبهتر است
۲۷نظرهای خریدارانGET /reviews · PATCH /reviews/77مژدهبهتر است
۲۸گزارش بازدید و فروش محصولاتGET /reports/productsمژده، آقا بهرامبهتر است
۲۹اسکریپت ویجت روی همه صفحه‌ها<script>شیرینبهتر است
۳۰دیدن سبدGET /cart.jsonشیرینبهتر است
۳۱افزودن به سبدPOST /cart/itemsشیرینبهتر است
۳۲تغییر تعداد و حذف از سبدPATCH /cart/items/a81f · DELETE /cart/items/a81fشیرینبهتر است
۳۳ورود خریدار با کد پیامکیPOST /checkout/otp · POST /checkout/loginشیرینبهتر است
۳۴آدرس‌ها و روش‌های ارسالGET /checkout/addresses · POST /checkout/addresses · GET /checkout/shipping-optionsشیرینبهتر است
۳۵کد تخفیف روی سبدPOST /checkout/coupon · DELETE /checkout/couponشیرینبهتر است
۳۶ثبت سفارش و لینک پرداختPOST /checkout/place-orderشیرینبهتر است
۳۹نصب موری روی یک فروشگاهPOST {address Mori gives you}شیرین، مژده، آقا بهرامبهتر است
۴۰حذف موری از یک فروشگاهPOST {address Mori gives you}شیرین، مژده، آقا بهرامبهتر است
۴۱لیست فاکتورهاGET /invoicesآقا بهرامضروری
۴۲دریافت‌ها و پرداخت‌هاGET /paymentsآقا بهرامضروری
۴۳طرف‌حساب‌ها و ماندهGET /contactsآقا بهرامبهتر است
۴۴کالاها و قیمت خریدGET /itemsآقا بهرامبهتر است
۴۵چک‌ها و قسط‌های سررسیدGET /chequesآقا بهرامبهتر است
۴۶مانده بانک و صندوقGET /accountsآقا بهرامبهتر است
۴۷ثبت فاکتور فروشPOST /invoicesآقا بهرامبهتر است
۴۸ثبت دریافت یا پرداختPOST /paymentsآقا بهرامبهتر است
۴۹ثبت لید از گفتگوPOST /leadsشیرینضروری
۵۰پیدا کردن مشتریGET /contactsمژده، آقا بهرامبهتر است
۵۱یادداشت و پیگیری روی مشتریPOST /contacts/88/notesمژده، آقا بهرامبهتر است

الف. قواعد کلی

برای همه کارت‌ها، جز بخش «ز» که از مرورگر خریدار و روی دامنه خود سایت است.

قاعدهیعنی
۱. آدرس و قالبهمه درخواست‌ها روی HTTPS و با JSON (UTF-8). آدرس پایه برای هر فروشگاه یکی است، مثلاً https://example.ir/api/mori/v1، و همه مسیرهای این سند نسبت به آن‌اند. حسابداری و CRM هر کدام آدرس پایه خودشان را دارند.
۲. احراز هویتهدر Authorization: Api-Key {api_key}. فروشنده کلید را در پنل می‌سازد و در داشبورد موری وارد می‌کند. کلید فقط به داده همان فروشگاه دسترسی دارد و دو سطح دارد: read (فقط خواندن) و write (خواندن و نوشتن، برای مژده و آقا بهرام). شیرین در فروشگاه فقط read لازم دارد؛ در CRM، کلید شیرین باید اجازه ساخت لید (کارت ۴۹) داشته باشد. فروشنده باید بتواند کلید را باطل کند. برای چک کلید فروشگاه بعد از اتصال، GET /products?per_page=1 صدا زده می‌شود. حسابداری و CRM یک مسیر فقط‌خواندنی برای چک کلید معرفی کنند (مثلاً GET /me)؛ چک اتصال هیچ سند یا لیدی نمی‌سازد.
۳. پولعدد صحیح، بدون اعشار و جداکننده. هر پاسخی که مبلغ دارد فیلد currency دارد (IRR یا IRT)؛ مبلغ‌های تودرتو واحد شیء بالایی را دارند. در نوشتن همان واحدی را می‌فرستیم که در خواندن برگشته.
۴. زمانISO 8601 با منطقه زمانی، مثل 2026-11-14T10:00:00+03:30، هم در پاسخ و هم در پارامترها. تاریخ سند حسابداری بدون ساعت: 2026-11-14 (میلادی).
۵. صفحه‌بندیpage از ۱، per_page تا ۱۰۰. پاسخ لیست‌ها: count (تعداد کل نتیجه)، page، per_page، max_pages و آرایه نتیجه. ترتیب ثابت تا صفحه‌ها روی هم نیفتند.
۶. سرعتیک محصول یا یک سفارش زیر ۲ ثانیه، یک صفحه ۱۰۰تایی زیر ۱۰ ثانیه. حداقل ۵ درخواست در ثانیه برای هر کلید. بیش از سقف: 429 با هدر Retry-After (ثانیه). سقف را در مستندات بنویسید. نمونه مشکل: سقف ۱۰ درخواست در دقیقه یعنی خواندن ۱۰۰ محصول ۱۵ دقیقه طول می‌کشد.
۷. فایروالدرخواست‌های موری از سرورهای داخل ایران می‌آیند، سرور به سرور. فایروال یا CDN سایت (مثل آروان یا کلودفلر) جلوی این آدرس‌ها چالش «ربات نیستم» یا مسدودسازی نگذارد.
۸. نوشتنPATCH فقط فیلدهای فرستاده‌شده را عوض می‌کند و پاسخش شیء کامل بعد از ذخیره است؛ ما پاسخ را با چیزی که فرستادیم مقایسه می‌کنیم. فیلد لیستی کل لیست را جایگزین می‌کند. null یعنی خالی کردن. فیلد ناشناخته یا فقط‌خواندنی: 422، نه نادیده گرفتن بی‌صدا.
۹. هم‌زمانی (بهتر است)پاسخ GET هر محصول و سفارش هدر ETag دارد. اگر PATCH با If-Match آمد و شیء از آن موقع عوض شده بود، 412 برگردد و چیزی نوشته نشود. این جلوی جایگزین شدن ویرایشی را می‌گیرد که فروشنده همان لحظه در پنل کرده.
۱۰. تکرار نشدن (بهتر است)POSTی که هدر Idempotency-Key دارد، اگر با همان کلید تا ۲۴ ساعت دوباره آمد، همان نتیجه قبلی را برگرداند و محصول، سفارش، فاکتور یا لید دوم نسازد. اگر اتصال وسط ساختن قطع شود، بدون این هدر نمی‌دانیم ساخته شده یا نه.

شکل خطا

همه خطاها یک شکل دارند. message برای آدم است و فارسی هم می‌تواند باشد؛ fields فقط برای 422.

JSON
{ "error": { "code": "validation_failed", "message": "...", "fields": { "price": "must be above 0" } } }
کد HTTPerror.codeیعنی
400bad_requestپارامتر یا JSON خراب
401invalid_keyکلید نامعتبر یا باطل‌شده
402shop_suspendedاشتراک فروشگاه پرداخت نشده
403forbidden_scopeکلید فقط read است و درخواست نوشتن آمده
404not_foundمحصول، سفارش یا مسیر وجود ندارد
409conflictتکراری یا ناسازگار؛ message بگوید چرا (مثل last_image)
412precondition_failedETag عوض شده؛ دوباره بخوان
422validation_failedفیلد نامعتبر؛ fields بگوید کدام و چرا
429rate_limitedبیش از سقف؛ Retry-After
5xxserver_errorخطای سرور؛ دوباره امتحان می‌کنیم

مدل داده

فیلدهایی که در پاسخ محصول و سفارش لازم داریم. محصول بدون تنوع: variants خالی و قیمت و موجودی روی خود محصول. محصول تنوع‌دار: قیمت و موجودی روی هر تنوع، و ساختن، ویرایش یا حذف تنوع‌ها با فرستادن کل آرایه variants در کارت ۸ (تنوع با id ویرایش، بدون id ساخته، و تنوعی که نیامده حذف می‌شود).

محصول

فیلدنوعاولویتمعنی
idint | stringضروریشناسه ثابت؛ هیچ‌وقت عوض نشود
titlestringضرورینام محصول
urlstringضروریلینک عمومی صفحه محصول
statuspublished | draft | hiddenضروریفقط published برای خریدار دیده می‌شود
priceintضروریقیمت فروش الان، بعد از تخفیف
old_priceint | nullضروریقیمت خط‌خورده قبل از تخفیف؛ null یعنی تخفیف ندارد
currencyIRR | IRTضروریریال یا تومان؛ همه مبلغ‌ها با همین واحد
stock_typelimited | unlimited | call_for_priceضروریموجودی شمرده می‌شود، نامحدود، یا «تماس بگیرید»
stockint | nullضروریبرای limited: تعداد. برای محصول تنوع‌دار: جمع موجودی تنوع‌ها
availableboolضروریالان قابل خرید هست یا نه
descriptionHTMLضروریتوضیح کامل
imagesImage[]ضروریبه ترتیب نمایش؛ اولی عکس اصلی
category_idsint[]بهتر استهمه دسته‌های محصول؛ اولی دسته اصلی
variantsVariant[]ضروریخالی برای محصول بدون تنوع
attributes{name, value}[]بهتر استمشخصات فنی مثل جنس و ابعاد
updated_atISO 8601ضروریآخرین تغییر؛ پایه updated_since
sku, barcodestring | nullبهتر استکد کالا و بارکد
brand{id, name} | nullبهتر استدر نوشتن: brand_id
seo_title, seo_descriptionstringبهتر استعنوان و توضیح برای گوگل
tagsstring[]بهتر استبرچسب‌ها
weightint | nullبهتر استوزن بسته به گرم، برای هزینه ارسال
cost_priceint | nullبهتر استقیمت خرید، فقط برای سودی که آقا بهرام حساب می‌کند؛ هیچ‌وقت به خریدار نشان داده نمی‌شود
rating, review_countnumber, intبهتر استمیانگین امتیاز و تعداد نظر

تنوع (Variant)

فیلدنوعاولویتمعنی
idint | stringضروریشناسه ثابت تنوع
options{name, value}[]ضروریمثل رنگ نقره‌ای و سایز ۴۲
price, old_priceint, int | nullضروریمثل محصول
stockint | nullضروریnull یعنی شمرده نمی‌شود
availableboolضروریاین تنوع قابل خرید هست یا نه
is_defaultboolضروریدقیقاً یک تنوع پیش‌فرض؛ price محصول = price این تنوع
skustring | nullبهتر استکد کالای این تنوع
image_idint | nullبهتر استعکس این تنوع، از images محصول
cost_priceint | nullبهتر استقیمت خرید این تنوع، مثل محصول

سفارش

فیلدنوعاولویتمعنی
id, numberint | stringضروریشناسه داخلی و شماره‌ای که خریدار می‌بیند
statuspending | processing | shipped | delivered | cancelled | refundedضروریوضعیت سفارش
payment_statusunpaid | paid | failed | refundedضروریوضعیت پرداخت
created_at, updated_atISO 8601ضروریزمان ثبت و آخرین تغییر
paid_atISO 8601 | nullضروریبرای پرداخت‌نشده null
total, subtotal, discount_total, shipping_totalintضروریtotal = مبلغی که خریدار داد، با ارسال، بعد از تخفیف
currencyIRR | IRTضروریواحد همه مبلغ‌های سفارش
customer.mobilestringضروریبرای اینکه شیرین هویت خریدار را بسنجد
items{product_id, variant_id, title, quantity, unit_price, line_total}[]ضروریاقلام سفارش
shipping{method, status, carrier, tracking_code, tracking_url}ضروریارسال و کد رهگیری
payment_method, coupon_codesstring, string[]بهتر استروش پرداخت و کدهای تخفیف
customer.name, shipping_addressstring | null, object | nullبهتر استفقط به فروشنده نشان داده می‌شود، نه به خریدار دیگر
refunds{amount, created_at, reason}[]بهتر استبازپرداخت‌ها؛ آقا بهرام فروش خالص و واریز درگاه را با آن جور می‌کند
fees{name, amount}[]بهتر استخط‌های اضافه یا کسر روی سفارش (کارت ۳۷)؛ منفی یعنی کسر
source{utm_source, utm_medium, landing_url, referrer}بهتر استخریدار از کجا آمد؛ از کوکی یا پارامترهای اولین بازدید
meta.mori_thread_idstring | nullبهتر استاز کوکی mori_thread_id هنگام ثبت سفارش؛ فروش از گفتگو را دقیق می‌شمارد

ب. خواندن کاتالوگ

شیرین هر شب کل کاتالوگ را می‌خواند و در طول روز فقط تغییرها را؛ جواب‌هایش به خریدار از همین داده است. مژده قبل از هر ویرایش وضعیت فعلی را از همین آدرس‌ها می‌خواند و جیمی محصول‌ها را برای پست و کمپین برمی‌دارد.

۱. لیست محصولات

ضروریبرای شیرین، مژده، جیمیموری ← فروشگاه
درخواست
GET /products?page=1&per_page=100
    &updated_since=2026-11-13T00:00:00+03:30
    &status=published
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "count": 555,
  "page": 1,
  "per_page": 100,
  "max_pages": 6,
  "products": [ ... ]
}

هر عضو products کامل و دقیقاً مثل پاسخ کارت ۲ است (با variants و images). updated_since و status اختیاری‌اند. ترتیب ثابت (id صعودی) تا صفحه‌ها روی هم نیفتند. محصول حذف‌شده در لیست نمی‌آید؛ ما با خواندن کامل شبانه آن را از کاتالوگ خودمان حذف می‌کنیم. کاتالوگ تا ۲۰٬۰۰۰ محصول یعنی ۲۰۰ صفحه.

۲. یک محصول

ضروریبرای شیرین، مژده، جیمیموری ← فروشگاه
درخواست
GET /products/4854601
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "id": 4854601,
  "title": "Steel wall socket",
  "url": "https://example.ir/product/4854601",
  "status": "published",
  "price": 7800000,
  "old_price": 8500000,
  "currency": "IRT",
  "stock_type": "limited",
  "stock": 12,
  "available": true,
  "sku": "SK-4854601",
  "barcode": null,
  "weight": 350,
  "cost_price": 5200000,
  "description": "<p>...full HTML...</p>",
  "seo_title": "...",
  "seo_description": "...",
  "category_ids": [12, 31],
  "brand": { "id": 3, "name": "Melloni" },
  "tags": ["socket"],
  "attributes": [
    { "name": "Material", "value": "Steel" }
  ],
  "images": [{
    "id": 22,
    "url": "https://cdn.example.ir/p/1.jpg",
    "alt": "...",
    "position": 0
  }],
  "variants": [{
    "id": 991,
    "sku": "SK-4854601-SL",
    "options": [
      { "name": "Color", "value": "Silver" }
    ],
    "price": 7800000,
    "old_price": null,
    "stock": 3,
    "available": true,
    "is_default": true,
    "image_id": 22
  }],
  "rating": 4.5,
  "review_count": 12,
  "created_at": "2026-08-01T09:00:00+03:30",
  "updated_at": "2026-11-12T13:16:47+03:30"
}

فیلدها در بخش «مدل داده» تعریف شده‌اند. وسط گفتگو صدا زده می‌شود: پاسخ زیر ۲ ثانیه. مقدارهای نمونه در این سند انگلیسی‌اند؛ در واقعیت متن فارسی است.

۳. دسته‌بندی‌ها

بهتر استبرای شیرین، مژدهموری ← فروشگاه
درخواست
GET /categories
GET /categories/12
Authorization: Api-Key {api_key}
پاسخ
200 OK

[{
  "id": 12,
  "name": "Sockets",
  "parent_id": null,
  "url": "https://example.ir/category/12",
  "description": "<p>...</p>",
  "image": "https://cdn.example.ir/c/12.jpg",
  "seo_title": "...",
  "seo_description": "...",
  "product_count": 48
}]

GET /categories همه دسته‌ها را در یک پاسخ و بدون صفحه‌بندی برمی‌گرداند. GET /categories/{id} یک شیء دسته با همین فیلدها برمی‌گرداند، نه لیست، و اگر نباشد 404 (کارت ۵۲). parent_id برای ساختن درخت دسته‌ها.

۴. برندها

بهتر استبرای شیرین، مژدهموری ← فروشگاه
درخواست
GET /brands
Authorization: Api-Key {api_key}
پاسخ
200 OK

[{
  "id": 3,
  "name": "Melloni",
  "url": "https://example.ir/brand/3",
  "logo": "https://cdn.example.ir/b/3.png"
}]

همه برندها در یک پاسخ.

۵. ویژگی‌های استفاده‌شده

بهتر استبرای مژدهموری ← فروشگاه
درخواست
GET /attributes
Authorization: Api-Key {api_key}
پاسخ
200 OK

[{
  "name": "Color",
  "kind": "option",
  "values": ["Silver", "Black"]
}, {
  "name": "Material",
  "kind": "spec",
  "values": ["Steel"]
}]

نام ویژگی‌هایی که فروشگاه همین حالا دارد. مژده برای محصول جدید از همین نام‌ها استفاده می‌کند و نام تازه نمی‌سازد. kind یکی از option (تنوع، مثل رنگ و سایز) و spec (مشخصات فنی).

۶. اطلاعات فروشگاه

بهتر استبرای شیرین، مژده، جیمیموری ← فروشگاه
درخواست
GET /store
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "name": "Example Shop",
  "domain": "example.ir",
  "description": "...",
  "logo": "https://cdn.example.ir/logo.svg",
  "theme_color": "...",
  "currency": "IRT",
  "phone": "021-00000000",
  "email": "info@example.ir",
  "address": "...",
  "working_hours": "Sat-Thu 09:00-18:00",
  "social": {
    "instagram": "https://instagram.com/...",
    "telegram": "https://t.me/...",
    "whatsapp": "https://wa.me/98..."
  },
  "shipping_methods": [{
    "id": "post",
    "name": "...",
    "active": true,
    "price": 450000,
    "free_above": 20000000,
    "delivery_days": "2-4"
  }],
  "payment_methods": [{
    "key": "zarinpal",
    "name": "...",
    "type": "online",
    "active": true
  }]
}

type روش پرداخت یکی از online، cod (پرداخت در محل) و card_to_card. id روش ارسال و key روش پرداخت در کارت‌های ۲۵ و ۲۶ استفاده می‌شوند.

۷. صفحه‌ها و نوشته‌های وبلاگ

بهتر استبرای شیرین، مژدهموری ← فروشگاه
درخواست
GET /pages?type=faq&page=1
Authorization: Api-Key {api_key}

GET /pages/17
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "count": 9,
  "page": 1,
  "max_pages": 1,
  "pages": [{
    "id": 17,
    "type": "faq",
    "status": "published",
    "title": "...",
    "url": "https://example.ir/page/faq",
    "body": "<p>...full HTML...</p>",
    "seo_title": "...",
    "seo_description": "...",
    "updated_at": "2026-08-01T09:00:00+03:30"
  }]
}

type یکی از about، contact، faq، shipping، returns، terms، privacy، blog و other. نوشته‌های وبلاگ هم صفحه‌اند با type=blog. شیرین از صفحه‌های ارسال، مرجوعی و سؤالات متداول جواب می‌دهد.

ج. ویرایش محصول

مژده هر تغییر را اول به فروشنده نشان می‌دهد و فقط بعد از «بله» او می‌نویسد، بعد دوباره می‌خواند و مقایسه می‌کند. پس پاسخ هر نوشتن باید شیء کامل بعد از ذخیره باشد.

۸. ویرایش محصول

ضروریبرای مژدهموری ← فروشگاه
درخواست
PATCH /products/4854601
Authorization: Api-Key {api_key}
If-Match: "{etag}"

{
  "price": 7500000,
  "old_price": 7800000,
  "stock": 20,
  "status": "published",
  "description": "<p>...</p>",
  "seo_title": "...",
  "category_ids": [12, 31, 40],
  "attributes": [
    { "name": "Material", "value": "Steel" },
    { "name": "Warranty", "value": "1 year" }
  ]
}
پاسخ
200 OK

{ ...full product, same as card 2... }

فقط فیلدهای فرستاده‌شده عوض می‌شوند. فیلدهای لیستی (category_ids، attributes، tags، variants) کل لیست را جایگزین می‌کنند. null یعنی خالی کردن. قابل نوشتن: title، status، description، price، old_price، stock_type، stock، available، category_ids، attributes، variants، sku، barcode، brand_id، seo_title، seo_description، tags، weight و cost_price. برند با brand_id عوض می‌شود، نه brand. برای محصول تنوع‌دار، price، old_price و stock محصول از تنوع‌ها حساب می‌شوند و جدا نوشته نمی‌شوند (422)؛ آن‌ها را در variants یا کارت ۹ بفرستید. عکس‌ها با کارت‌های ۱۱ تا ۱۳. If-Match اختیاری است (قواعد کلی، بند ۹).

۹. ویرایش یک تنوع

ضروریبرای مژدهموری ← فروشگاه
درخواست
PATCH /products/4854601/variants/991
Authorization: Api-Key {api_key}

{
  "price": 7400000,
  "old_price": 7800000,
  "stock": 5,
  "sku": "SK-4854601-SL"
}
پاسخ
200 OK

{ ...full product, same as card 2... }

قیمت و موجودی هر رنگ یا سایز جداگانه. old_price برابر 0 یا null یعنی بدون تخفیف. پاسخ کل محصول است چون قیمت محصول به تنوع پیش‌فرض بسته است.

۱۰. ساخت محصول

بهتر استبرای مژدهموری ← فروشگاه
درخواست
POST /products
Authorization: Api-Key {api_key}
Idempotency-Key: 7d0c6c1e-...

{
  "title": "Steel wall socket",
  "status": "draft",
  "price": 7800000,
  "stock_type": "limited",
  "category_ids": [12],
  "brand_id": 3,
  "description": "<p>...</p>",
  "attributes": [
    { "name": "Material", "value": "Steel" }
  ],
  "variants": [{
    "options": [
      { "name": "Color", "value": "Silver" }
    ],
    "price": 7800000,
    "stock": 3,
    "is_default": true
  }]
}
پاسخ
201 Created

{ ...full product, same as card 2... }

مژده محصول را draft می‌سازد، عکس‌ها را با کارت ۱۱ اضافه می‌کند و بعد با کارت ۸ status=published می‌کند. title، price و stock_type ضروری‌اند؛ دسته فقط اگر فروشگاه دسته‌بندی دارد.

۱۱. افزودن عکس

بهتر استبرای مژدهموری ← فروشگاه
درخواست
POST /products/4854601/images
Authorization: Api-Key {api_key}
Content-Type: multipart/form-data

file=@photo.jpg
alt=...
position=0
make_default=true
پاسخ
201 Created

{
  "id": 23,
  "url": "https://cdn.example.ir/p/2.jpg",
  "alt": "...",
  "position": 0
}

jpg، png یا webp تا ۱۰ مگابایت. make_default=true یعنی عکس اول محصول شود. برای عکس یک تنوع: بعد از آپلود، image_id آن تنوع را با کارت ۹ عوض کنید.

۱۲. ترتیب و متن جایگزین عکس

بهتر استبرای مژدهموری ← فروشگاه
درخواست
PATCH /products/4854601/images/23
Authorization: Api-Key {api_key}

{
  "alt": "...",
  "position": 0
}
پاسخ
200 OK

{ ...image... }

position=0 یعنی عکس اصلی محصول. بقیه عکس‌ها یکی عقب می‌روند.

۱۳. حذف عکس

بهتر استبرای مژدهموری ← فروشگاه
درخواست
DELETE /products/4854601/images/23
Authorization: Api-Key {api_key}
پاسخ
204 No Content

409
{
  "error": {
    "code": "conflict",
    "message": "last_image: the only image cannot be deleted"
  }
}

حذف تنها عکس محصول رد شود (409).

۱۴. ویرایش گروهی قیمت و موجودی

بهتر استبرای مژدهموری ← فروشگاه
درخواست
PATCH /products/bulk
Authorization: Api-Key {api_key}

{
  "items": [
    { "product_id": 4854601, "variant_id": 991,
      "price": 7400000, "stock": 5 },
    { "product_id": 4854602,
      "stock": 0 }
  ]
}
پاسخ
200 OK

{
  "results": [
    { "product_id": 4854601, "variant_id": 991,
      "status": "ok" },
    { "product_id": 4854602,
      "status": "error",
      "error": { "code": "not_found",
        "message": "product 4854602 not found" } }
  ]
}

تا ۱۰۰ ردیف. خطای یک ردیف بقیه را متوقف نکند. برای «همه محصولات این دسته ۱۰٪ تخفیف» و به‌روز کردن موجودی از فایل اکسل تأمین‌کننده.

د. دسته، برند و صفحه

برای مرتب کردن کاتالوگ و سئو. شکل پاسخ هر کدام همان شکل خواندن آن در بخش «ب» است.

۱۵. ساخت دسته

بهتر استبرای مژدهموری ← فروشگاه
درخواست
POST /categories
Authorization: Api-Key {api_key}

{
  "name": "Shampoo",
  "parent_id": 12,
  "description": "<p>...</p>",
  "seo_title": "...",
  "seo_description": "..."
}
پاسخ
201 Created

{ ...category, same as card 3... }

نام تکراری زیر همان والد رد شود (409 با id دسته موجود).

۱۶. ویرایش دسته

بهتر استبرای مژدهموری ← فروشگاه
درخواست
PATCH /categories/12
Authorization: Api-Key {api_key}

{
  "name": "...",
  "description": "<p>...</p>",
  "seo_title": "...",
  "seo_description": "..."
}
پاسخ
200 OK

{ ...category... }

عکس دسته: همین آدرس با multipart/form-data و فیلدهای image و image_alt.

۱۷. ساخت برند

بهتر استبرای مژدهموری ← فروشگاه
درخواست
POST /brands
Authorization: Api-Key {api_key}

{ "name": "Flormar" }
پاسخ
201 Created

{ ...brand, same as card 4... }

نام تکراری: 409 با id برند موجود.

۱۸. ساخت و ویرایش صفحه یا نوشته وبلاگ

بهتر استبرای مژدهموری ← فروشگاه
درخواست
POST /pages
PATCH /pages/17
Authorization: Api-Key {api_key}

{
  "type": "blog",
  "status": "draft",
  "title": "...",
  "body": "<p>...</p>",
  "seo_title": "...",
  "seo_description": "..."
}
پاسخ
200 OK

{ ...page, same as card 7... }

عوض کردن title آدرس صفحه را عوض نکند (لینک‌های قبلی نشکنند).

۵۲. حذف دسته

بهتر استبرای مژدهموری ← فروشگاه
درخواست
DELETE /categories/12
Authorization: Api-Key {api_key}
پاسخ
204 No Content

فقط دسته خالی حذف شود. اگر محصولی هنوز در آن است (دسته اصلی یا اضافه)، یا زیردسته دارد، یا منوی سایت به آن لینک می‌دهد: 409 با message که بگوید کدام‌ها. مژده اول محصول‌ها را با کارت ۸ به دسته دیگر می‌برد و بعد حذف می‌کند، و با GET /categories/12 (کارت ۳) چک می‌کند که 404 برگردد.

هـ. سفارش‌ها

شیرین وضعیت سفارش را به خریدار می‌گوید و فروش‌هایی را که از گفتگو آمده می‌شمارد. مژده سفارش‌ها را گزارش می‌دهد و وضعیت و کد رهگیری را ثبت می‌کند. آقا بهرام فروش، بازپرداخت و واریزهای درگاه را با همین سفارش‌ها حساب می‌کند.

۱۹. یک سفارش

ضروریبرای شیرین، مژده، آقا بهرامموری ← فروشگاه
درخواست
GET /orders/9784051344
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "id": 9784051344,
  "number": "48069",
  "status": "processing",
  "payment_status": "paid",
  "payment_method": "online",
  "created_at": "2026-11-10T11:02:00+03:30",
  "paid_at": "2026-11-10T11:05:41+03:30",
  "updated_at": "2026-11-10T11:05:41+03:30",
  "currency": "IRT",
  "subtotal": 12500000,
  "discount_total": 500000,
  "shipping_total": 450000,
  "total": 12450000,
  "coupon_codes": ["MORI10"],
  "fees": [],
  "refunds": [],
  "customer": {
    "name": "...",
    "mobile": "09120000000"
  },
  "shipping_address": {
    "province": "...",
    "city": "...",
    "address": "...",
    "postal_code": "1234567890"
  },
  "shipping": {
    "method": "post",
    "status": "shipped",
    "carrier": "post",
    "tracking_code": "1234567890123456789012",
    "tracking_url": "https://tracking.post.ir/..."
  },
  "customer_note": "...",
  "items": [{
    "product_id": 4854601,
    "variant_id": 991,
    "title": "Steel wall socket",
    "sku": "SK-4854601-SL",
    "quantity": 2,
    "unit_price": 6250000,
    "line_total": 12500000
  }],
  "source": {
    "utm_source": "mori",
    "utm_medium": "mori_widget",
    "landing_url": "https://example.ir/p/4854601",
    "referrer": "https://www.google.com/"
  },
  "meta": { "mori_thread_id": "6f1c..." }
}

وسط گفتگو صدا زده می‌شود: پاسخ زیر ۲ ثانیه. شیرین فقط وقتی وضعیت را می‌گوید که موبایلی که خریدار تایپ کرد با customer.mobile یکی باشد؛ پس customer.mobile ضروری است. سفارش را هم با id و هم با number پیدا کنید. fees، refunds، source و meta در بخش «مدل داده» توضیح داده شده‌اند.

۲۰. لیست سفارش‌ها

ضروریبرای شیرین، مژده، آقا بهرامموری ← فروشگاه
درخواست
GET /orders?page=1&per_page=100
    &created_after=2026-11-01T00:00:00+03:30
    &created_before=2026-11-14T00:00:00+03:30
    &updated_since=2026-11-13T00:00:00+03:30
    &status=processing,shipped
    &payment_status=paid
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "count": 555,
  "page": 1,
  "per_page": 100,
  "max_pages": 6,
  "orders": [ ... ]
}

هر عضو orders دقیقاً مثل پاسخ کارت ۱۹ است. همه فیلترها اختیاری‌اند. ترتیب: جدیدترین اول. count باید تعداد واقعی کل نتیجه باشد، نه فقط این صفحه.

۲۱. ثبت وضعیت و کد رهگیری

بهتر استبرای مژدهموری ← فروشگاه
درخواست
PATCH /orders/9784051344
Authorization: Api-Key {api_key}

{
  "status": "shipped",
  "shipping": {
    "carrier": "post",
    "tracking_code": "1234567890123456789012"
  },
  "note": "...",
  "buyer_note": "سفارش شما آماده ارسال است"
}
پاسخ
200 OK

{ ...full order, same as card 19... }

فقط status، shipping.carrier، shipping.tracking_code، shipping.tracking_url، note و buyer_note قابل نوشتن‌اند. note یادداشت داخلی فروشنده است و خریدار آن را نمی‌بیند. buyer_note پیام فروشنده به خریدار است: در صفحه سفارش خریدار دیده شود و از راه معمول اعلان فروشگاه (ایمیل یا پیامک) برسد. اقلام سفارش را تغییر نمی‌دهیم؛ مبلغ فقط با کارت ۳۷. اگر فروشگاه با عوض شدن وضعیت به خریدار پیامک می‌دهد، این‌جا هم بدهد.

۲۲. ثبت سفارش دستی

بهتر استبرای مژدهموری ← فروشگاه
درخواست
POST /orders
Authorization: Api-Key {api_key}
Idempotency-Key: 1b9e...

{
  "status": "processing",
  "payment_status": "paid",
  "payment_method": "card_to_card",
  "customer": { "name": "...", "mobile": "0912..." },
  "shipping_address": { ... },
  "shipping_method": "post",
  "items": [
    { "product_id": 4854601, "variant_id": 991,
      "quantity": 1 }
  ],
  "source": { "utm_source": "instagram" }
}
پاسخ
201 Created

{ ...full order, same as card 19... }

برای سفارش‌هایی که فروشنده در دایرکت اینستاگرام یا تلفنی گرفته. موجودی کم شود، مثل سفارش سایت.

۳۷. خط مبلغ و یادداشت روی سفارش

بهتر استبرای آقا بهرام، مژدهموری ← فروشگاه
درخواست
POST /orders/9784051344/fees
Authorization: Api-Key {api_key}
Idempotency-Key: 4c2a...

{
  "fees": [
    { "name": "Gift wrap", "amount": 200000 },
    { "name": "Agreed discount", "amount": -500000 }
  ],
  "note": "Invoice 1405-112, 30% paid"
}
پاسخ
200 OK

{ ...full order, same as card 19... }

وقتی مبلغی که با خریدار توافق شده با سایت فرق دارد. هر خط یک مبلغ با دلیلش است؛ منفی یعنی کسر. خط‌های تازه به fees قبلی اضافه می‌شوند و آن‌ها را جایگزین نمی‌کنند، و total سفارش دوباره حساب شود. note یک یادداشت داخلی تازه است. note تنها هم قبول است (خلاصه فاکتور یا قرارداد روی سفارش). همان Idempotency-Key دوباره آمد: نه خط و نه یادداشت دوباره اضافه نشود. تغییر مبلغ با آقا بهرام است؛ اگر کسب‌وکار آقا بهرام ندارد، مژده. هر دو فقط بعد از «بله» فروشنده می‌نویسند.

۳۸. تغییر گروهی وضعیت سفارش‌ها

بهتر استبرای مژدهموری ← فروشگاه
درخواست
PATCH /orders/bulk
Authorization: Api-Key {api_key}

{
  "items": [
    { "order_id": 9784051344, "status": "shipped",
      "shipping": { "tracking_code": "1234..." } },
    { "order_id": 9784051345, "status": "delivered" }
  ]
}
پاسخ
200 OK

{
  "results": [
    { "order_id": 9784051344, "status": "ok" },
    { "order_id": 9784051345,
      "status": "error",
      "error": { "code": "not_found",
        "message": "order 9784051345 not found" } }
  ]
}

تا ۱۰۰ سفارش، با همان فیلدهای کارت ۲۱. خطای یک ردیف بقیه را متوقف نکند. برای «همه سفارش‌های دیروز ارسال شد» و کدهای رهگیری که فروشنده یک‌جا از پست می‌گیرد.

و. اطلاعات فروشگاه، تخفیف، ارسال، پرداخت و نظرها

کارهای روزانه فروشنده که مژده با یک پیام انجام می‌دهد؛ مثلاً «امشب ساعت ۱۱ پیک رو خاموش کن».

۲۳. ساخت کد تخفیف

بهتر استبرای مژدهموری ← فروشگاه
درخواست
POST /discounts
Authorization: Api-Key {api_key}

{
  "code": "YALDA15",
  "type": "percent",
  "value": 15,
  "starts_at": "2026-12-18T00:00:00+03:30",
  "expires_at": "2026-12-21T23:59:59+03:30",
  "usage_limit": 100,
  "per_customer_limit": 1,
  "min_order": 5000000,
  "product_ids": [],
  "category_ids": [12]
}
پاسخ
201 Created

{
  "id": 551,
  "code": "YALDA15",
  "used": 0,
  "active": true
}

type یکی از percent و amount. لیست کدها: GET /discounts با همین شکل و فیلد used. کد تکراری: 409.

۲۴. پایان کد تخفیف

بهتر استبرای مژدهموری ← فروشگاه
درخواست
PATCH /discounts/551
Authorization: Api-Key {api_key}

{ "active": false }
پاسخ
200 OK

{ ...discount... }

کد پاک نشود تا آمار استفاده‌اش بماند.

۲۵. روشن و خاموش کردن روش ارسال

بهتر استبرای مژدهموری ← فروشگاه
درخواست
PATCH /shipping-methods/post
Authorization: Api-Key {api_key}

{ "active": false }
پاسخ
200 OK

{ ...shipping method, same as in card 6..., "currency": "IRT" }

id از shipping_methods در کارت ۶. price، free_above و delivery_days هم قابل نوشتن‌اند. خاموش کردن آخرین روش ارسال روشن با 409 رد شود، چون خریدار دیگر نمی‌تواند سفارش ثبت کند؛ اول روش دیگری را روشن کنید.

۲۶. روشن و خاموش کردن درگاه پرداخت

بهتر استبرای مژدهموری ← فروشگاه
درخواست
PATCH /payment-methods/zarinpal
Authorization: Api-Key {api_key}

{ "active": false }
پاسخ
200 OK

{ ...payment method, same as in card 6... }

key از payment_methods در کارت ۶. حداقل یک روش پرداخت باید روشن بماند؛ خاموش کردن آخری با 409 رد شود.

۵۳. ویرایش اطلاعات فروشگاه

بهتر استبرای مژدهموری ← فروشگاه
درخواست
PATCH /store
Authorization: Api-Key {api_key}

{
  "description": "...",
  "phone": "021-00000000",
  "working_hours": "Sat-Thu 09:00-18:00",
  "social": { "instagram": "https://instagram.com/..." }
}
پاسخ
200 OK

{ ...store, same as card 6... }

هر فیلد متنی کارت ۶ قابل نوشتن است: name، description، phone، email، address، working_hours، social و theme_color. domain، currency، shipping_methods و payment_methods فقط‌خواندنی‌اند (422)؛ ارسال و پرداخت با کارت‌های ۲۵، ۲۶ و ۵۴. لوگو: همین آدرس با multipart/form-data و فیلد logo.

۵۴. ساخت روش ارسال

بهتر استبرای مژدهموری ← فروشگاه
درخواست
POST /shipping-methods
Authorization: Api-Key {api_key}
Idempotency-Key: 6f1c...

{
  "name": "تیپاکس",
  "description": "ارسال به همه شهرها",
  "price": 900000,
  "free_above": null,
  "delivery_days": "2-3"
}
پاسخ
201 Created

{ "id": "tipax", ...shipping method, same as in card 6..., "currency": "IRT" }

name و delivery_days لازم‌اند؛ بدون هر کدام 422. name همان چیزی است که خریدار هنگام پرداخت می‌بیند. اگر روشی با همین name هست: 409، و مژده همان را با کارت ۲۵ روشن یا خاموش می‌کند. price صفر یعنی رایگان، null یعنی پس‌کرایه. روش تازه برای همه مناطقی که فروشگاه ارسال دارد ساخته می‌شود؛ name و description محدوده را محدود نمی‌کنند. روش تازه روشن ساخته می‌شود؛ مژده فقط بعد از تأیید فروشنده این درخواست را می‌فرستد.

۲۷. نظرهای خریداران

بهتر استبرای مژدهموری ← فروشگاه
درخواست
GET /reviews?status=pending&product_id=4854601
Authorization: Api-Key {api_key}

PATCH /reviews/77
Authorization: Api-Key {api_key}

{ "status": "approved", "reply": "..." }
پاسخ
200 OK

{
  "count": 3,
  "page": 1,
  "max_pages": 1,
  "reviews": [{
    "id": 77,
    "product_id": 4854601,
    "status": "pending",
    "rating": 5,
    "text": "...",
    "verified_buyer": true,
    "created_at": "2026-11-09T18:00:00+03:30"
  }]
}

status یکی از pending، approved و spam. ایمیل و موبایل نظردهنده لازم نیست.

۲۸. گزارش بازدید و فروش محصولات

بهتر استبرای مژده، آقا بهرامموری ← فروشگاه
درخواست
GET /reports/products
    ?from=2026-11-01T00:00:00+03:30
    &to=2026-11-14T00:00:00+03:30
Authorization: Api-Key {api_key}
پاسخ
200 OK

[{
  "product_id": 4854601,
  "views": 1240,
  "orders": 18,
  "units_sold": 22,
  "revenue": 171600000,
  "currency": "IRT"
}]

فقط سفارش‌های پرداخت‌شده و لغونشده در بازه from تا to. views هم فقط در همان بازه، نه کل عمر محصول.

ز. روی سایت: ویجت، سبد و خرید داخل گفتگو

این درخواست‌ها را ویجت موری از مرورگر خریدار، روی دامنه خود فروشگاه و با کوکی همان خریدار می‌فرستد؛ نه از سرور موری و بدون کلید API.

۲۹. اسکریپت ویجت روی همه صفحه‌ها

بهتر استبرای شیرینفروشگاه ← مرورگر خریدار
درخواست
<script id="mori-react-widget" type="module"
  src="https://mori-js.s3.ir-thr-at1.arvanstorage.ir/widget.js"
  data-sharing-id="{mori_token}"></script>
پاسخ
-

در head همه صفحه‌ها، از جمله سبد خرید و صفحه تشکر از خرید. mori_token را فروشنده از داشبورد موری برمی‌دارد (یا پلتفرم از پاسخ کارت ۳۹). سیاست امنیتی محتوای سایت (Content-Security-Policy) باید این آدرس و api.mori.style را اجازه بدهد.

۳۰. دیدن سبد

بهتر استبرای شیرینمرورگر خریدار ← فروشگاه
درخواست
GET /cart.json
پاسخ
200 OK

{
  "items": [{
    "line_id": "a81f",
    "product_id": 4854601,
    "variant_id": 991,
    "title": "Steel wall socket",
    "image": "https://cdn.example.ir/p/1.jpg",
    "quantity": 1,
    "unit_price": 7800000,
    "total": 7800000
  }],
  "items_count": 1,
  "total": 7800000,
  "currency": "IRT",
  "checkout_url": "https://example.ir/cart"
}

سبد همان خریداری که صفحه را باز کرده (از روی کوکی او). سبد خالی: items خالی، نه 404.

۳۱. افزودن به سبد

بهتر استبرای شیرینمرورگر خریدار ← فروشگاه
درخواست
POST /cart/items
X-CSRF-Token: {token}

{
  "product_id": 4854601,
  "variant_id": 991,
  "quantity": 1
}
پاسخ
200 OK

{ ...full cart, same as card 30... }

409
{
  "error": {
    "code": "out_of_stock",
    "message": "..."
  }
}

کدهای خطا: out_of_stock، variant_required، product_not_found و max_quantity. توکن CSRF را ویجت از تگ meta با name=csrf-token در صفحه می‌خواند. variant_id برای محصول بدون تنوع null است.

۳۲. تغییر تعداد و حذف از سبد

بهتر استبرای شیرینمرورگر خریدار ← فروشگاه
درخواست
PATCH /cart/items/a81f
X-CSRF-Token: {token}

{ "quantity": 3 }

DELETE /cart/items/a81f
X-CSRF-Token: {token}
پاسخ
200 OK

{ ...full cart, same as card 30... }

هر دو، سبد کامل را برمی‌گردانند. اگر سرور شما PATCH و DELETE را نمی‌پذیرد، POST /cart/items/{line_id} و POST /cart/items/{line_id}/remove هم قبول است.

۳۳. ورود خریدار با کد پیامکی

بهتر استبرای شیرینمرورگر خریدار ← فروشگاه
درخواست
POST /checkout/otp
{ "mobile": "09120000000" }

POST /checkout/login
{ "mobile": "09120000000", "code": "12345" }
پاسخ
200 OK
{ "sent": true, "resend_after": 120 }

200 OK
{ "logged_in": true, "name": "..." }

از این‌جا تا کارت ۳۶ برای وقتی است که خریدار بدون رفتن به صفحه سبد، داخل گفتگو خرید را تمام کند. بعد از ورود، کوکی جلسه همان کوکی سایت است. اگر سایت کپچا دارد، آن را در پاسخ otp برگردانید.

۳۴. آدرس‌ها و روش‌های ارسال

بهتر استبرای شیرینمرورگر خریدار ← فروشگاه
درخواست
GET /checkout/addresses
POST /checkout/addresses
{
  "province": "...", "city": "...",
  "address": "...", "postal_code": "...",
  "receiver_name": "...",
  "receiver_mobile": "0912..."
}

GET /checkout/shipping-options?address_id=5
پاسخ
GET addresses: 200 OK
[{ "id": 5, "province": "...", "city": "...", ... }]

POST addresses: 201 Created
{ "id": 5, "province": "...", "city": "...", ... }

GET shipping-options: 200 OK
[{
  "id": "post",
  "name": "...",
  "price": 450000,
  "currency": "IRT",
  "delivery_days": "2-4"
}]

آدرس‌ها مال همان خریداری‌اند که وارد شده (کارت ۳۳)؛ id آدرس، همان address_id کارت ۳۶ است. روش‌های ارسال برای همان آدرس و همان سبد، با هزینه واقعی.

۳۵. کد تخفیف روی سبد

بهتر استبرای شیرینمرورگر خریدار ← فروشگاه
درخواست
POST /checkout/coupon
{ "code": "YALDA15" }

DELETE /checkout/coupon
پاسخ
200 OK
{ ...full cart, with "discount" and "coupon"... }

422
{ "error": { "code": "validation_failed",
  "message": "این کد منقضی شده",
  "fields": { "code": "expired" } } }

هر دو، سبد کامل را برمی‌گردانند.

۳۶. ثبت سفارش و لینک پرداخت

بهتر استبرای شیرینمرورگر خریدار ← فروشگاه
درخواست
POST /checkout/place-order
X-CSRF-Token: {token}

{
  "address_id": 5,
  "shipping_option": "post",
  "payment_method": "zarinpal",
  "note": "..."
}
پاسخ
200 OK

{
  "order_id": 9784051344,
  "total": 12450000,
  "currency": "IRT",
  "payment_url": "https://example.ir/pay/9784051344"
}

ویجت payment_url را در یک تب باز می‌کند. بعد از پرداخت، کارت ۱۹ باید payment_status=paid برگرداند. meta.mori_thread_id را از کوکی mori_thread_id روی سفارش ذخیره کنید.

ح. نصب و حذف موری (برای پلتفرم‌های فروشگاه‌ساز)

پلتفرمی که موری را در فروشگاه‌ساز خودش نصب‌شدنی می‌کند، هنگام نصب و حذف به موری خبر می‌دهد تا فروشنده لازم نباشد کلید را دستی وارد کند. آدرس و رمز امضا را موقع راه‌اندازی به هر پلتفرم می‌دهیم. سایتی که خودش برنامه‌نویسی شده این بخش را لازم ندارد.

۳۹. نصب موری روی یک فروشگاه

بهتر استبرای شیرین، مژده، آقا بهرامپلتفرم ← موری
درخواست
POST {address Mori gives you}
Content-Type: application/json
X-{Platform}-Signature: sha256={hmac}

{
  "event": "app.installed",
  "shop_id": "8812",
  "shop_name": "Example Shop",
  "domain": "example.ir",
  "owner_mobile": "09120000000",
  "api_key": "{write key of this shop}"
}
پاسخ
200 OK

{ "mori_token": "abc123" }

shop_id، domain، api_key و owner_mobile ضروری‌اند. امضا HMAC-SHA256 کل بدنه با رمز مشترک است، به شکل هگز، در هدری به نام پلتفرم شما (برای شاپفا X-Shopfa-Signature)؛ آدرس، نام هدر و رمز را موقع راه‌اندازی می‌دهیم. امضای غلط: 401. JSON خراب یا فیلد ضروری خالی: 400. موری حساب فروشنده را با همین موبایل پیدا یا می‌سازد، کاتالوگ را با کلید می‌خواند و دستیار را می‌سازد. mori_token همان data-sharing-id کارت ۲۹ است: پلتفرم اسکریپت را خودش روی سایت بگذارد. نصب دوباره همان فروشگاه چیز تکراری نمی‌سازد. دو نصب هم‌زمان، یا موبایلی که به فروشگاه دیگری وصل است: 409.

۴۰. حذف موری از یک فروشگاه

بهتر استبرای شیرین، مژده، آقا بهرامپلتفرم ← موری
درخواست
POST {address Mori gives you}
Content-Type: application/json
X-{Platform}-Signature: sha256={hmac}

{
  "event": "app.uninstalled",
  "shop_id": "8812"
}
پاسخ
200 OK

{}

ویجت خاموش می‌شود و موری دیگر با آن کلید درخواستی نمی‌فرستد. کلید را در پنل خودتان هم باطل کنید. رویدادی که موری نمی‌شناسد با 200 و ignored جواب می‌گیرد.

ط. نرم‌افزار حسابداری

برای کسب‌وکاری که حسابداری‌اش روی نرم‌افزار خودش است. آقا بهرام از این‌ها فروش، سود ماهانه، طلب و بدهی هر طرف‌حساب، چک‌های سررسید و مانده بانک را جواب می‌دهد و فاکتور فروش سایت را، با تأیید فروشنده، در حسابداری ثبت می‌کند. آدرس پایه جدا از فروشگاه است ولی همه قواعد بخش «الف» این‌جا هم برقرار است. حداقل برای شروع: کارت‌های ۴۱ و ۴۲.

۴۱. لیست فاکتورها

ضروریبرای آقا بهرامموری ← نرم‌افزار حسابداری
درخواست
GET /invoices?type=sale&page=1&per_page=100
    &from=2026-11-01&to=2026-11-14
    &updated_since=2026-11-13T00:00:00+03:30
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "count": 120, "page": 1, "per_page": 100, "max_pages": 2,
  "invoices": [{
    "id": 7012,
    "number": "1405-112",
    "type": "sale",
    "status": "final",
    "date": "2026-11-10",
    "contact": { "id": 88, "name": "..." },
    "currency": "IRT",
    "subtotal": 12500000,
    "discount_total": 500000,
    "tax_total": 0,
    "total": 12000000,
    "paid_amount": 12000000,
    "order_number": "48069",
    "items": [{
      "item_id": 301,
      "sku": "SK-4854601",
      "title": "Steel wall socket",
      "quantity": 2,
      "unit_price": 6250000,
      "line_total": 12500000
    }],
    "updated_at": "2026-11-10T11:20:00+03:30"
  }]
}

type یکی از sale، purchase، sale_return و purchase_return؛ status یکی از draft، final و cancelled. date تاریخ میلادی سند است. order_number شماره سفارش سایت اگر فاکتور از آن آمده؛ آقا بهرام با آن فروش سایت را با حسابداری یکی می‌کند. هر فاکتور تنها با GET /invoices/{id} هم.

۴۲. دریافت‌ها و پرداخت‌ها

ضروریبرای آقا بهرامموری ← نرم‌افزار حسابداری
درخواست
GET /payments?direction=in&page=1&per_page=100
    &from=2026-11-01&to=2026-11-14
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "count": 64, "page": 1, "per_page": 100, "max_pages": 1,
  "payments": [{
    "id": 5520,
    "date": "2026-11-10",
    "direction": "in",
    "amount": 12000000,
    "currency": "IRT",
    "method": "gateway",
    "category": "sale",
    "account": { "id": 2, "name": "..." },
    "contact": { "id": 88, "name": "..." },
    "invoice_id": 7012,
    "note": "...",
    "updated_at": "2026-11-10T11:21:00+03:30"
  }]
}

direction یکی از in (پول آمد) و out (پول رفت). method یکی از cash، card، transfer، gateway و cheque. category یکی از sale، supplier، rent، salary، shipping، ads، tax و other (یا فهرست خودتان، یک بار با معنی هر کدام). amount همیشه مثبت است.

۴۳. طرف‌حساب‌ها و مانده

بهتر استبرای آقا بهرامموری ← نرم‌افزار حسابداری
درخواست
GET /contacts?balance=nonzero&page=1
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "count": 37, "page": 1, "per_page": 100, "max_pages": 1,
  "contacts": [{
    "id": 88,
    "name": "...",
    "kind": "customer",
    "mobile": "0912...",
    "balance": 4500000,
    "currency": "IRT",
    "updated_at": "2026-11-12T09:00:00+03:30"
  }]
}

kind یکی از customer، supplier و both. balance مثبت یعنی او به شما بدهکار است، منفی یعنی شما به او. آقا بهرام از این «کی چقدر بدهکاره» را جواب می‌دهد. mobile فقط به فروشنده نشان داده می‌شود.

۴۴. کالاها و قیمت خرید

بهتر استبرای آقا بهرامموری ← نرم‌افزار حسابداری
درخواست
GET /items?page=1&per_page=100
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "count": 210, "page": 1, "per_page": 100, "max_pages": 3,
  "items": [{
    "id": 301,
    "sku": "SK-4854601",
    "title": "Steel wall socket",
    "unit": "piece",
    "buy_price": 5200000,
    "sell_price": 7800000,
    "stock": 12,
    "currency": "IRT",
    "product_id": 4854601
  }]
}

buy_price برای سود ماهانه: فروش هر کالا ضرب در قیمت خریدش. product_id شناسه همان محصول در سایت (کارت ۲) تا دو طرف یکی شوند؛ اگر ندارید، sku مشترک کافی است.

۴۵. چک‌ها و قسط‌های سررسید

بهتر استبرای آقا بهرامموری ← نرم‌افزار حسابداری
درخواست
GET /cheques?status=open&due_before=2027-01-31
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "count": 6, "page": 1, "per_page": 100, "max_pages": 1,
  "cheques": [{
    "id": 41,
    "direction": "out",
    "kind": "cheque",
    "number": "823411",
    "bank": "...",
    "amount": 25000000,
    "currency": "IRT",
    "due_date": "2026-11-29",
    "contact": { "id": 12, "name": "..." },
    "status": "open"
  }]
}

direction یکی از in (چکی که گرفته‌اید) و out (چکی که داده‌اید). kind یکی از cheque و instalment. status یکی از open، cleared و bounced. آقا بهرام ۷ و ۳ روز قبل از سررسید یادآوری می‌کند و نمودار پرداختی‌های ۸ هفته بعد را می‌کشد.

۴۶. مانده بانک و صندوق

بهتر استبرای آقا بهرامموری ← نرم‌افزار حسابداری
درخواست
GET /accounts
Authorization: Api-Key {api_key}
پاسخ
200 OK

[{
  "id": 2,
  "name": "...",
  "kind": "bank",
  "balance": 184000000,
  "currency": "IRT",
  "updated_at": "2026-11-14T08:00:00+03:30"
}]

همه حساب‌ها در یک پاسخ. kind یکی از bank، cash و gateway.

۴۷. ثبت فاکتور فروش

بهتر استبرای آقا بهرامموری ← نرم‌افزار حسابداری
درخواست
POST /invoices
Authorization: Api-Key {api_key}
Idempotency-Key: 4c2a...

{
  "type": "sale",
  "date": "2026-11-10",
  "contact_id": 88,
  "order_number": "48069",
  "items": [
    { "item_id": 301, "quantity": 2,
      "unit_price": 6250000 }
  ],
  "discount_total": 500000,
  "shipping_total": 450000,
  "note": "..."
}
پاسخ
201 Created

{ ...full invoice, same as card 41... }

فقط فاکتور تازه؛ ویرایش و حذف فاکتور در خود نرم‌افزار انجام می‌شود. خریدار تازه: به جای contact_id، contact با name و mobile. همان order_number دوباره: 409 با id فاکتور موجود. آقا بهرام هر فاکتور را اول به فروشنده نشان می‌دهد و فقط بعد از «بله» می‌فرستد.

۴۸. ثبت دریافت یا پرداخت

بهتر استبرای آقا بهرامموری ← نرم‌افزار حسابداری
درخواست
POST /payments
Authorization: Api-Key {api_key}
Idempotency-Key: 9e11...

{
  "direction": "in",
  "date": "2026-11-10",
  "amount": 12000000,
  "method": "gateway",
  "category": "sale",
  "account_id": 2,
  "contact_id": 88,
  "invoice_id": 7012,
  "note": "..."
}
پاسخ
201 Created

{ ...payment, same as card 42... }

مثل کارت ۴۷: فقط ثبت تازه و فقط بعد از «بله» فروشنده. موری هیچ‌وقت پول جابه‌جا نمی‌کند؛ این فقط ثبت در دفتر است.

ی. نرم‌افزار CRM

برای کسب‌وکاری که مشتری‌ها و پیگیری‌هایش را در CRM خودش نگه می‌دارد. شیرین شماره‌هایی را که خریدارها در گفتگو می‌دهند به CRM می‌فرستد؛ مژده و آقا بهرام وقتی فروشنده درباره یک مشتری می‌پرسد او را پیدا می‌کنند و با تأیید فروشنده پیگیری ثبت می‌کنند. آدرس پایه جدا از فروشگاه است ولی همه قواعد بخش «الف» این‌جا هم برقرار است. حداقل برای شروع: کارت ۴۹.

۴۹. ثبت لید از گفتگو

ضروریبرای شیرینموری ← نرم‌افزار CRM
درخواست
POST /leads
Authorization: Api-Key {api_key}
Idempotency-Key: 6f1c...-1

{
  "created_at": "2026-11-14T16:20:00+03:30",
  "name": "...",
  "mobile": "09120000000",
  "message": "...",
  "product_ids": [4854601],
  "page_url": "https://example.ir/product/4854601",
  "mori_thread_id": "6f1c...",
  "source": "mori_widget"
}
پاسخ
201 Created

{
  "id": "L-301",
  "contact_id": 88,
  "duplicate": false
}

شیرین فقط شماره‌ای را می‌فرستد که خریدار خودش داده، با شرطی که فروشنده در «تولید لید» داشبورد موری نوشته. message خلاصه چیزی است که خریدار خواست. موبایل تکراری روی همان مشتری بنشیند و مشتری دوم ساخته نشود (duplicate: true). name ممکن است null باشد.

۵۰. پیدا کردن مشتری

بهتر استبرای مژده، آقا بهرامموری ← نرم‌افزار CRM
درخواست
GET /contacts?mobile=09120000000
Authorization: Api-Key {api_key}

GET /contacts?tag=vip&updated_since=2026-11-01T00:00:00+03:30
Authorization: Api-Key {api_key}
پاسخ
200 OK

{
  "count": 1, "page": 1, "per_page": 100, "max_pages": 1,
  "contacts": [{
    "id": 88,
    "name": "...",
    "mobile": "09120000000",
    "stage": "customer",
    "tags": ["vip"],
    "orders_count": 4,
    "total_spent": 48000000,
    "currency": "IRT",
    "last_order_at": "2026-11-10T11:02:00+03:30",
    "assigned_to": "...",
    "updated_at": "2026-11-12T09:00:00+03:30"
  }]
}

stage یکی از lead، customer و lost (یا مراحل خودتان، یک بار با معنی هر کدام). فقط وقتی فروشنده می‌پرسد خوانده می‌شود؛ نام و موبایل در گزارش گروهی، پست زمان‌بندی‌شده یا به خریدار دیگر نشان داده نمی‌شود و در حافظه دستیار ذخیره نمی‌شود.

۵۱. یادداشت و پیگیری روی مشتری

بهتر استبرای مژده، آقا بهرامموری ← نرم‌افزار CRM
درخواست
POST /contacts/88/notes
Authorization: Api-Key {api_key}

{
  "kind": "task",
  "text": "...",
  "due_at": "2026-11-17T10:00:00+03:30"
}
پاسخ
201 Created

{
  "id": 9031,
  "kind": "task",
  "text": "...",
  "due_at": "2026-11-17T10:00:00+03:30",
  "created_at": "2026-11-14T16:25:00+03:30"
}

kind یکی از note و task؛ due_at فقط برای task. فقط بعد از «بله» فروشنده نوشته می‌شود.

ک. چیزهایی که لازم نداریم

  • ظاهر سایت (بنر، منو، استوری، رنگ قالب، پاپ‌آپ): هر پلتفرم مدل خودش را دارد و یک API مشترک برایش معنی ندارد.
  • حذف محصول: مژده محصول را حذف نمی‌کند، فقط status=hidden یا draft.
  • لیست مشتری‌ها و اطلاعات تماس آن‌ها از فروشگاه، جز آنچه روی خود سفارش است. اگر CRM دارید، فقط کارت‌های بخش «ی».
  • تغییر اقلام سفارشی که ثبت شده و هر نوع جابه‌جایی پول. تنها تغییر مبلغ، خط کارت ۳۷ است.
  • ویرایش یا حذف سند حسابداری؛ آقا بهرام فقط سند تازه ثبت می‌کند.

ل. برای تحویل

  • آدرس پایه API و مستندات شما، با سقف تعداد درخواست.
  • یک فروشگاه تستی و دو کلید آن (read و write)، با این‌ها: یک محصول بدون تنوع، یک محصول با رنگ و سایز، یک محصول ناموجود، یک محصول تخفیف‌دار، و دو سفارش نمونه (یکی پرداخت‌شده و ارسال‌شده با کد رهگیری).
  • برای حسابداری یا CRM: یک حساب تستی با چند فاکتور، دریافت، چک و مشتری نمونه.
  • ما با همین حساب‌ها همه کارت‌هایی را که پیاده کرده‌اید امتحان می‌کنیم و نتیجه را برایتان می‌فرستیم.