API ניתוח ודוחות #

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

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

כל נקודת קצה בדף זה דורשת היקף (scope) מדויק, לא את שניהם: העבר לכל היותר אחד מ-campaign_id (מיושן) או agent_id היכן שנקודת הקצה מקבלת זאת. שליחת שניהם מחזירה 400, ומזהה (id) שאינו בחשבונך מחזיר 404 במקום 403, כך שמזהים של חשבונות אחרים נשארים בלתי ניתנים לניחוש.

כל הנתיבים להלן יחסיים לכתובת ה-URL הבסיסית של ה-API:

https://api.youraiconnector.com/v1

כל בקשה חייבת לעבור אימות. ראה Authentication עבור ארבע השיטות המקובלות. הדוגמאות כאן משתמשות ב-header מסוג X-API-Key (וטופס פרמטר שאילתה אחד עבור cURL).

טווח תאריכים #

כל שלוש נקודות הקצה מקבלות את אותם מסנני תאריכים אופציונליים:

תאריכים מתפרשים לפי UTC. ברירת המחדל של הטווח היא 30 הימים האחרונים והוא מוגבל ל-366 ימים — טווח רחב יותר יחזיר 400. from חייב להיות לפני או שווה ל-to.

הדגל truncated #

נקודות הקצה סיכום ו-קרדיטים מגבילות את מספר הרשומות שבקשה בודדת סורקת. אם הטווח שלך עמוס מספיק כדי להגיע למגבלה זו, התגובה כוללת "truncated": true. כאשר אתה רואה זאת, המספרים מבוססים על סריקה חלקית — צמצם את טווח התאריכים שלך (או דפדף עם חלון קטן יותר) כדי לקבל נתונים מלאים.

סיכום נפח הודעות #

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

GET /analytics/summary

cURL

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/summary?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/summary",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

תגובה

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total": 1240,
    "sent": 800,
    "delivered": 760,
    "read": 540,
    "replied": 210,
    "booked": 35,
    "contact_created": 120,
    "credits_spent": 412.5,
    "credits_recharged": 500
  },
  "by_date": [
    {
      "date": "2026-05-01",
      "total": 40,
      "sent": 25,
      "delivered": 24,
      "read": 18,
      "replied": 7,
      "booked": 1,
      "contact_created": 4,
      "credits_spent": 13.5,
      "credits_recharged": 0
    }
  ],
  "truncated": false
}

לכל רשומה ב-by_date יש את אותם שדות מונה כמו ב-totals, בתוספת date.

אם תעביר campaign_id שאינו שייך לחשבון שלך, התגובה תהיה 404 עם { "success": false, "error": "Campaign not found" }.

ניצול קרדיט #

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

GET /analytics/credits

התאמות לעומת צריכה: שינויים ביתרה כגון בונוסים, חידושי תוכנית ותיקונים אינם נכללים ב-totals ובפירוטים — הם אינם צריכה אמיתית. הם עדיין מופיעים ברשימת ה-records, מסומנים ב-"is_adjustment": true.

סיכומים ופירוטים מופיעים רק בדף הראשון (כאשר לא מסופק cursor). בדפים הבאים, totals, by_reason, by_reason_cost ו-by_campaign מוחזרים כ-null — רק מערך ה-records ממשיך. זה מונע סריקה מחדש של כל הטווח עבור כל דף.

cURL

curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  limit: "50",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/credits?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

// To page: pass data.next_cursor as ?cursor on the next request, until it is null.

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/credits",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31", "limit": 50},
)
data = res.json()

# To page: pass data["next_cursor"] as cursor on the next request, until it is None.

תגובה (דף ראשון)

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "credits_used": 412.5,
    "cost_usd": 1.284512,
    "records": 318
  },
  "by_reason": {
    "AI Message": 380.0,
    "Campaign Message": 32.5
  },
  "by_reason_cost": {
    "AI Message": 1.284512,
    "Campaign Message": 0
  },
  "by_campaign": {
    "Spring Promo": 250.0,
    "Reactivation": 162.5
  },
  "records": [
    {
      "id": "rec_abc123",
      "amount": 1,
      "timestamp": "2026-05-31T14:02:11.000Z",
      "reason": "AI Message",
      "is_adjustment": false,
      "campaign_id": "campaign123",
      "campaign_name": "Spring Promo",
      "contact_id": "contact456",
      "contact_name": "Jane Smith",
      "credit_type": "ai",
      "custom_keys_used": false,
      "description": null,
      "cost_usd": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "ai_model": null,
      "request_id": null,
      "is_test": false
    }
  ],
  "next_cursor": "rec_abc123",
  "costs_redacted": false,
  "truncated": false
}

