מדריך REST API

⚠️ תת-מערכת Playbooks רדומה בגרסה המופצת

קוד ה-M3 Playbook (CPT, engine, טבלת sessions ונתיבי ה-REST של /playbooks) נכלל בתוסף אך אינו מאותחל: המתודה Plugin::init_m3_system() ריקה, ופריט התפריט בניהול הוסר. לכן נתיבי ה-REST של playbooks אינם רשומים, טבלאות waa_playbook* אינן נוצרות, וה-hooks של playbook למטה אינם רצים בהתקנה רגילה. החומר נשמר לצורכי עיון. בגרסה הנוכחית השתמשו ב-Custom Rules, Topics, Context ו-Promotions.

מדריך REST API

WooAI Chatbot Pro מספק REST API מקיף לשילוב פונקציונליות צ’אטבוט, ניהול הגדרות וגישה לנתוני אנליטיקה. מדריך זה מתעד את כל נקודות הקצה הזמינות, דרישות אימות, סכמות בקשה/תגובה ודוגמאות שימוש.

שימו לב: אם אתם מקבלים שגיאות 401, בדקו קודם את ה-nonce. ב-9 מתוך 10 מקרים
זה תוסף caching ששומר nonce ישן. WP Rocket, LiteSpeed Cache – כולם.
ראו פתרון בעיות #3 לתיקון.

1. סקירת API

מבנה כתובת בסיס

כל נקודות הקצה של ה-API רשומות תחת WordPress REST API namespace:

https://your-site.com/wp-json/woo-ai/v1/{endpoint}

Namespaces

Namespace	תיאור	סטטוס
`woo-ai/v1`	Namespace ראשי של API	פעיל
`woo-ai-chatbot/v1`	Namespace ישן לתאימות לאחור	מיושן

ה-namespace הישן (woo-ai-chatbot/v1) ממשיך לעבוד עבור אינטגרציות קיימות אך יוסר בגרסה עתידית. כל המימושים החדשים צריכים להשתמש ב-woo-ai/v1.

אימות

ה-API תומך בשני דפוסי אימות בהתאם לרמת הגישה של נקודת הקצה:

נקודות קצה ציבוריות (לא דורשות אימות):
– GET /public/topics – קבלת נושאים מופעלים לתצוגת widget
– POST /public/topics/contextual – קבלת נושאים מסוננים לפי הקשר

נקודות קצה מוגנות דורשות אחת מהבאות:

WordPress Nonce (JavaScript בצד לקוח):
javascript fetch('/wp-json/woo-ai/v1/chat/message', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-WP-Nonce': wooAiChatbot.nonce }, body: JSON.stringify({ session_id: '...', message: '...' }) });
Cookie Authentication (משתמשי WordPress מחוברים):
אוטומטי כאשר מבצעים בקשות מאותו דומיין עם cookies תקפים של WordPress.
Application Passwords (אינטגרציות חיצוניות):
סיסמאות אפליקציה של WordPress 5.6+ לצרכנים חיצוניים של API.

הגבלת קצב בקשות

נקודות קצה של צ’אט מיישמות הגבלת קצב למניעת שימוש לרעה:

מגבלה	חלון זמן	היקף
30 בקשות	60 שניות	לפי מזהה משתמש או כתובת IP

כאשר מגבלת הקצב נחרגת, ה-API מחזיר:

{
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please wait a moment and try again.",
    "data": { "status": 429 }
}

דרישות הרשאות

קטגוריית נקודת קצה	יכולת נדרשת
Chat (ציבורי)	nonce תקף בלבד
Analytics	`manage_woocommerce`
Playbooks	`manage_woocommerce`
Topics (admin)	`manage_woocommerce`
RAG	`manage_woocommerce`
License	`manage_options`
Promotions	`manage_woocommerce`

2. נקודות קצה של צ’אט

נקודות קצה של צ’אט מטפלות בהודעות בזמן אמת, מחזור חיים של session ופעולות עגלת WooCommerce.

POST /chat/message

שליחת הודעת משתמש לצ’אטבוט AI וקבלת תגובה.

בקשה:

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/chat/message" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "session_id": "abc123-def456-ghi789",
    "message": "What products do you recommend for outdoor activities?"
  }'

