مدیریت محصولات وردست با n8n و API

Developers

نویسنده: امیررضا رحیمی

با API وردست می‌توانید محصولات دستیار خود را بدون ورود دستی به پنل، به‌صورت خودکار لیست، اضافه، ویرایش و حذف کنید. در این آموزش این کار را با n8n انجام می‌دهیم؛ همین منطق با هر ابزار دیگری (یا کد) هم کار می‌کند.

مفاهیم پایه

هر دستیار دقیقاً یک پایگاه دانش (Knowledge Base) دارد که خودکار هنگام ساخت دستیار ساخته می‌شود.
«محصول» یک موجودیت جدا نیست؛ یک سند در همان پایگاه دانش با نوع Product است.
محصولات با هدر Vardast-Tenant-ID به پایگاه دانش وصل می‌شوند و مقدار این هدر همان kb_id دستیار است.
زنجیرهٔ دسترسی این‌طور است: API key ← دستیار ← kb_id ← Vardast-Tenant-ID ← محصولات

دو مقدار ثابتی که لازم دارید

BASE_URL برابر است با https://apigw.vardast.chat
API_KEY همان کلید API شماست.

همهٔ درخواست‌ها با هدر X-API-Key احراز هویت می‌شوند.

قدم ۰ — ساخت کلید API (وب‌سرویس)

اگر هنوز کلید API ندارید، اول باید یک کانال وب‌سرویس بسازید:

در پنل وردست وارد بخش اتصال اکانت / ساخت کانال جدید شوید.
از میان کانال‌ها گزینهٔ وب‌سرویس (API) را انتخاب کنید (اتصال وردست به سیستم یا اپلیکیشن اختصاصی شما).

انتخاب کانال وب‌سرویس (API) در صفحهٔ اتصال اکانت وردست

کانال را بسازید.
سپس به تنظیمات اکانت بروید و از همان‌جا توکن دسترسی (همان API key) را بردارید.

همین توکن، مقداری است که در قدم بعد به‌عنوان X-API-Key در n8n استفاده می‌کنید. آن را محرمانه نگه دارید؛ این کلید به داده‌های اکانت شما دسترسی دارد.

قدم ۱ — ساخت Credential در n8n (یک‌بار)

در n8n مسیر Credentials را باز کنید و یک Header Auth جدید بسازید:

مقدار Name را X-API-Key بگذارید.
مقدار Value را کلید API خودتان بگذارید.

آن را با نامی مثل «Vardast API Key» ذخیره کنید. از این پس در هر HTTP Request از همین Credential استفاده می‌کنید.

قدم ۲ — پیدا کردن kb_id دستیار (فقط یک‌بار)

kb_id دستیار شما ثابت است و تغییر نمی‌کند؛ پس فقط یک‌بار آن را می‌گیرید و ذخیره می‌کنید. یک HTTP Request بسازید:

روش (Method): GET
آدرس: {BASE_URL}/uaa/public/messenger/api/assistants/
احراز هویت: همان Header Auth بالا

در خروجی، دستیار خود را پیدا کنید و مقدار kb_id آن را کپی کنید. نمونهٔ خروجی:

{
  "assistant_name": "نام دستیار شما",
  "kb_id": "00000000-0000-0000-0000-000000000000"
}

این kb_id را در متغیرهای پروژهٔ n8n ذخیره کنید تا در همهٔ درخواست‌های بعدی از آن استفاده کنید. دیگر لازم نیست هر بار این درخواست را بزنید.

قدم ۳ — گرفتن لیست محصولات

یک HTTP Request با این مشخصات بسازید:

روش: GET
آدرس: {BASE_URL}/documents/knowledge/list
هدر اضافه: Vardast-Tenant-ID برابر با kb_id
پارامترهای Query:

type با مقدار Product (اجباری)
page شمارهٔ صفحه (پیش‌فرض ۱)
page_size تعداد در هر صفحه (پیش‌فرض ۱۰)
title برای جستجو در نام محصول (اختیاری)