הערות שדה:

• amount — קרדיטים שחויבו עבור הרשומה. אפס עבור רשומות שחויבו במפתח ה-API של הספק שלך.
• is_adjustment — true עבור שינויים ביתרה (לא נכללים בסיכומים/פירוטים).
• cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — מאוכלסים רק ברשומות שחויבו במפתח ה-API של הספק שלך; אחרת אפס או null.
• is_test — true עבור הרצות ניסיון/בדיקה, שלעולם אינן מחויבות.
• next_cursor — הסמן לדף הבא, או null כאשר אין יותר רשומות.

ריכוז עלויות AI #

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

GET /analytics/ai-cost

cURL

curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/ai-cost?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/ai-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

תגובה

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total_usd": 12.4821,
    "byok_usd": 12.4821,
    "platform_usd": 0,
    "calls": 4210
  },
  "days": [
    {
      "date": "2026-05-01",
      "total_usd": 0.4012,
      "byok_usd": 0.4012,
      "platform_usd": 0,
      "input_usd": 0.18,
      "output_usd": 0.19,
      "cache_creation_usd": 0.02,
      "cache_read_usd": 0.0112,
      "calls": 140,
      "by_provider": { "anthropic": 0.4012 }
    }
  ],
  "costs_redacted": false
}

הערות שדה:

• byok_usd — הוצאות שחויבו במפתחות ה-API של הספק שלך.
• platform_usd — חלק ההוצאות שרץ על הפלטפורמה במקום על המפתח שלך.
• input_usd, output_usd, cache_creation_usd, cache_read_usd — רכיבי העלות המרכיבים את total_usd.
• by_provider — הוצאות בדולר ארה"ב לפי שם ספק ה-AI.
• נתוני דולר ארה"ב מוחזרים רק לחשבונות המשתמשים במפתח ספק משלהם. עבור חשבונות המשלמים באמצעות קרדיט, כל שדה דולרי הוא אפס ו-costs_redacted הוא true (ספירות הקריאות נשארות גלויות).

סדרות מדדים #

מחזירה סדרת עתים אחת או יותר של מדדים בקריאה אחת, מקובצת אופציונלית לפי עד שני ממדים — נקודת הקצה לחיבור תרשים. בקשה אחת יכולה לענות על “נשלחו ונענו ליום, לפי ערוץ, עבור קמפיין זה” ללא צורך בקריאה נפרדת לכל קמפיין.

GET /analytics/series

כל תגובה נושאת מערך labels (ציר הזמן, מאופס לכל הטווח) וכניסה אחת ב-series לכל קבוצה, כאשר כל אחת מחזיקה מערך אחד לכל מדד מבוקש המיושר ל-labels. סדרות מעבר ל-limit אינן מושמטות — הן מתכנסות ל-other_bucket, המחושב כסך הטווח פחות הסדרות שהוחזרו, כך שתרשים מוצג תמיד מסתכם למספרים האמיתיים שלך; truncated הוא true בכל פעם שזה קורה.

מאיפה מגיעים המספרים: sent, delivered, read ו-replied מגיעים מרשומות הודעות, הנושאות את הערוץ ומספר השולח. booked, contact_created ו-credits_spent מגיעים מזרם האירועים, שאינו נושא מספר שולח, לכן מדדים אלו נוחתים בדלי ה-null-מספר כאשר אתה מקבץ לפי number.

טווח התאריכים של נקודת קצה זו מוגבל ל-92 ימים (מחמיר יותר מהמגבלה של 366 ימים המשמשת במקומות אחרים בדף זה).

cURL

curl "https://api.youraiconnector.com/v1/analytics/series?from=2026-05-01&to=2026-05-31&metrics=sent,replied,booked&group_by=campaign,channel&limit=10&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  metrics: "sent,replied,booked",
  group_by: "campaign,channel",
  limit: "10",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/series?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/series",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "from": "2026-05-01",
        "to": "2026-05-31",
        "metrics": "sent,replied,booked",
        "group_by": "campaign,channel",
        "limit": 10,
    },
)
data = res.json()

תגובה

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "granularity": "day",
  "labels": ["2026-05-01", "2026-05-02"],
  "group_by": ["campaign", "channel"],
  "metrics": ["sent", "replied", "booked"],
  "series": [
    {
      "key": {
        "campaign_id": "campaign123",
        "campaign_name": "Spring Promo",
        "channel": "whatsapp"
      },
      "total": 812,
      "metrics": {
        "sent": [40, 35],
        "replied": [12, 9],
        "booked": [2, 1]
      }
    }
  ],
  "other_bucket": {
    "series_count": 6,
    "total": 340,
    "metrics": {
      "sent": [18, 20],
      "replied": [5, 6],
      "booked": [0, 1]
    }
  },
  "truncated": true
}

