גיליונות עסקיים ישראליים עם GWS

שלב 1: אימות התקנה ואימות GWS CLI

לפני ביצוע פעולות בגיליונות Google, יש לוודא ש-Google Workspace CLI מותקן ומאומת.

# בדיקה האם gws מותקן
gws --version

# אם לא מותקן, התקנה גלובלית
npm install -g @google/gws

# אימות עם Google OAuth
gws auth login

# אימות סטטוס ההתחברות
gws auth status

אם המשתמש לא הגדיר פרויקט Google Cloud, יש להדריך אותו דרך gws auth setup ליצירת אישורי OAuth.

שלב 2: יצירת גיליון מעקב פיננסי חדש

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

מבנה הגיליון לפרילנסרים ישראליים:

קטגוריות ניכוי מס לעסקים ישראליים:

ליצירת הגיליון עם כותרות:

# יצירת גיליון חדש (מחזיר מזהה גיליון)
gws sheets create --title "Business Tracker 2026"

# הגדרת כותרות בשורה הראשונה
gws sheets append --spreadsheet-id SPREADSHEET_ID --range "Sheet1!A1:J1" \
  --values '[["Date","Description","Category","Amount (excl. VAT)","VAT (17%)","Total (incl. VAT)","Type","Invoice #","Payment Method","Notes"]]'

שלב 3: הוספת רשומות הכנסה והוצאה

כאשר המשתמש רוצה לרשום עסקה, יש לחשב את המע"מ אוטומטית ולהוסיף את השורה.

לרשומות הכנסה (המשתמש קיבל תשלום):

# חישוב: אם המשתמש קיבל 5,850 ש"ח סה"כ, הפירוט הוא:
# סכום ללא מע"מ = סה"כ / 1.17 = 5,000 ש"ח
# מע"מ = סכום * 0.17 = 850 ש"ח
gws sheets append --spreadsheet-id SPREADSHEET_ID --range "Sheet1!A:J" \
  --values '[["15/01/2026","Web Development Project","Professional Services","5000","850","5850","Income","INV-2026-001","Bank Transfer",""]]'

לרשומות הוצאה:

# דוגמה: חשבון אינטרנט בזק של 234 ש"ח (200 + 34 מע"מ)
gws sheets append --spreadsheet-id SPREADSHEET_ID --range "Sheet1!A:J" \
  --values '[["20/01/2026","Bezeq Internet","Phone & Internet","200","34","234","Expense","","Direct Debit",""]]'

נוסחאות חישוב מע"מ:

שלב 4: קריאה וסיכום נתונים פיננסיים

כאשר המשתמש צריך סקירה פיננסית, יש לקרוא את הנתונים ולחשב סיכומים.

# קריאת כל הרשומות מהגיליון
gws sheets read --spreadsheet-id SPREADSHEET_ID --range "Sheet1!A:J"

# קריאת רשומות בפלט JSON לעיבוד תוכניתי
gws sheets read --spreadsheet-id SPREADSHEET_ID --range "Sheet1!A:J" --output json

לאחר קריאת הנתונים, יש לחשב ולהציג:

• סה"כ הכנסות לתקופה
• סה"כ הוצאות לתקופה
• רווח נקי (הכנסות פחות הוצאות)
• סה"כ מע"מ שנגבה (על הכנסות)
• סה"כ מע"מ ששולם (על הוצאות, מע"מ תשומות)
• חבות מע"מ (נגבה פחות ששולם, הסכום לדיווח לרשות המיסים)

תקופות דיווח מע"מ דו-חודשיות (ישראל):

שלב 5: הפקת דוחות סיכום תקופות מס

כאשר המשתמש צריך להכין נתונים לרואה החשבון או לדיווח מע"מ, יש ליצור גיליון סיכום.

# קריאת כל הנתונים
gws sheets read --spreadsheet-id SPREADSHEET_ID --range "Sheet1!A:J" --output json

לאחר הקריאה, יש להשתמש ב-Python (דרך scripts/vat-summary.py) כדי:

1. לסנן עסקאות לפי התקופה הדו-חודשית
2. לקבץ לפי הכנסות מול הוצאות
3. לחשב סה"כ מע"מ שנגבה ומע"מ תשומות
4. להפיק סיכום מתאים לרואה חשבון

לאחר מכן לכתוב את הסיכום ללשונית חדשה:

# יצירת כותרות סיכום בלשונית חדשה
gws sheets append --spreadsheet-id SPREADSHEET_ID --range "VAT-Period-1!A1:D1" \
  --values '[["Category","Total Amount","Total VAT","Transaction Count"]]'

# הוספת שורות סיכום
gws sheets append --spreadsheet-id SPREADSHEET_ID --range "VAT-Period-1!A:D" \
  --values '[["Total Income","50000","8500","15"],["Total Expenses","20000","3400","25"],["VAT Liability","","5100",""],["Net Profit","30000","",""]]'

שלב 6: גיבוי גיליונות כ-CSV

כאשר המשתמש רוצה ליצור גיבויים מקומיים או לשתף נתונים עם רואה החשבון, יש לייצא ל-CSV.

# ייצוא גיליון המעקב הראשי כ-CSV
gws sheets read --spreadsheet-id SPREADSHEET_ID --range "Sheet1!A:J" --output csv > business-tracker-2026.csv

# ייצוא תקופת מע"מ ספציפית
gws sheets read --spreadsheet-id SPREADSHEET_ID --range "VAT-Period-1!A:D" --output csv > vat-period-1-2026.csv

ניתן להשתמש בסקריפט scripts/backup-sheets.py לגיבוי אוטומטי של מספר לשוניות:

python scripts/backup-sheets.py --spreadsheet-id SPREADSHEET_ID --output-dir ./backups/2026-01

שלב 7: רישום אוטומטי של תשלומים מקלט מובנה

כאשר המשתמש מספק נתוני עסקאות בכמות (מדף חשבון בנק או רשימת חשבוניות), יש לנתח ולהוסיף מספר רשומות בבת אחת.

# הוספת מספר שורות בקריאה אחת
gws sheets append --spreadsheet-id SPREADSHEET_ID --range "Sheet1!A:J" \
  --values '[
    ["01/02/2026","Client A - Monthly Retainer","Professional Services","10000","1700","11700","Income","INV-2026-010","Bank Transfer",""],
    ["03/02/2026","AWS Hosting","Software & Subscriptions","450","76.50","526.50","Expense","","Credit Card",""],
    ["05/02/2026","Business Lunch - Client B","Meals & Entertainment","300","51","351","Expense","","Credit Card","80% deductible"]
  ]'

שלב 8: שימוש במצב Dry-Run לאימות

לפני ביצוע שינויים, תמיד להציע למשתמש תצוגה מקדימה.

# תצוגה מקדימה של מה שיתווסף ללא כתיבה בפועל
gws sheets append --spreadsheet-id SPREADSHEET_ID --range "Sheet1!A:J" \
  --values '[["15/03/2026","Test Entry","Office Rent","5000","850","5850","Expense","","Bank Transfer",""]]' \
  --dry-run

דוגמה 1: פרילנסר ישראלי מקים מעקב חודשי

המשתמש אומר: "תיצור לי גיליון Google למעקב הכנסות והוצאות עם מע"מ"

פעולות:

1. הרצת gws sheets create --title "Freelance Tracker 2026" ליצירת הגיליון
2. הוספת שורת כותרות עם כל 10 העמודות (תאריך עד הערות)
3. הצגת מזהה הגיליון והקישור למשתמש
4. הסבר מבנה העמודות ואיך המע"מ יחושב לכל רשומה

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

דוגמה 2: הפקת סיכום מע"מ דו-חודשי לרואה חשבון