פרמטרים:

פרמטר	סוג	חובה	תיאור
`session_id`	string	כן	מזהה session תקף (20-50 תווים אלפאנומריים עם מקפים)
`message`	string	כן	תוכן הודעת המשתמש (עד 4000 תווים)

תגובה (200 OK):

{
    "success": true,
    "session_id": "abc123-def456-ghi789",
    "message": {
        "role": "assistant",
        "content": "I'd recommend checking out our hiking boots and camping gear collection!",
        "metadata": {
            "products": [
                {
                    "id": 123,
                    "name": "Trail Master Hiking Boots",
                    "price": "89.99",
                    "price_html": "<span class="woocommerce-Price-amount">$89.99</span>",
                    "image": "https://example.com/boots.jpg",
                    "url": "https://example.com/product/hiking-boots/",
                    "in_stock": true
                }
            ],
            "suggestions": ["View all outdoor gear", "Check delivery options"]
        }
    },
    "products": [...],
    "suggestions": [...],
    "type": "product_recommendation",
    "intent": "product_search"
}

תגובות שגיאה:

סטטוס	קוד	תיאור
404	`invalid_session`	Session לא נמצא או פג תוקף
429	`rate_limit_exceeded`	יותר מדי בקשות
500	`message_processing_failed`	שגיאת עיבוד AI

GET /chat/session

קבלת נתוני session כולל היסטוריית שיחה והקשר.

בקשה:

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/chat/session?session_id=abc123-def456-ghi789" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה (200 OK):

{
    "success": true,
    "session": {
        "session_id": "abc123-def456-ghi789",
        "conversation_history": [
            { "role": "user", "content": "Hello" },
            { "role": "assistant", "content": "Welcome! How can I help?" }
        ],
        "context": {
            "cart": { "items": [], "total": "0.00" },
            "current_product": null,
            "recently_viewed": []
        },
        "created_at": "2024-01-15T10:30:00Z",
        "expires_at": "2024-01-15T11:30:00Z"
    }
}

POST /chat/session

יצירת session צ’אט חדש. Sessions פגי תוקף אחרי שעה כברירת מחדל.

בקשה:

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/chat/session" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{ "user_id": 42 }'

פרמטרים:

פרמטר	סוג	חובה	תיאור
`user_id`	integer	לא	מזהה משתמש WordPress (למשתמשים מחוברים)

תגובה (201 Created):

{
    "success": true,
    "session_id": "abc123-def456-ghi789",
    "expires_at": "2024-01-15T11:30:00Z"
}

DELETE /chat/session/{id}

סיום session צ’אט פעיל.

בקשה:

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/chat/session/abc123-def456-ghi789" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה (200 OK):

{
    "success": true,
    "message": "Session ended successfully."
}

POST /chat/events

מעקב אחר אירועי אנליטיקה מ-widget הצ’אט.

בקשה:

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/chat/events" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "sessionId": "abc123-def456-ghi789",
    "eventType": "product_click",
    "eventData": { "product_id": 123, "position": 1 },
    "timestamp": 1705312200000
  }'

תגובה (200 OK):

{
    "success": true,
    "message": "Event tracked successfully."
}

פעולות עגלה

POST /cart/add

הוספת מוצר לעגלת WooCommerce.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/cart/add" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "product_id": 123,
    "quantity": 2,
    "variation_id": 456,
    "variation": { "attribute_color": "blue" }
  }'

GET /cart

קבלת תוכן העגלה הנוכחי.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/cart" 
  -H "X-WP-Nonce: your_nonce_here"

DELETE /cart

ניקוי העגלה כולה.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/cart" 
  -H "X-WP-Nonce: your_nonce_here"

DELETE /cart/item/{key}

הסרת פריט ספציפי מהעגלה.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/cart/item/abc123def456" 
  -H "X-WP-Nonce: your_nonce_here"

