API עסקאות

עסקה היא הזדמנות מכירה אחת בלוח ה-Sales Pipeline שלך — כותרת, ערך, השלב שבו היא נמצאת, ובאופן אופציונלי איש הקשר שאליו היא שייכת וחבר הצוות שאליו היא מוקצית. מדריך זה מכסה קריאה וניהול של עסקאות באמצעות ה-API.

כתובת בסיס (Base URL) — https://api.youraiconnector.com/v1
אימות (Authentication) — מפתח ה-API שלך (ראו אימות)
שגיאות ועימוד (Errors & paging) — ראו שגיאות ועימוד

כל הדוגמאות להלן מציגות את טופס השאילתה ?apiKey= ב-cURL ואת הכותרת X-API-Key ב-JavaScript וב-Python — שתי הדרכים עובדות בכל נקודת קצה (endpoint).

אובייקט העסקה

{
  "id": "deal_abc123",
  "title": "Annual plan – Jane's Clinic",
  "description": "Asked for pricing on the annual plan.",
  "company": "Jane's Clinic",
  "notes": "Prefers a call after 5pm.",
  "stage": "stage-2",
  "pipeline_id": "default",
  "value": 4800,
  "probability": 60,
  "priority": "high",
  "status": "open",
  "source": "whatsapp",
  "position": 0,
  "contact_id": "ctc_9f8e7d",
  "assigned_to": "usr_4a2b",
  "tags": ["clinic"],
  "close_date": "2026-10-01T00:00:00.000Z",
  "created_at": "2026-09-05T09:12:00.000Z",
  "updated_at": "2026-09-05T09:40:00.000Z",
  "stage_entered_at": "2026-09-05T09:40:00.000Z"
}

stage הוא המזהה של אחד משלבי הצינור (pipeline) שלך — קרא אותם באמצעות GET /pipelines (ראה צינורות להלן). מזהי שלבים הם ייחודיים בכל הצינורות שלך, לכן pipeline_id נגזר מהשלב והוא לקריאה בלבד: default הוא הצינור הראשי שלך, והוא null כאשר השלב אינו קיים עוד. חותמות זמן הן בתקן ISO 8601.

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

רשימת עסקאות

GET /deals — מחזיר את העסקאות בחשבון שלך, מהחדשה ביותר לישנה ביותר.

פרמטרי שאילתה (כולם אופציונליים): stage (מזהה שלב), pipeline_id (רק העסקאות בצינור זה), contact_id, limit (ברירת מחדל 50, מקסימום 200), cursor (מה-next_cursor של הדף הקודם).

cURL

curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/deals?stage=stage-2&limit=50", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { deals, next_cursor } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/deals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-2", "limit": 50},
)
deals = res.json()["deals"]

תגובה (200)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

קבלת עסקה

GET /deals/{dealId}

curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

תגובה (200)

{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }

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

יצירת עסקה

POST /deals — title ו-stage הם שדות חובה; stage חייב להיות אחד ממזהי השלבים של ה-pipeline שלך.

curl -X POST "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }'

תגובה (201)

{ "success": true, "deal_id": "deal_abc123" }

עדכון עסקה

PUT /deals/{dealId} — שלח רק את השדות שברצונך לשנות (title, description, notes, value, stage, status, priority, contact_id, …). value חייב להיות מספר.

curl -X PUT "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5200, "priority": "high" }'

תגובה (200): { "success": true, "deal_id": "deal_abc123" }

העברת עסקה לשלב אחר

POST /deals/{dealId}/move — גוף { "new_stage_id": "stage-3", "new_position": 0 }. מיקום 0 מציב את הכרטיס בראש העמודה.

curl -X POST "https://api.youraiconnector.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-3", "new_position": 0 }'

תגובה (200): { "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }

מחיקת עסקה

DELETE /deals/{dealId} — מסיר את העסקה. לא ניתן לבטל פעולה זו.

curl -X DELETE "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

תגובה (200): { "success": true }

צינורות (Pipelines)

לכל חשבון יש צינור ראשי (id: "default"); ניתן להוסיף עד תשעה נוספים, כל אחד עם השלבים שלו. מזהי שלבים ותגיות הפעלה חייבים להיות ייחודיים בכל הצינורות בחשבון, וכל צינור יכול לסמן שלב אחד כ-won שלו ואחד כתוצאה lost.

רשימת צינורות

GET /pipelines — כל צינור, הראשי ראשון, כל אחד עם השלבים שלו ממוינים לפי מיקום.

curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"

תגובה (200):

{
  "success": true,
  "data": {
    "pipelines": [
      {
        "id": "default",
        "name": "Sales",
        "position": 0,
        "is_default": true,
        "settings": { "sync_stage_tags": false },
        "stages": [
          { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null },
          { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" }
        ]
      }
    ]
  }
}

יצירת צינור

POST /pipelines — גוף { "id"?, "name", "stages"?, "settings"? }. השאר את id ריק כדי ליצור אחד באופן אוטומטי. כל שלב מקבל את אותם שדות כמו בתיבת הדו-שיח שלבים: id, name, color, position, trigger_tag אופציונלי (נתיב תגית, users/{uid}/tags/{tagId}), default_value, auto_move_after_days + auto_move_to_stage (שלב באותו צינור) ו-outcome ("won" או "lost").

curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviews",
    "name": "Review requests",
    "stages": [
      { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 },
      { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" }
    ]
  }'

תגובה (201): { "success": true, "data": { "pipeline": { ... } } }. מזהה שלב או תגית הפעלה שכבר נמצאים בשימוש על ידי צינור אחר הם 400 המציינים את הצינור ההוא; מזהה שכבר קיים הוא 409.

עדכון צינור

PUT /pipelines/{pipelineId} — גוף { "name"?, "stages"?, "settings"? }. stages מחליף את כל הרשימה, בדומה לתיבת הדו-שיח שלבים. השתמש ב-default עבור הצינור הראשי. לא ניתן לשנות את מזהה הצינור עצמו.

מחיקת צינור

DELETE /pipelines/{pipelineId} — מסיר צינור נוסף (לא ניתן למחוק את הראשי). אם עדיין יש עסקאות בשלבים שלו, הקריאה תענה ב-409 עם deal_count; הוסף את ?delete_deals=true כדי למחוק את העסקאות הללו יחד עם הצינור. לא ניתן לבטל פעולה זו.

תגובה (204).

צעדים הבאים

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

API עסקאות #

אובייקט העסקה #

רשימת עסקאות #

קבלת עסקה #

יצירת עסקה #

עדכון עסקה #

העברת עסקה לשלב אחר #

מחיקת עסקה #

צינורות (Pipelines) #

רשימת צינורות #

יצירת צינור #

עדכון צינור #

מחיקת צינור #

צעדים הבאים #