בנו אינטגרציות פיננסיות על הדאטה של Moneytor

# Moneytor API

## אימות
שלחו JWT API Token בכותרת Authorization. את הטוקן יוצרים מתוך אזור ההגדרות של משתמש Premium. כל טוקן תקף ל-30 יום בלבד.

```http
Authorization: Bearer <JWT_API_TOKEN>
```

הטוקן הוא JWT חתום שמכיל user_id,‏ jti ו-exp. השרת מאמת חתימה, בודק שהתוקף לא פג ושהטוקן לא בוטל, ואז מפעיל מגבלות שימוש.

## מגבלות שימוש
30 בקשות לשעה ו-300 בקשות ליום לכל משתמש, לפי UTC.

## GET /api/v1/assetWorth

מחזיר תמונת מצב מסוכמת: סך נכסים, חובות, שווי נטו ורשימת מוצרים קצרה.

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

### Query params
אין פרמטרים

### שדות תגובה
- `ok` (boolean): מציין שהבקשה הצליחה.
- `asOf` (string): חותמת זמן ISO-8601 של יצירת התגובה.
- `baseCurrency` (string): מטבע הבסיס של החישובים. כרגע תמיד ILS.
- `totalBalances` (object): אובייקט סיכומי יתרות לפי קטגוריות נכסים וחובות.
- `netWorth` (number): נכסים פחות חובות במטבע הבסיס.
- `productsSummary` (array): רשימת מוצרים קצרה עם id, form, name ו-balanceInBase.

### דוגמת תגובה
```json
{
  "ok": true,
  "asOf": "2026-05-23T08:18:26.341Z",
  "baseCurrency": "ILS",
  "totalBalances": {
    "assets": 6707996.69,
    "debts": 188464.84,
    "bankAssets": 1286905,
    "pensionAssets": 3213333,
    "shareAssets": 1069765.84,
    "cryptoAssets": 1120005.45,
    "lastUpdate": {
      "bankAssets": "2026-05-20T19:00:58.479538+00:00",
      "pensionAssets": "2025-05-08T15:26:55.130484+00:00"
    }
  },
  "netWorth": 6519531.85,
  "productsSummary": [
    {
      "id": "6255",
      "form": "bank",
      "name": "אופן פיננס סנדבוקס פקדון",
      "balanceInBase": 16819
    },
    {
      "id": "6028",
      "form": "crypto",
      "name": "שם ארנק הקריפטו",
      "balanceInBase": 1120005.45
    }
  ]
}
```

## GET /api/v1/assets

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

מתי להשתמש: כשצריך לבנות סנכרון, Agent שמנתח מוצר-מוצר, או אינטגרציה שצריכה פירוט holdings.

### Query params
אין פרמטרים

### שדות תגובה
- `ok` (boolean): מציין שהבקשה הצליחה.
- `asOf` (string): חותמת זמן ISO-8601 של יצירת התגובה.
- `baseCurrency` (string): מטבע הבסיס של החישובים. כרגע תמיד ILS.
- `count` (number): מספר הנכסים במערך assets.
- `assets` (array): מערך נכסים. לכל נכס יש id, form, name, currency, balanceInBaseCurrency ו-partOfPortfolio.

