مستندات اتصال به سایت

مقدمه

API همگام‌سازی (Store API) به مالک فروشگاه اجازه می‌دهد سایت شخصی خود (ووکامرس، فروشگاه اختصاصی، اپلیکیشن و …) را به انبار جت انبار متصل کند. این API سه کار اصلی انجام می‌دهد:

• دریافت لیست محصولات به‌همراه موجودی فعلی و قیمت پیشنهادی فروش
• دریافت اطلاعات یک یا چند محصول مشخص با کد محصول
• ثبت فروش (کاهش موجودی) هنگامی که در سایت سفارشی ثبت می‌شود

تمام مسیرها از /api/v1/store-api قابل دسترس هستند و برای احراز هویت به کلید API نیاز دارند. اگر سایت شما ووکامرسی است، مستقیم به بخش افزونه ووکامرس بروید.

افزونه ووکامرس (بدون کدنویسی)

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

کارهایی که افزونه انجام می‌دهد

• کاتالوگ (جت انبار ← سایت): قیمت و موجودی محصولات پیوند داده‌شده هر ۱ تا ۱۰ دقیقه (قابل تنظیم) از جت انبار در ووکامرس به‌روز می‌شود.
• فروش (سایت ← جت انبار): هنگامی که یک سفارش به وضعیت انتخابی (مثلاً «تکمیل شده») می‌رسد، برای هر قلم فروخته‌شده یک تراکنش خروج در جت انبار ثبت می‌شود.

پیش‌نیازها

• وردپرس نسخه‌ی ۶.۰ به بالا
• PHP نسخه‌ی ۷.۴ به بالا
• ووکامرس نسخه‌ی ۷.۰ به بالا

نصب افزونه (به‌صورت دستی از فایل zip)

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

1. ابتدا فایل افزونه را دانلود کنید:
   ⬇ دانلود افزونه ووکامرس (نسخه ۱.۰.۰)
2. وارد پیشخوان وردپرس شوید و به مسیر افزونه‌ها ← افزودن ← بارگذاری افزونه بروید.
3. فایل jetanbar-woocommerce-v1-0-0.zip را که دانلود کرده‌اید انتخاب و سپس روی «هم‌اکنون نصب کن» کلیک کنید.
4. پس از پایان نصب، افزونه را فعال کنید.
5. به مسیر ووکامرس ← همگام‌سازی جت انبار بروید تا تنظیمات را انجام دهید (در ادامه توضیح داده شده).

راه‌اندازی و تنظیمات

1. در اپلیکیشن جت انبار، از تنظیمات ← کلید همگام‌سازی کلید API خود (sk_live_…) را کپی کنید.
2. در وردپرس، در صفحه‌ی ووکامرس ← همگام‌سازی جت انبار، کلید API و آدرس جت انبار را وارد کنید. واحد پول سایت (تومان/ریال)، بازه‌ی همگام‌سازی و وضعیت سفارش را تنظیم و ذخیره کنید.
3. با دکمه‌ی «تست اتصال» مطمئن شوید ارتباط برقرار است.
4. در صفحه‌ی ویرایش هر محصول ووکامرس، در باکس «همگام‌سازی جت انبار»، محصول موردنظر را با کد PRD-XXXXXX جستجو و پیوند دهید. تیک «همگام‌سازی قیمت» و/یا «همگام‌سازی موجودی» را بزنید.

تنظیمات افزونه

دریافت کلید API

کلید API یک رشته‌ی یکتا به‌شکل sk_live_… است که هویت فروشگاه شما را مشخص می‌کند. برای دریافت آن:

1. وارد اپلیکیشن جت انبار شوید و به تنظیمات ← کلید همگام‌سازی بروید.
2. کلید نمایش داده می‌شود؛ آن را کپی کنید.
3. در صورت نیاز می‌توانید با دکمه‌ی «بازسازی کلید»، کلید جدیدی بسازید (کلید قبلی بلافاصله باطل می‌شود).

احراز هویت

کلید API را در هر درخواست در هدر x-api-key ارسال کنید (استفاده از پارامتر کوئری ?key= نیز برای سازگاری پشتیبانی می‌شود).

GET https://jetanbar.ir/api/v1/store-api/products?limit=5
Host: jetanbar.ir
x-api-key: sk_live_1a2b3c4d5e6f...
Accept: application/json

تمام پاسخ‌ها در یک پوشش یکسان برگردانده می‌شوند. موفق: { "success": true, "message": "...", "data": {...} } و خطا: { "success": false, "message": "...", "errCode": "..." }.

کدهای خطای رایج:

مرجع اندپوینت‌ها

GET /products

لیست محصولات فروشگاه را به‌همراه موجودی فعلی و قیمت پیشنهادی برمی‌گرداند.

پارامترهای کوئری (همگی اختیاری):

نمونه درخواست:

curl -G "https://jetanbar.ir/api/v1/store-api/products" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=5" \
  --data-urlencode "search=هدف" \
  -H "x-api-key: sk_live_1a2b3c4d5e6f..."

نمونه پاسخ:

