# חברו את חשבון ה-Coach שלכם לכל כלי AI: MCP, API ו-Webhooks

> חברו את חשבון ה-Coach שלכם ל-ChatGPT, ל-Claude, ל-Claude Code ול-Cursor דרך MCP, או לאוטומציות משלכם עם REST API ו-Webhooks. התחברות OAuth או מפתחות API עם הרשאות, ישירות מההגדרות בחשבון.

Canonical: https://www.coach-platform.com/developers
Last updated: 2026-09-25

הגישה ל-API ול-MCP מגיעה מחשבון ה-Coach שלכם: דרך התחברות OAuth מהירה, בלי מפתח, או עם מפתח API שיוצרים בהגדרות, תחת "חיבור ל-AI ואוטומציות". כך ChatGPT, Claude, Claude Code, Cursor או אוטומציות שאתם בונים (או מי שבונה אותן בשבילכם) יכולים לקרוא ולעדכן את המתאמנים, התוכניות, התפריטים והפגישות שלכם, רק בהרשאות שאישרתם.

- **כתובת בסיס ל-REST**: `https://api.coach-platform.com/api/public`
- **שרת MCP**: `https://api.coach-platform.com/api/public/mcp`
- **אימות**: `Bearer cp_live_... או OAuth`
- **תיעוד**: `OpenAPI 3.0 · API v1.0`

**חיבור Claude Code לשרת ה-MCP**

```bash
claude mcp add --transport http coach-platform \
  https://api.coach-platform.com/api/public/mcp \
  --header "Authorization: Bearer cp_live_..."
```

**בדיקת זמינות, בלי מפתח**

```bash
curl https://api.coach-platform.com/api/public/health
```

```json
{"status":"ok","timestamp":"2026-09-25T12:05:29.782Z","version":"1.0"}
```

## סוכן מובנה, MCP או API: שלושה ערוצים נפרדים

שלושת הערוצים עובדים מול אותם נתונים של החשבון שלכם, אבל הם לא אותו דבר. הסוכן המובנה רץ בתוך Coach, ואילו שרת ה-MCP וה-API מחברים לחשבון כלים חיצוניים, לפי ההרשאות שאישרתם לכל חיבור.

### הסוכן המובנה של Coach

בתוך החשבון שלכם, בלי קוד ובלי חיבור

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

### שרת MCP

ל-ChatGPT, Claude, Claude Code ו-Cursor שאתם כבר עובדים איתם

MCP (Model Context Protocol) הוא תקן פתוח שמאפשר לעוזרי AI להשתמש בכלים של מערכות אחרות. אחרי שמחברים אותו לחשבון ה-Coach שלכם, כלי ה-AI שאתם עובדים איתו מקבל גישה לתמונת המצב של המתאמנים, למעקב ההיענות, לתוכניות, לתפריטים, לפגישות ולמשימות, לפי ההרשאות שאישרתם.

### REST API ו-Webhooks

לאוטומציות שלכם ב-Make, ב-Zapier או בקוד

לאוטומציות שאתם בונים, או שמישהו בונה בשבילכם, על הנתונים של החשבון: JSON מעל HTTPS, מפתח API עם הרשאות נפרדות, מפרט OpenAPI מלא ו-Idempotency-Key לניסיונות חוזרים בטוחים. Webhooks חתומים ב-HMAC מודיעים למערכת שלכם על מתאמן חדש, אימון שנרשם, פגישה שנקבעה או טופס שמולא.

## חברו את החשבון שלכם ל-Claude, ל-ChatGPT, ל-Claude Code ול-Cursor

כתובת שרת ה-MCP זהה בכל הכלים, והגישה תמיד עוברת דרך חשבון ה-Coach שלכם. ב-Claude וב-ChatGPT מתחברים ב-OAuth דרך מסך האישור של Coach, בלי מפתח. בכלי פיתוח משתמשים במפתח API שיוצרים בהגדרות, תחת "חיבור ל-AI ואוטומציות".

**כתובת שרת ה-MCP (Streamable HTTP)**

```
https://api.coach-platform.com/api/public/mcp
```

### Claude

claude.ai, אפליקציית Claude למחשב ו-Cowork. OAuth, בלי מפתח.

