מקור: [העמוד הציבורי של FINLY](https://finly.co.il/developers/)

גישה לסוכני AI

# כלים שאפשר לקרוא,
תוצאות שאפשר לבדוק.

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

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

ואם הבדיקה תראה שאין כדאיות — נגיד לכם זאת ביושר.

## מעלים דוח דרך הסוכן ומקבלים ניתוח

כתובת MCP לדוחות: ` https://finly.co.il/mcp/reports `. כתובת REST: ` https://finly.co.il/agent/v1/reports `. החיבור אינו דורש OAuth, מפתח API או סשן פורטל. אלה כתובות נפרדות משירות הידע והחישובים שבהמשך.

[כלי הדוחות וסכמות הנתונים](https://finly.co.il/agent/v1/reports/capabilities) · [חוזה OpenAPI חי לדוחות](https://finly.co.il/agent/v1/reports/openapi.json)

1. מתחילים בקריאת ` get_report_analysis_requirements ` עם ` {} `. התשובה כוללת ` authorization_required: false `, הודעת עיבוד בשדה ` processing_notice `, קישור למדיניות הפרטיות, מגבלות ואתגר אבטחה.
2. פועלים במסגרת המשימה וההרשאה שהמשתמש נתן לסוכן. FINLY אינה דורשת מסך הסכמה או אישור נוסף לניתוח הרגיל; הודעת העיבוד מסבירה מה נעשה במידע. שימוש ב־OCR חיצוני דורש שהרשאת המשימה תכלול את העברת המידע לספק, כמפורט בהמשך.
3. שומרים באופן פרטי את ` operation ` שהתקבל בדרישות לפני ההעלאה. פותרים את אתגר האבטחה ומעבירים את הקובץ ואת הפעולה אל ` analyze_balance_report `. אין צורך בשדה אישור או ב־hash של נוסח לניתוח הרגיל.
4. קוראים את התוצאה בתשובת HTTP, או אוספים אותה בעזרת מזהה הפעולה אם החיבור נקטע. משתמשים ב־` result ` רק כשהסטטוס מציין הצלחה, ומוסרים לאדם את הדוח הקריא שב־` result.document `. נתונים חלקיים אינם ניתוח מלא.

אפשר לקבל את הדרישות גם דרך REST:

```
POST /agent/v1/reports/tools/get_report_analysis_requirements
Content-Type: application/json

{}
```

בקשת הניתוח נשלחת אל ` POST /agent/v1/reports/tools/analyze_balance_report `. הגוף כולל את תוכן הקובץ בשדה ` content_base64 `, את האתגר בשדה ` security_challenge ` ואת הפתרון בשדה ` security_proof `. הסכמה המלאה נמצאת בחוזה החי.

FINLY אינה אוספת הצהרת אישור לניתוח הרגיל: ` handling.consent_evidence: "not_collected" `. הדרישות אינן מחזירות ` authorization_policy `. לתאימות, שדה ` authorization ` מהחוזה הישן, במבנה תקין, מתקבל בלי אימות גרסת המדיניות ואינו משמש או נאסף כאישור.

### הדוח שמוסרים לאדם

בתוצאה מוצלחת נוסף לצד הנתונים המובנים ` result.document `. המסמך מזוהה באמצעות ` format: "finly-report-v1" ` ו־` locale: "he" `, וכולל את השדות ` text ` ו־` html `. מסרו את ` document.text ` לקריאה או את ` document.html ` כקובץ HTML בעברית מימין לשמאל. ה־JSON המובנה מיועד להמשך עבודה של הסוכן, ולא כתחליף לדוח הקריא לאדם. הדוח הקריא כולל את עובדות הניתוח ואת מגבלותיו.

אם המצג גדול מדי, ` result.document_error: "report_document_unavailable" ` מחליף את המסמך הקריא והעובדות המובנות נשארות בתוצאה. אין להעלות את הדוח מחדש: אפשר להסביר לאדם את העובדות שכבר הוחזרו ולציין שהמסמך המעוצב אינו זמין.

### PDF דיגיטלי כברירת מחדל

מסמך עם שכבת טקסט קריאה מעובד מקומית. OCR חיצוני כבוי כברירת מחדל ועשוי להעביר את דוח המשכנתה, לרבות פרטים אישיים ופיננסיים, ל־Google Document AI מחוץ לישראל. אם הרשאת המשימה הקיימת כוללת העברה זו, הסוכן יכול לבחור בה באמצעות ` external_ocr ` עם ` authorization_basis: "existing_task" `, ` task_authorizes_external_processing: true `, ו־` policy_version ` ו־` text_sha256 ` מתוך ` external_ocr_delegated_policy `. אין צורך בבקשת אישור נוספת מטעם FINLY או בהעתקת hash בידי הלקוח. זוהי הצהרת הסוכן; ה־hash מקבע את הודעת הספק ואינו ראיה שהלקוח ראה או אישר אותה. הסוכן אחראי להיקף ההרשאה. ללא הרשאה כזו נשארים בעיבוד מקומי, או משתמשים במסלול האישור הנפרד הקודם עם ` approved: true ` ופרטי ` external_ocr_policy `. [מדיניות הפרטיות](https://finly.co.il/privacy) מתארת את ספק העיבוד והעברת המידע.

### מגבלות ואבטחת בקשה

עד 18 MiB לקובץ לאחר פענוח base64 ועד 25 MiB לגוף JSON. זמן העיבוד מוגבל ל־120 שניות. לא שולחים שדות של שם קובץ, כתובת קובץ, אימייל או מזהי לווים.

אתגר האבטחה תקף לעשר דקות, כבול לכתובת ה־IP ומשמש פעם אחת. מחשבים ` SHA-256(security_challenge + ':' + security_proof) ` עד ששני הבתים הראשונים הם אפס, כלומר 16 ביטים אפסיים. יש לקבל את האתגר ולשלוח את הניתוח מאותה כתובת יציאה לרשת. זהו proof-of-work להגבלת ניצול השירות, ואינו הוכחת הסכמת משתמש.

### תוצאה שאבדה, בלי העלאה נוספת

הקובץ המקורי אינו נשמר. כשמצרפים ` operation `, התוצאה נשמרת בזיכרון תהליך מוצפן למשך עד 15 דקות ממועד הנפקת הפעולה. אין הארכת תוקף בקריאה, והפעלה מחדש של השירות מאבדת אותה. בקשה ישנה ללא ` operation ` נשארת ללא שמירת תוצאה.

הכלי ` get_report_analysis_result ` זמין ב־` POST /agent/v1/reports/tools/get_report_analysis_result `. שולחים בגוף ` operation ` עם ` result_handle ` ו־` result_token ` שנשמרו לפני ההעלאה. אם העיבוד נמשך, ממתינים לפי התשובה; אין להעלות את הדוח מחדש. אם הפעולה פגה או נמחקה, התוצאה אינה ניתנת לשחזור מהשירות.

הכלי ` delete_report_analysis_result ` זמין ב־` POST /agent/v1/reports/tools/delete_report_analysis_result ` עם אותה פעולה בגוף. הוא מבטל עבודה שטרם הסתיימה ומוחק תוצאה זמינה. אותו מזהה עם אותו קובץ ואופן עיבוד אינו מפעיל ניתוח נוסף; תוכן שונה באותה פעולה נדחה.

המפתח מאפשר גישה לתוצאה: אין לשים אותו בכתובת, בצילום מסך, ביומן משותף או בהודעה לאדם אחר. בתשובת ` 429 ` ממתינים לפי ` Retry-After `. כותרות ` RateLimit ` ו־` RateLimit-Policy ` מציגות את מכסת בקשות ה־HTTP המקומית שנמדדה; מכסת הניתוחים נבדקת בנפרד.

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

### לקוח שורת פקודה להורדה

[הורדת לקוח FINLY ל־Node.js](https://finly.co.il/developers/agent-report-client.mjs). הקובץ עצמאי ואינו דורש גישה למאגר הקוד, חשבון או חבילת לקוח נוספת. לאחר הורדתו, ברירת המחדל מציגה דרישות בלבד ואינה מעלה קובץ:

```
node agent-report-client.mjs --requirements
```

לניתוח רגיל מספיק ` --file ` ונתיב מקומי. הוספת ` --output ` שומרת אצלכם דוח אנושי ב־UTF-8: סיומת ` .html ` לדוח HTML בעברית מימין לשמאל, או ` .txt ` לטקסט קריא. שמירה זו מקומית; היא אינה מוסיפה שמירה בשרת FINLY.

```
node agent-report-client.mjs --file "report.pdf" --output "finly-analysis.html"
```

לפני ההעלאה הלקוח יוצר קובץ שחזור פרטי לצד קובץ הקלט או הפלט. אפשר לבחור את מיקומו באמצעות ` --recovery-file `. הקובץ מכיל את מפתח התוצאה ותוקפו, ולכן שומרים אותו באופן פרטי. אם לא ניתן לשמור אותו בבטחה, הדוח לא מועלה.

```
node agent-report-client.mjs --resume "operation.recovery.json" --output "finly-analysis.html"
```

מחליפים את שם הדוגמה בנתיב ` recovery.path ` שהלקוח החזיר. הפקודה אוספת תוצאה קיימת בלבד. למחיקה משתמשים ב־` --delete-result "operation.recovery.json" `; אין בכך מחיקה של דוח שכבר נשמר במחשב שלכם.

הלקוח אינו דורס קובץ קיים. אם השמירה המקומית נכשלת, פלט ה־JSON עדיין כולל את ` result ` ובנוסף ` save_error `. אין צורך בניתוח או בהעלאה נוספים: אם ` result.document ` זמין, אפשר לשמור את תוכנו מהתשובה שכבר התקבלה בשם קובץ אחר.

**הורידו מחדש את הלקוח אם יש אצלכם עותק קודם.** ` --approve-policy ` מיושן ומתעלמים ממנו. רק כשהרשאת המשימה כוללת את העברת הדוח ל־Google Document AI מחוץ לישראל, בוחרים ` --task-authorizes-external-ocr `; הלקוח מאמת את הודעת הספק ושולח את גרסתה וה־hash שלה אוטומטית. למסלול האישור הנפרד הקודם נשמר ` --approve-external-ocr ` עם ה־hash הנוכחי שאושר. אין לשלב את שני הדגלים, וללא אחד מהם העיבוד מקומי. הלקוח מסרב למדיניות שאינה תקפה ולהפניות HTTP, ואינו מנסה להעלות את הדוח שוב אוטומטית.

## חיבור לידע ולחישובים

כתובת MCP ציבורית: ` https://finly.co.il/mcp `. התעבורה היא Streamable HTTP עם תשובות JSON. לקוחות בגרסת ` 2025-11-25 ` או ` 2025-06-18 ` או ` 2025-03-26 ` יכולים להתחבר באמצעות initialization רגיל.

לקוחות ` 2026-07-28 ` שולחים את גרסת הפרוטוקול ואת היכולות בכל בקשה. לדוגמה, גילוי שרת:

```
POST /mcp
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover

{
  "jsonrpc": "2.0",
  "id": "discover-1",
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}
```

בקריאת ` tools/call ` מוסיפים גם ` Mcp-Name ` שתואם לשם הכלי. פרטי המטא־דאטה וכותרות הבקשה חייבים להתאים. אין צורך ב־Resources או Prompts כדי להשתמש בכלים.

[קטלוג וסכמות JSON](https://finly.co.il/developers/public-manifest.json) · [חוזה OpenAPI](https://finly.co.il/developers/public-openapi.json)

הקבצים הם צילום של חוזה הבנייה. בשירות פעיל מגלים את הכלים הזמינים דרך ` tools/list ` או ` GET /agent/v1/public/capabilities `.

## כלי הידע והחישוב

| כלי | מה מקבלים |
| --- | --- |
| ` get_capabilities ` | כלים זמינים וקטלוג מזהי נושאים, שאלות ומדריכים. |
| ` search_public_knowledge ` | חיפוש שאלה כללית בעברית בתוך הידע הציבורי המאושר, עם מקורות ותאריכים. |
| ` search_mortgage_knowledge ` | מידע מאושר לפי מזהה נושא או שאלה מהקטלוג. |
| ` get_claim ` | טענה מסוימת, מקורה וגרסתה. |
| ` get_guide ` | שלבי מדריך וקישור למקור. |
| ` calculate_payment ` | תשלום תאורטי בריבית קבועה, ללא הצמדה. |
| ` calculate_ltv_ratio ` | יחס סכום ההלוואה לשווי הנכס. |
| ` calculate_pti_ratio ` | יחס ההחזר להכנסה, לפי הגדרת הקלט. |

לחיפוש כללי משתמשים ב־` search_public_knowledge ` עם ` {"query":"איך אני מוציא דוח יתרות מבנק לאומי","locale":"he","limit":5} `. השאלה באורך 2–160 תווים, ובעברית; אין להזין בה פרטי לקוח או תוכן דוח. לחיפוש לפי מזהה מתחילים ב־` get_capabilities ` עם ` {"locale":"he"} `, ובוחרים מזהה עבור ` search_mortgage_knowledge `. אין בכלי הידע שדה להעלאת מסמך; דוחות שולחים לשירות הדוחות הנפרד.

### אותו חישוב דרך REST

כתובת הבסיס: ` https://finly.co.il/agent/v1/public `. גילוי כלים: ` GET /capabilities `; חוזה חי: ` GET /openapi.json `. נתיבי הדוגמה להלן יחסיים ל־` https://finly.co.il `.

```
POST /agent/v1/public/tools/calculate_payment
Content-Type: application/json

{
  "principal_agorot": 100000000,
  "nominal_annual_decimal": 0.05,
  "term_months": 240
}
```

כסף נמסר באגורות שלמות. ריבית שנתית נומינלית נמסרת כשבר עשרוני: ` 0.05 ` פירושו 5%. תוצאות החישוב הן היפותטיות; יחסי LTV ו־PTI אינם קביעת זכאות או הצעת בנק.

## קוראים את הסטטוס לפני התוצאה

רק תשובה עם ` status: "success" ` כוללת ` result `. בכל מצב אחר חוזר ` no_action ` עם קוד מפורש. אין להסיק הצלחה מקוד HTTP בלבד.

- ` insufficient_data ` — מתקנים קלט לפי הסכמה; לא משלימים נתון בניחוש.
- ` needs_review ` או ` stale_data ` — המידע אינו זמין כעובדה עדכנית.
- ` approval_required ` — קיימת הצעה שממתינה לאדם; הפעולה טרם בוצעה.
- ` revoked ` או ` expired ` — נדרשת הרשאה חדשה.
- ` 429 ` — ממתינים לפי ` Retry-After `.

משמרים את ` request_id ` לצורך בירור, ומציגים את ההנחות והמגבלות הרלוונטיות. מידע מצוטט נשען על ` evidence ` ועל תאריך הבדיקה של המקור.

## גילוי וחיבור אוטומטי

[קטלוג API לפי RFC 9727](https://finly.co.il/.well-known/api-catalog) מפנה לשני שירותי MCP ציבוריים ולחיבורי Office ו־Customer המוגנים, עם חוזי OpenAPI, מטא־דאטה של הרשאה ותיעוד בכתובות מוחלטות. חיבור מוגן דורש הפעלה והרשאה; הופעתו בקטלוג אינה מבטיחה שהוא פעיל, וכתובת שלא הופעלה עשויה להחזיר 404. אפשר לקרוא גם את [התיעוד ב־Markdown](https://finly.co.il/developers/index.md) ואת [ההפניה הציבורית המורחבת](https://finly.co.il/llms-full.txt).

[מצב ממשקי הגילוי הציבוריים](https://finly.co.il/status) מציג בדיקה מוגבלת מהמכשיר שלכם וזמן בדיקה. הוא אינו בודק ניתוח דוח, חיבורי לקוח או את כלל מערכות FINLY.

קריאות לכלים מיועדות לסוכנים בצד השרת או למקורות דפדפן שאושרו במפורש. אין תמיכת CORS כללית לסוכן מכל אתר; זמינות מטא־דאטה בדפדפן אינה מתירה קריאה לכלים ממקור זר.

[כרטיס שרת הידע](https://finly.co.il/.well-known/mcp/server-card.json) מוצע לפי טיוטת Draft SEP-1649; [אינדקס Skills](https://finly.co.il/.well-known/agent-skills/index.json) מוצע לפי טיוטת Draft 0.2.0, עם קובץ הוראות ציבורי וגיבוב לבדיקת שלמותו. אלה אפשרויות גילוי ללקוחות שתומכים בטיוטות, ולא הבטחה להתקנה או לגילוי בכל סוכן.

קובצי הרישום ל־MCP Registry הוכנו לפרסום; FINLY אינה מציגה זאת כרישום שכבר בוצע. החיבור הישיר בכתובות שלמעלה אינו תלוי ברישום.

## חיבור משרד בהרשאה

חיבור Office תלוי בהגדרת השירות ולקוח OAuth מורשה: לקוח רשום מראש, או מסמך מטא־דאטה של לקוח כאשר CIMD הופעל במפורש. החיבור דורש OAuth עם PKCE S256 ואישור מפורש של אדם מחובר ב־FINLY. מטא־דאטה אינה מקנה הרשאה. כל חיבור מוגבל לפעולות שהאדם אישר ולהרשאותיו הנוכחיות. אפשר לבטל חיבור במסך ״חיבורי סוכנים״.

כלי הצעה מחזירים קבלה וקישור לאישור בתוך FINLY. הכנת טיוטת הודעה אינה שליחתה: קבלה עם ` action_effect: "prepared_draft_only" ` מעידה על הכנת טיוטה בלבד.

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

## מעקב ובקשת חזרה בהרשאת הלקוח

**מצב: הרחבה מקומית הממתינה לפריסה ולהפעלה.** התיאור אינו אישור שהכלים זמינים באתר או פורסמו ב־MCP Registry. המעקב תלוי ב־` AGENT_CUSTOMER_MONITORING_ENABLED `, ו־webhook דורש גם ` AGENT_CUSTOMER_WEBHOOKS_ENABLED `. אחרי ההפעלה מגלים את הכלים וה־scopes בפועל דרך השירות המוגן.

משתמשים בשרת ההרשאה שמפורסם ב־` WWW-Authenticate `, ב־PKCE S256 וב־` resource ` המלא המדויק של ` /mcp/customer `. נקודת ההרשאה בשרת המנפיק היא ` /public/agent-oauth/authorize `; היא מפנה Customer אל ` /portal/agent/connect ` במקור פורטל הלקוח המוגדר. הלקוח מתחבר, בוחר תיק אחד, scopes ותוקף של עד 30 ימים, ומאשר במפורש. צפייה וביטול זמינים ב־` /portal/agents `. אין להסיק הרשאה ממייל, ממטא־דאטה או ממפתח של תוצאת דוח.

- ` watch_refinance_opportunities ` פותח מעקב; ` get_refinance_watch ` קורא מצב; ` list_refinance_watch_events ` קורא אירועים; ` cancel_refinance_watch ` מבטל מעקב.
- ` request_advisor_handoff ` יוצר משימת חזרה; ` get_advisor_handoff ` קורא את מצבה. ` requested ` מעיד שמשימה נוצרה, ולא שהיועץ כבר טיפל.
- ` register_refinance_webhook ` מאמת יעד HTTPS להתראות מתוך מטא־דאטת הלקוח המאושרת.

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

צירוף ניתוח דורש בנוסף את ה־scope ` customer:attach_report_context ` שנבחר בהרשאת הפורטל; זה אינו כלי נפרד. מעבירים את פרטי הפעולה הפרטיים בשדה ` analysis_context ` בגוף בקשת החזרה, ולא בכתובת URL. תוצאת הניתוח המאומתת נשמרת מוצפנת, ללא קובץ ה־PDF או מפתח השליפה. הגישה מסתיימת במוקדם מבין תפוגת ההרשאה ו־30 ימים מהצירוף; לאחר התפוגה התוצאה נמחקת במחזורי הניקוי. קריאת היועץ דורשת הרשאה ושיתוף תקפים ונרשמת ביומן ביקורת. ביטול הרשאה ומחיקת פרטי התיק שולטים בגישה ובמחיקה; הם אינם מוחקים עותקים שכבר נמסרו לסוכן.

יעד webhook נבחר מצילום המטא־דאטה המאושר והקבוע של הלקוח הרשום או CIMD ומאומת ב־challenge. האירועים חתומים וכוללים מזהי אירוע ומעקב, זמן וסיבות בדיקה; אין בהם שמות, תוכן דוח, יתרות או ריביות. שומרים את סוד החתימה באופן פרטי ומזהים ניסיונות חוזרים לפי ` event_id `. אירועים זמינים עד שבעה ימים, ולאחר תפוגתם נמחקים במחזורי הניקוי. ביטול או תפוגת הרשאה חוסמים גישה ומשלוחים חדשים, ואינם מבטלים משימת טיפול שהמשרד כבר קיבל. פרטי השמירה והנמענים ב־[מדיניות הפרטיות](https://finly.co.il/privacy).