PUT /cart/item/{key}

עדכון כמות פריט בעגלה.

curl -X PUT "https://your-site.com/wp-json/woo-ai/v1/cart/item/abc123def456" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{ "quantity": 3 }'

POST /cart/coupon

הפעלת קוד קופון על העגלה.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/cart/coupon" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{ "coupon_code": "SAVE20" }'

POST /cart/checkout

קבלת כתובת checkout עם פרמטרים אופציונליים.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/cart/checkout" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{ "params": { "source": "chatbot" } }'

תגובה:

{
    "success": true,
    "checkout_url": "https://your-site.com/checkout/?source=chatbot"
}

3. נקודות קצה של אנליטיקה

נקודות קצה של אנליטיקה מספקות KPIs, מדדי ביצועים ויכולות יצוא נתונים.

GET /analytics

קבלת נתוני לוח מחוונים מלאים של אנליטיקה.

בקשה:

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics?from=2024-01-01&to=2024-01-31" 
  -H "X-WP-Nonce: your_nonce_here"

פרמטרים:

פרמטר	סוג	חובה	ברירת מחדל	תיאור
`from`	string	לא	30 יום אחורה	תאריך התחלה (Y-m-d או ISO 8601)
`to`	string	לא	היום	תאריך סיום (Y-m-d או ISO 8601)

תגובה (200 OK):

{
    "kpis": {
        "total_sessions": 1250,
        "total_messages": 4320,
        "avg_messages_per_session": 3.45,
        "conversion_rate": 8.5,
        "product_clicks": 890,
        "add_to_cart_count": 234
    },
    "topProducts": [
        {
            "id": 123,
            "name": "Premium Widget",
            "mentions": 156,
            "clicks": 89,
            "conversionRate": 12.5
        }
    ],
    "chartData": [
        { "hour": "00:00", "value": 12 },
        { "hour": "01:00", "value": 8 }
    ],
    "dateRange": {
        "from": "2024-01-01",
        "to": "2024-01-31"
    }
}

GET /analytics/summary

קבלת סיכום KPI בלבד (נקודת קצה קלילה).

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/summary?from=2024-01-01&to=2024-01-31" 
  -H "X-WP-Nonce: your_nonce_here"

GET /analytics/topics

קבלת מדדי ביצועים של נושאים.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/topics?from=2024-01-01&to=2024-01-31" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "topics": [
        {
            "slug": "shipping_delivery",
            "name": "Shipping & Delivery",
            "count": 342,
            "percentage": 28.5
        }
    ],
    "dateRange": { "from": "2024-01-01", "to": "2024-01-31" }
}

GET /analytics/products

קבלת מדדי ביצועים של מוצרים.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/products?from=2024-01-01&to=2024-01-31&limit=10" 
  -H "X-WP-Nonce: your_nonce_here"

פרמטרים:

פרמטר	סוג	ברירת מחדל	טווח	תיאור
`limit`	integer	10	1-100	מספר מקסימלי של מוצרים להחזיר

GET /analytics/funnel

קבלת נתוני משפך המרה.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/funnel?from=2024-01-01&to=2024-01-31" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "funnel": {
        "sessions": 1250,
        "engaged_sessions": 980,
        "product_views": 654,
        "add_to_cart": 234,
        "checkouts": 156,
        "purchases": 89
    },
    "dateRange": { "from": "2024-01-01", "to": "2024-01-31" }
}

GET /analytics/hourly

קבלת התפלגות פעילות שעתית.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/hourly?from=2024-01-01&to=2024-01-31" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "hourly": [
        { "hour": "00:00", "count": 45 },
        { "hour": "01:00", "count": 23 }
    ],
    "raw": {
        "0": 45, "1": 23, "2": 12
    },
    "dateRange": { "from": "2024-01-01", "to": "2024-01-31" }
}

GET /analytics/queries

קבלת שאילתות משתמש מובילות.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/queries?from=2024-01-01&to=2024-01-31&limit=10" 
  -H "X-WP-Nonce: your_nonce_here"