1. ב-Claude נכנסים ל-**Customize › Connectors**, לוחצים על **+** ובוחרים **Add custom connector**.
2. מדביקים את כתובת שרת ה-MCP של Coach ולוחצים **Add**.
3. Claude פותח את מסך ההתחברות של Coach. מתחברים לחשבון, מסמנים אילו הרשאות לתת ומאשרים.
4. בשיחה חדשה מפעילים את המחבר דרך הכפתור **+** ואז **Connectors**, ומבקשים, למשל: "מי מהמתאמנים שלי בסיכון לנשירה?". לפני שכלי רץ, Claude מבקש אישור.

בחשבונות Team ו-Enterprise, בעלי הארגון מוסיפים את המחבר תחת **Organization settings › Connectors**. רק בעל חשבון ה-Coach יכול לאשר חיבור OAuth.

### ChatGPT

ChatGPT, דרך Plugins. OAuth, בלי מפתח.

1. ב-ChatGPT נכנסים ל-**Settings › Plugins** ולוחצים על **Browse directory**.
2. לוחצים על **Add** ובוחרים **Add custom MCP server**.
3. בשדה **Name** כותבים **Coach Platform** ומדביקים את כתובת שרת ה-MCP של Coach.
4. ChatGPT מפנה למסך ההתחברות של Coach. מתחברים, מסמנים הרשאות ומאשרים.
5. בשיחה חדשה מוסיפים את החיבור מתפריט הכלים. פעולות כתיבה דורשות אישור כברירת מחדל.

לפי התיעוד של OpenAI, שרתי MCP מותאמים אישית זמינים בחשבונות Plus, Pro, Business, Enterprise ו-Edu, בגרסת הדפדפן. השרת של Coach מממש גם את הכלים `search` ו-`fetch`, שבהם ChatGPT משתמש לחיפוש ולמחקר מעמיק (Deep Research).

### Claude Code

CLI בטרמינל. מפתח API.

1. בלוח הבקרה של Coach נכנסים להגדרות, בוחרים "חיבור ל-AI ואוטומציות", עוברים ללשונית Claude, פותחים את "חיבור עם מפתח ידני" ויוצרים מפתח חיבור. המפתח המלא מוצג פעם אחת בלבד.
2. מריצים את הפקודה בטרמינל, עם המפתח שלכם במקום `cp_live_...`.
3. בתוך Claude Code מריצים `/mcp` כדי לוודא שהשרת מחובר.

**Claude Code**

```bash
claude mcp add --transport http coach-platform \
  https://api.coach-platform.com/api/public/mcp \
  --header "Authorization: Bearer cp_live_..."
```

Claude Code וכלי פיתוח אחרים מתחברים עם מפתח API, כי ההתחברות ב-OAuth זמינה כרגע רק מ-Claude ומ-ChatGPT.

### Cursor

קובץ mcp.json או התקנה בקליק. מפתח API.

1. יוצרים מפתח חיבור בלוח הבקרה, כמו ב-Claude Code. מיד אחרי היצירה מופיע שם גם הכפתור "הוסף ל-Cursor בקליק".
2. או מוסיפים את ההגדרה ידנית לקובץ `~/.cursor/mcp.json` כדי שתעבוד בכל הפרויקטים, או לקובץ `.cursor/mcp.json` בתיקיית הפרויקט.

**~/.cursor/mcp.json**

```json
{
  "mcpServers": {
    "coach-platform": {
      "url": "https://api.coach-platform.com/api/public/mcp",
      "headers": {
        "Authorization": "Bearer cp_live_..."
      }
    }
  }
}
```

### כל לקוח MCP אחר

כל לקוח שתומך ב-Streamable HTTP מתחבר לאותה כתובת, עם הכותרת `Authorization: Bearer cp_live_...` או `X-API-Key`. פרטי השרת, רשימת הכלים עם ההרשאה שכל כלי דורש ופרופילי הכלים זמינים בלי אימות ב-`GET /api/public/mcp/info`, כולל הגדרה מומלצת לחיבור דרך Claude API.

## מה עוזר AI יכול לעשות בחשבון שלכם

שרת ה-MCP חושף יותר מ-240 כלים. העוזר רואה רק את הכלים שההרשאות של החיבור מאפשרות, וכלי כתיבה תומכים בתצוגה מקדימה (dryRun) לפני שמירה. הנה חלק מהם, לפי תחום:

### תמונת מצב של העסק והמתאמנים

סקירה של כל העסק, מי מתחיל להתרחק ותמונה מלאה של מתאמן בקריאה אחת.

`get_business_overview`, `find_at_risk_trainees`, `get_trainee_overview`, `search`, `fetch`

### אימונים

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

`get_active_training_plan`, `get_exercise_performance`, `get_trainee_personal_records`, `assign_training_plan`, `update_training_plan`, `create_workout_block`