{
  "success": true,
  "message": "ok",
  "data": {
    "products": [
      {
        "productId": "PRD-K7Q2M9",
        "name": "هدف هودی سامسونگ",
        "barcode": "6290123456789",
        "description": "...",
        "photoUrl": "https://.../uploads/private/abc.png?exp=...&sig=...",
        "currentStock": 42,
        "sellPrice": 1250000
      }
    ],
    "page": 1,
    "limit": 5,
    "total": 137,
    "totalPages": 28
  }
}

• sellPrice: بالاترین قیمت فروش ثبت‌شده برای محصول است که به تومان تبدیل شده. اگر قیمتی ثبت نشده باشد null است.
• photoUrl: یک لینک امضا‌شده با اعتبار ۷ روز است که مستقیم در <img src> قابل استفاده است (بدون نیاز به هدر احراز هویت). پس از ۷ روز باید محصول را دوباره دریافت کنید.
• این اندپوینت تا ۶۰ ثانیه کش می‌شود و با هر تغییر موجودی به‌روز می‌گردد.

POST /products/batch

برای دریافت اطلاعات چند محصول مشخص (تا ۵۰۰ کد هم‌زمان) استفاده می‌شود؛ مناسب برای همگام‌سازی سایت.

بدنه‌ی درخواست:

curl -X POST "https://jetanbar.ir/api/v1/store-api/products/batch" \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["PRD-K7Q2M9", "PRD-AB3X9K"] }'

نمونه پاسخ:

{
  "success": true,
  "message": "ok",
  "data": {
    "products": [
      { "productId": "PRD-K7Q2M9", "name": "...", "currentStock": 42, "sellPrice": 1250000 }
    ]
  }
}

• کدهای نامعتبر یا متعلق به فروشگاه دیگر بی‌صدا حذف می‌شوند.
• این اندپوینت تا ۳۰ ثانیه کش می‌شود.

POST /transactions/out

یک تراکنش خروج (فروش) ثبت می‌کند و موجودی را کاهش می‌دهد. این تراکنش فاکتور ایجاد نمی‌کند و فیلدهای قیمت خرید هرگز در پاسخ باز نمی‌گردند.

بدنه‌ی درخواست:

* فیلدهای ارزی همگی باید با هم ارسال شوند یا هیچ‌کدام. اگر ارسال نشوند، سرور به‌صورت خودکار معادل دلاری را با نرخ روز محاسبه می‌کند.

curl -X POST "https://jetanbar.ir/api/v1/store-api/transactions/out" \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "PRD-K7Q2M9",
    "quantity": 2,
    "unitPriceToman": 1250000,
    "customerName": "علی رضایی",
    "customerPhone": "09123456789",
    "notes": "سفارش شماره #1234 از وبسایت"
  }'

نمونه پاسخ (201):

{
  "success": true,
  "message": "تراکنش خروج ثبت شد",
  "data": {
    "transactionId": "TXN-AB3X9K",
    "productId": "PRD-K7Q2M9",
    "productName": "هدف هودی سامسونگ",
    "type": "OUT",
    "quantity": 2,
    "unitPriceToman": 1250000,
    "unitPriceForeignCurrency": 14.88,
    "foreignCurrencyType": "USD",
    "exchangeRate": 84000,
    "customerName": "علی رضایی",
    "customerPhone": "09123456789",
    "notes": "سفارش شماره #1234 از وبسایت",
    "date": "2026-08-04T12:34:56.789Z"
  }
}

• اگر productId متعلق به این فروشگاه نباشد، خطای ۴۲۲ با پیام «محصول متعلق به این فروشگاه یافت نشد» برگردانده می‌شود.
• برای جلوگیری از ثبت دوبار، در سمت سایت خود شناسه‌ی سفارش را در notes ذخیره کنید و پیش از ارسال، بررسی کنید.

قالب شناسه‌ها

کد نمونه (برای سایت‌های غیر ووکامرسی)

اگر سایت اختصاصی دارید، در ادامه دو نمونه‌ی آماده برای دریافت محصولات و ثبت فروش آورده‌شده است.

JavaScript (fetch) — دریافت محصولات

const API_KEY = "sk_live_1a2b3c4d5e6f...";
const BASE = "https://jetanbar.ir/api/v1/store-api";

const res = await fetch(`${BASE}/products?limit=10`, {
  headers: { "x-api-key": API_KEY, Accept: "application/json" },
});
const { data } = await res.json();
console.log(data.products); // [{ productId, name, currentStock, sellPrice, photoUrl, ... }]

PHP (wp_remote_request) — ثبت فروش

$API_KEY = "sk_live_1a2b3c4d5e6f...";
$BASE = "https://jetanbar.ir/api/v1/store-api";

$response = wp_remote_request("{$BASE}/transactions/out", [
  "method"  => "POST",
  "headers" => [
    "x-api-key"       => $API_KEY,
    "Content-Type"    => "application/json; charset=utf-8",
    "Accept"          => "application/json",
  ],
  "timeout" => 20,
  "body"    => wp_json_encode([
    "productId"      => "PRD-K7Q2M9",
    "quantity"       => 2,
    "unitPriceToman" => 1250000,
    "customerName"   => "علی رضایی",
    "notes"          => "سفارش شماره #1234 از وبسایت",
  ]),
]);

$body = json_decode(wp_remote_retrieve_body($response), true);
if (!empty($body["success"])) {
  $txnId = $body["data"]["transactionId"]; // "TXN-AB3X9K"
}