יצירה, עדכון ומחיקה

מבנה הבקשות

כתובת הבסיס: https://api.godaily.co.il/v1.

כל בקשה משתמשת ב־Authorization: Bearer $DAILY_API_KEY. בקשות עם גוף משתמשות ב־Content-Type: application/json. השדות משתמשים ב־snake_case, כולל אובייקטים מקוננים. שדות שאינם בחוזה נדחים ב־400 invalid_body; אין לשלוח business_id, בעלים או שדות מערכת. העסק נגזר מהמפתח המאומת בלבד.

כל השדות

הרפרנס המלא כולל סכמות בקשה שנוצרות מתוך ה־DTOs של המערכת: שדות חובה, סוגים, ערכים אפשריים, אילוצים, אובייקטים מקוננים ומערכים. אין צורך להסתפק בשדות שבדוגמאות.

במשאבים הוותיקים, GET /customers/{id}/details, GET /suppliers/{id}/details, GET /leads/{id}/details, GET /products/{id}/details, GET /tasks/{id}/details ו־GET /documents/{id}/details מחזירים את הפרטים המורחבים. נתיבי הקריאה הקיימים נשמרו לתאימות. בהוצאות, טיוטות, תגיות, קטגוריות וחומרי גלם נתיב GET /{resource}/{id} מחזיר פרטים מלאים.

השדה draft_data הוא אובייקט חופשי: המפתחות שבתוכו נשמרים כפי שנשלחו. הוא אינו קובע הרשאות או שיוך עסקי.

סוגי ערכים

• סכומים בפעולות הכתיבה ובתגובות הפרטים המורחבים הם מחרוזות עשרוניות ביחידות המטבע הראשיות: "125.50".
• שדות ותיקים שמסתיימים ב־_minor נשארו מספרים שלמים ביחידות המשנה. אין להעביר את הערך שלהם ישירות לשדה מחיר בכתיבה.
• כמויות מלאי הן מחרוזות עם עד שלוש ספרות אחרי הנקודה.
• ערכי enum בבקשות ובפרטים המורחבים הם בדיוק הערכים שבסכמה, לרוב באותיות גדולות. סטטוס משימה הוא פתוח, בוצע או מבוטל; הקריאה הוותיקה ממשיכה להחזיר סטטוס ציבורי באנגלית.
• בעדכון, שדה שלא נשלח נשאר ללא שינוי. null מותר רק כשהסכמה מציינת זאת במפורש. מערכים שנשלחו מחליפים את האוסף בהתאם לכללי הישות; [] מנקה אוסף שניתן לעריכה.
• מזהים, תאריכי יצירה, יתרות מחושבות, מספרי מסמכים ונתוני ביקורת מנוהלים בשרת. סודות, אסימוני סליקה ופרטי אחסון פנימיים אינם חלק מהתגובה הציבורית.

דוגמה: מחזור חיים של לקוח

המפתח צריך הרשאות customers:write וגם customers:read.

const apiKey = process.env.DAILY_API_KEY;
if (!apiKey) throw new Error('חסר מפתח API');
const base = 'https://api.godaily.co.il/v1';
async function request(path: string, method = 'GET', data?: unknown) {
  const response = await fetch(`${base}${path}`, {
    method,
    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
    body: data === undefined ? undefined : JSON.stringify(data),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${result.error?.code}; ${result.request_id}`);
  return result.data;
}
const customer = await request('/customers', 'POST', {
  name: 'לקוח אינטגרציה',
  contact_person: 'צוות הרכש',
  currency: 'ILS',
  notes: 'נוצר באמצעות האינטגרציה',
  address: { city: 'תל אביב', country_code: 'IL' },
});
await request(`/customers/${customer.id}`, 'PATCH', { notes: 'פרטי הלקוח עודכנו' });
const details = await request(`/customers/${customer.id}/details`);
if (details.notes !== 'פרטי הלקוח עודכנו') throw new Error('העדכון לא הוחזר');
await request(`/customers/${customer.id}`, 'DELETE');
await request(`/customers/${customer.id}/restore`, 'POST');

הרשאות של פעולה משולבת

הרשאת :write אינה מעניקה :read אוטומטית, ומפתחות קיימים אינם מקבלים הרשאות חדשות אוטומטית.

• שינוי שדות מלאי או מתכון דרך מוצר או חומר גלם דורש גם inventory:write.
• יצירת מוצר חדש מתוך שורת מסמך דורשת גם products:write.
• יצירת משימה עם מסמך דורשת גם tasks:write.
• שמירת ברירות מחדל אצל הלקוח מתוך מסמך דורשת גם customers:write.
• החלת תנועת מלאי דרך מסמך דורשת גם inventory:write.
• המרת ליד ללקוח דורשת leads:write וגם customers:write.

בנוסף להרשאות המפתח, חלים המנוי, הגדרות העסק והוולידציה של השירות העסקי.

מניעת כפילויות ועריכה במקביל

יצירת מסמך מחייבת client_request_id מסוג UUID. ניסיון חוזר של אותה יצירה צריך להשתמש באותו מזהה; אין למחזר אותו למסמך אחר.

בכל פעולות הכתיבה בהוצאות, קטגוריות ותשלומי הוצאות נדרשת כותרת Idempotency-Key באורך 16–100 תווים: אותיות באנגלית, ספרות, מקף או קו תחתון. המפתח תחום לעסק, למפתח ה־API ולפעולה. שליחה חוזרת עם אותו מפתח ואותו גוף מחזירה את התוצאה שנשמרה; גוף אחר מחזיר 409. ביצירת פעולה חדשה יש לבחור מזהה חדש.

עריכת הוצאה, אישור, ביטול ומחיקה מחייבים expected_revision שנשלף מהרשומה. גם הקצאות תשלום וקטגוריות משתמשות בשדות גרסה כמפורט בסכמה. ב־409 יש לשלוף שוב ולבדוק את השינוי לפני שליחה חוזרת.

בשאר פעולות היצירה אין מנגנון כללי של Idempotency-Key. לאחר ניתוק רשת יש לאתר את הרשומה לפני שמנסים ליצור אותה שוב. אין להחיל באופן עיוור את מדיניות הניסיונות החוזרים של GET על POST.

מחיקה ומסמכים סופיים

מחיקה פועלת לפי כללי הישות: לקוחות, ספקים, מוצרים, תגיות ומשימות משתמשים במחיקה לוגית; ליד שלא הומר ללקוח נמחק עם פעילויותיו ותחומי העניין שלו, בעוד המשימות נשמרות והקישור לליד מתנתק. ליד שהומר ללקוח אינו ניתן למחיקה.

מסמך שהופק, תשלום רשום ותנועת מלאי שמקושרת למסמך הם רישומים חשבונאיים. תיקון נעשה במסמך מקושר, בזיכוי או בפעולת ביטול מתאימה. טיוטות ניתנות לעריכה ולמחיקה. עדכון מסמך שהופק מאפשר את הערת הטיפול בלבד; הוא אינו משנה את סכומי המסמך.