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

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

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

כלי הדוחות והסכמות · חוזה OpenAPI חי לדוחות

1. מתחילים בקריאת get_report_analysis_requirements עם {}. התשובה מפרסמת את נוסח האישור הנוכחי, גרסתו וה־hash שלו, את הקישור למדיניות הפרטיות, את המגבלות ואת אתגר האבטחה.
2. מציגים למשתמש את הנוסח והקישור ומקבלים אישור מפורש לעיבוד הדוח ולהחזרת הניתוח לסוכן הקורא. העלאת קובץ או הוראה כללית להשתמש בכלים אינן מחליפות את האישור הזה.
3. פותרים את אתגר האבטחה ומעבירים את הקובץ אל analyze_balance_report. משתמשים בגרסה וב־hash שהתקבלו בשלב הראשון, בלי להמציא או לשמור בדוגמה ערכים קבועים.
4. קוראים את התוצאה באותה תשובת HTTP. משתמשים ב־result רק כשהסטטוס מציין הצלחה; נתונים חלקיים אינם ניתוח מלא.

אפשר לקבל את הדרישות גם דרך 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 ואת האישור בשדה authorization. בתוך האישור נדרשים שדה הגרסה policy_version, שדה גיבוב הנוסח text_sha256 ושתי הצהרות האישור: user_approved_processing: true וכן user_approved_result_sharing: true, לאחר האישור האנושי. הסכמה המלאה נמצאת בחוזה החי.

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

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

מסמך עם שכבת טקסט קריאה מעובד מקומית. עיבוד OCR חיצוני כבוי כברירת מחדל. לסריקה או צילום ייתכן שנדרש PDF דיגיטלי חדש, או אישור נפרד לנוסח העיבוד מחוץ לישראל שמוחזר בדרישות. רק לאחר אישור זה מצרפים external_ocr עם approved: true, הגרסה וה־hash המתאימים. מדיניות הפרטיות מתארת את ספק העיבוד והעברת המידע.

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

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

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

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

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

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

הורדת לקוח FINLY ל־Node.js. הקובץ עצמאי ואינו דורש גישה למאגר הקוד, חשבון או חבילת לקוח נוספת. לאחר הורדתו, ברירת המחדל מציגה דרישות בלבד ואינה מעלה קובץ:

node agent-report-client.mjs --requirements

לאחר הצגת הנוסח וקבלת אישור המשתמש, מפעילים אותו עם --file ונתיב מקומי, ועם --approve-policy וה־hash המדויק שאושר. רק עבור אישור OCR נפרד מצרפים גם --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 · חוזה OpenAPI

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

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

מתחילים ב־get_capabilities עם {"locale":"he"}, ובוחרים מזהה מהתוצאה. בשבעת כלי הידע והחישוב אין שדה לחיפוש חופשי, להעלאת מסמך או להזנת פרטי זיהוי. להעלאת דוח משתמשים בשירות הדוחות הנפרד שתואר למעלה.

אותו חישוב דרך 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 ועל תאריך הבדיקה של המקור.

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

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

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

שיתוף אישי מתוך פורטל הלקוח וכלי Customer הפרטיים נשארים סגורים. שירות הדוחות הציבורי קורא רק את הקובץ שנשלח באותה בקשה ואינו מקנה גישה לתיקים או למסמכים השמורים ב־FINLY.