logo
REST API

مستندات API شاپ پیلوت

راهنمای یکپارچه‌سازی چت‌بات، کاتالوگ و سفارش‌ها با بک‌اند، اپ موبایل یا CRM

ابتدا در پنل بات بسازید و سرویس API را فعال کنید. سپس با توکن API پیام بفرستید، محصول و دسته‌بندی بسازید یا ویرایش کنید و سفارش‌ها را مشاهده کنید. پاسخ‌ها JSON و قابل parse در هر زبان برنامه‌نویسی هستند.

لیست endpointها GET /api/list
راهنمای کامل راه‌اندازی از صفر تا صد

۱. ساخت بات

در پنل بات بسازید، آموزش دهید و وضعیت آن را فعال کنید.

۲. دریافت API Token

از بخش پروفایل پنل، توکن API خود را کپی کنید.

۳. فراخوانی REST

درخواست HTTP بزنید و پاسخ JSON را در UI خود نمایش دهید.

POST /chat/template API Token

ارسال پیام به بات

پیام کاربر را به بات فعال ارسال می‌کند و پاسخ هوشمند JSON دریافت می‌کنید.

این endpoint اصلی یکپارچه‌سازی REST است. با ارسال متن پیام، شناسه بات و کلید API، پاسخ بات را دریافت می‌کنید. برای ادامه مکالمه مهمان، فیلد guest_key را در درخواست‌های بعدی ارسال کنید.

پارامترها

نام نوع الزامی توضیح
text string بله متن پیام کاربر (حداکثر ۵۰۰۰ کاراکتر)
bot_uid uuid بله شناسه یکتای بات فعال در پنل
api_key string بله توکن API از بخش پروفایل پنل
guest_key uuid خیر شناسه مهمان برای ادامه مکالمه (در پاسخ اول برگردانده می‌شود)

Request Body