המשתמש אומר: "תכין סיכום מע"מ לינואר-פברואר 2026 ותייצא כ-CSV"

פעולות:

1. הרצת gws sheets read למשיכת כל הרשומות מגיליון המעקב
2. הרצת python scripts/vat-summary.py לסינון עסקאות ינואר-פברואר וחישוב סיכומים
3. כתיבת הסיכום ללשונית חדשה "VAT-Period-1-2026" בגיליון
4. ייצוא לשונית הסיכום כ-CSV עם gws sheets read --output csv
5. הצגת הסיכום: סה"כ הכנסות, סה"כ הוצאות, מע"מ שנגבה, מע"מ תשומות, חבות מע"מ נטו

תוצאה: סיכום תקופת מע"מ נקי הן בגיליון Google והן כקובץ CSV מקומי מוכן לשליחה לרואה החשבון.

דוגמה 3: רישום אוטומטי של העברות בנקאיות לגיליון הוצאות

המשתמש אומר: "קיבלתי החודש תשלומים: לקוח א' שילם 11,700 על ייעוץ, שילמתי 526.50 על אחסון, ו-351 על ארוחה עסקית"

פעולות:

1. ניתוח כל עסקה, חישוב פירוט מע"מ (חלוקת סה"כ ב-1.17)
2. קטגוריזציה: ייעוץ = שירותים מקצועיים (הכנסה), אחסון = תוכנה ומנויים (הוצאה), ארוחה = ארוחות ואירוח (הוצאה, 80% מוכר)
3. שימוש ב-gws sheets append עם מערך ערכים מרובי-שורות
4. אישור שכל הרשומות נרשמו עם חישובי מע"מ נכונים

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

סקריפטים

• scripts/vat-summary.py -- הפקת דוחות סיכום מע"מ דו-חודשיים מנתוני הגיליון. הרצה: python scripts/vat-summary.py --help
• scripts/backup-sheets.py -- גיבוי לשוניות Google Sheets כקבצי CSV מקומיים. הרצה: python scripts/backup-sheets.py --help

מסמכי עזר

• references/israeli-tax-categories.md -- רשימה מלאה של קטגוריות הוצאות מוכרות למס בישראל עם שיעורי ניכוי. יש לעיין בו בעת סיווג הוצאה עסקית.
• references/gws-sheets-recipes.md -- מתכונים נפוצים ל-gws CLI לפעולות Google Sheets. יש לעיין בו בעת ביצוע פעולות גיליון מעבר לקריאה/הוספה בסיסית.

שגיאה: "gws: command not found"

סיבה: Google Workspace CLI לא מותקן או לא נמצא ב-PATH. פתרון: התקנה עם npm install -g @google/gws. בשימוש עם npx, יש להוסיף תחילית npx @google/gws לפקודות.

שגיאה: "Authentication required" או "Token expired"

סיבה: המשתמש לא ביצע אימות או שטוקן ה-OAuth פג תוקף. פתרון: הרצת gws auth login לאימות מחדש. אם פרויקט Google Cloud לא הוגדר, יש להריץ תחילה gws auth setup.

שגיאה: "Spreadsheet not found" או "404"

סיבה: מזהה הגיליון שגוי או שלמשתמש אין גישה. פתרון: יש לאמת את מזהה הגיליון מכתובת ה-URL של Google Sheets (המחרוזת בין /d/ ל-/edit). יש לוודא שלחשבון Google המאומת יש הרשאת עריכה לגיליון.

שגיאה: "VAT calculation mismatch"

סיבה: הבדלי עיגול בין חישוב ידני לנוסחאות הגיליון. פתרון: תמיד לעגל מע"מ ל-2 ספרות אחרי הנקודה. יש להשתמש בנוסחה: Math.round(amount * 17) / 100 לחישובי שקלים מדויקים. רשות המיסים מקבלת עיגול לאגורה הקרובה.