GET /analytics/comparison

קבלת השוואה שבוע מול שבוע.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/comparison" 
  -H "X-WP-Nonce: your_nonce_here"

GET /analytics/export

יצוא נתוני אנליטיקה כ-CSV.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/analytics/export?from=2024-01-01&to=2024-01-31" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "csv": "date,sessions,messages,conversionsn2024-01-01,45,123,5n...",
    "filename": "analytics-2024-01-01-2024-01-31.csv",
    "mimeType": "text/csv"
}

POST /analytics/events

מעקב אחר אירוע אנליטיקה מותאם אישית.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/analytics/events" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "event": "custom_action",
    "data": { "action": "feature_used", "value": "quick_reply" }
  }'

POST /analytics/cache/clear

ניקוי מטמון האנליטיקה.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/analytics/cache/clear" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "success": true,
    "deletedCount": 24,
    "message": "Cleared 24 cache entries."
}

4. נקודות קצה של Playbooks

Playbooks מגדירים זרימות שיחה אוטומטיות ופעולות.

GET /playbooks

רשימת כל ה-playbooks עם סינון אופציונלי.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/playbooks?status=active&per_page=20&orderby=priority&order=DESC" 
  -H "X-WP-Nonce: your_nonce_here"

פרמטרים:

פרמטר	סוג	ברירת מחדל	תיאור
`status`	string	–	סינון לפי סטטוס (`active`, `inactive`)
`intent`	string	–	סינון לפי מזהה intent
`per_page`	integer	-1	תוצאות לעמוד (-1 לכולם)
`orderby`	string	`priority`	שדה מיון (`priority`, `created_at`)
`order`	string	`DESC`	כיוון מיון (`ASC`, `DESC`)

תגובה (200 OK):

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Return Policy",
            "intent": "returns",
            "priority": 10,
            "steps": [...],
            "conditions": [...],
            "trigger": "auto",
            "status": "active",
            "created_at": "2024-01-15T10:30:00Z",
            "updated_at": "2024-01-16T14:22:00Z"
        }
    ],
    "count": 6
}

POST /playbooks

יצירת playbook חדש.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/playbooks" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "name": "Shipping Information",
    "intent": "shipping_query",
    "priority": 8,
    "trigger": "auto",
    "steps": [
        {
            "id": "step_1",
            "type": "message",
            "content": "We offer free shipping on orders over $50!",
            "next_step": "step_2"
        },
        {
            "id": "step_2",
            "type": "options",
            "content": "Would you like more details?",
            "options": [
                { "label": "Delivery times", "value": "delivery" },
                { "label": "Track order", "value": "tracking" }
            ]
        }
    ],
    "conditions": [
        { "type": "cart_total", "operator": "less_than", "value": 50 }
    ]
  }'

סכמת Playbook:

שדה	סוג	חובה	תיאור
`name`	string	כן	שם תצוגה של Playbook
`intent`	string	כן	מזהה Intent להפעלה
`priority`	integer	לא	עדיפות ביצוע (0-100, גבוה יותר = ראשון)
`steps`	array	כן	מערך של אובייקטי צעדים
`conditions`	array	לא	תנאי הפעלה
`trigger`	string	לא	סוג הפעלה (`auto`, `manual`)
`status`	string	לא	סטטוס (`active`, `draft`)

סוגי צעדים:

סוג	תיאור	מאפיינים
`message`	הצגת הודעת טקסט	`content`, `next_step`
`options`	הצגת אפשרויות בחירה	`content`, `options[]`
`product`	הצגת מוצר(ים)	`product_ids[]`
`action`	ביצוע פעולה	`actions[]`

תגובה (201 Created):

{
    "success": true,
    "data": { ... },
    "message": "Playbook created successfully."
}

GET /playbooks/{id}

קבלת playbook בודד לפי מזהה.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/playbooks/1" 
  -H "X-WP-Nonce: your_nonce_here"

PUT /playbooks/{id}