{
    "text": "وضعیت سفارش #8823 چیه؟",
    "bot_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "api_key": "your_api_token_here",
    "guest_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Response 200

{
    "status": "success",
    "result": "سفارش 8823 در وضعیت «آماده ارسال» است.",
    "q": [],
    "base_message": "وضعیت سفارش #8823 چیه؟",
    "total_token": 142,
    "time_response": 1.24,
    "suggest": [
        "بله، لینک رهگیری بفرست"
    ],
    "guest_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

خطاهای رایج

  • 401 کلید API نامعتبر است.
  • 403 این کلید API به این بات دسترسی ندارد.
  • 404 بات فعال یافت نشد.
  • 422 خطای اعتبارسنجی پارامترها.
GET /is-active-server بدون احراز هویت

بررسی وضعیت سرور AI

وضعیت دسترسی به سرویس هوش مصنوعی را بررسی می‌کند.

برای health check و مانیتورینگ استفاده کنید. اگر سرویس AI در دسترس باشد مقدار status برابر success است.

Response 200

{
    "status": "success"
}

خطاهای رایج

  • 200 در صورت عدم دسترسی، status برابر error است.
GET /api/shoppilot/services Bearer Token

لیست سرویس‌ها

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

قبل از مدیریت محصول، دسته‌بندی یا سفارش، شناسه سرویس (user_service_id) را از این endpoint بگیرید. هدر Authorization: Bearer {api_token} الزامی است.

Response 200

{
    "services": [
        {
            "id": 12,
            "status": "active",
            "is_active": true,
            "products_count": 48,
            "orders_count": 19,
            "categories_count": 6,
            "catalog_product": {
                "name": "چت‌بات فروشگاهی",
                "slug": "wordpress-sales-chatbot"
            }
        }
    ]
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
POST /api/shoppilot/products Bearer Token

ایجاد محصول

محصول جدید در کاتالوگ سرویس ایجاد می‌کند (یا در صورت وجود woocommerce_id همان محصول را به‌روز می‌کند).

برای سرویس‌های غیروردپرسی (کاتالوگ دستی) محصول را مستقیم می‌سازید. اگر woocommerce_id ارسال شود و محصول قبلی با همان شناسه وجود داشته باشد، به‌روزرسانی انجام می‌شود. فیلد category_ids شناسه‌های دسته‌بندی داخلی شاپ‌پیلوت است.

پارامترها

نام نوع الزامی توضیح
user_service_id integer بله شناسه سرویس کاربر
name string بله نام محصول
slug string خیر اسلاگ یکتا؛ در صورت خالی بودن خودکار ساخته می‌شود
type string خیر simple | grouped | external | variable
status string خیر draft | pending | private | publish
regular_price number خیر قیمت اصلی
sale_price number خیر قیمت فروش ویژه
sku string خیر کد کالا
stock_status string خیر instock | outofstock | onbackorder
stock_quantity integer خیر موجودی (در صورت مدیریت موجودی)
description string خیر توضیحات کامل
short_description string خیر توضیح کوتاه
category_ids array خیر آرایه شناسه دسته‌بندی‌ها
images array خیر آرایه تصاویر با کلید src
woocommerce_id integer خیر شناسه ووکامرس برای سینک/آپ‌سرت

Request Body

{
    "user_service_id": 12,
    "name": "هدفون بلوتوثی نویزکنسلینگ",
    "slug": "bluetooth-anc-headphones",
    "status": "publish",
    "regular_price": 2890000,
    "sale_price": 2490000,
    "sku": "HP-ANC-01",
    "stock_status": "instock",
    "stock_quantity": 25,
    "short_description": "هدفون بی‌سیم با حذف نویز فعال",
    "category_ids": [
        3,
        8
    ],
    "images": [
        {
            "src": "https://example.com/images/headphones.jpg"
        }
    ]
}

Response 200

{
    "id": 101,
    "user_service_id": 12,
    "name": "هدفون بلوتوثی نویزکنسلینگ",
    "slug": "bluetooth-anc-headphones",
    "status": "publish",
    "regular_price": "2890000",
    "sale_price": "2490000",
    "sku": "HP-ANC-01",
    "stock_status": "instock",
    "categories": [
        {
            "id": 3,
            "name": "صوتی"
        }
    ]
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
  • 404 Service not found
  • 422 خطای اعتبارسنجی یا محدودیت سینک ووکامرس
PUT /api/shoppilot/products/{id} Bearer Token

ویرایش محصول

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

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

پارامترها

نام نوع الزامی توضیح
id integer بله شناسه محصول در مسیر URL
name string خیر نام جدید محصول
regular_price number خیر قیمت اصلی
sale_price number خیر قیمت فروش ویژه
status string خیر draft | pending | private | publish
stock_status string خیر instock | outofstock | onbackorder
stock_quantity integer خیر موجودی
category_ids array خیر جایگزینی دسته‌بندی‌ها
description string خیر توضیحات کامل

Request Body

{
    "name": "هدفون بلوتوثی نویزکنسلینگ — نسخه ۲۰۲۶",
    "regular_price": 3090000,
    "sale_price": 2690000,
    "stock_quantity": 18,
    "category_ids": [
        3,
        8,
        15
    ]
}

Response 200

{
    "id": 101,
    "name": "هدفون بلوتوثی نویزکنسلینگ — نسخه ۲۰۲۶",
    "regular_price": "3090000",
    "sale_price": "2690000",
    "stock_quantity": 18,
    "categories": [
        {
            "id": 3,
            "name": "صوتی"
        },
        {
            "id": 15,
            "name": "پرفروش"
        }
    ]
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
  • 404 Product not found
GET /api/shoppilot/products Bearer Token

لیست محصولات

محصولات کاتالوگ کاربر را با فیلتر اختیاری سرویس و جستجو برمی‌گرداند.

پارامترهای جستجو را به‌صورت query string ارسال کنید. حداکثر ۱۰۰ مورد در هر پاسخ برگردانده می‌شود.

پارامترها

نام نوع الزامی توضیح
service_id integer خیر فیلتر بر اساس شناسه سرویس
q string خیر جستجو در نام، SKU و اسلاگ

Response 200

{
    "items": [
        {
            "id": 101,
            "name": "هدفون بلوتوثی نویزکنسلینگ",
            "sku": "HP-ANC-01",
            "status": "publish",
            "regular_price": "2890000",
            "stock_status": "instock"
        }
    ],
    "services": [
        {
            "id": 12,
            "label": "چت‌بات فروشگاهی"
        }
    ]
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
POST /api/shoppilot/categories Bearer Token

ایجاد و ویرایش دسته‌بندی

دسته‌بندی جدید می‌سازد؛ با ارسال woocommerce_id موجود، همان دسته‌بندی به‌روزرسانی می‌شود.

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

پارامترها

نام نوع الزامی توضیح
user_service_id integer بله شناسه سرویس کاربر
name string بله نام دسته‌بندی
slug string خیر اسلاگ؛ در صورت خالی بودن خودکار ساخته می‌شود
description string خیر توضیحات
parent_id integer خیر شناسه دسته والد داخلی
woocommerce_id integer خیر شناسه ووکامرس برای ایجاد یا ویرایش
woocommerce_parent_id integer خیر شناسه والد در ووکامرس
menu_order integer خیر ترتیب نمایش
image object خیر اطلاعات تصویر دسته

Request Body

{
    "user_service_id": 12,
    "name": "صوتی و هدفون",
    "slug": "audio-headphones",
    "description": "هدفون، هندزفری و اسپیکر",
    "parent_id": null,
    "menu_order": 1
}

Response 200

{
    "id": 3,
    "user_service_id": 12,
    "name": "صوتی و هدفون",
    "slug": "audio-headphones",
    "description": "هدفون، هندزفری و اسپیکر",
    "parent_id": null,
    "menu_order": 1
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
  • 404 Service not found
  • 422 خطای اعتبارسنجی یا محدودیت سینک ووکامرس
GET /api/shoppilot/product-categories Bearer Token

لیست دسته‌بندی‌ها

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

پارامتر service_id الزامی است تا لیست دسته‌بندی‌ها برگردد؛ بدون آن فقط لیست سرویس‌ها برای انتخاب نمایش داده می‌شود.

پارامترها

نام نوع الزامی توضیح
service_id integer بله شناسه سرویس — بدون آن فقط لیست سرویس‌ها برمی‌گردد

Response 200

{
    "mode": "categories",
    "items": [
        {
            "id": 3,
            "name": "صوتی و هدفون",
            "slug": "audio-headphones",
            "parent_name": "—",
            "products_count": 12,
            "menu_order": 1
        }
    ],
    "service": {
        "id": 12,
        "label": "چت‌بات فروشگاهی"
    }
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
GET /api/shoppilot/services/{serviceId}/orders Bearer Token

مشاهده سفارش‌های یک سرویس

سفارش‌های یک سرویس را با صفحه‌بندی برمی‌گرداند.

برای داشبوردها و یکپارچه‌سازی بک‌اند مناسب است. پارامتر limit بین ۵ تا ۵۰ و page از ۱ شروع می‌شود.

پارامترها

نام نوع الزامی توضیح
serviceId integer بله شناسه سرویس در مسیر URL
limit integer خیر تعداد در هر صفحه (پیش‌فرض ۲۵، حداکثر ۵۰)
page integer خیر شماره صفحه (پیش‌فرض ۱)

Response 200

{
    "items": [
        {
            "id": 8823,
            "order_number": "8823",
            "status": "processing",
            "total": "2490000",
            "currency": "IRT",
            "billing_first_name": "سارا",
            "billing_last_name": "محمدی",
            "billing_phone": "09121234567",
            "ordered_at": "2026-07-14T08:20:00+03:30"
        }
    ],
    "pagination": {
        "current_page": 1,
        "last_page": 3,
        "per_page": 25,
        "total": 61
    }
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
  • 404 Service not found
GET /api/shoppilot/orders Bearer Token

مشاهده همه سفارش‌ها

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

برای لیست کلی پنل یا اپ دسکتاپ. می‌توانید فقط سفارش‌های در انتظار را با مسیر /api/shoppilot/orders/pending بگیرید.

پارامترها

نام نوع الزامی توضیح
service_id integer خیر فیلتر بر اساس سرویس
q string خیر جستجو در شماره سفارش، نام یا تلفن

Response 200

{
    "items": [
        {
            "id": 8823,
            "order_number": "8823",
            "status": "processing",
            "total": "2490000",
            "billing_phone": "09121234567"
        }
    ],
    "services": [
        {
            "id": 12,
            "label": "چت‌بات فروشگاهی"
        }
    ],
    "pending_only": false
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
POST /api/shoppilot/orders Bearer Token

ایجاد / همگام‌سازی سفارش

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

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

پارامترها

نام نوع الزامی توضیح
user_service_id integer بله شناسه سرویس کاربر
woocommerce_id integer خیر شناسه سفارش در منبع خارجی برای آپ‌سرت
order_number string خیر شماره نمایشی سفارش
status string خیر وضعیت سفارش (مثلاً pending, processing, completed)
total number خیر مبلغ کل
currency string خیر واحد پول
billing_first_name string خیر نام مشتری
billing_last_name string خیر نام خانوادگی مشتری
billing_phone string خیر تلفن مشتری
billing_email string خیر ایمیل مشتری
line_items array خیر اقلام سفارش
source string خیر woocommerce | chat
ordered_at date خیر زمان سفارش

Request Body

{
    "user_service_id": 12,
    "order_number": "8823",
    "status": "processing",
    "currency": "IRT",
    "total": 2490000,
    "billing_first_name": "سارا",
    "billing_last_name": "محمدی",
    "billing_phone": "09121234567",
    "source": "chat",
    "line_items": [
        {
            "name": "هدفون بلوتوثی نویزکنسلینگ",
            "quantity": 1,
            "total": 2490000
        }
    ]
}

Response 200

{
    "id": 8823,
    "user_service_id": 12,
    "order_number": "8823",
    "status": "processing",
    "total": "2490000",
    "billing_phone": "09121234567",
    "sync_status": "synced"
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
  • 404 Service not found
  • 422 خطای اعتبارسنجی پارامترها
PUT /api/shoppilot/orders/{id} Bearer Token

ویرایش سفارش

وضعیت یا جزئیات یک سفارش موجود را به‌روزرسانی می‌کند.

شناسه سفارش داخلی شاپ‌پیلوت را در مسیر ارسال کنید. فیلدهای user_id و user_service_id قابل تغییر نیستند.

پارامترها

نام نوع الزامی توضیح
id integer بله شناسه سفارش در مسیر URL
status string خیر وضعیت جدید
total number خیر مبلغ کل
payment_url string خیر لینک پرداخت
customer_note string خیر یادداشت مشتری

Request Body

{
    "status": "completed",
    "payment_method_title": "پرداخت آنلاین"
}

Response 200

{
    "id": 8823,
    "order_number": "8823",
    "status": "completed",
    "payment_method_title": "پرداخت آنلاین"
}

خطاهای رایج

  • 401 Unauthenticated / Invalid API token
  • 404 Order not found

آماده یکپارچه‌سازی هستید؟

ثبت‌نام کنید، بات بسازید و سرویس API را فعال کنید — اولین درخواست را امروز بزنید.

شروع رایگان

فعال‌سازی Pay as you go

مکالمه با هوش مصنوعی