### תזונה

התפריט הפעיל, יומן האכילה והשוואה בין מה שתוכנן למה שנאכל בפועל.

`get_active_nutrition_menu`, `list_trainee_nutrition_log`, `get_nutrition_adherence`, `assign_nutrition_menu`, `create_recipe`

### מעקב והיענות

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

`get_monitoring_overview`, `list_training_inactive`, `list_incomplete_updates`, `list_stalled_exercises`

### תקשורת, משימות ופגישות

התראות באפליקציה, שיחות, משימות, פגישות והערות על תקופת הליווי.

`send_notification`, `get_conversations`, `create_task`, `create_meeting`, `add_escort_note`

### מסעות לקוח, טפסים ותזמון

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

`enroll_trainee_in_journey`, `schedule_plan_change`, `list_journeys`, `create_form`, `list_form_responses`

### פרופיל כלים לכל חיבור

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

| פרופיל | מזהה | היקף | תיאור |
| --- | --- | --- | --- |
| ליבה | `core` | כ-40 כלים | הכלים היומיומיים: סקירת מתאמן, תוכניות ותפריטים פעילים, מעקב, צ׳אט, משימות ופגישות. זו ברירת המחדל של כל חיבור חדש, והיא נותנת את הדיוק הגבוה ביותר. |
| אימון מלא | `coaching` | כ-160 כלים | כל העבודה היומיומית של מאמן, כולל פריודיזציה, מסעות לקוח, טפסים, הערות ותזמון. בלי ניהול צוות, גיימיפיקציה, תוכן וספריות. |
| הכול | `full` | יותר מ-240 כלים | כל הכלים שההרשאות מאפשרות. מתאים ללקוחות שיודעים לטעון כלים לפי דרישה, למשל בעזרת חיפוש כלים. |

## שש אוטומציות שאפשר להפעיל על החשבון שלכם

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

### ליד מהאתר הופך למתאמן

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

נשען על: `POST /trainees`, `POST /escorts`, `POST /journeys/{journeyId}/enroll`

### סיכום שבועי למאמן

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

נשען על: `GET /monitoring/overview`, `GET /monitoring/training`, `GET /monitoring/nutrition`, `GET /monitoring/incomplete-updates`

### אוטומציות ב-Make וב-Zapier

טופס שמתאמן ממלא, פגישה שנקבעת או מדידה שנרשמת נשלחים אוטומטית ל-Google Sheets, ל-Slack או לכל כלי אחר, בלי לכתוב קוד. בלוח הבקרה יש הוראות מוכנות ל-Make ול-Zapier.

נשען על: `webhook form.response.received`, `webhook meeting.scheduled`, `webhook measurement.recorded`

### דשבורד היענות ותוצאות

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

נשען על: `GET /workout-logs`, `GET /trainees/{traineeId}/weekly-activity`, `GET /trainees/{traineeId}/personal-records`, `GET /quick-wins`

### תוכניות ותפריטים שנבנים עם AI

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

נשען על: `get_active_escort`, `get_exercise_performance`, `update_training_plan`, `assign_nutrition_menu`

### חיבור לסליקה או לחנות חיצונית

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

נשען על: `GET /products`, `POST /purchases`, `POST /notifications`

## התחלה מהירה עם ה-REST API

ה-REST API משמש לאוטומציות על הנתונים של החשבון שלכם, בין שאתם כותבים אותן ובין שמישהו בונה אותן בשבילכם. כל הבקשות נשלחות ב-HTTPS לכתובת הבסיס `https://api.coach-platform.com/api/public`, בפורמט JSON. תשובה תקינה מחזירה אובייקט `data`, ושגיאה מחזירה אובייקט `error` עם קוד קבוע.

### 1. אימות עם מפתח API

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

**כותרת אימות (אחת מהשתיים)**

```http
Authorization: Bearer cp_live_...
X-API-Key: cp_live_...
```

### 2. קריאה ראשונה

רשימת המתאמנים שיש להם תקופת ליווי פעילה, 25 בכל עמוד. כל רשימה מחזירה גם אובייקט `pagination` עם `page`, `limit`, `total` ו-`hasMore`. גודל עמוד הוא 25 כברירת מחדל ועד 500.

**curl**

```bash
COACH_API=https://api.coach-platform.com/api/public

curl "$COACH_API/trainees?status=active&limit=25" \
  -H "Authorization: Bearer cp_live_..."
```