הערות שדה:

• key — הזהות של סדרה אחת. רק המפתחות עבור ממדי ה-group_by המבוקשים נוכחים; ממד שערכו אינו ידוע עבור שורה (הודעה ללא קמפיין, אירוע ללא ערוץ) חוזר כ-null במקום להיות מושמט, כך שהסדרות עדיין מסתכמות לסכומים הכוללים.
• other_bucket — null כאשר שום דבר לא התכנס.
• נקודת קצה זו מחזירה 503 עם "error_code": "analytics_unavailable" כאשר מסד הנתונים של הדיווח אינו יכול לענות עבור החשבון שלך, במקום 200 מלא באפסים — תרשים מאופס היה נקרא כעובדה.

תוצאות שיחה #

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

GET /analytics/outcomes

העבר group_by=tag כדי לכווץ את ציר הזמן ולקבל סכומי טווח לכל תג בלבד — במצב זה labels ריק וכל מערך counts של תג ריק, בעוד total עדיין מאוכלס.

טווח התאריכים של נקודת קצה זו מוגבל ל-92 ימים.

cURL

curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/outcomes?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/outcomes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

תגובה

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "group_by": "date",
  "labels": ["2026-05-01", "2026-05-02"],
  "by_tag": [
    { "tag": "interested", "total": 84, "counts": [3, 5] },
    { "tag": "not_interested", "total": 40, "counts": [1, 2] },
    { "tag": null, "total": 12, "counts": [0, 1] }
  ],
  "totals": {
    "sessions": 260,
    "replied": 210,
    "booked": 35,
    "human_alerted": 18,
    "unresolved": 12
  }
}

הערות שדה:

• by_tag[].tag — null עבור שיחות שה-AI מעולם לא הקצה להן תגית תוצאה.
• totals.human_alerted — שיחות שהועברו לאדם; זה נכתב בכל העברה ולא הוצג בעבר על ידי אף נקודת קצה.
• אותה התנהגות 503/analytics_unavailable כמו בסדרות מדדים כאשר מסד הנתונים של הדיווחים אינו יכול לספק תשובה.

תובנות לוח מחוונים #

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

GET /analytics/dashboard-insights

נקודת קצה זו משתמשת ב-startDate/endDate (לא ב-from/to) מכיוון שהיא חולקת את המימוש שלה עם לוח המחוונים בתוך האפליקציה. הטווח מוגבל ל-92 ימים והוא נחתך, לא נדחה, כאשר הוא רחב יותר.

Null פירושו לא זמין, לא אפס. מספר בלוקים (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) מחושבים ממסד הנתונים של הדיווחים וחוזרים כ-null כאשר הוא אינו יכול לספק תשובה עבור החשבון שלך. אל תציג בלוק null כתרשים ריק.

cURL

curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()

תגובה (מקוצרת — מטען זה גדול; ראה את הפניית ה-API עבור הסכימה המלאה)

{
  "success": true,
  "data": {
    "heatmap": {
      "buckets": [
        { "weekday": 1, "hour": 9, "sent": 12, "replied": 5, "replyRate": 0.42 }
      ]
    },
    "topCampaigns": [
      { "campaignId": "campaign123", "name": "Spring Promo", "sent": 420, "replied": 180, "booked": 22, "replyRate": 0.43, "creditsSpent": 210.5 }
    ],
    "channelVolume": [
      { "channel": "whatsapp", "sent": 800, "received": 540, "lastMessageAt": "2026-05-31T14:02:11.000Z" }
    ],
    "inboxSla": { "medianFirstResponseMs": 92000, "sampleSize": 140 },
    "activityFeed": [
      { "id": "evt_1", "kind": "booked", "at": "2026-05-31T14:02:11.000Z", "contactId": "contact456", "contactName": "Jane Smith", "campaignId": "campaign123", "campaignName": "Spring Promo", "label": "Jane Smith booked an appointment" }
    ],
    "numberStats": null,
    "channelDailySeries": null,
    "metricDailyBreakdown": null,
    "contactsByCountry": null,
    "ai_human_split": null
  }
}

הערות שדה:

• heatmap.buckets[].weekday — 0 הוא יום ראשון עד 6 הוא יום שבת.
• numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — כל אחד מהם באופן עצמאי null כאשר מסד הנתונים של הדיווחים אינו זמין עבור החשבון שלך; כל שאר הבלוקים עדיין יוחזרו.

