محصولات

تمام مسیرها زیر v1/assistants/:assistantCode/products هستند. هر دستیار کاتالوگ جدای خودش را دارد. وقتی ابزار جستجوی محصول برای یک دستیار در کنسول روشن باشد، دستیار محصولات را در همین کاتالوگ پیدا می‌کند و با عکس، قیمت و لینک به مشتری نشان می‌دهد.

محصولات با شناسه‌ی خودتان (externalId — کد کالا یا شناسه‌ی محصول در فروشگاهتان) شناخته می‌شوند؛ پس لازم نیست شناسه‌ای از ما نگه دارید. نوشتن بر اساس externalId idempotent است: فرستادن یک محصول دو بار، چیزی را تغییر نمی‌دهد.

کاتالوگ در پلکسیت ذخیره می‌شود و خواندن (GET) همیشه فوری است. جستجو در پس‌زمینه ایندکس می‌شود: محصولی که همین حالا نوشته‌اید ظرف چند ثانیه قابل جستجو می‌شود. فیلد indexState هر محصول نشان می‌دهد در چه وضعیتی است.

شیء محصول


{
  "id": "6b1f0c2d9e3a4f58a7c1d2e3f4a5b6c7",
  "externalId": "sku-123",
  "title": "گوشی سامسونگ Galaxy A15",
  "category": "موبایل",
  "subcategory": "سامسونگ",
  "attributes": { "رنگ": "آبی", "ram": 8 },
  "description": "نمایشگر ۶.۵ اینچ، ۱۲۸ گیگابایت.",
  "imageUrl": "https://cdn.example.com/a15.png",
  "url": "https://shop.example.com/p/sku-123",
  "price": 12000000,
  "currency": "تومان",
  "inStock": true,
  "indexState": "synced",
  "indexedAt": "2026-10-04T09:30:00.000Z",
  "createdAt": "2026-10-04T09:29:58.000Z",
  "updatedAt": "2026-10-04T09:29:58.000Z"
}

