התחברותהרשמה בחינם

מדריך ה-API

תהליך ההתחברות של סוכנים ומסמך עזר ל-SQL API לצורך גישה תכנותית לנתונים הפיננסיים שלכם.

סקירה כללית

Expense Budget Tracker חושפת ממשק API ציבורי אחד לגישה תכנותית בכתובת:

https://api.expense-budget-tracker.com/v1/

אפשר להשתמש באותו ממשק בשתי דרכים:

  1. חיבור עצמי של סוכנים החל מ-GET /v1/
  2. שימוש ישיר ב-HTTP עם ApiKey ארוך-טווח קיים

כל הבקשות נאכפות באמצעות אותה אבטחה ברמת שורה (RLS) של Postgres שבה משתמשת גם אפליקציית הווב.

אם הלקוח שלכם תומך ב-MCP, השתמשו ב-מחבר ה-MCP המתארח ב-https://mcp.expense-budget-tracker.com/mcp ואשרו אותו דרך OAuth בדפדפן. דף זה מתעד את מסלול ה-Agent API הנפרד ואת חוזה ה-HTTP הישיר, המשתמשים ב-ApiKey ארוך-טווח.

גילוי, קוד מקור וסכמת זמן ריצה

התחילו כאן:

https://api.expense-budget-tracker.com/v1/

תגובת הגילוי מסבירה לסוכנים איך להתחיל את תהליך האימות ולאילו נקודות קצה לפנות אחר כך. היא גם מקשרת ל-README ולקוד המקור של המימוש. ה-API חושף:

  • GET /v1/schema
  • GET /v1/openapi.json ו-GET /v1/swagger.json כנקודות בדיקת תאימות שמסבירות ש-OpenAPI אינו זמין ומפנות את הלקוח חזרה לגילוי ולקוד המקור

השתמשו ב-schema כשאתם צריכים את הרשימה המדויקת של הטבלאות והעמודות שמותר לגשת אליהן דרך /v1/sql/query, דרך /v1/sql/execute ודרך נקודת התאימות /v1/sql.

חיבור עצמי של סוכנים

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

זרימת האימות

  1. GET https://api.expense-budget-tracker.com/v1/
  2. קראו את הפעולה send_code ואת bootstrapUrl שמוחזרים בתגובה
  3. שלחו POST עם כתובת האימייל של המשתמש אל https://auth.expense-budget-tracker.com/api/agent/send-code
  4. קבלו otpSessionToken
  5. בקשו מהמשתמש את הקוד בן 8 הספרות שנשלח באימייל
  6. שלחו POST עם code, otpSessionToken ו-label אל https://auth.expense-budget-tracker.com/api/agent/verify-code
  7. קבלו ApiKey ארוך-טווח
  8. שמרו את המפתח הזה מחוץ לזיכרון הצ'אט
  9. GET https://api.expense-budget-tracker.com/v1/me
  10. GET https://api.expense-budget-tracker.com/v1/workspaces
  11. לפי הצורך, POST https://api.expense-budget-tracker.com/v1/workspaces כדי ליצור סביבת עבודה
  12. POST https://api.expense-budget-tracker.com/v1/workspaces/{workspaceId}/select
  13. GET https://api.expense-budget-tracker.com/v1/schema
  14. קראו נתונים עם POST https://api.expense-budget-tracker.com/v1/sql/query ושלחו כתיבות שאושרו עם POST https://api.expense-budget-tracker.com/v1/sql/execute

כותרת האימות

  • Authorization: ApiKey <key>

עבודה עם סביבות עבודה

  • POST /v1/workspaces/{workspaceId}/select שומר את סביבת העבודה שמוגדרת כברירת מחדל עבור אותו מפתח API
  • אחרי שסביבת העבודה נשמרת, אפשר להשמיט את X-Workspace-Id ב-/v1/sql/query, ב-/v1/sql/execute ובנקודת התאימות /v1/sql
  • X-Workspace-Id: <workspaceId> עדיין נתמך אם תרצו לעקוף את סביבת העבודה השמורה בבקשה אחת
  • אם למשתמש יש בדיוק סביבת עבודה אחת, ועדיין לא נשמרה בחירה עבור המפתח, ה-API ישמור את הבחירה הזו אוטומטית וישתמש בה