### שדות משותפים לכל נכס
- `id` (string): מזהה המוצר כמחרוזת.
- `productId` (number): מזהה המוצר המספרי.
- `userProductId` (number): מזהה הקישור בין המשתמש למוצר.
- `portfolioProductId` (number): מזהה הקישור בין התיק למוצר.
- `portfolio_products_id` (number): שם שדה מקור לקישור תיק-מוצר.
- `user_products_id` (number): שם שדה מקור לקישור משתמש-מוצר.
- `form` (string): סוג הנכס. אחד משמונת הערכים המתועדים מטה.
- `name` (string): שם הנכס כפי שמופיע במאניטור.
- `currency` (object): מטבע הנכס עם value, name, sign ו-rate.
- `liquidity` (boolean|null): האם הנכס נזיל. בחובות הערך עשוי להיות null.
- `ownership` (number|null): אחוז בעלות המשתמש בנכס.
- `insights` (string[]|null): מזהי תובנות שמקושרות לנכס, אם קיימות.
- `updatedAt` (string): זמן עדכון אחרון בפורמט ISO.
- `provider` (string|null): שם ספק/מקור נתונים כאשר קיים.
- `openfinance_asset_id` (string|null): מזהה מקור Open Finance המקורי.
- `openfinance_connection_id` (string|null): מזהה חיבור Open Finance המקורי.
- `openfinanceAssetId` (string|null): מזהה Open Finance מנורמל ב-camelCase.
- `openfinanceConnectionId` (string|null): מזהה חיבור Open Finance מנורמל ב-camelCase.
- `balanceInBaseCurrency` (number): שווי הנכס במטבע הבסיס של התגובה.
- `partOfPortfolio` (number): חלק הנכס מתוך התיק באחוזים.

### סוגי נכסים ושדות לפי form
### `bank` — בנק / פיקדון
חשבונות עו"ש, פיקדונות ומזומן בנקאי.

- `country` (object): מדינת החשבון.
- `accountType` (object): סוג חשבון, למשל balance או saving.
- `bank` (string): שם הבנק או המוסד.
- `amount` (number): יתרה נוכחית במטבע המקורי.
- `interest` (number): ריבית שנתית, אם הוזנה.
- `monthlyDeposit` (number): הפקדה חודשית לפיקדונות.
- `closeExitPoint` (string): נקודת יציאה קרובה לפיקדון.
- `maturityDate` (string): תאריך פירעון או סיום.
- `bankNumber` (string|number): מספר בנק.
- `branchNumber` (string|number): מספר סניף.
- `accountNumber` (string|number): מספר חשבון.
- `tax` (number): שיעור מס רלוונטי באחוזים.

### `pension` — פנסיה / גמל / השתלמות
חסכונות פנסיוניים וקופות שמגיעים ידנית או ממסלקה.

- `institution` (object): גוף מנהל.
- `productType` (object): סוג מוצר פנסיוני.
- `route` (object): מסלול השקעה.
- `number` (object): מספר קופה/פוליסה.
- `fund_id` (object): מזהה קרן במקור הנתונים.
- `fundId` (string): מזהה קרן מנורמל.
- `amount` (number): סכום צבור נוכחי.
- `expectedYield` (number): תשואה צפויה שנתית.
- `managementFeeFromSavings` (number): דמי ניהול מצבירה.
- `managementFeeFromDeposit` (number): דמי ניהול מהפקדה.
- `depositFrequency` (object): תדירות הפקדות.
- `monthlyDepositEmployee` (number): הפקדת עובד חודשית.
- `monthlyDepositEmployer` (number): הפקדת מעסיק חודשית.
- `yearsToRetirement` (number|null): מספר שנים משוער לפרישה.
- `projectedMonthlyPension` (number): קצבה חודשית צפויה ממסלקה.
- `investmentDistribution` (array): חלוקת השקעה למסלולים, כאשר קיימת.
- `enrichedFund` (object): מידע מועשר על הקרן ממאגרי תשואות.
- `additionalFundInfo` (object): מידע משלים על מסלול ההשקעה.

#### `investmentDistribution[]` (array<object>)
חלוקה למסלולי השקעה.

- `routeName` (string): שם המסלול.
- `routeCode` (string): קוד המסלול.
- `amount` (number): סכום במסלול.
- `depositPercentage` (number): אחוז הפקדה למסלול.

### `share` — ניירות ערך
תיק מניות, קרנות וניירות ערך עם פירוט החזקות.