עדכון playbook קיים.

curl -X PUT "https://your-site.com/wp-json/woo-ai/v1/playbooks/1" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "name": "Updated Shipping Info",
    "priority": 9
  }'

DELETE /playbooks/{id}

מחיקת playbook לצמיתות.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/playbooks/1" 
  -H "X-WP-Nonce: your_nonce_here"

POST /playbooks/{id}/duplicate

יצירת עותק של playbook קיים.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/playbooks/1/duplicate" 
  -H "X-WP-Nonce: your_nonce_here"

POST /playbooks/{id}/toggle

החלפת סטטוס playbook בין active ל-draft.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/playbooks/1/toggle" 
  -H "X-WP-Nonce: your_nonce_here"

5. נקודות קצה של נושאים (Topics)

נושאים מקטלגים כוונות שיחה לניתוב ואנליטיקה.

נקודות קצה של מנהל (דורשות `manage_woocommerce`)

GET /topics

רשימת כל הנושאים.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/topics" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

[
    {
        "id": "shipping_delivery",
        "slug": "shipping_delivery",
        "name": "Shipping & Delivery",
        "description": "Shipping methods, delivery times, tracking",
        "icon": "truck",
        "keywords": ["shipping", "delivery", "tracking"],
        "patterns": ["when.*arrive", "track.*order"],
        "priority": 7,
        "enabled": true,
        "detection_methods": ["keyword", "intent", "context"],
        "questions": 28,
        "usage": 87
    }
]

POST /topics

יצירת נושא חדש.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/topics" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "slug": "gift_wrapping",
    "name": "Gift Wrapping",
    "description": "Gift wrap options and pricing",
    "keywords": ["gift", "wrap", "wrapping", "present"],
    "patterns": ["gift.*wrap", "wrap.*present"],
    "priority": 5,
    "enabled": true,
    "detection_methods": ["keyword", "intent"]
  }'

PUT /topics/{id}

עדכון נושא קיים.

curl -X PUT "https://your-site.com/wp-json/woo-ai/v1/topics/gift_wrapping" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "priority": 6,
    "enabled": true
  }'

DELETE /topics/{id}

מחיקת נושא.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/topics/gift_wrapping" 
  -H "X-WP-Nonce: your_nonce_here"

POST /topics/{id}/toggle

החלפת סטטוס enabled של נושא.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/topics/shipping_delivery/toggle" 
  -H "X-WP-Nonce: your_nonce_here"

נקודות קצה ציבוריות (ללא אימות)

GET /public/topics

קבלת כל הנושאים המופעלים לתצוגת widget.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/public/topics"

תגובה:

[
    {
        "id": "shipping_delivery",
        "slug": "shipping_delivery",
        "name": "Shipping & Delivery",
        "description": "Shipping methods, delivery times, tracking",
        "icon": "truck",
        "keywords": ["shipping", "delivery"],
        "sampleQuestions": ["When will it arrive?", "Track my order"],
        "enabled": true
    }
]

POST /public/topics/contextual

קבלת נושאים מסוננים לפי הקשר עמוד.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/public/topics/contextual" 
  -H "Content-Type: application/json" 
  -d '{
    "page_type": "product",
    "product_id": 123,
    "category_id": 45,
    "utm_source": "email",
    "utm_campaign": "summer_sale"
  }'

תגובה:

{
    "topics": [
        {
            "id": "product_information",
            "name": "Product Information",
            "relevance_score": 85
        },
        {
            "id": "size_fit",
            "name": "Size & Fit",
            "relevance_score": 80
        }
    ],
    "context": {
        "page_type": "product",
        "product_id": 123
    }
}

6. נקודות קצה של RAG

נקודות קצה של RAG (Retrieval-Augmented Generation) מנהלות אינדוקס מוצרים לחיפוש סמנטי.

GET /rag/status