תובנות AI ללוח המחוונים #

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

GET /analytics/dashboard-ai-insights

נקודת קצה זו היא ברמת החשבון — היא אינה דורשת הגדרת קמפיין או סוכן.

cURL

curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()

תגובה

{
  "success": true,
  "data": {
    "insights": [
      { "tone": "win", "title": "Reply rate is up", "detail": "Your reply rate climbed to 43% this period, up from 36% the period before." },
      { "tone": "watch", "title": "Bookings slowed midweek", "detail": "Wednesday bookings dropped to a third of Monday's, worth a look at your Wednesday follow-up timing." },
      { "tone": "tip", "title": "Re-send to non-repliers", "detail": "212 contacts received a message but never replied — a short follow-up template often recovers 10-15% of them." }
    ]
  }
}

חסר startDate או endDate יחזיר 400.

ציר זמן של פעילות ישות #

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

GET /analytics/entity-activity

cURL

curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ entityType: "contact", entityId: "contact456" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/entity-activity?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/entity-activity",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"entityType": "contact", "entityId": "contact456"},
)
data = res.json()

תגובה

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "evt_9",
        "kind": "appointment_booked",
        "at": "2026-05-31T14:02:11.000Z",
        "label": "Booked an appointment for June 3",
        "detail": "Consultation call, 30 minutes"
      },
      {
        "id": "evt_8",
        "kind": "message_replied",
        "at": "2026-05-31T13:58:02.000Z",
        "label": "Replied: \"Yes, that time works\""
      }
    ]
  }
}

ערך entityType/entityId חסר או לא תקין יחזיר 400. ישות שאינה קיימת בחשבונך תחזיר 404, כך שמזהים של חשבונות אחרים נשארים בלתי ניתנים לניחוש.

ספירות אירועים מצטברות (Legacy) #

מחזיר את אותן ספירות אירועים מצטברות כמו סיכום נפח הודעות, אך במבנה camelCase (contactCreated במקום contact_created, byDate במקום by_date) שחלק מהאינטגרציות הישנות נבנו לפיו. העדף את /analytics/summary עבור אינטגרציות חדשות — נקודת קצה זו קיימת רק כדי שלוח המחוונים באפליקציה וה-API יחלקו מימוש אחד.

GET /analytics/aggregate

cURL

curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

תגובה

{
  "success": true,
  "data": {
    "from": "2026-05-01",
    "to": "2026-05-31",
    "total": 1240,
    "byAnalyticType": {
      "total": 1240,
      "sent": 800,
      "delivered": 760,
      "read": 540,
      "replied": 210,
      "booked": 35,
      "contactCreated": 120,
      "creditsSpent": 412.5,
      "creditsRecharged": 500
    },
    "byDate": [
      { "date": "2026-05-01", "byAnalyticType": { "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contactCreated": 4, "creditsSpent": 13.5, "creditsRecharged": 0 } }
    ]
  }
}

ריכוז תתי-חשבונות של סוכנות #

שגיאות ב-Analytics API #

נקודות הקצה של Analytics מחזירות את מעטפת השגיאה הסטנדרטית:

{
  "success": false,
  "error": "Date range too large. Maximum is 366 days."
}

בנקודת קצה של ניתוח נתונים, פורמט תאריך לא תקין או חלון מחוץ לטווח יחזיר 400, ו-campaign_id או agent_id לא ידועים יחזירו 404. שליחת גם campaign_id וגם agent_id בנקודת קצה שמקבלת את שניהם היא גם 400 — העבר לכל היותר אחד. נקודות הקצה של דיווח מבוסס PG בלבד (סדרות מדדים, תוצאות שיחה, ריכוז סוכנות) מחזירות 503 עם "error_code": "analytics_unavailable" במקום 200 מלא באפסים כאשר מסד הנתונים של הדיווח אינו יכול להשיב עבור חשבונך — נסה שוב בקרוב. הקודים המשותפים שכל נקודת קצה יכולה להחזיר — 401, 403 (התוכנית שלך אינה כוללת גישת API, או, בריכוז סוכנות, החשבון שלך אינו Agency/Dev), 429 (מגבלת קצב) ו-500 — מפורטים עם הנחיות לניסיון חוזר ב-שגיאות ועימוד.

צעדים הבאים #

• אימות — ארבע הדרכים לאימות בקשה.
• שגיאות ומגבלות קצב — קודי סטטוס והמגבלה של 300 בקשות לדקה.
• API של קמפיינים — הקמפיינים שניתן לסנן לפיהם את הנתונים האלה.