מדריך REST API

מדריך 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 – קבלת נושאים מסוננים לפי הקשר

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

  1. 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: '...' }) });

  2. Cookie Authentication (משתמשי WordPress מחוברים):
    אוטומטי כאשר מבצעים בקשות מאותו דומיין עם cookies תקפים של WordPress.

  3. 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

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

# התחלת אינדוקס
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" }'

# עצירת אינדוקס
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 הישן באינטגרציות שלכם:

// לפני (מיושן)
fetch('/wp-json/woo-ai-chatbot/v1/chat/message', { ... });

// אחרי (נוכחי)
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