קבלת סטטוס אינדוקס נוכחי.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/rag/status" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "isIndexing": false,
    "totalProducts": 1250,
    "indexedProducts": 1200,
    "vectorCount": 1200,
    "lastIndexedAt": "2024-01-15T14:30:00Z",
    "status": "completed",
    "storageBackend": "supabase"
}

POST /rag/index

התחלה או עצירה של אינדוקס מוצרים.

# Start indexing
curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/index" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{ "action": "start" }'

# Stop indexing
curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/index" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{ "action": "stop" }'

DELETE /rag/index

ניקוי כל המוצרים המאונדקסים.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/rag/index" 
  -H "X-WP-Nonce: your_nonce_here"

POST /rag/index/product/{id}

אינדוקס מוצר בודד (שימושי לבדיקות).

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/index/product/123" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "success": true,
    "message": "Product "Premium Widget" indexed successfully.",
    "product": {
        "id": 123,
        "name": "Premium Widget"
    }
}

POST /rag/test-connection

בדיקת חיבור למסד נתונים וקטורי של Supabase.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/test-connection" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "supabaseUrl": "https://your-project.supabase.co",
    "supabaseApiKey": "your-api-key",
    "supabaseTableName": "product_embeddings"
  }'

תגובה (200 OK):

{
    "success": true,
    "message": "Connected successfully! Found 1200 embeddings.",
    "stats": {
        "total_embeddings": 1200,
        "newest_embedding": "2024-01-15T14:30:00Z"
    }
}

ניהול מוצרים מוחרגים

GET /rag/excluded-products

קבלת רשימת מוצרים מוחרגים מאינדוקס.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/rag/excluded-products" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

[123, 456, 789]

POST /rag/excluded-products

הוספת מוצרים לרשימת ההחרגה.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/rag/excluded-products" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{ "product_ids": [123, 456] }'

DELETE /rag/excluded-products/{id}

הסרת מוצר מרשימת ההחרגה.

curl -X DELETE "https://your-site.com/wp-json/woo-ai/v1/rag/excluded-products/123" 
  -H "X-WP-Nonce: your_nonce_here"

7. נקודות קצה של רישיון

נקודות קצה של ניהול רישיון דורשות יכולת manage_options.

GET /license

קבלת סטטוס רישיון נוכחי.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/license" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "is_valid": true,
    "license_key": "XXXX-XXXX-XXXX-XXXX",
    "plan": "professional",
    "expires_at": "2025-01-15T00:00:00Z",
    "features": {
        "max_sessions": 10000,
        "ai_provider": "openai",
        "vector_search": true
    }
}

POST /license/activate

הפעלת מפתח רישיון.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/license/activate" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{ "license_key": "XXXX-XXXX-XXXX-XXXX" }'

תגובה (200 OK):

{
    "success": true,
    "message": "License activated successfully.",
    "data": { ... }
}

תגובת שגיאה (400):

{
    "code": "invalid_license",
    "message": "The license key is invalid or has expired.",
    "data": { "status": 400 }
}

POST /license/deactivate

ביטול הרישיון הנוכחי.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/license/deactivate" 
  -H "X-WP-Nonce: your_nonce_here"

POST /license/validate

אילוץ אימות מחדש של הרישיון הנוכחי.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/license/validate" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "success": true,
    "is_valid": true,
    "data": { ... }
}

8. נקודות קצה של מבצעים

ניהול מבצעי מוצרים לנראות מוגברת בתגובות צ’אט.

GET /promotions

רשימת כל המבצעים.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/promotions?active=true" 
  -H "X-WP-Nonce: your_nonce_here"

POST /promotions

יצירת מבצע חדש.

curl -X POST "https://your-site.com/wp-json/woo-ai/v1/promotions" 
  -H "Content-Type: application/json" 
  -H "X-WP-Nonce: your_nonce_here" 
  -d '{
    "name": "Summer Sale",
    "type": "manual",
    "product_ids": [123, 456, 789],
    "boost_multiplier": 2.0,
    "active": true,
    "valid_from": "2024-06-01T00:00:00Z",
    "valid_to": "2024-08-31T23:59:59Z"
  }'

GET /promotions/products