نمونهٔ پاسخ:

{
  "items": [
    {
      "id": "doc-uuid-123",
      "title": "کفش دو آبی",
      "value": "{...payload کامل محصول...}",
      "content": "{...متن‌های قابل جستجو...}"
    }
  ],
  "total": 142,
  "pages": 15,
  "page": 1
}

نکته‌های مهم:

فیلد value خودش یک رشتهٔ JSON است؛ برای دیدن فیلدهای محصول آن را Parse کنید.
فیلد id همان شناسهٔ سند است که در ویرایش و حذف لازم می‌شود. آن را با identifier (کد محصول) اشتباه نگیرید.
endpoint گرفتن «یک محصول تکی» وجود ندارد؛ یا با title جستجو کنید یا از روی id در n8n فیلتر کنید.

قدم ۴ — افزودن محصول

بدنهٔ درخواست چهار فیلد دارد. دقت کنید که content و value خودشان رشتهٔ JSON هستند، نه شیء.

type همیشه برابر Product
title نام محصول
content متن‌های قابل جستجو (چیزی که دستیار می‌بیند): شامل name، description، short_description
value اطلاعات کامل محصول (چیزی که پنل نمایش می‌دهد)

فیلدهای داخل value:

identifier کد یا شناسهٔ محصول — اجباری، بعد از ساخت تغییرش ندهید
name نام محصول — اجباری
stock موجودی
short_description توضیح کوتاه (حداکثر ۵۰۰ کاراکتر)
description توضیح کامل (حداکثر ۵۰۰ کاراکتر)
price قیمت به‌صورت رشته
permalink لینک محصول (اگر داده شود باید HTTPS معتبر باشد)
default_image آدرس تصویر (جدا آپلود می‌شود)

درخواست ساخت:

روش: POST
آدرس: {BASE_URL}/documents/knowledge/
هدرها: X-API-Key و Vardast-Tenant-ID و Content-Type: application/json

نمونهٔ بدنه:

{
  "type": "Product",
  "title": "کفش دو آبی",
  "content": "{\"name\":\"کفش دو آبی\",\"description\":\"مناسب دویدن روزانه\",\"short_description\":\"سبک و راحت\"}",
  "value": "{\"identifier\":\"1001\",\"name\":\"کفش دو آبی\",\"stock\":\"25\",\"price\":\"890000\",\"permalink\":\"\",\"default_image\":\"\"}"
}

قاعدهٔ طلایی: content و value هر دو نام و توضیحات را تکرار می‌کنند. همیشه هر دو را با هم و از یک منبع بسازید؛ وگرنه دادهٔ نمایشی و دادهٔ جستجوی دستیار از هم جدا می‌شوند و ممکن است دستیار قیمت قدیمی را به مشتری بگوید در حالی‌که پنل قیمت جدید را نشان می‌دهد.

پاسخ موفق، شیء محصولِ ساخته‌شده را همراه با id برمی‌گرداند. این id را برای ویرایش و حذف نگه دارید.

قدم ۵ — ویرایش محصول

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

روش: PUT
آدرس: {BASE_URL}/documents/knowledge/{documentId}
هدرها: مثل قبل

در آدرس، {documentId} همان id محصول از خروجی لیست است. مقدار identifier را داخل value تغییر ندهید.

قدم ۶ — حذف محصول

برای حذف یک محصول:

روش: DELETE
آدرس: {BASE_URL}/documents/knowledge/{documentId}
هدرها: X-API-Key و Vardast-Tenant-ID

یک آدرس دیگر هم برای حذف همهٔ محصولات یک پایگاه دانش وجود دارد: DELETE {BASE_URL}/documents/knowledge/all?types=Product. این کل محصولات را پاک می‌کند؛ با احتیاط و ترجیحاً پشت یک مرحلهٔ تأیید دستی استفاده کنید.

آپلود تصویر محصول