**תשובה (200)**

```json
{
  "data": [
    {
      "id": "65f2a1b3c4d5e6f7a8b9c0d1",
      "name": "Dana Cohen",
      "email": "dana@example.com",
      "phoneNumber": "0501234567",
      "createdAt": "2026-09-01T08:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "hasMore": false
  }
}
```

### 3. יצירה בטוחה עם Idempotency-Key

שולחים מזהה ייחודי בכותרת `Idempotency-Key`. אם אותה בקשה נשלחת שוב בתוך 24 שעות, חוזרת התשובה המקורית עם הכותרת `Idempotent-Replay: true` ולא נוצר מתאמן כפול. הכותרת נתמכת ב-POST, PATCH ו-DELETE, ושימוש חוזר באותו מזהה עם גוף אחר מחזיר 409 `IDEMPOTENCY_KEY_REUSED`. ביצירת מתאמן, השדות name, email ו-phoneNumber הם חובה.

**curl**

```bash
COACH_API=https://api.coach-platform.com/api/public

curl -X POST "$COACH_API/trainees" \
  -H "Authorization: Bearer cp_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Dana Cohen",
    "email": "dana@example.com",
    "phoneNumber": "0501234567"
  }'
```

### 4. שגיאות

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

| סטטוס | קוד | משמעות |
| --- | --- | --- |
| 401 | `UNAUTHORIZED` | המפתח חסר או לא בפורמט הנכון |
| 401 | `INVALID_API_KEY` | המפתח לא מוכר, למשל אחרי שנמחק |
| 403 | `INSUFFICIENT_SCOPE` | למפתח חסרה ההרשאה שנקודת הקצה דורשת |
| 404 | `NOT_FOUND` | המשאב לא קיים או לא שייך לחשבון |
| 409 | `CONFLICT` | התנגשות, למשל עריכה של תוכנית שמשותפת לכמה מתאמנים |
| 429 | `RATE_LIMITED` | חריגה ממגבלת הבקשות לדקה |
| 429 | `DAILY_QUOTA_EXCEEDED` | המכסה היומית של המפתח נוצלה |

הרשימה המלאה, עם הסבר ודרך תיקון לכל קוד, זמינה בלי אימות ב-`GET /api/public/errors`.

**תשובה (403)**

```json
{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Missing required scope: trainees:write",
    "fix": "Edit the key and grant the missing scope."
  }
}
```

### נקודות הקצה לפי תחום

109 פעולות ב-88 נתיבים, לפי מפרט ה-OpenAPI. כל הנתיבים מתחילים ב-`/api/public`, והפירוט המלא של כל פעולה נמצא בתיעוד.

| תחום | פעולות | דוגמאות |
| --- | --- | --- |
| גילוי ועיון, בלי אימות | 6 פעולות | `GET /health`, `GET /catalog` |
| פרופיל המאמן | פעולה אחת | `GET /me` |
| מתאמנים | 13 פעולות | `GET /trainees`, `POST /trainees` |
| תוויות | 5 פעולות | `GET /labels`, `POST /trainees/{traineeId}/labels` |
| תקופות ליווי | 9 פעולות | `POST /escorts`, `POST /escorts/notes/bulk` |
| תוכניות אימון | 7 פעולות | `GET /training-plans`, `POST /training-plans` |
| יומני אימון | 2 פעולות | `GET /workout-logs`, `GET /trainees/{traineeId}/exercise-notes` |
| מאגר התרגילים | 4 פעולות | `GET /exercises`, `GET /exercises/settings` |
| תפריטי תזונה | 10 פעולות | `GET /nutrition-menus`, `GET /food-items` |
| פגישות | 5 פעולות | `GET /meetings`, `POST /meetings` |
| טפסים ועדכונים | 7 פעולות | `GET /forms`, `GET /forms/registration` |
| התראות באפליקציה | 2 פעולות | `POST /notifications`, `POST /notifications/bulk` |
| מעקב והיענות | 19 פעולות | `GET /monitoring/overview`, `GET /monitoring/training` |
| מסעות לקוח | 8 פעולות | `GET /journeys`, `GET /journeys/enrollments` |
| צוות | פעולה אחת | `GET /employees` |
| מוצרים | 2 פעולות | `GET /products`, `GET /products/{productId}` |
| רכישות | 7 פעולות | `GET /purchases`, `POST /purchases` |
| Webhooks | פעולה אחת | `GET /webhooks` |