- `broker` (string): שם ברוקר או מוסד.
- `stocksData` (array): רשימת ניירות הערך בתיק.
- `stocksOptions` (array): אפשרויות חיפוש/בחירה ששימשו בממשק.
- `cash` (number): מזומן בחשבון המסחר.
- `minimumFee` (number): עמלת מינימום.
- `shiftFee` (number): עמלת העברה/פעולה.
- `showAfterTax` (boolean): האם להציג שווי אחרי מס.
- `yesefTax` (boolean|null): האם חל מס יסף.
- `offsetLosses` (boolean): האם לקזז הפסדים.
- `ibkr_account_id` (string): מזהה חשבון IBKR, אם קיים.

#### `stocksData[]` (array<object>)
שורת החזקה בודדת.

- `stockName` (string): סימול או שם נייר.
- `amount` (number): כמות יחידות.
- `purchasePrice` (number): מחיר קנייה ליחידה.
- `purchaseDate` (string|null): תאריך קנייה.
- `stockPrice` (number): מחיר נוכחי במטבע הנייר.
- `stockPriceInBaseCurrency` (number): מחיר נוכחי במטבע הבסיס.
- `currency` (object): מטבע נייר הערך.
- `totalWorth` (number): שווי כולל במטבע המקורי.
- `totalWorthInBaseCurrency` (number): שווי כולל במטבע הבסיס.
- `balanceInBaseCurrency` (number): שווי החזקה אחרי התאמות במטבע הבסיס.

### `rsu` — RSU / אופציות / ESPP
מענקי מניות, אופציות ו-ESPP עם חישובי הבשלה ומס.

- `broker` (string): סוג או שם ברוקר/תוכנית.
- `rsuData` (array): רשימת מענקים או אופציות.
- `rsuOptions` (array): אפשרויות חיפוש/בחירה ששימשו בממשק.
- `showAfterTax` (boolean): האם לחשב אחרי מס.
- `showVestedOnly` (boolean): האם לכלול רק יחידות שהבשילו.
- `taxRate` (number): שיעור מס באחוזים.
- `yesefTax` (boolean|null): האם חל מס יסף.
- `optionGrantType` (string|null): סוג מענק אופציות.
- `ipoDate` (string|null): תאריך IPO רלוונטי לאופציות.
- `ipoPrice` (number|null): מחיר IPO רלוונטי לאופציות.
- `showSaleInTwoYears` (boolean): האם לחשב תרחיש מכירה אחרי שנתיים.
- `stockName` (string): שם מניה ראשי ברמת המוצר.
- `stockPrice` (string|number): מחיר מניה ראשי.
- `stockPriceInBaseCurrency` (number): מחיר מניה במטבע הבסיס.
- `stockMarket` (string|null): שוק/בורסה.

#### `rsuData[]` (array<object>)
שורת מענק בודדת.

- `stockName` (string): שם או סימול מניה.
- `totalAmount` (number): סך יחידות במענק.
- `vestedAmount` (number): יחידות שהבשילו.
- `effectiveAmount` (number): כמות אפקטיבית לחישוב.
- `grantPrice` (number): מחיר מענק/מימוש.
- `grantDate` (string|null): תאריך מענק.
- `buyPrice` (number|null): מחיר קנייה ב-ESPP.
- `stockPrice` (number): מחיר מניה נוכחי.
- `currency` (object): מטבע המניה.
- `totalWorth` (number): שווי כולל במטבע המקורי.
- `totalWorthInBaseCurrency` (number): שווי כולל במטבע הבסיס.
- `balanceInBaseCurrency` (number): שווי אחרי בחירת vested/מס במטבע הבסיס.

### `crypto` — קריפטו
ארנקי קריפטו והחזקות מטבעות.

- `cryptoData` (array): רשימת מטבעות בארנק.
- `cryptoOptions` (array): אפשרויות חיפוש/בחירה ששימשו בממשק.
- `cash` (number): מזומן משויך לארנק, אם קיים.
- `showAfterTax` (boolean): האם לחשב אחרי מס.
- `yesefTax` (boolean): האם חל מס יסף.
- `offsetLosses` (boolean): האם לקזז הפסדי קריפטו.

