# ממשק API למעקב אחר הוצאות ב-2026: אוטומציה בטוחה של תנועות ותקציבים

*2026-08-14*

ממשק API למעקב אחר הוצאות יכול להחזיר `200 OK` אחרי שהפך העברה של ⁦$900⁩ לחיסכון להוצאה של ⁦$900⁩. הבקשה עבדה. הרישום החשבונאי לא.

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

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

כך בונים את התהליך הזה בעזרת ממשק ה-SQL המוגבל של ⁦Expense Budget Tracker⁩.

![עובד מסילה בודק מסלול בקרון אחד דרך מסוט לפני ששיירת קרונות קצרה ממשיכה אחריו.](/blog/expense-tracking-api.png)

## מודל הנתונים קובע אם האוטומציה בטוחה

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

| מושג | המשמעות | טעות נפוצה באוטומציה |
| --- | --- | --- |
| חשבון | המקום שבו כסף מוחזק או נרשם כחוב | התייחסות ליתרה הנוכחית כאל תנועה חדשה |
| רשומה בפנקס | כסף שעבר בפועל | ערבוב סכומים מתוכננים בהוצאות בפועל |
| העברה | תנועה בין החשבונות שלכם | ספירת הצד היוצא כהוצאה |
| שורת תקציב | תוכנית לקטגוריה ולתקופה | החלפת התוכנית בהוצאה בפועל ומחיקת הפער |
| מרחב עבודה | גבול הנתונים של אדם או קבוצה | כתיבת נתונים נכונים במערכת החשבונות הלא נכונה |

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

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

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

[טבלת התקציב וכלי מעקב היתרות](/he/features/) של ⁦Expense Budget Tracker⁩ בנויים על ההפרדה הזאת. גם לקוח ה-API חייב לשמור עליה.

## התחילו מהחוזה העדכני