[לכל נקודות הקצה בתיעוד ה-API](https://www.coach-platform.com/docs/api). מפרט ה-OpenAPI המלא: [https://www.coach-platform.com/openapi.json](https://www.coach-platform.com/openapi.json)

## הרשאות, מגבלות קצב ומכסות

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

| הרשאה | מזהה | רגישה |
| --- | --- | --- |
| קריאת מתאמנים | `trainees:read` |  |
| כתיבת מתאמנים | `trainees:write` | רגישה |
| קריאת תוויות | `labels:read` |  |
| כתיבת תוויות | `labels:write` |  |
| קריאת תקופות ליווי | `escorts:read` |  |
| כתיבת תקופות ליווי | `escorts:write` |  |
| קריאת תזונה | `nutrition:read` |  |
| כתיבת תזונה | `nutrition:write` |  |
| קריאת אימונים | `workouts:read` |  |
| כתיבת אימונים | `workouts:write` |  |
| קריאת פגישות | `meetings:read` |  |
| כתיבת פגישות | `meetings:write` |  |
| קריאת עובדים | `employees:read` |  |
| קריאת שיחות וסימון צ׳אטים | `messaging:read` |  |
| שליחת הודעות WhatsApp | `messaging:send` | רגישה |
| שליחת התראות | `notifications:send` | רגישה |
| קריאת מעקב | `monitoring:read` |  |
| כתיבת מעקב | `monitoring:write` |  |
| קריאת מסעות לקוח | `journeys:read` |  |
| כתיבת מסעות לקוח | `journeys:write` |  |
| קריאת משימות | `tasks:read` |  |
| כתיבת משימות | `tasks:write` |  |
| קריאת טפסים | `forms:read` |  |
| כתיבת טפסים | `forms:write` |  |
| קריאת מדריכים ומסמכים | `content:read` |  |
| כתיבת מדריכים ומסמכים | `content:write` |  |
| קריאת גיימיפיקציה | `gamification:read` |  |
| הענקת נקודות ניסיון | `gamification:write` |  |
| ניהול חשבון | `admin:manage` | רגישה |
| קריאת Webhooks | `webhooks:read` |  |
| קריאת פרופיל מאמן | `coach:read` |  |
| קריאת מוצרים | `products:read` |  |
| קריאת רכישות | `purchases:read` |  |
| רישום רכישות למתאמן | `purchases:write` | רגישה |

### מגבלות קצב ומכסות

| מגבלה | ערך |
| --- | --- |
| בקשות לדקה, לכל מפתח | 120 כברירת מחדל. אפשר להגדיר לכל מפתח ערך עד 6,000. |
| מכסה יומית לקריאות REST | 5,000 בקשות כברירת מחדל, מתאפסת בחצות לפי שעון ישראל. אפשר לשנות או לבטל אותה. |
| נקודות קצה בלי אימות | 60 בקשות לדקה לכל כתובת IP. |
| גודל גוף הבקשה | עד 1MB. |
| עימוד | 25 פריטים בעמוד כברירת מחדל, ועד 500. |
| Idempotency-Key | התשובה נשמרת ל-24 שעות, ב-POST, PATCH ו-DELETE. |
| התראות באפליקציה | עד 10 התראות דרך ה-API לכל מתאמן ביום. |
| רישום למסע לקוח | רישום אחד בשנייה לכל חשבון. |

חריגה ממגבלת הדקה מחזירה 429 `RATE_LIMITED` עם הכותרת `Retry-After`, וחריגה מהמכסה היומית מחזירה 429 `DAILY_QUOTA_EXCEEDED`. כשמוגדרת מכסה יומית, כל תשובה כוללת את הכותרות `X-Coach-Daily-Quota-Limit`, `X-Coach-Daily-Quota-Used` ו-`X-Coach-Daily-Quota-Reset`. מגבלות המערכת זמינות גם בלי אימות ב-`GET /api/public/limits`.

## Webhooks חתומים לאירועים בעסק

בלוח הבקרה (הגדרות, "חיבור ל-AI ואוטומציות", לשונית Webhooks) מגדירים כתובת יעד ובוחרים אירועים. בכל פעם שאירוע כזה קורה, Coach שולחת בקשת POST חתומה. אפשר לסנן לפי מתאמנים, תוויות, עובדים או סניפים, לשלוח בדיקה בלחיצה, לצפות בהיסטוריית המשלוחים ולשלוח מחדש משלוח שנכשל.

### 26 אירועים זמינים

| אירוע | מזהה |
| --- | --- |
| מתאמן חדש נרשם | `trainee.created` |
| פרטי מתאמן עודכנו | `trainee.updated` |
| מתאמן נמחק | `trainee.deleted` |
| מתאמן שוחזר מהארכיון | `trainee.restored` |
| תקופת ליווי חדשה התחילה | `escort.created` |
| תקופת ליווי עודכנה | `escort.updated` |
| תקופת ליווי בוטלה | `escort.canceled` |
| תקופת ליווי הוקפאה | `escort.suspended` |
| תקופת ליווי חזרה מהקפאה | `escort.resumed` |
| תפריט תזונה נוצר | `nutrition.menu.created` |
| תפריט תזונה עודכן | `nutrition.menu.updated` |
| תוכנית אימון נוצרה | `workout.plan.created` |
| תוכנית אימון עודכנה | `workout.plan.updated` |
| אימון נרשם | `workout.log.created` |
| פגישה נקבעה | `meeting.scheduled` |
| פגישה עודכנה | `meeting.updated` |
| פגישה בוטלה | `meeting.canceled` |
| מדידה נרשמה | `measurement.recorded` |
| מילוי טופס התקבל | `form.response.received` |
| ליד חדש נכנס | `lead.created` |
| שלב הליד השתנה | `lead.stage_changed` |
| ליד שויך לעובד | `lead.assigned` |
| ליד ענה | `lead.replied` |
| ליד אבד | `lead.lost` |
| ליד נסגר בהצלחה | `lead.won` |
| ליד הפך למתאמן | `lead.converted` |

**כותרות המשלוח**

```http
Content-Type: application/json
User-Agent: CoachPlatform-Webhook/1.0
X-Coach-Event: trainee.created
X-Coach-Delivery-Id: 66f1c0a2b3c4d5e6f7a8b9c0-trainee-created-a67ab105-2001-4f11-80c7-6e196b0bddd6
X-Coach-Signature: t=1790325731,v1=<hex HMAC-SHA256>
```

**גוף המשלוח (JSON)**

```json
{
  "id": "66f1c0a2b3c4d5e6f7a8b9c0-trainee-created-a67ab105-2001-4f11-80c7-6e196b0bddd6",
  "event": "trainee.created",
  "createdAt": "2026-09-25T08:42:11.123Z",
  "data": {
    "traineeId": "65f2a1b3c4d5e6f7a8b9c0d1",
    "name": "Dana Cohen",
    "email": "dana@example.com"
  }
}
```

### אימות החתימה

הכותרת `X-Coach-Signature` בנויה כך: `t=<unix>,v1=<hex>`. מחשבים HMAC-SHA256 עם הסוד של ה-Webhook (`whsec_...`) על המחרוזת `${t}.${rawBody}`, כלומר על גוף הבקשה הגולמי לפני פענוח ה-JSON, משווים בזמן קבוע ודוחים חותמות זמן ישנות מכמה דקות.

### משלוח וניסיונות חוזרים

- כל ניסיון מחכה לתשובה עד 10 שניות.
- משלוח שנכשל נשלח שוב עד 5 פעמים, בהשהיה שגדלה בכל פעם החל מ-10 שניות.
- ניסיונות חוזרים שומרים על אותו X-Coach-Delivery-Id, אז כדאי לטפל בכל מזהה פעם אחת בלבד.
- אחרי 20 כישלונות רצופים היעד מושבת אוטומטית, ואפשר לשלוח מחדש משלוחים שנכשלו מלוח הבקרה.
- בהחלפת סוד עם תקופת חפיפה נשלחות שתי חתימות v1, ומספיק שאחת מהן תתאים.
- אפשר להגדיר עד 20 יעדים לחשבון, וכתובות שמפנות לרשת פנימית נחסמות.

**Node.js (Express)**

```js
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const secret = process.env.COACH_WEBHOOK_SECRET;
const MAX_AGE_SECONDS = 300;

const isValidSignature = (header, rawBody) => {
  const parts = header.split(',').map((part) => part.split('='));
  const timestamp = parts.find(([key]) => key === 't')?.[1];
  const signatures = parts
    .filter(([key]) => key === 'v1')
    .map(([, value]) => value);
  if (!timestamp || signatures.length === 0) return false;
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > MAX_AGE_SECONDS) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return signatures.some(
    (signature) =>
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)),
  );
};

const rawJson = express.raw({ type: 'application/json' });

app.post('/webhooks/coach', rawJson, (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!isValidSignature(req.get('X-Coach-Signature') ?? '', rawBody)) {
    return res.status(401).end();
  }
  const { event, data } = JSON.parse(rawBody);
  console.log(event, data);
  res.status(200).end();
});

app.listen(3000);
```

## בעל החשבון מחליט מה כל חיבור רואה ועושה

כל גישה ל-Coach מבחוץ עוברת דרך מפתח API או חיבור OAuth עם הרשאות מוגדרות, ואפשר לצמצם, להשבית או לנתק כל אחד מהם בכל רגע.

### הרשאות לכל מפתח

34 הרשאות נפרדות לקריאה, לכתיבה ולשליחה. יש רמות גישה מוכנות (קריאה בלבד, קריאה ועדכון, קריאה ושליחת התראות), והרשאות רגישות כמו שליחת הודעות מסומנות באזהרה.

### OAuth עם מסך אישור

Claude ו-ChatGPT מתחברים דרך מסך האישור של Coach, עם PKCE. הרשאות שליחת ההודעות וההתראות לא מסומנות מראש, ורק בעל החשבון יכול לאשר חיבור. אסימון גישה תקף לשעה, ואסימון רענון ל-30 יום.

### השבתה, מחיקה והחלפה

אפשר להשבית, למחוק או להחליף מפתח בכל רגע. בהחלפה בוחרים תקופת חפיפה, ממיידית ועד 7 ימים, והמפתח הישן ממשיך לעבוד עד סופה עם הכותרת `X-Coach-Deprecated-Key`. מחיקת חיבור OAuth מנתקת אותו.

### הגבלות לכל מפתח

רשימת כתובות IP מותרות, דומיינים מותרים לקריאות מדפדפן, תאריך תפוגה, מגבלת בקשות לדקה ומכסה יומית.

### חיבור נפרד לכל איש צוות

בעל החשבון יכול להפעיל לאיש צוות את ההרשאה "חיבור Claude (MCP)". החיבור שלו רואה רק את המתאמנים שמשויכים אליו ופועל לפי ההרשאות שלו, והרשאת ניהול החשבון אף פעם לא זמינה לו.

### יומן פעולות

יצירה, עריכה והחלפה של מפתחות ו-Webhooks, חיבורי OAuth, כל פעולת כתיבה דרך ה-API או ה-MCP וכל ניסיון גישה שנחסם נרשמים ביומן הפעולות, עם סינון וייצוא ל-CSV.

### תצוגה מקדימה בכלי MCP

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

### המפתח המלא לא נשמר

המפתח מוצג פעם אחת בלבד, ביצירה. אצלנו נשמר רק גיבוב SHA-256 שלו, ובהמשך מוצגת רק הקידומת שמאפשרת לזהות אותו.

### הגנות רשת

שרת ה-MCP מקבל בקשות מדפדפן רק ממקורות מוכרים של לקוחות AI, כהגנה מפני DNS rebinding, ו-Webhooks לא נשלחים לכתובות ברשת פנימית.

## שאלות נפוצות על ה-API וה-MCP של Coach

### מי יכול להשתמש ב-API וב-MCP של Coach?

ה-API וה-MCP מיועדים למאמנים ולתזונאים שעובדים עם Coach. כל חיבור וכל מפתח נוצרים מתוך חשבון קיים, בהתחברות OAuth או בהגדרות תחת "חיבור ל-AI ואוטומציות", ועובדים רק מול הנתונים של אותו חשבון. אפשר למסור מפתח למי שבונה לכם אוטומציות, לתת לו רק את ההרשאות שהוא צריך מתוך 34 הרשאות אפשריות, ולהשבית, למחוק או להחליף את המפתח בכל רגע. איש צוות שמקבל חיבור משלו רואה רק את המתאמנים שמשויכים אליו.

### יש ל-Coach שרת MCP?

כן. שרת ה-MCP של Coach נמצא בכתובת https://api.coach-platform.com/api/public/mcp ועובד בתקן Streamable HTTP. Claude ו-ChatGPT מתחברים אליו ב-OAuth דרך מסך האישור של Coach, בלי מפתח, ו-Claude Code, Cursor וכל לקוח MCP אחר מתחברים עם מפתח API בכותרת Authorization. העוזר רואה רק את הכלים שההרשאות ופרופיל הכלים של החיבור מאפשרים.

### איך מחברים את Claude לחשבון ה-Coach?

ב-Claude נכנסים ל-Customize ואז Connectors, לוחצים על "+" ובוחרים Add custom connector, מדביקים את כתובת שרת ה-MCP ולוחצים Add. Claude פותח את מסך ההתחברות של Coach, שם מסמנים הרשאות ומאשרים. ב-Claude Code מריצים את הפקודה claude mcp add --transport http עם כתובת השרת ועם הכותרת Authorization: Bearer ומפתח שיוצרים בהגדרות של Coach.

### איך מחברים את ChatGPT?

ב-ChatGPT נכנסים ל-Settings ואז Plugins, לוחצים על Browse directory, אחר כך על Add ובוחרים Add custom MCP server. בשדה Name כותבים Coach Platform ומדביקים את כתובת שרת ה-MCP של Coach. ChatGPT מפנה למסך ההתחברות של Coach לאישור ההרשאות. שרתי MCP מותאמים אישית זמינים בחשבונות ChatGPT בתשלום, ופעולות כתיבה דורשות אישור כברירת מחדל.

### מה ההבדל בין הסוכן המובנה של Coach לבין MCP?

הסוכן המובנה הוא עוזר ה-AI שבתוך לוח הבקרה של Coach. הוא עונה על שאלות על העסק ומכין פעולות שמוצגות ככרטיס אישור, בלי שום חיבור חיצוני. MCP הוא ערוץ נפרד, שמאפשר לכלי AI חיצוני כמו ChatGPT, Claude או Cursor להשתמש בכלים של Coach לפי ההרשאות שאושרו. אפשר להשתמש בכל אחד מהם בלי השני.

### איך יוצרים מפתח API?

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

### מה מגבלות הקצב של ה-API?

כל מפתח מוגבל כברירת מחדל ל-120 בקשות בדקה, ואפשר להגדיר לו כל ערך עד 6,000. לקריאות REST יש גם מכסה יומית של 5,000 בקשות כברירת מחדל, שמתאפסת בחצות לפי שעון ישראל ואפשר לשנות או לבטל אותה. חריגה מחזירה 429 עם הקוד RATE_LIMITED או DAILY_QUOTA_EXCEEDED, והכותרות X-Coach-Daily-Quota-Limit, X-Coach-Daily-Quota-Used ו-X-Coach-Daily-Quota-Reset מראות כמה נוצל ומתי המכסה מתאפסת.

### איך מאמתים שקריאת Webhook הגיעה מ-Coach?

כל משלוח מגיע עם הכותרת X-Coach-Signature בפורמט t=<unix>,v1=<hex>. מחשבים HMAC-SHA256 עם הסוד של ה-Webhook (whsec_...) על מחרוזת שמורכבת מחותמת הזמן t, נקודה, וגוף הבקשה הגולמי כפי שהתקבל, לפני פענוח ה-JSON. את התוצאה, בקידוד hex, משווים לערך v1 בהשוואה בזמן קבוע. דוחים משלוח שחותמת הזמן שלו ישנה מכמה דקות, ובתקופת החלפת סוד מקבלים משלוח שאחד מערכי v1 שלו תואם.

### אילו אירועים אפשר לקבל ב-Webhook?

יש 26 אירועים: trainee.created, trainee.updated, trainee.deleted, trainee.restored, escort.created, escort.updated, escort.canceled, escort.suspended, escort.resumed, nutrition.menu.created, nutrition.menu.updated, workout.plan.created, workout.plan.updated, workout.log.created, meeting.scheduled, meeting.updated, meeting.canceled, measurement.recorded, form.response.received, lead.created, lead.stage_changed, lead.assigned, lead.replied, lead.lost, lead.won, lead.converted. הרשימה המלאה, עם מבנה הנתונים של כל אירוע, זמינה בלי אימות ב-GET /api/public/catalog.

### איפה התיעוד המלא?

התיעוד האינטראקטיבי נמצא ב-coach-platform.com/docs/api, ומפרט ה-OpenAPI המלא זמין ב-https://www.coach-platform.com/openapi.json. בנוסף, אפשר לקרוא בלי אימות את GET /api/public/catalog (הרשאות, אירועים וכלי MCP), GET /api/public/errors, GET /api/public/limits, GET /api/public/changelog ו-GET /api/public/llms.txt.

## קישורים נוספים

- [תיעוד ה-API המלא](https://www.coach-platform.com/docs/api)
- [מדריך חיבור ל-ChatGPT ול-Claude, בלי קוד](https://www.coach-platform.com/connect-ai)
- [המחירון של Coach](https://www.coach-platform.com/pricing)
- [מפרט OpenAPI](https://www.coach-platform.com/openapi.json)