#### `cryptoData[]` (array<object>)
החזקה במטבע בודד.

- `coinName` (string): סימול המטבע.
- `amount` (number): כמות מטבעות.
- `purchasePrice` (number): מחיר קנייה.
- `purchaseDate` (string|null): תאריך קנייה.
- `purchaseFee` (number|null): עמלת קנייה.
- `coinRate` (number): שער מטבע נוכחי.
- `totalWorth` (number): שווי כולל במטבע המקורי.
- `totalWorthInBaseCurrency` (number): שווי כולל במטבע הבסיס.
- `balanceInBaseCurrency` (number): שווי החזקה במטבע הבסיס.

### `debt` — חוב / הלוואה / משכנתא
הלוואות, משכנתאות וחיובי אשראי שמוצגים כחובות.

- `debtInstitution` (string): שם הגוף המלווה.
- `debtType` (string): סוג חוב, למשל loan או mortgage.
- `startDate` (string): תאריך התחלת החוב.
- `routesData` (array): מסלולי החוב או ההלוואה.
- `returnType` (string): סוג החזר, אם קיים.
- `graceType` (object): סוג גרייס.
- `graceYears` (object): משך גרייס בשנים.

#### `routesData[]` (array<object>)
מסלול חוב בודד.

- `remainder` (number): יתרת חוב במסלול.
- `trackInterestType` (object): סוג ריבית המסלול.
- `interest` (number): ריבית שנתית.
- `monthlyRepayment` (number): החזר חודשי.
- `originalSum` (number): סכום מקורי.
- `debtPeriodInMonths` (number): משך החוב בחודשים.

### `realestate` — נדל"ן
נכסי נדל"ן עם פרטי נכס, שכירות ותזרים.

- `value` (number): שווי נוכחי.
- `purchasePrice` (number): מחיר קנייה.
- `purchaseDate` (string): תאריך רכישה.
- `purchaseExpenses` (number): הוצאות רכישה.
- `linkedMortgage` (object): משכנתא מקושרת.
- `expectedValueIncrease` (number): עליית ערך צפויה.
- `saleCommission` (number): עמלת מכירה.
- `profitTax` (number): מס שבח/רווח.
- `address` (string): כתובת מלאה.
- `country` (object): מדינה.
- `city` (string): עיר.
- `street` (string): רחוב.
- `builtArea` (number): שטח בנוי.
- `propertyType` (object): סוג נכס.
- `bedrooms` (number): מספר חדרי שינה.
- `bathrooms` (number): מספר חדרי רחצה.
- `parking` (number): מספר חניות.
- `rent` (number): שכירות חודשית/תקופתית.
- `rentType` (object): סוג שכירות.
- `cashflowsData` (array): הכנסות והוצאות לנכס.
- `latitude` (number): קו רוחב.
- `longitude` (number): קו אורך.

#### `cashflowsData[]` (array<object>)
שורת תזרים נדל"ן.

- `expenditureType` (object): סוג הכנסה/הוצאה.
- `frequency` (object): תדירות.
- `fixedAmountPercentage` (boolean): האם הסכום הוא אחוז.
- `amount` (number): סכום השורה.
- `sum` (number): סכום מחושב.

### `other` — אחר
נכסים כלליים שאינם משתייכים לסוג ייעודי.

- `currentValue` (number): שווי נוכחי.
- `expectedMonthlyIncome` (number): הכנסה חודשית צפויה.
- `expectedMonthlyExpenses` (number): הוצאות חודשיות צפויות.
- `expectedSellingExpenses` (number): הוצאות מכירה צפויות.
- `buyingPrice` (number): מחיר קנייה.
- `country` (object): מדינה.
- `managementFee` (number): דמי ניהול.
- `purchaseDate` (string): תאריך רכישה.
- `predictedValueIncrease` (number): עליית ערך צפויה.