اگر می‌خواهید برای محصول تصویر بگذارید، اول تصویر را جدا آپلود کنید و سپس آدرس برگشتی را در default_image بگذارید. این تنها درخواستی است که هدر Vardast-Tenant-ID نمی‌خواهد:

روش: POST
آدرس: {BASE_URL}/file-server/upload
بدنه: از نوع فایل (multipart/form-data) با فیلد file — فقط jpg یا png

در پاسخ، فیلد file_url را بردارید و در default_image داخل value محصول قرار دهید.

فایل آمادهٔ n8n (کپی و import کنید)

برای اینکه لازم نباشد نودها را از صفر بسازید، فلوی کامل CRUD زیر را آماده کرده‌ایم. کل متن JSON را کپی کنید و در n8n، روی صفحهٔ خالی workflow آن را Paste کنید (Ctrl+V یا Cmd+V)؛ همهٔ نودها ساخته می‌شوند. سپس فقط نود Config را باز کنید و سه مقدار API_KEY، KB_ID و در صورت نیاز BASE_URL را پر کنید.

این فلو یک چرخهٔ کامل را نشان می‌دهد: لیست می‌گیرد، یک محصول می‌سازد، همان را ویرایش می‌کند و در پایان حذف می‌کند. برای کار واقعی، هر نود را جدا استفاده کنید و در ویرایش و حذف، به‌جای شناسهٔ محصولِ تازه‌ساخته، documentId محصول واقعی خود را بگذارید (نودها note راهنما دارند).

نمای کامل فلوی CRUD محصولات در n8n: نودهای Config، List، Create، Update و Delete

