API עסקאות

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

כתובת בסיס (Base URL) — https://api.dmchamp.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",
  "stage": "stage-2",
  "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 הוא המזהה (id) של אחד משלבי ה-pipeline שלך — ניתן לקרוא אותם מהגדרות ה-pipeline שלך (GET /users/me/pipeline-settings). חותמות זמן הן בפורמט ISO 8601.

רשימת עסקאות

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

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

cURL

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

JavaScript

const res = await fetch("https://api.dmchamp.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.dmchamp.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.dmchamp.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.dmchamp.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, value, stage, status, priority, contact_id, …). value חייב להיות מספר.

curl -X PUT "https://api.dmchamp.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.dmchamp.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.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

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

צעדים הבאים

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

API עסקאות #

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

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

קבלת עסקה #

יצירת עסקה #

עדכון עסקה #

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

מחיקת עסקה #

צעדים הבאים #