### דוגמת תגובה
```json
{
  "ok": true,
  "asOf": "2026-05-23T08:39:05.559Z",
  "baseCurrency": "ILS",
  "count": 2,
  "assets": [
    {
      "id": "6255",
      "productId": 6255,
      "form": "bank",
      "name": "אופן פיננס סנדבוקס פקדון",
      "liquidity": true,
      "ownership": 100,
      "currency": {
        "value": "ILS",
        "name": "",
        "sign": "",
        "rate": -1
      },
      "balanceInBaseCurrency": 16819,
      "partOfPortfolio": 0.2507,
      "updatedAt": "2026-05-19T17:00:55.816049+00:00"
    },
    {
      "id": "6028",
      "productId": 6028,
      "form": "crypto",
      "name": "שם ארנק הקריפטו",
      "cryptoData": [
        {
          "coinName": "BTC",
          "amount": 5,
          "coinRate": 74719.35,
          "totalWorthInBaseCurrency": 1120005.45,
          "balanceInBaseCurrency": 1120005.45
        }
      ],
      "balanceInBaseCurrency": 1120005.45,
      "partOfPortfolio": 16.6966
    }
  ]
}
```

## GET /api/v1/transactions

מחזיר תנועות Open Finance ותנועות ידניות, עם סינון תאריכים ו-limit.

מתי להשתמש: כשצריך לנתח הוצאות, הכנסות, קטגוריות או לבנות Agent תזרימי.

### Query params
- `from` (ISO date string): תאריך התחלה כולל. ערך לא תקין ייחשב כאילו לא נשלח.
- `to` (ISO date string): תאריך סיום כולל. ערך לא תקין ייחשב כאילו לא נשלח.
- `limit` (number): מספר תנועות להחזיר. מוגבל לטווח 1-2000.

### שדות תגובה
- `ok` (boolean): מציין שהבקשה הצליחה.
- `asOf` (string): חותמת זמן ISO-8601 של יצירת התגובה.
- `count` (number): מספר התנועות שחזרו אחרי limit.
- `totalAvailable` (number): מספר התנועות הזמינות אחרי סינון תאריכים.
- `transactions` (array): מערך תנועות עם id, date, amount, currency, description, category, accountId ו-type.

### דוגמת תגובה
```json
{
  "ok": true,
  "asOf": "2026-05-23T08:39:37.419Z",
  "count": 2,
  "totalAvailable": 117,
  "transactions": [
    {
      "id": "01KQRZXN78ZD6DZ8NM8YC1YSCY",
      "date": "2026-02-09",
      "amount": 1800,
      "currency": "ILS",
      "description": "מב. הפועלים-י",
      "category": "BANK_TRANSFER",
      "accountId": "QUNDT1VOVCNU...",
      "type": "CHECKING"
    },
    {
      "id": "01KQRZXN78RHYEC5G5DZ99E7GT",
      "date": "2026-03-10",
      "amount": -3236.36,
      "currency": "ILS",
      "description": "לאומי מאסטרקרד",
      "category": "CREDIT_CARD_CHECKING",
      "accountId": "QUNDT1VOVCNU...",
      "type": "CHECKING"
    }
  ]
}
```

## שגיאות
- 401 Invalid API key: `{"ok":false,"error":"Invalid API key"}`
- 401 API token expired: `{"ok":false,"error":"API token expired","code":"api_token_expired","message":"This API token has expired. Create a new token in Moneytor API settings.","renew_url":"https://app.moneytor.co.il/settings#api"}`
- 403 Premium subscription required: `{"ok":false,"error":"Premium subscription required"}`
- 405 Method not allowed: `{"ok":false,"error":"Method not allowed"}`
- 429 API limit reached: `{"ok":false,"error":"API limit reached","limit":"hourly","limit_max":30,"used":31,"resets_at":"2026-05-23T09:00:00.000Z","message":"API limit reached — hourly"}`

## ידידותי לסוכני AI
התיעוד זמין גם כ-Markdown, llms.txt ו-OpenAPI כדי שסוכנים יוכלו להבין את ה-API ללא גירוד HTML.