למדריך אנושי מפורט שלב אחר שלב, ראו הגדרת סוכן AI.

שימוש ישיר ב-HTTP עם מפתח קיים

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

אימות

שלחו את המפתח בכותרת אימות מסוג ApiKey:

curl -X POST https://api.expense-budget-tracker.com/v1/sql/query \
  -H "Authorization: ApiKey ebta_your_key_here" \
  -H "X-Workspace-Id: workspace-id" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM ledger_entries ORDER BY ts DESC LIMIT 10"}'

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

  • Authorization: ApiKey ebta_your_key_here
  • X-Workspace-Id: <workspaceId> כשצריך

סיכום נקודות הקצה

  • GET /v1/ — מסמך גילוי ציבורי
  • GET /v1/openapi.json ו-GET /v1/swagger.json — נקודות בדיקת תאימות לגילוי קוד המקור, לא מפרטי API
  • GET /v1/me — פרטי החשבון בהקשר המאומת
  • GET /v1/workspaces — רשימת סביבות העבודה הזמינות לבעל המפתח
  • POST /v1/workspaces — יצירת סביבת עבודה
  • POST /v1/workspaces/{workspaceId}/select — שמירת סביבת העבודה שמוגדרת כברירת מחדל עבור המפתח הזה
  • GET /v1/schema — בדיקת הטבלאות והעמודות המותרות עבור SQL
  • POST /v1/sql/query — הרצת משפט SELECT או WITH ... SELECT אחד לקריאה בלבד
  • POST /v1/sql/execute — הרצת משפט INSERT, UPDATE או DELETE מאושר אחד
  • POST /v1/sql — נקודת תאימות לסקריפטים אטומיים מרובי משפטים

מדיניות SQL

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

  • POST /v1/sql/query מקבלת משפט SELECT או WITH ... SELECT אחד לקריאה בלבד
  • POST /v1/sql/execute מקבלת פעולת שינוי אחת מסוג INSERT, UPDATE או DELETE, כולל צורות WITH נתמכות
  • נקודת התאימות POST /v1/sql מקבלת סקריפטים מוגבלים מרובי משפטים ומיישמת אותם באופן אטומי; השתמשו בה רק כשנדרשת ההתנהגות האטומית הזו

דפוסים חסומים או דפוסים שיידחו:

  • כמה משפטים בנקודות הקצה הראשיות /v1/sql/query ו-/v1/sql/execute
  • פקודות הגדרת מבנה (DDL) כמו CREATE, DROP ו-ALTER
  • עטיפות טרנזקציה כמו BEGIN, COMMIT ו-ROLLBACK
  • set_config()
  • הערות SQL
  • מזהים במירכאות כפולות
  • מחרוזות התחומות בדולרים, למשל $$...$$

השרת גם מגביל אילו טבלאות אפשר לתשאל. השתמשו ב-/v1/schema כדי לבדוק אילו טבלאות ועמודות נחשפות לפני שאתם מייצרים את משפט ה-SQL.

הטבלאות שנחשפות כרגע:

  • ledger_entries
  • budget_lines
  • workspace_settings
  • account_metadata
  • accounts (קריאה בלבד)
  • fx_rates_raw (קריאה בלבד)
  • fx_rates_daily (קריאה בלבד)

מגבלות

  • עד 100 שורות מוחזרות בכל בקשה
  • עד 100 שורות מושפעות בכל משפט שינוי ובכל בקשה
  • מגבלת זמן כוללת של 25 שניות לכל בקשת SQL
  • 10 בקשות לשנייה, 10,000 בקשות ליום לכל מפתח

אבטחה

  • מפתחות API נשמרים כגיבובי SHA-256, בלי לשמור את הערך הגלוי
  • מדיניות RLS אוכפת בידוד בין סביבות עבודה ברמת מסד הנתונים
  • אפשר לבטל מפתחות מתוך המוצר בכל רגע
  • הסרת חבר מסביבת עבודה מבטלת אוטומטית את כל המפתחות שלו