{
  "name": "Vardast Products - CRUD",
  "nodes": [
    {
      "parameters": {},
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Start",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [-400, 300]
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            { "id": "a1", "name": "BASE_URL", "value": "https://apigw.vardast.chat", "type": "string" },
            { "id": "a2", "name": "API_KEY", "value": "YOUR_API_KEY_HERE", "type": "string" },
            { "id": "a3", "name": "KB_ID", "value": "YOUR_KB_ID_HERE", "type": "string" }
          ]
        },
        "options": {}
      },
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "Config",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [-180, 300]
    },
    {
      "parameters": {
        "url": "={{ $json.BASE_URL }}/documents/knowledge/list",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            { "name": "X-API-Key", "value": "={{ $json.API_KEY }}" },
            { "name": "Vardast-Tenant-ID", "value": "={{ $json.KB_ID }}" }
          ]
        },
        "sendQuery": true,
        "queryParameters": {
          "parameters": [
            { "name": "type", "value": "Product" },
            { "name": "page", "value": "1" },
            { "name": "page_size", "value": "10" }
          ]
        },
        "options": {}
      },
      "id": "33333333-3333-3333-3333-333333333333",
      "name": "List Products",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [140, 100]
    },
    {
      "parameters": {
        "method": "POST",
        "url": "={{ $('Config').item.json.BASE_URL }}/documents/knowledge/",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            { "name": "X-API-Key", "value": "={{ $('Config').item.json.API_KEY }}" },
            { "name": "Vardast-Tenant-ID", "value": "={{ $('Config').item.json.KB_ID }}" },
            { "name": "Content-Type", "value": "application/json" }
          ]
        },
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "={\n  \"type\": \"Product\",\n  \"title\": \"PRODUCT_NAME\",\n  \"content\": \"{\\\"name\\\":\\\"PRODUCT_NAME\\\",\\\"description\\\":\\\"DESCRIPTION\\\",\\\"short_description\\\":\\\"SHORT_DESCRIPTION\\\"}\",\n  \"value\": \"{\\\"identifier\\\":\\\"SKU_CODE\\\",\\\"name\\\":\\\"PRODUCT_NAME\\\",\\\"stock\\\":\\\"0\\\",\\\"short_description\\\":\\\"SHORT_DESCRIPTION\\\",\\\"description\\\":\\\"DESCRIPTION\\\",\\\"price\\\":\\\"0\\\",\\\"permalink\\\":\\\"\\\",\\\"default_image\\\":\\\"\\\"}\"\n}",
        "options": {}
      },
      "id": "44444444-4444-4444-4444-444444444444",
      "name": "Create Product",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [140, 300]
    },
    {
      "parameters": {
        "method": "PUT",
        "url": "={{ $('Config').item.json.BASE_URL }}/documents/knowledge/{{ $('Create Product').item.json.id }}",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            { "name": "X-API-Key", "value": "={{ $('Config').item.json.API_KEY }}" },
            { "name": "Vardast-Tenant-ID", "value": "={{ $('Config').item.json.KB_ID }}" },
            { "name": "Content-Type", "value": "application/json" }
          ]
        },
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "={\n  \"type\": \"Product\",\n  \"title\": \"PRODUCT_NAME\",\n  \"content\": \"{\\\"name\\\":\\\"PRODUCT_NAME\\\",\\\"description\\\":\\\"NEW_DESCRIPTION\\\",\\\"short_description\\\":\\\"SHORT_DESCRIPTION\\\"}\",\n  \"value\": \"{\\\"identifier\\\":\\\"SKU_CODE\\\",\\\"name\\\":\\\"PRODUCT_NAME\\\",\\\"stock\\\":\\\"0\\\",\\\"short_description\\\":\\\"SHORT_DESCRIPTION\\\",\\\"description\\\":\\\"NEW_DESCRIPTION\\\",\\\"price\\\":\\\"0\\\",\\\"permalink\\\":\\\"\\\",\\\"default_image\\\":\\\"\\\"}\"\n}",
        "options": {}
      },
      "id": "55555555-5555-5555-5555-555555555555",
      "name": "Update Product",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [420, 300]
    },
    {
      "parameters": {
        "method": "DELETE",
        "url": "={{ $('Config').item.json.BASE_URL }}/documents/knowledge/{{ $('Create Product').item.json.id }}",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            { "name": "X-API-Key", "value": "={{ $('Config').item.json.API_KEY }}" },
            { "name": "Vardast-Tenant-ID", "value": "={{ $('Config').item.json.KB_ID }}" }
          ]
        },
        "options": {}
      },
      "id": "66666666-6666-6666-6666-666666666666",
      "name": "Delete Product",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [700, 300]
    }
  ],
  "connections": {
    "Start": { "main": [[{ "node": "Config", "type": "main", "index": 0 }]] },
    "Config": { "main": [[
      { "node": "List Products", "type": "main", "index": 0 },
      { "node": "Create Product", "type": "main", "index": 0 }
    ]] },
    "Create Product": { "main": [[{ "node": "Update Product", "type": "main", "index": 0 }]] },
    "Update Product": { "main": [[{ "node": "Delete Product", "type": "main", "index": 0 }]] }
  },
  "settings": { "executionOrder": "v1" }
}

سه شناسه‌ای که نباید اشتباه گرفته شوند

kb_id شناسهٔ پایگاه دانش است و مقدار هدر Vardast-Tenant-ID را می‌سازد.
id (یا documentId) شناسهٔ سند محصول است و در آدرس ویرایش و حذف می‌آید.
identifier کد تجاری محصول (SKU) است، داخل value قرار دارد و ثابت می‌ماند.

جمع‌بندی جدول آدرس‌ها

لیست دستیارها برای گرفتن kb_id: GET /uaa/public/messenger/api/assistants/
لیست و جستجوی محصولات: GET /documents/knowledge/list?type=Product
ساخت محصول: POST /documents/knowledge/
ویرایش محصول: PUT /documents/knowledge/{documentId}
حذف یک محصول: DELETE /documents/knowledge/{documentId}
حذف همهٔ محصولات: DELETE /documents/knowledge/all?types=Product
آپلود تصویر: POST /file-server/upload

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