קבלת כל מזהי המוצרים המקודמים (בשימוש על ידי מערכת RAG).

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/promotions/products" 
  -H "X-WP-Nonce: your_nonce_here"

תגובה:

{
    "product_ids": [123, 456, 789, 1011],
    "count": 4
}

נקודות קצה שירות

GET /products/search

חיפוש מוצרי WooCommerce.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/products/search?search=hiking&category=outdoor&per_page=20" 
  -H "X-WP-Nonce: your_nonce_here"

GET /categories

קבלת כל קטגוריות המוצרים.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/categories" 
  -H "X-WP-Nonce: your_nonce_here"

GET /tags

קבלת כל תגיות המוצרים.

curl -X GET "https://your-site.com/wp-json/woo-ai/v1/tags" 
  -H "X-WP-Nonce: your_nonce_here"

9. טיפול בשגיאות

פורמט תגובת שגיאה

כל תגובות השגיאה עוקבות אחר פורמט סטנדרטי של WordPress REST API:

{
    "code": "error_code",
    "message": "Human-readable error message",
    "data": {
        "status": 400
    }
}

קודי שגיאה נפוצים

סטטוס HTTP	קוד	תיאור
400	`invalid_data`	אימות בקשה נכשל
400	`invalid_date_range`	טווח תאריכים חורג משנה או from > to
400	`already_indexing`	אינדוקס RAG כבר מתבצע
400	`exists`	משאב כבר קיים (למשל slug נושא כפול)
403	`missing_nonce`	כותרת X-WP-Nonce לא סופקה
403	`invalid_nonce`	אימות nonce נכשל
403	`rest_forbidden`	למשתמש חסרה היכולת הנדרשת
404	`not_found`	משאב לא נמצא
404	`invalid_session`	Session צ’אט פג תוקף או לא תקף
404	`product_not_found`	מוצר WooCommerce לא נמצא
429	`rate_limit_exceeded`	יותר מדי בקשות
500	`server_error`	שגיאת שרת פנימית
500	`message_processing_failed`	שגיאת ספק AI
500	`clear_failed`	נכשל בניקוי אינדקס RAG

טיפול בשגיאות ב-JavaScript

async function sendMessage(sessionId, message) {
    try {
        const response = await fetch('/wp-json/woo-ai/v1/chat/message', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-WP-Nonce': wooAiChatbot.nonce
            },
            body: JSON.stringify({ session_id: sessionId, message })
        });

        if (!response.ok) {
            const error = await response.json();

            switch (error.code) {
                case 'rate_limit_exceeded':
                    // Show rate limit message, retry after delay
                    await delay(5000);
                    return sendMessage(sessionId, message);

                case 'invalid_session':
                    // Create new session and retry
                    const newSession = await createSession();
                    return sendMessage(newSession.session_id, message);

                default:
                    throw new Error(error.message);
            }
        }

        return await response.json();
    } catch (err) {
        console.error('Chat API error:', err);
        throw err;
    }
}

10. ניהול גרסאות והוצאה משימוש

היסטוריית גרסאות API

גרסה	סטטוס	הערות
`woo-ai/v1`	פעיל	Namespace ראשי נוכחי
`woo-ai-chatbot/v1`	מיושן	תמיכה לאחור, יוסר בגרסה 2.0

מדיניות הוצאה משימוש

נקודות קצה שהוצאו משימוש ממשיכות לעבוד לפחות 2 גרסאות מרכזיות
אזהרות הוצאה משימוש נרשמות במצב WP_DEBUG
מדריכי מיגרציה מסופקים בהערות גרסה

מיגרציה מומלצת

החליפו את ה-namespace הישן באינטגרציות שלכם:

// Before (deprecated)
fetch('/wp-json/woo-ai-chatbot/v1/chat/message', { ... });

// After (current)
fetch('/wp-json/woo-ai/v1/chat/message', { ... });

נספח: עזר מהיר

סיכום נקודות קצה של צ’אט

