📦 מדריך API – הוספה ועדכון פריטים (Items)

Base URL:

https://app.example.com

כל הבקשות הן מסוג:

POST
Content-Type: application/json; charset=UTF-8

---

🔐 אימות (Authentication)

יש להעביר api_key באחת מהדרכים:

אפשרות 1 – Header

api_key: YOUR_API_KEY

אפשרות 2 – בתוך ה-JSON

{
  "api_key": "YOUR_API_KEY"
}

---

📌 Endpoints זמינים

פעולה	Endpoint
הוספת פריט חדש	/api/items/addItem
עדכון פריט קיים	/api/items/updateItem
הוספה או עדכון	/api/items/addOrUpdateItem

---

➕ הוספת פריט חדש

Endpoint:

POST /api/items/addItem

שדות חובה

שדה	סוג	תיאור
name	string	שם הפריט
amount	number	מחיר הפריט
test	0 או 1	מצב בדיקה (1 = לא נשמר בפועל)

שדות אופציונליים

שדה	סוג	תיאור
item_no	string	מק"ט
description	string	תיאור
currency_id	integer	מזהה מטבע (ברירת מחדל: מטבע החברה)
vat_included_yn	0 או 1	האם המחיר כולל מע"מ
no_vat_yn	0 או 1	פטור ממע"מ
external_item_id	string	מזהה חיצוני
inventory_management_yn	0 או 1	ניהול מלאי
inventory_count	number	כמות במלאי
archive_yn	0 או 1	פריט בארכיון

⚠ חשוב: שדות בוליאניים מקבלים רק 0 או 1 (לא true/false).

דוגמת בקשה

{
  "api_key": "YOUR_API_KEY",
  "test": 0,
  "name": "חבילת ייעוץ",
  "item_no": "CONSULT-001",
  "description": "חבילת ייעוץ חודשית",
  "amount": 500.00,
  "vat_included_yn": 1
}

---

✏️ עדכון פריט קיים

Endpoint:

POST /api/items/updateItem

זיהוי הפריט לעדכון (לפי סדר עדיפות)

1. id – GUID שהוחזר בזמן היצירה
2. item_no – מק"ט
3. external_item_id – מזהה חיצוני

יש לשלוח לפחות אחד מהם.

בעדכון: רק השדות שנשלחים יתעדכנו. שדות שלא נשלחו יישארו ללא שינוי.

דוגמת בקשה

{
  "api_key": "YOUR_API_KEY",
  "test": 0,
  "item_no": "CONSULT-001",
  "amount": 600.00
}

---

🔄 הוספה או עדכון (Upsert)

POST /api/items/addOrUpdateItem

אם הפריט קיים → יתבצע עדכון
אם אינו קיים → ייווצר פריט חדש

---

🧪 מצב בדיקה (test)

ערך	התנהגות
0	שמירה רגילה
1	בדיקה בלבד – הנתון לא נשמר בפועל

---

✅ תגובה מוצלחת

{
  "status_code": "0",
  "status_description": "OK",
  "id": "guid-של-הפריט",
  "item_id": 123
}

---

❌ תגובת שגיאה

{
  "status_code": "3",
  "status_description": "הודעת שגיאה"
}

---

📎 דוגמת curl

curl -X POST https://app.example.com/api/items/addItem \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "test": 0,
    "name": "חבילת ייעוץ",
    "amount": 500.00
  }'