برای برنامه‌نویس‌ها
API اتصال فروشگاه اختصاصی به نوتراز
سایت فروشگاهی‌تان را خودتان ساخته‌اید؟ با همان API که افزونه ووکامرس استفاده می‌کند، سفارش‌ها فاکتور می‌شوند، مشتریان ثبت می‌شوند و موجودی سایت و انبار یکی می‌ماند.
در یک نگاه
پنج اندپوینت، یک کلید و یک قاعده: مرجع موجودی نوتراز است.
| روش | مسیر | کار |
|---|---|---|
| GET | /integrations/store/status/ | بررسی سلامت اتصال، پلن و سقف فاکتور ماهانه |
| POST | /integrations/store/products/ | ارسال کالاها (حداکثر ۱۰۰ مورد در هر درخواست) |
| POST | /integrations/store/customers/ | ارسال مشتریان (حداکثر ۱۰۰ مورد) |
| POST | /integrations/store/orders/ | ارسال سفارش‌ها (حداکثر ۲۵ مورد) |
| GET | /integrations/store/stock/ | خواندن موجودی؛ با ?since= فقط تغییرات |
نشانی پایه: https://notaraz.ir/api/v1. نسخه ماشین‌خوان همین مستندات (OpenAPI) در /api/docs است.
۱. گرفتن کلید
کلید را مالک کسب‌وکار از پنل می‌سازد و برنامه‌نویس آن را در سرور نگه می‌دارد.
- ۱. وارد نوتراز شوید: تنظیمات ← فروشگاه اینترنتی ← «ساخت کلید برای سایت اختصاصی».
- ۲. نام و نشانی سایت را بنویسید. اگر می‌خواهید تغییر موجودی را همان لحظه دریافت کنید، نشانی وبهوک را هم بدهید.
- ۳. کلید اتصال و کلید امضا یک‌بار نمایش داده می‌شوند. آن‌ها را در متغیرهای محیطی سرور بگذارید، نه در کد سمت مرورگر.
کلید در هر درخواست به این شکل فرستاده می‌شود: Authorization: Notaraz ntz_…
۲. فرستادن سفارش
هر سفارش با شناسه خودتان کلید می‌خورد. ارسال دوباره چیزی را دو بار ثبت نمی‌کند.
curl -X POST "https://notaraz.ir/api/v1/integrations/store/orders/" \
-H "Authorization: Notaraz ntz_xxxxxxxxxxxx_yyyyyyyyyyyyyyyy" \
-H "Content-Type: application/json" \
-d '{
"items": [{
"id": 1043,
"number": "1043",
"status": "paid",
"currency": "IRT",
"date_created": "2026-09-16T10:12:00+03:30",
"date_paid": "2026-09-16T10:12:30+03:30",
"payment_method": "zarinpal",
"customer": {
"id": 77, "first_name": "سارا", "last_name": "رضایی",
"phone": "09351234567", "email": "sara@example.com"
},
"lines": [{
"id": 1, "product_id": 55, "name": "تی‌شرت آبی", "sku": "TS-BLUE",
"quantity": "2", "subtotal": "500000", "total": "500000", "total_tax": "45000"
}],
"shipping_total": "30000", "total": "575000"
}]
}'{
"results": [{
"external_id": "1043",
"status": "created",
"invoice_id": 812,
"invoice_number": "1043",
"invoice_status": "paid"
}]
}وضعیت سفارش که شما می‌فرستید
- paid: پرداخت شده. فاکتور فروش صادر و پرداخت ثبت می‌شود
- awaiting_payment: در انتظار پرداخت. هنوز فاکتوری ساخته نمی‌شود
- shipped: ارسال شده. مثل پرداخت‌شده رفتار می‌شود
- cancelled: لغو شده. فاکتور پرداخت‌نشده ابطال می‌شود
- returned: مرجوعی. برگشت از فروش با پرداخت وجه ثبت می‌شود
نتیجه‌ای که برمی‌گردد
- created: فاکتور تازه ساخته شد
- updated: سفارش قبلاً ثبت شده بود و فقط وضعیتش به‌روز شد
- skipped: هنوز قابل فاکتور نیست (در انتظار پرداخت)
- attention: موجودی کافی نبود. فاکتور به صورت پیش‌نویس منتظر است
- blocked: سقف فاکتور ماهانه پلن پر شده. بعد از ارتقا دوباره بفرستید
- error: داده‌های این مورد پذیرفته نشد. توضیح در فیلد detail
۳. کالاها و موجودی
موجودی اولیه از سایت خوانده می‌شود. از آن به بعد نوتراز مرجع است.
const res = await fetch("https://notaraz.ir/api/v1/integrations/store/products/", {
method: "POST",
headers: {
Authorization: `Notaraz ${process.env.NOTARAZ_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [{
id: 55,
name: "تی‌شرت آبی",
sku: "TS-BLUE",
price: "250000",
manage_stock: true,
stock_quantity: "12",
}],
}),
});
const { results } = await res.json();
// results[0].quantity → موجودی فعلی در نوتراز# read what changed since last time
curl "https://notaraz.ir/api/v1/integrations/store/stock/?since=2026-09-16T06:40:00%2B00:00" \
-H "Authorization: Notaraz ntz_xxxxxxxxxxxx_yyyyyyyyyyyyyyyy"
{
"items": [{ "external_id": "55", "product_id": 4120, "quantity": "8" }],
"orders": ["1043"],
"as_of": "2026-09-16T07:05:11.402188+00:00"
}- کالایی که کد (SKU) آن از قبل در نوتراز باشد، به همان کالا وصل می‌شود و موجودی نوتراز دست‌نخورده می‌ماند.
- مقدار quantity: null یعنی آن کالا در نوتراز موجودی‌دار نیست و سایت نباید موجودی‌اش را مدیریت کند.
- فهرست orders در پاسخ موجودی، سفارش‌هایی را می‌گوید که این اعداد قبلاً آن‌ها را کم کرده‌اند. اگر سایت شما سفارش‌های ارسال‌نشده را از موجودی کنار می‌گذارد، این‌ها را دوباره کم نکنید.
۴. دریافت لحظه‌ای تغییر موجودی
اختیاری: اگر نشانی وبهوک داده باشید، نوتراز تغییرات را می‌فرستد.
<?php
// POST from Notaraz → your site. Verify before trusting it.
$secret = getenv('NOTARAZ_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_NOTARAZ_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_NOTARAZ_SIGNATURE'] ?? '';
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
http_response_code(401); exit;
}
$expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401); exit;
}
foreach (json_decode($body, true)['items'] as $item) {
// $item['quantity'] === null → this product is not stock-tracked
set_stock_of($item['external_id'], $item['quantity']);
}امضا با الگوریتم HMAC-SHA256 روی رشته {timestamp}.{body} ساخته می‌شود و در هدر X-Notaraz-Signature می‌آید. اگر نشانی وبهوک ندهید، هیچ درخواستی به سایت شما فرستاده نمی‌شود و خودتان موجودی را می‌خوانید.
نکته‌های عملی
چیزهایی که هنگام پیاده‌سازی به آن‌ها برمی‌خورید.
- ارسال دوباره بی‌خطر است. هر سفارش، کالا و مشتری با شناسه سایت شما کلید می‌خورد؛ اگر پاسخی دریافت نکردید، بدون نگرانی دوباره بفرستید.
- سفارش‌های قدیمی موجودی را کم نمی‌کنند. سفارشی که تاریخش پیش از ساخت کلید باشد فقط در دفاتر ثبت می‌شود، چون موجودی اولیه‌ای که فرستادید از قبل آن را کم کرده است.
- کمبود موجودی سفارش را دور نمی‌اندازد. فاکتور به‌صورت پیش‌نویس می‌ماند تا موجودی را اصلاح کنید؛ همان سفارش را دوباره بفرستید تا صادر شود.
- پاسخ ۴۲۹ یعنی تعداد درخواست زیاد است. کمی صبر کنید و دوباره تلاش کنید؛ ارسال گروهی (چند مورد در یک درخواست) بهترین راه است.
- واحد پول ریال، تومان، هزار ریال و هزار تومان پشتیبانی می‌شود و به واحد کسب‌وکار تبدیل می‌شود.
نوتراز
فروشگاه اختصاصی‌تان را وصل کنید
ساخت حساب رایگان است و ۱۴ روز اول همه امکانات باز است.