# Priority Community Node - מדריך שימוש ודוגמאות

## תוכן עניינים
1. [הקדמה](#הקדמה)
2. [התקנה והגדרה](#התקנה-והגדרה)
3. [אימות (Authentication)](#אימות-authentication)
4. [משאבים זמינים](#משאבים-זמינים)
5. [דוגמאות שימוש מפורטות](#דוגמאות-שימוש-מפורטות)
6. [טיפים וטריקים](#טיפים-וטריקים)
7. [פתרון בעיות](#פתרון-בעיות)

## הקדמה

הנוד הקומיוניטי של Priority מאפשר אינטגרציה מלאה עם מערכת Priority באמצעות REST API מבוסס OData. הנוד תומך בכל הפונקציונליות של Priority כולל CRUD operations, שאילתות מתקדמות, קבצים מצורפים, טקסט, batch operations ועוד.

### תכונות עיקריות:
- ✅ **אימות מלא**: Basic, PAT, OAuth2
- ✅ **פעולות CRUD**: יצירה, קריאה, עדכון, מחיקה
- ✅ **שאילתות מתקדמות**: $filter, $orderby, $select, $expand, $since
- ✅ **קבצים מצורפים**: העלאה והורדה עם תמיכה ב-Data URI
- ✅ **טקסט**: תמיכה ב-HTML עם חתימה
- ✅ **Batch Operations**: פעולות מרובות עם תלויות
- ✅ **Webhooks**: התראות אירועים
- ✅ **Metadata**: מידע על המערכת והגרסאות

## התקנה והגדרה

### 1. התקנת הנוד
```bash
npm install n8n-nodes-priority
```

### 2. הגדרת Credentials

#### Basic Authentication
```
Service Root URL: https://your-priority-server.com/odata/Priority/tabula.ini/your-company
Authentication: Basic
Username: your-username
Password: your-password
Application ID: (אופציונלי)
Application Key: (אופציונלי)
Language Code: 3 (US English)
```

#### Personal Access Token (PAT)
```
Service Root URL: https://your-priority-server.com/odata/Priority/tabula.ini/your-company
Authentication: Personal Access Token (PAT)
Access Token: your-pat-token
Application ID: (אופציונלי)
Application Key: (אופציונלי)
Language Code: 3 (US English)
```

#### OAuth2
```
Service Root URL: https://your-priority-server.com/odata/Priority/tabula.ini/your-company
Authentication: OAuth2
Client ID: your-client-id
Client Secret: your-client-secret
Auth URL: https://your-priority-server.com/accounts/connect/authorize
Access Token URL: https://your-priority-server.com/accounts/connect/token
Scope: openid rest_api
```

## משאבים זמינים

### 1. Entity - פעולות על ישויות
- **Get**: קבלת ישות בודדת
- **Get Many**: קבלת רשימת ישויות עם שאילתות
- **Create**: יצירת ישות חדשה
- **Update**: עדכון ישות קיימת
- **Delete**: מחיקת ישות
- **Get Attachment**: קבלת קבצים מצורפים
- **Upload Attachment**: העלאת קבצים מצורפים

### 2. Metadata - מידע על המערכת
- **Get Service Root**: קבלת רשימת ישויות זמינות
- **Get Metadata**: קבלת metadata מלא של המערכת
- **Get Entity Metadata**: קבלת metadata של ישות ספציפית (v23.0+)
- **Get Priority Version**: קבלת גרסת Priority
- **Get OData Version**: קבלת גרסת OData
- **Refresh Metadata**: רענון metadata (v22.0+)

### 3. Text - פעולות טקסט
- **Get Text**: קבלת תוכן טקסט
- **Set Text**: הגדרת תוכן טקסט (תמיכה ב-HTML)

### 4. Attachment - קבצים מצורפים
- **Get Attachments**: קבלת רשימת קבצים מצורפים
- **Upload Attachment**: העלאת קובץ חדש
- **Download Attachment**: הורדת קובץ ספציפי

### 5. Batch - פעולות מרובות
- **Execute Batch**: ביצוע מספר פעולות יחד

### 6. Webhook - התראות אירועים
- **Subscribe**: הרשמה לאירועים
- **Unsubscribe**: ביטול הרשמה
- **List Subscriptions**: רשימת הרשמות פעילות

## דוגמאות שימוש מפורטות

### דוגמה 1: קבלת רשימת לקוחות

**Resource**: Entity  
**Operation**: Get Many  
**Collection**: CUSTOMERS  
**Query Options**:
```json
{
  "$select": "CUSTNAME,CUSTDES,EMAIL,PHONE",
  "$filter": "CUSTNAME ne 'T000001'",
  "$orderby": "CUSTNAME asc",
  "$top": 50
}
```

**תוצאה**:
```json
{
  "@odata.context": "serviceRoot/$metadata#CUSTOMERS",
  "value": [
    {
      "CUSTNAME": "C000001",
      "CUSTDES": "Acme Corporation",
      "EMAIL": "contact@acme.com",
      "PHONE": "+1-555-0123"
    }
  ]
}
```

### דוגמה 2: יצירת הזמנה חדשה עם פריטים

**Resource**: Entity  
**Operation**: Create  
**Collection**: ORDERS  
**JSON Body**:
```json
{
  "CUSTNAME": "C000001",
  "ORDERITEMS_SUBFORM": [
    {
      "PARTNAME": "P001",
      "TQUANT": 5,
      "DUEDATE": "2024-12-31T00:00:00+02:00"
    },
    {
      "PARTNAME": "P002", 
      "TQUANT": 3,
      "DUEDATE": "2024-12-31T00:00:00+02:00"
    }
  ]
}
```

### דוגמה 3: שאילתה מתקדמת עם סינון תאריכים

**Resource**: Entity  
**Operation**: Get Many  
**Collection**: ORDERS  
**Query Options**:
```json
{
  "$filter": "CURDATE ge 2024-01-01T00:00:00+02:00 and TOTPRICE gt 1000",
  "$expand": "ORDERITEMS_SUBFORM($select=PARTNAME,TQUANT,PRICE)",
  "$select": "ORDNAME,CUSTNAME,CURDATE,TOTPRICE",
  "$orderby": "CURDATE desc",
  "$top": 20
}
```

### דוגמה 4: שימוש ב-$since לסנכרון אינקרמנטלי

**Resource**: Entity  
**Operation**: Get Many  
**Collection**: ORDERS  
**Query Options**:
```json
{
  "$since": "2024-01-15T06:00:00Z",
  "$select": "ORDNAME,CUSTNAME,CURDATE",
  "$expand": "ORDERITEMS_SUBFORM($select=PARTNAME,TQUANT)"
}
```
מומלץ להשתמש ב-UTC (`Z`) עבור `$since` כדי להימנע מפערי סנכרון בזמן שינויי שעון קיץ.

### דוגמה 5: העלאת קובץ מצורף

**Resource**: Attachment  
**Operation**: Upload Attachment  
**Collection**: ORDERS  
**Entity ID**: SO200001  
**Attachment Subform**: EXTFILES_SUBFORM  
**File Description**: "Contract Document"  
**File Data**: "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDtsO..."  
**File Extension**: ".pdf"

### דוגמה 6: הוספת טקסט עם HTML

**Resource**: Text  
**Operation**: Set Text  
**Collection**: ORDERS  
**Entity ID**: SO200001  
**Text Field**: ORDERSTEXT_SUBFORM  
**Text Content**: "<p>הזמנה חשובה</p><p><strong>הערה:</strong> יש לטפל בהזמנה זו בהקדם</p>"  
**Append Mode**: true  
**Include Signature**: false

### דוגמה 7: Batch Operations - פעולות מרובות

**Resource**: Batch  
**Operation**: Execute Batch  
**Batch Operations**:
```json
[
  {
    "id": "1",
    "method": "POST",
    "url": "ORDERS",
    "body": {
      "CUSTNAME": "C000001"
    }
  },
  {
    "id": "2",
    "method": "POST", 
    "url": "$1/ORDERITEMS_SUBFORM",
    "dependsOn": ["1"],
    "body": {
      "PARTNAME": "P001",
      "TQUANT": 10
    }
  },
  {
    "id": "3",
    "method": "POST",
    "url": "$1/ORDERITEMS_SUBFORM", 
    "dependsOn": ["1"],
    "body": {
      "PARTNAME": "P002",
      "TQUANT": 5
    }
  }
]
```

### דוגמה 8: קבלת מידע על המערכת

**Resource**: Metadata  
**Operation**: Get Priority Version  

**תוצאה**:
```json
{
  "@odata.context": "serviceRoot/$metadata#Edm.String",
  "value": "22.0-20.0.0.119"
}
```

### דוגמה 9: Webhook - הרשמה לאירועים

**Resource**: Webhook  
**Operation**: Subscribe  
**Webhook URL**: "https://your-app.com/webhook"  
**Events**: ["created", "updated", "deleted"]  
**Entity Types**: "CUSTOMERS,ORDERS"

### דוגמה 10: שאילתה עם Composite Keys

**Resource**: Entity  
**Operation**: Get  
**Collection**: AINVOICES  
**Entity ID**: "IVNUM='T9696',IVTYPE='A',DEBIT='D'"

## טיפים וטריקים

### 1. ביצועים אופטימליים
```json
// ❌ רע - מקבל את כל השדות
{
  "Collection": "CUSTOMERS"
}

// ✅ טוב - מקבל רק שדות נדרשים
{
  "Collection": "CUSTOMERS",
  "Query Options": {
    "$select": "CUSTNAME,CUSTDES,EMAIL"
  }
}
```

### 2. שימוש ב-$expand חכם
```json
// ❌ רע - expand עמוק מדי
{
  "$expand": "ORDERITEMS_SUBFORM($expand=DEEP_SUBFORM($expand=DEEPER_SUBFORM))"
}

// ✅ טוב - expand של 2-3 רמות בלבד
{
  "$expand": "ORDERITEMS_SUBFORM($select=PARTNAME,TQUANT,PRICE)"
}
```

### 3. סינון תאריכים נכון
```json
// ❌ רע - פורמט תאריך לא נכון
{
  "$filter": "CURDATE ge 2024-01-01"
}

// ✅ טוב - פורמט ISO עם timezone
{
  "$filter": "CURDATE ge 2024-01-01T00:00:00+02:00"
}
```

### 4. שימוש ב-$since לסנכרון
```json
// במקום לקבל את כל הנתונים כל פעם
{
  "Collection": "ORDERS"
}

// השתמש ב-$since לקבלת שינויים בלבד
{
  "Collection": "ORDERS",
  "Query Options": {
    "$since": "2024-01-15T06:00:00Z"
  }
}
```

### 5. Batch Operations לפעולות מרובות
```json
// במקום 3 בקשות נפרדות
// POST /ORDERS
// POST /ORDERS('SO001')/ORDERITEMS_SUBFORM
// POST /ORDERS('SO001')/ORDERITEMS_SUBFORM

// השתמש ב-Batch Operation אחת
{
  "requests": [
    {"id": "1", "method": "POST", "url": "ORDERS", "body": {...}},
    {"id": "2", "method": "POST", "url": "$1/ORDERITEMS_SUBFORM", "dependsOn": ["1"], "body": {...}},
    {"id": "3", "method": "POST", "url": "$1/ORDERITEMS_SUBFORM", "dependsOn": ["1"], "body": {...}}
  ]
}
```

## פתרון בעיות

### שגיאות נפוצות

#### 1. שגיאת אימות (401)
```
Error: Unauthorized
```
**פתרון**: בדוק את ה-Credentials והגדרות האימות

#### 2. ישות לא נמצאה (404)
```
Error: Not Found
```
**פתרון**: ודא שה-Entity ID נכון ושהקולקציה קיימת

#### 3. שגיאת validation (400)
```
Error: Bad Request
```
**פתרון**: בדוק את ה-JSON Body והפרמטרים הנדרשים

#### 4. שגיאת הרשאות (403)
```
Error: Forbidden
```
**פתרון**: בדוק הרשאות המשתמש במערכת Priority

### דיבוג

#### 1. בדיקת חיבור
```json
{
  "Resource": "Metadata",
  "Operation": "Get Service Root"
}
```

#### 2. בדיקת גרסה
```json
{
  "Resource": "Metadata", 
  "Operation": "Get Priority Version"
}
```

#### 3. בדיקת metadata
```json
{
  "Resource": "Metadata",
  "Operation": "Get Entity Metadata",
  "Entity Name": "CUSTOMERS"
}
```

### לוגים וניטור

1. **הפעל לוגים מפורטים** ב-n8n
2. **בדוק את ה-Response** לכל בקשה
3. **השתמש ב-Error Handling** nodes
4. **מעקב אחר ביצועים** עם $top ו-$skip

## דוגמאות מתקדמות

### דוגמה 1: סנכרון לקוחות עם CRM חיצוני
```json
{
  "Resource": "Entity",
  "Operation": "Get Many", 
  "Collection": "CUSTOMERS",
  "Query Options": {
    "$since": "2024-01-01T00:00:00Z",
    "$select": "CUSTNAME,CUSTDES,EMAIL,PHONE,ADDRESS",
    "$expand": "CUSTNOTESA_SUBFORM($select=NOTE,CURDATE)",
    "$orderby": "CUSTNAME"
  }
}
```

### דוגמה 2: דוח מכירות יומי
```json
{
  "Resource": "Entity",
  "Operation": "Get Many",
  "Collection": "ORDERS", 
  "Query Options": {
    "$filter": "CURDATE ge 2024-01-15T00:00:00+02:00 and CURDATE le 2024-01-15T23:59:59+02:00",
    "$select": "ORDNAME,CUSTNAME,CURDATE,TOTPRICE,ORDSTATUSDES",
    "$expand": "ORDERITEMS_SUBFORM($select=PARTNAME,TQUANT,PRICE)",
    "$orderby": "CURDATE desc"
  }
}
```

### דוגמה 3: בדיקת מלאי נמוך
```json
{
  "Resource": "Entity",
  "Operation": "Get Many",
  "Collection": "LOGPART",
  "Query Options": {
    "$filter": "ONHAND lt 10 and TYPE eq 'P'",
    "$select": "PARTNAME,PARTDES,ONHAND,MINBAL,LASTPRICE",
    "$orderby": "ONHAND asc",
    "$top": 50
  }
}
```

### דוגמה 4: יצירת הזמנה מורכבת
```json
{
  "Resource": "Batch",
  "Operation": "Execute Batch",
  "Batch Operations": [
    {
      "id": "1",
      "method": "POST",
      "url": "ORDERS",
      "body": {
        "CUSTNAME": "C000001",
        "CURDATE": "2024-01-15T00:00:00+02:00"
      }
    },
    {
      "id": "2", 
      "method": "POST",
      "url": "$1/ORDERITEMS_SUBFORM",
      "dependsOn": ["1"],
      "body": {
        "PARTNAME": "P001",
        "TQUANT": 10,
        "DUEDATE": "2024-02-01T00:00:00+02:00"
      }
    },
    {
      "id": "3",
      "method": "POST", 
      "url": "$1/ORDERSTEXT_SUBFORM",
      "dependsOn": ["1"],
      "body": {
        "TEXT": "<p>הזמנה מיוחדת - יש לטפל בהקדם</p>",
        "APPEND": false,
        "SIGNATURE": true
      }
    }
  ]
}
```

## סיכום

הנוד הקומיוניטי של Priority מספק גישה מלאה ומקיפה לכל הפונקציונליות של מערכת Priority. עם תמיכה בכל סוגי האימות, פעולות CRUD מתקדמות, שאילתות OData מלאות, ופונקציות מתקדמות כמו batch operations ו-webhooks, הנוד מאפשר אינטגרציה חלקה ויעילה עם מערכות Priority.

### קישורים שימושיים:
- **npm Package**: https://www.npmjs.com/package/n8n-nodes-priority
- **GitHub Repository**: https://github.com/HirezRa/n8n-nodes-priority
- **Priority REST API Documentation**: https://prioritysoftware.github.io/restapi/
- **n8n Documentation**: https://docs.n8n.io/

---

*נוצר עבור n8n-nodes-priority v0.3.1*