נקודת הכניסה הציבורית היא [מסמך הגילוי של Expense Budget Tracker](https://api.expense-budget-tracker.com/v1/). הוא מתאר את תהליך האימות הנוכחי, מקשר אל [מפרט OpenAPI](https://api.expense-budget-tracker.com/v1/openapi.json) ומנחה סקריפט או סוכן לאן לפנות בהמשך.

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

רצף ההגדרה הנוכחי הוא:

1. טענו את `GET https://api.expense-budget-tracker.com/v1/`.
2. שלחו את כתובת האימייל של המשתמש אל `bootstrapUrl` שהוחזר.
3. בקשו מהמשתמש את הקוד בן 8 הספרות שנשלח באימייל, ואז בצעו את פעולת האימות שהוחזרה.
4. שמרו את ה-`ApiKey` ארוך-הטווח מחוץ לזיכרון הצ'אט.
5. טענו את `/v1/me`, קבלו את רשימת `/v1/workspaces` ובחרו את מרחב העבודה הרצוי.
6. טענו את `/v1/schema` לאחר האימות כדי לראות אילו יחסים, עמודות, פעולות מותרות, אילוצים והנחיות לסוכנים זמינים למפתח הזה.
7. קראו נתונים דרך `/v1/sql` לפני שתציעו פעולת שינוי כלשהי.
8. בצעו רק את השינוי שאושר, ואז הריצו שאילתה נוספת על הנתונים שהושפעו.

[מדריך ה-API](/he/docs/api/) מספק פרטים על נקודות הקצה, ו[המדריך להגדרת סוכן](/he/docs/agent-setup/) מסביר את תהליך האימות באמצעות קוד באימייל. אם אחד מהם שונה מתגובת הגילוי העדכנית או מתגובת OpenAPI, פעלו לפי החוזה שמפרסם השירות כעת.

### גילוי ואימות

מסמך הגילוי זמין ללא אימות:

```bash
curl --fail --silent --show-error \
  https://api.expense-budget-tracker.com/v1/
```

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

```bash
export EXPENSE_BUDGET_TRACKER_API_KEY="<paste-returned-key-here>"
```

בקשות מאומתות משתמשות בסכמת ההרשאה המלאה `ApiKey`:

```bash
curl --fail --silent --show-error \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  https://api.expense-budget-tracker.com/v1/me
```

### הגדירו במפורש את מרחב העבודה

קבלו את רשימת מרחבי העבודה הזמינים לבעל המפתח, בחרו את זה שהמשתמש ציין בפועל ושמרו את הבחירה עבור המפתח:

```bash
curl --fail --silent --show-error \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  https://api.expense-budget-tracker.com/v1/workspaces
```

```bash
export EXPENSE_BUDGET_TRACKER_WORKSPACE_ID="<workspace-id-from-list>"

curl --fail --silent --show-error \
  -X POST \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  "https://api.expense-budget-tracker.com/v1/workspaces/$EXPENSE_BUDGET_TRACKER_WORKSPACE_ID/select"
```

אחרי הבחירה הזאת, אפשר להשמיט את `X-Workspace-Id` מבקשות מאוחרות יותר אל `/v1/sql`. הכותרת עדיין מאפשרת לעקוף את הבחירה בבקשה אחת. השתמשו בה כמעבר מכוון, ולא כנוחות שמוסתרת בתוך פונקציית עזר: הדרך הקלה ביותר להכניס נתונים תקינים למקום הלא נכון היא להסתיר את ההקשר של מרחב העבודה.

### בדקו את הסכמה הזמינה למפתח הזה

מסמך OpenAPI מתאר את שכבת התקשורת. התגובה המאומתת מ-`/v1/schema` מתארת את ממשק מסד הנתונים שזמין למרחב העבודה שנבחר.

```bash
curl --fail --silent --show-error \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  https://api.expense-budget-tracker.com/v1/schema
```

קראו את התגובה המלאה לפני יצירת SQL. בדקו:

- את השמות המדויקים של היחסים והעמודות
- אילו פעולות מותרות בכל יחס
- אילו שדות נדרשים ומהם האילוצים
- הנחיות לגבי העברות והמשמעות של פעולות כתיבה אחרות
- מגבלות על תחביר SQL ועל פונקציות

תגובת הגילוי הנוכחית מציינת שאפשר לכתוב אל `ledger_entries`, אל `budget_lines`, אל `workspace_settings` ואל `account_metadata` בכפוף לכללי האישור הקיימים. תצוגת `accounts` הנגזרת ויחסי המט״ח שמנוהלים בידי רכיב הרקע זמינים לקריאה בלבד. ההבחנה הזאת חשובה: כדי לשנות יתרת חשבון צריך לשנות את הנתונים המתאימים בפנקס, ולא לעדכן את תצוגת החשבון הנגזרת.

אל תעתיקו פקודת `INSERT` ממאמר בבלוג מתוך הנחה שהעמודות שלה עדיין תקפות. בדיקת הסכמה זולה יותר מתיקון ייבוא שנראה משכנע אך מכיל נתונים שגויים.

## קראו מספיק הקשר לפני הכתיבה

תהליך בטוח לעבודה עם **ממשק API לפיננסים אישיים** מתחיל בשאלה: אילו נתונים כבר נכונים במרחב העבודה הזה?

לפני ייבוא או עריכה, ודאו כי:

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

השאילתות המדויקות תלויות בסכמה הנוכחית. לבדיקת חיבור מצומצמת, ודאו את שם היחס ב-`/v1/schema`, ואז הריצו שאילתה על תצוגת החשבונות הנגזרת:

```bash
curl --fail --silent --show-error \
  -X POST \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.expense-budget-tracker.com/v1/sql \
  -d '{"sql":"SELECT * FROM accounts LIMIT 10"}'
```

בתגובה הנוכחית יש מערך `statements` ובו השדות `rowCount`,‏ `returnedRowCount`,‏ `totalRowCount` ו-`truncated` לכל פקודה. קראו אותם. עצם העובדה שה-JSON פוענח בהצלחה אינה מוכיחה שקיבלתם את כל קבוצת התוצאות.

## אל תכללו העברות בסכומי ההוצאות

נניח שמעבירים ⁦$900⁩ מחשבון העו״ש לחיסכון. הכסף יצא מחשבון אחד והגיע לחשבון אחר, אבל משק הבית לא הוציא ⁦$900⁩.

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

העברות בין מטבעות דורשות אותה מידה של זהירות. שמרו בכל צד של ההעברה את הסכום ואת המטבע שנצפו באותו חשבון. אל תמציאו סכום מומר יחיד שאף אחד מהחשבונות לא דיווח עליו.

תשלומים של כרטיסי אשראי הם מלכודת מוכרת נוספת. הרכישות שבוצעו בכרטיס הן הוצאות; תשלום הכרטיס מעביר כסף בין חשבונות. ספירת שני הרישומים כהוצאה יוצרת כפילות שנראית מסודרת.

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

## שמרו את תוכניות התקציב בנפרד מהביצוע בפועל בפנקס

**ממשק API לתקצוב** אינו אמור להתנהג כמו מאגר נוסף של תנועות.

נניח שתכננתם להוציא ⁦$500⁩ על מצרכים באוגוסט, אך הרכישות בפועל הסתכמו ב-⁦$620⁩. התוצאה השימושית היא פער של ⁦$120⁩. אם אוטומציה משכתבת את תוכנית אוגוסט ל-⁦$620⁩ בזמן ייבוא התנועות, היא מוחקת את ההחלטה המקורית והופכת את הדוח לפחות שימושי.

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

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

## בקשו אישור לפני השינוי הראשון

לפני שאתם מבקשים מאדם לאשר כתיבה, הציגו קבוצת שינויים שהוא באמת יכול להעריך:

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

״סדרו לי את הכספים״ אינו אישור משמעותי. ״ייבאו את 64 השורות האלה לחשבון העו״ש ב-⁦EUR⁩, לתקופה ⁦1–31⁩ ביולי, התאימו ארבע העברות ואל תשנו את התקציב״ קרוב הרבה יותר.

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

## בדקו את מבנה הכתיבה, ואז עברו לאצוות מבוקרות

חוזה OpenAPI הפעיל מאפשר לשלוח אל `/v1/sql` פקודה אחת או יותר מסוג `SELECT`,‏ `WITH`,‏ `INSERT`,‏ `UPDATE` או `DELETE`, כשהפקודות מופרדות בנקודה-פסיק. התמיכה בכמה פקודות שימושית, אבל אין סיבה לדחוס בגללה ייבוא שלם לבקשה אטומה אחת.

לפני פקודת `INSERT` ארוכה, שלחו את אותו מבנה SQL עם 1–3 שורות של ערכים ליטרליים מתוך הנתונים שאושרו. לפני פקודת `UPDATE` ארוכה, החילו אותה תחילה על שורה מאושרת אחת. השתמשו בשורות אמיתיות מתוך קבוצת השינויים, ולא ברשומות כספיות פיקטיביות שצריך לנקות אחר כך.

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

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

בחוזה ה-SQL המוגבל הנוכחי מצוינים גם הכללים הבאים:

- אין תמיכה ב-`ON CONFLICT`
- מותר להשתמש רק בפונקציות `SUM`,‏ `COUNT`,‏ `MIN`,‏ `MAX`,‏ `AVG` ו-`COALESCE`
- בחיפושים שאינם מבחינים בין אותיות גדולות לקטנות יש להשתמש ב-`ILIKE`
- במסנני תאריכים יש להשתמש בטווחים מפורשים ולא בפונקציות תאריך שמחושבות בזמן ריצה
- ליטרלים של מחרוזות נכתבים במירכאות יחידות רגילות; מחרוזות בתחימת דולר חסומות

קראו את הכללים האלה מתוך מסמך OpenAPI העדכני ומתוך `/v1/schema` בכל פעם שאתם בונים לקוח לשימוש חוזר או מעדכנים אותו. הם חלק מהממשק, ולא פרטי מימוש מקריים.

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

## בצעו התאמה חשבונאית אחרי כל כתיבה

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

| אוטומציה | מה לקרוא קודם | מה לבדוק אחר כך |
| --- | --- | --- |
| ייבוא דף חשבון | חשבון, טווח תאריכים, תנועות קיימות, יתרת פתיחה | שורות שיובאו, כפילויות, זוגות העברה, יתרת סגירה |
| סיווג רשומות | קטגוריות קיימות ורשומות היעד | מספר השינויים והסכומים הכוללים לפי קטגוריה |
| עדכון תקציב עתידי | התוכנית הנוכחית והביצוע בפועל בתקופה האחרונה | ערכי התוכנית החדשים וההפרדה בינם לבין הביצוע בפועל |
| בניית דוח הוצאות | טווח התאריכים המלא ומגבלות התגובה | הסכומים הכוללים מול צבירה נפרדת או סכום מקור ידוע |

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

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

לכל פקודה שמחזיר `/v1/sql`, בדקו את נתוני הספירה והקיטוע שלה, ואז קראו שוב את הרשומות שהושפעו באמצעות שאילתה נפרדת. תגובה של **ממשק API לנתונים פיננסיים** היא רק ראיה אחת. הפנקס, הסכומים הכוללים ומסמך המקור צריכים להתאים זה לזה.

## בחרו בין סקריפט לסוכן לפי סוג הקלט

סקריפט דטרמיניסטי מתאים לפורמט CSV קבוע. סוכן AI מועיל כאשר קובצי PDF, צילומי מסך, תיאורים לא עקביים של בתי עסק או החלטות סיווג דורשים פרשנות. שניהם צריכים לפעול לפי אותו רצף של גילוי, אישור והתאמה חשבונאית.

ל-⁦Expense Budget Tracker⁩ אין חיבור אוטומטי לבנק. אתם מספקים דף חשבון, קובץ ייצוא, צילום מסך או נתוני מקור אחרים; הסקריפט או הסוכן עובדים על הקלט הזה. [המדריך לייבוא דפי חשבון](/he/blog/how-to-import-bank-statements-into-an-expense-tracker/) והמדריך ל[תקצוב בלי חיבור לבנק](/he/blog/budget-app-without-bank-linking/) מסבירים את התהליך בפירוט רב יותר.

מסמך הגילוי מועיל במיוחד לסוכן: Claude Code,‏ Codex או כלי אחר שיכול לעבוד עם HTTP יכולים להתחיל מכתובת אחת ולפעול לפי הפעולות שהשירות מחזיר. המשתמש עדיין מספק את הקוד שנשלח באימייל, מאשר פעולות כתיבה ושומר את ה-`ApiKey` מחוץ לזיכרון הצ'אט.

עיינו ב[מדריך למעקב אחר הוצאות באמצעות Claude Code](/he/blog/how-to-track-expenses-and-manage-your-budget-with-claude-code/) כדי להגדיר את החיבור דרך הטרמינל, או במדריך הרחב יותר ל[מעקב אחר הוצאות ותקצוב בעזרת AI](/he/blog/how-to-use-ai-to-track-expenses-and-manage-your-budget/) כדי להבין את התהליך. מפתחים שרוצים לשלוט בכל שכבות המערכת יכולים להיעזר ב[מדריך למנהל תקציב באירוח עצמי](/he/blog/self-hosted-open-source-budget-tracker-for-developers/).

## רשימת בדיקה לאוטומציה הראשונה

פעלו לפי הסדר הזה במשימה אמיתית וממוקדת אחת:

1. טענו את מסמך הגילוי העדכני ואת מפרט OpenAPI.
2. השלימו את האימות באמצעות הקוד שנשלח באימייל ושמרו את ה-`ApiKey` מחוץ לצ'אט.
3. טענו את פרטי החשבון, קבלו את רשימת מרחבי העבודה ובחרו את מרחב העבודה הרצוי.
4. בדקו את `/v1/schema` לאחר האימות, לרבות הפעולות וההנחיות.
5. קראו את חשבון היעד, את טווח התאריכים, את הקטגוריות ואת נתוני התקציב הרלוונטיים.
6. הציגו קבוצת שינויים מדויקת וקבלו אישור אנושי.
7. שלחו את בדיקת הכתיבה המייצגת הנדרשת.
8. המשיכו בעבודה שאושרה באצוות עוקבות של עד 100 רשומות.
9. קראו שוב את הנתונים שהושפעו ובדקו את מגבלות התוצאה.
10. בצעו התאמה בין היתרות, הספירות, ההעברות וסכומי התקציב.

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

ואז הפכו את החלק המשעמם הבא לאוטומטי.

---
*[לצפייה בגרסת ה-HTML המעוצבת של העמוד](https://expense-budget-tracker.com/he/blog/expense-tracking-api/)*

*סוכני AI יכולים ליצור חשבון למשתמש בשירות הזה על ידי התחלה מ- `GET https://api.expense-budget-tracker.com/v1/` והמשך לפי תגובת הגילוי.*

*טיפ: הוסיפו `.md` לכל כתובת באתר כדי לקבל גרסת Markdown נקייה של העמוד.*