فیلد	نوع	توضیح
`id`	`string`	شناسه‌ی داخلی پلکسیت برای محصول. فقط‌خواندنی؛ همه‌ی مسیرها محصول را با `externalId` آدرس می‌دهند.
`externalId`	`string`	در ایجاد الزامی است. ۱ تا ۱۹۱ نویسه، بدون فاصله و بدون `/` یا `\`. در هر دستیار یکتاست و قابل تغییر نیست.
`title`	`string`	الزامی. ۱ تا ۲٬۰۰۰ نویسه. اولین چیزی که جستجو با آن تطبیق می‌دهد.
`category` / `subcategory`	`string \| null`	هرکدام تا ۵۰۰ نویسه. بدون حساسیت به بزرگی/کوچکی حروف، فاصله و شکل حروف عربی/فارسی تطبیق داده می‌شود.
`attributes`	`object`	تا ۱۰۰ مورد. کلید تا ۲۰۰ نویسه؛ مقدار یک رشته (تا ۵۰۰ نویسه)، عدد یا boolean. عددها نوع خود را نگه می‌دارند و فیلتر بازه‌ای روی آن‌ها کار می‌کند. نام‌های `price` و `in_stock` رزرو هستند — از فیلدهای `price` و `inStock` استفاده کنید.
`description`	`string \| null`	تا ۱۰٬۰۰۰ نویسه. به دستیار و مشتری نشان داده می‌شود؛ در رتبه‌بندی نقشی ندارد.
`imageUrl` / `url`	`string \| null`	نشانی `http(s)` تا ۲٬۰۴۸ نویسه. به مشتری نشان داده می‌شود.
`price`	`number \| null`	صفر یا بیشتر. یک عدد ساده، به واحدی که خودتان انتخاب می‌کنید.
`currency`	`string \| null`	تا ۸ نویسه، کنار قیمت نمایش داده می‌شود (مثلاً `IRR` یا `تومان`).
`inStock`	`boolean`	پیش‌فرض `true`.
`indexState`	`string`	`pending` (در صف جستجو)، `synced` (قابل جستجو) یا `failed` (آخرین تلاش ناموفق بود؛ خودکار دوباره تلاش می‌شود).
`indexedAt`	`string \| null`	زمانی که نسخه‌ی فعلی قابل جستجو شد.

ایجاد محصول


POST /v1/assistants/:assistantCode/products

بدنه: فیلدهای بالا (externalId و title الزامی). پاسخ 201 با خود محصول. اگر externalId از قبل وجود داشته باشد 409 (products.external_id_taken)؛ برای upsert از PUT استفاده کنید.

curl


curl -X POST "https://api.plexit.ir/v1/assistants/<assistantCode>/products" \
  -H "Authorization: Bearer $PLEXIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "sku-123",
    "title": "گوشی سامسونگ Galaxy A15",
    "category": "موبایل",
    "attributes": { "رنگ": "آبی" },
    "price": 12000000,
    "currency": "تومان",
    "imageUrl": "https://cdn.example.com/a15.png"
  }'

فهرست محصولات


GET /v1/assistants/:assistantCode/products?limit=50&cursor=&q=&category=&state=

Query	توضیح
`limit`	۱ تا ۲۰۰، پیش‌فرض ۵۰.
`cursor`	مقدار `nextCursor` صفحه‌ی قبل. مبهم است — خودتان نسازید.
`q`	بخشی از عنوان یا `externalId`.
`category`	دسته‌بندی دقیق.
`state`	`pending`، `synced` یا `failed`.


{
  "data": { "list": [ /* محصولات */ ], "nextCursor": "MTIzNA" },
  "response": { "status": "success" }
}

برخلاف بقیه‌ی فهرست‌ها، این یکی با cursor صفحه‌بندی می‌شود: صفحه در data.list و data.nextCursor می‌آید (در صفحه‌ی آخر null) و count وجود ندارد.

محصولات به ترتیب اولین ایجاد برگردانده می‌شوند.

دریافت یک محصول


GET /v1/assistants/:assistantCode/products/:externalId

اگر چنین محصولی نباشد 404 (products.not_found).

ایجاد یا جایگزینی محصول


PUT /v1/assistants/:assistantCode/products/:externalId

بدنه: فیلدهای محصول (بدون externalId که در مسیر است). محصول جایگزین می‌شود: فیلدی که نفرستید پاک می‌شود. چه ساخته شود چه جایگزین، پاسخ 200 با خود محصول است.

ویرایش محصول


PATCH /v1/assistants/:assistantCode/products/:externalId

فقط فیلدهایی که می‌فرستید تغییر می‌کنند. برای پاک کردن category، subcategory، description، imageUrl، url، price یا currency مقدار null بفرستید. اگر attributes بفرستید کل شیء را جایگزین می‌کند. تغییر فقط description، imageUrl، url یا currency محصول را دوباره به صف جستجو نمی‌فرستد.

حذف محصول


DELETE /v1/assistants/:assistantCode/products/:externalId

محصول بلافاصله از خواندن و از نتایج جستجو ناپدید می‌شود.

وارد کردن چند محصول


POST /v1/assistants/:assistantCode/products/import


{ "products": [ { "externalId": "sku-1", "title": "…" }, { "externalId": "sku-2", "title": "…" } ] }

تا ۱٬۰۰۰ محصول در هر درخواست، هرکدام با فیلدهای بالا (externalId و title الزامی). محصولاتی که از قبل هستند به‌صورت جایگزینی کامل به‌روز می‌شوند (مثل PUT) و بقیه ساخته می‌شوند. هر externalId در یک درخواست فقط یک بار می‌تواند بیاید (400 با products.duplicate_external_id). درخواست «همه یا هیچ» است: اگر یک محصول نامعتبر باشد، هیچ‌کدام ذخیره نمی‌شود.


{
  "data": { "created": 2, "updated": 1, "unchanged": 7 },
  "response": { "status": "success" }
}

unchanged محصولاتی را می‌شمارد که با نسخه‌ی ذخیره‌شده یکسان بودند — پس فرستادن دوره‌ای کل فید ارزان است. راهنمای وارد کردن را ببینید.

حذف چند محصول


POST /v1/assistants/:assistantCode/products/delete


{ "externalIds": ["sku-1", "sku-2"] }

تا ۱٬۰۰۰ شناسه. شناسه‌ای که وجود ندارد شمرده می‌شود و خطا نیست:


{ "data": { "deleted": 1, "notFound": 1 }, "response": { "status": "success" } }

جستجوی محصولات


POST /v1/assistants/:assistantCode/products/search

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

فیلد	نوع	الزامی	توضیح
`query`	`string`	بله	۱ تا ۱٬۰۰۰ نویسه، با زبان خود مشتری. هر زبانی.
`category` / `subcategory`	`string`	خیر	فقط محصولات این دسته. سخت‌گیرانه.
`attributes`	`object`	خیر	`{ "رنگ": "آبی" }`. محصولی که مقدار آن ویژگی با این فرق دارد حذف می‌شود؛ محصولی که آن ویژگی را ندارد می‌ماند.
`minPrice` / `maxPrice`	`number`	خیر	کران‌های شامل. اگر یکی داده شود، محصولات بدون قیمت حذف می‌شوند.
`inStock`	`boolean`	خیر	`true` یعنی فقط محصولات موجود.
`limit`	`integer`	خیر	۱ تا ۱۰۰، پیش‌فرض ۲۰.
`offset`	`integer`	خیر	۰ تا ۱٬۰۰۰، پیش‌فرض ۰.

curl


curl -X POST "https://api.plexit.ir/v1/assistants/<assistantCode>/products/search" \
  -H "Authorization: Bearer $PLEXIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "گوشی سامسونگ آبی", "maxPrice": 15000000, "inStock": true, "limit": 5 }'


{
  "data": {
    "list": [ { "id": "…", "externalId": "sku-123", "title": "گوشی سامسونگ Galaxy A15", "price": 12000000, "distance": 0.12 } ],
    "count": 1
  },
  "response": { "status": "success" }
}

هر نتیجه یک محصول کامل به‌علاوه‌ی distance است — کمتر یعنی نزدیک‌تر، و بهترین‌ها اول می‌آیند. list خالی یعنی چیزی با فیلترها جور نبود. محصولی که لحظه‌ای پیش نوشته شده ممکن است هنوز قابل جستجو نباشد (indexState را ببینید). اگر جستجو در آن محیط فعال نباشد، API پاسخ 503 (products.search_unavailable) می‌دهد، ولی نوشتن و خواندن محصولات همچنان کار می‌کند.

محدودیت‌ها و خطاها

کاتالوگ هر دستیار به‌طور پیش‌فرض تا ۱۰٬۰۰۰ محصول است؛ فراتر رفتن 403 (products.limit_reached) می‌دهد.
بدنه‌ی درخواست حداکثر ۳ مگابایت است.
هر مسیر از محدودیت نرخ کلید کم می‌کند.
خطای اعتبارسنجی 400 همراه با fields است (به خطاها نگاه کنید). نوشتن نام‌های رزرو price یا in_stock در attributes یکی از آن‌هاست.
اگر :assistantCode دستیار حساب شما نباشد 404 با assistants.not_found.