שיטה	נקודת קצה	תיאור
POST	`/chat/message`	שליחת הודעה
GET	`/chat/session`	קבלת session
POST	`/chat/session`	יצירת session
DELETE	`/chat/session/{id}`	סיום session
POST	`/chat/events`	מעקב אירוע
POST	`/cart/add`	הוספה לעגלה
GET	`/cart`	קבלת עגלה
DELETE	`/cart`	ניקוי עגלה
DELETE	`/cart/item/{key}`	הסרת פריט
PUT	`/cart/item/{key}`	עדכון כמות
POST	`/cart/coupon`	הפעלת קופון
POST	`/cart/checkout`	קבלת כתובת checkout

סיכום נקודות קצה של אנליטיקה

שיטה	נקודת קצה	תיאור
GET	`/analytics`	לוח מחוונים מלא
GET	`/analytics/summary`	KPIs בלבד
GET	`/analytics/topics`	מדדי נושאים
GET	`/analytics/products`	מדדי מוצרים
GET	`/analytics/funnel`	משפך המרה
GET	`/analytics/hourly`	התפלגות שעתית
GET	`/analytics/queries`	שאילתות מובילות
GET	`/analytics/comparison`	שבוע מול שבוע
GET	`/analytics/export`	יצוא CSV
POST	`/analytics/cache/clear`	ניקוי מטמון

סיכום נקודות קצה של משאבי מנהל

משאב	פעולות CRUD
Playbooks	GET, POST, PUT, DELETE + duplicate, toggle
Topics	GET, POST, PUT, DELETE + toggle
Promotions	GET, POST, PUT, DELETE + toggle
RAG	status, index, test-connection, excluded-products
License	status, activate, deactivate, validate

מדריך REST API

מדריך REST API

1. סקירת API

מבנה כתובת בסיס

Namespaces

אימות

הגבלת קצב בקשות

דרישות הרשאות

2. נקודות קצה של צ’אט

POST /chat/message

GET /chat/session

POST /chat/session

DELETE /chat/session/{id}

POST /chat/events

פעולות עגלה

POST /cart/add

GET /cart

DELETE /cart

DELETE /cart/item/{key}

PUT /cart/item/{key}

POST /cart/coupon

POST /cart/checkout

3. נקודות קצה של אנליטיקה

GET /analytics

GET /analytics/summary

GET /analytics/topics

GET /analytics/products

GET /analytics/funnel

GET /analytics/hourly

GET /analytics/queries

GET /analytics/comparison

GET /analytics/export

POST /analytics/events

POST /analytics/cache/clear

4. נקודות קצה של Playbooks

GET /playbooks

POST /playbooks

GET /playbooks/{id}

PUT /playbooks/{id}

DELETE /playbooks/{id}

POST /playbooks/{id}/duplicate

POST /playbooks/{id}/toggle

5. נקודות קצה של נושאים (Topics)

נקודות קצה של מנהל (דורשות manage_woocommerce)

GET /topics

POST /topics

PUT /topics/{id}

DELETE /topics/{id}

POST /topics/{id}/toggle

נקודות קצה ציבוריות (ללא אימות)

GET /public/topics

POST /public/topics/contextual

6. נקודות קצה של RAG

GET /rag/status

POST /rag/index

DELETE /rag/index

POST /rag/index/product/{id}

POST /rag/test-connection

ניהול מוצרים מוחרגים

GET /rag/excluded-products

POST /rag/excluded-products

DELETE /rag/excluded-products/{id}

7. נקודות קצה של רישיון

GET /license

POST /license/activate

POST /license/deactivate

POST /license/validate

8. נקודות קצה של מבצעים

GET /promotions

POST /promotions

GET /promotions/products

נקודות קצה שירות

GET /products/search

GET /categories

GET /tags

9. טיפול בשגיאות

פורמט תגובת שגיאה

קודי שגיאה נפוצים

טיפול בשגיאות ב-JavaScript

10. ניהול גרסאות והוצאה משימוש

נקודות קצה של מנהל (דורשות `manage_woocommerce`)