דרישות Tec.Delivery לשכבת ייצוג הנתונים (REST API) של מערכת הניהול לצורך קבלת נתוני SCU

מסמך זה מתאר את הדרישות המינימליות לשכבת ייצוג הנתונים (להלן: API) של מערכת הניהול לצורך קבלת נתוני מוצרים באמצעות תוסף הסנכרון האוניברסלי של Tec.Delivery.

רעיון כללי

תוסף הסנכרון מקבל נתונים משכבת ייצוג הנתונים (להלן: API) של מערכת הניהול, לדוגמה 1C.

1. דרישות כלליות ל־API Endpoints

1.1 שיטות נתמכות

• GET /api/v1/get קבלת מוצרים וקטגוריות
  
• GET /api/v1/balance אופציונלי קבלת יתרות מלאי של מוצרים
  

הפרמטרים מועברים באמצעות Query String.

כתובות ה־URL המוצגות הן דוגמאות בלבד וניתן להחליפן בכל כתובת URL תקינה שתוגדר על ידי מפתח ה־API.

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

דוגמת בקשה:

/api/v1/get?type=product&modified_since=2026-02-01T00:00:00Z&limit=100&offset=0

פרמטרים נתמכים (סינון ודפדוף):

• type — category / product
• modified_since מורה ל־API להחזיר רשומות שזמן העדכון שלהן גדול או שווה לערך שצוין
• limit פרמטר דפדוף המגדיר את מספר הרשומות בכל אצווה
• offset פרמטר דפדוף המגדיר את ההיסט בתוצאות

3. שדות

כל אובייקט חייב להכיל את השדות הבאים:

4. לוגיקת יצירה, עדכון ומחיקה של מוצרים

```

• יצירה

  התוסף יוצר את כל המוצרים שהתקבלו ושמזהיהם אינם קיימים ב־Tec.Delivery.

• עדכון נתונים

  התוסף מעדכן את כל נתוני המוצר כאשר הערך של השדה modified_at משתנה.

• מחיקה

  אם מוצר נוצר בעבר ב־Tec.Delivery אך אינו מופיע בתגובה הנוכחית של ה־API, התוסף יסמן אותו כחסום והוא לא יוצג עוד בחנות.

```

5. עדכון תמונות

עדכניות תמונת המוצר מנוהלת באמצעות השדה image_hash. מומלץ להשתמש ב־Hash אמיתי של התמונה, אך ניתן להשתמש גם בשיטות אחרות לזיהוי שינויים, כגון תאריך עדכון התמונה או גרסת תמונה אחרת.

השדה image_hash מעובד באופן עצמאי מהשדה modified_at. לכן, לצורך עדכון תמונה בלבד, מספיק לשנות את ערך image_hash, ושאר נתוני המוצר יישארו ללא שינוי.

6. מבנה התגובה ודפדוף (חובה)

תגובת ה־API חייבת להיות אובייקט JSON תקין המכיל:

• data — מערך של מוצרים או קטגוריות
• total — מספר הרשומות הכולל התואם למסננים שהוגדרו, ללא התחשבות בדפדוף

ה־API חייב לתמוך בדפדוף ולקבל את הפרמטרים limit ו־offset.

דוגמת תגובה:

{
  "data": [
     {
      "id": "b01a1a32-8ba2-11e6-9cf3-10bf484d6226",
      "parent": "551b4ed9-c385-11e6-9cd7-10bf484d6226",
      "type": "product",
      "bulk": false,
      "name": "אורז ארוך מאודה Goodwill 800 גרם",
      "price": 145,
      "store_balance": 16,
      "modified_at": "2026-02-13T13:24:04",
      "description": "…",
      "image_url": "https://…/images/b01a1a32-8ba2-11e6-9cf3-10bf484d6226.jpg",
      "image_hash": "f9a15f0d6ebf943aea177f597cb96689c2d5c44d"
    },...
    ],
  "total": 15420
}

6. סנכרון מלאי (Endpoint אופציונלי)

אם החנות דורשת סנכרון תכוף של מלאי (לדוגמה, עקב היקף מכירות גבוה במצב סופרמרקט), מומלץ לממש Endpoint נפרד ופשוט יותר שמחזיר רק נתוני מלאי.

דוגמת בקשה:

/api/v1/balance?modified_since=2026-02-01T00:00:00Z&limit=100&offset=0

פרמטרים נתמכים:

• modified_since — מורה ל־API להחזיר רשומות שזמן עדכון המלאי שלהן גדול או שווה לערך שצוין
• limit — פרמטר דפדוף המגדיר את מספר הרשומות בכל אצווה
• offset — פרמטר דפדוף המגדיר את ההיסט בתוצאות

תגובה

{
  "data": [
     {
      "id": "b01a1a32-8ba2-11e6-9cf3-10bf484d6226",
      "store_balance": 16
    },...
    ],
  "total": 15420
}

7. מבנה היררכי (parent → child)

מודל קטלוג המוצרים הוא היררכי. עומק ההיררכיה המינימלי הוא 2 והמקסימלי הוא 3: