מחברים את Improvit למערכות שכבר עובדות אצלכם

תחילת עבודה

1. נכנסים כמנהל מערכת ופותחים את הגדרות ארגון ← API וחיבור למערכות (במצב מתקדם).
2. לוחצים על יצירת מפתח API ומעתיקים אותו. המפתח מוצג פעם אחת בלבד, לכן כדאי לשמור אותו במנהל הסודות שלכם.
3. מבצעים קריאה ראשונה. אם רשימת העובדים חוזרת, החיבור עובד.

כתובת בסיס: https://app.improvit.co.il/api/v1

curl "https://app.improvit.co.il/api/v1/employees" \
  -H "Authorization: Bearer $IMPROVIT_API_KEY"

כל הבקשות והתשובות ב-JSON (UTF-8). תאריכים בפורמט YYYY-MM-DD וחודשים בפורמט YYYY-MM, לפי שעון ישראל. סכומים במטבע של הארגון.

אימות

שולחים את המפתח בכותרת Authorization בכל בקשה. לכל ארגון יש מפתח פעיל אחד. יצירת מפתח חדש מבטלת מיד את הקודם וכך גם מבטלים מפתח שדלף.

Authorization: Bearer inc_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXX

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

חודש טיפוסי

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

כללי התאמה

• עובדים: לפי employeeId (מספר העובד שמוגדר ב-Improvit, בדרך כלל המספר במערכת השכר). אם אין, לפי שם מלא. ההתאמה לא רגישה לאותיות גדולות ולרווחים מיותרים.
• מדדים: לפי שם המדד כפי שמופיע ב-Improvit, או לפי ה-id שלו מ-GET /metrics. ה-id לא משתנה כשמשנים שם למדד ולכן עדיף להשתמש בו בחיבורים קבועים.
• ערכים: מספרים, או מחרוזות כמו "30,000" או "88%". null או מדד שלא נשלח משאירים את הערך הקיים. ערכים שליליים נדחים.
• בטוח לשליחה חוזרת: שולחים בכל פעם את הסיכום המלא מתחילת החודש, לא תוספות. שליחה כפולה של אותה בקשה לא משנה דבר.

רשימת עובדים

GET/api/v1/employees

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

curl "https://app.improvit.co.il/api/v1/employees" \
  -H "Authorization: Bearer $IMPROVIT_API_KEY"

{
  "employees": [
    {
      "id": "k3Jd9sQe2Lm",
      "employeeId": "1001",
      "name": "Dana Levi",
      "role": "sales",
      "roleName": "Sales associate",
      "branch": "Tel Aviv",
      "active": true,
      "kind": "employee"
    }
  ]
}

kind הוא "employee", או "agent" לסוכנות או זכיין חיצוניים. סוכנים מקבלים יעדים וביצועים כמו עובדים, אבל מקבלים תשלום מול חשבונית ולכן הם לא מופיעים בייצוא לשכר.

רשימת מדדים

GET/api/v1/metrics

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

curl "https://app.improvit.co.il/api/v1/metrics" \
  -H "Authorization: Bearer $IMPROVIT_API_KEY"

{
  "metrics": [
    { "id": "rev", "name": "Revenue", "unit": "ils", "unitLabel": "₪", "lowerIsBetter": false },
    { "id": "tv", "name": "TV sales", "unit": "units", "unitLabel": "units", "lowerIsBetter": false }
  ],
  "roles": [
    { "key": "sales", "name": "Sales associate", "metrics": ["rev", "tv"] }
  ]
}

שליחת יעדים

POST/api/v1/targets

קובע את היעדים של חודש. עם "open": true, החודש נפתח קודם לעובדים שנשלחו ועדיין אין להם אותו, בדיוק כמו "פתיחת החודש" במערכת (הבונוסים וההגדרות מועתקים מהחודש הקודם של העובד).

curl -X POST "https://app.improvit.co.il/api/v1/targets" \
  -H "Authorization: Bearer $IMPROVIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "month": "2026-11",
  "open": true,
  "rows": [
    {
      "employeeId": "1001",
      "targets": {
        "Revenue": 250000,
        "TV sales": 40
      }
    },
    {
      "name": "Avi Cohen",
      "targets": {
        "rev": 180000
      }
    }
  ]
}'

{
  "ok": true,
  "month": "2026-11",
  "openedEmployees": 2,
  "updatedEmployees": 2,
  "updatedValues": 3,
  "skipped": [],
  "unknownColumns": []
}

שליחת ביצועים

POST/api/v1/actuals

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

curl -X POST "https://app.improvit.co.il/api/v1/actuals" \
  -H "Authorization: Bearer $IMPROVIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "asOf": "2026-11-15",
  "rows": [
    {
      "employeeId": "1001",
      "values": {
        "Revenue": 131500,
        "TV sales": 22
      }
    }
  ]
}'

{
  "ok": true,
  "asOf": "2026-11-15",
  "updatedEmployees": 1,
  "updatedValues": 2,
  "skipped": [ { "label": "1002", "reason": "targets" } ],
  "unknownColumns": []
}

עובדים שלא השתנה אצלם דבר לא נספרים כמעודכנים וגם לא כמדולגים.

מבצעים מתפרצים: שולחים את המכירות של המבצע באותו אובייקט values, לפי קוד הפריט, שם הפריט או שם המבצע (כמות שנמכרה מתחילת החודש). לסכום המכירה מוסיפים למפתח " amount" או " סכום", למשל "AC-12 amount". מתעדכנים רק מבצעים שמופיעים בחודש של העובד.

שליחת ביטולים

POST/api/v1/cancellations

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

curl -X POST "https://app.improvit.co.il/api/v1/cancellations" \
  -H "Authorization: Bearer $IMPROVIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "employeeId": "1001",
      "reference": "SO-55120",
      "values": {
        "TV sales": 1,
        "Revenue": 4200
      },
      "originalMonth": "2026-10",
      "date": "2026-11-04",
      "note": "Customer returned the TV"
    }
  ]
}'

{
  "ok": true,
  "month": "2026-11",
  "added": 1,
  "updated": 0,
  "unchanged": 0,
  "skipped": [],
  "results": [ { "index": 0, "reference": "SO-55120", "status": "added" } ]
}

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

ייצוא לשכר

GET/api/v1/payroll

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

curl "https://app.improvit.co.il/api/v1/payroll?month=2026-10" \
  -H "Authorization: Bearer $IMPROVIT_API_KEY"

{
  "month": "2026-10",
  "currency": "ILS",
  "statusFilter": "closed",
  "count": 1,
  "total": 4850,
  "rows": [
    {
      "employeeId": "1001",
      "name": "Dana Levi",
      "branch": "Tel Aviv",
      "role": "Sales associate",
      "status": "closed",
      "score": 1.08,
      "commission": 3250,
      "targetBonus": 1000,
      "performanceBonus": 600,
      "flashDeals": 0,
      "total": 4850,
      "cancellations": { "TV sales": 1 },
      "currency": "ILS",
      "final": true,
      "closedAt": "2026-11-02T08:14:00.000Z"
    }
  ]
}

curl "https://app.improvit.co.il/api/v1/payroll?month=2026-10&format=csv" \
  -H "Authorization: Bearer $IMPROVIT_API_KEY" -o payroll-2026-10.csv

שגיאות

שגיאות מחזירות קוד HTTP וגוף עם קוד קבוע והודעה קריאה:

{ "error": { "code": "bad_month", "message": "month must be YYYY-MM." } }

שורות שדולגו

בקשה יכולה להצליח גם כשחלק מהשורות דולגו. לכל שורה שדולגה יש סיבה:

unknownColumns מפרט שמות מדדים בבקשה שלא תואמים אף מדד. בודקים אותם מול GET /metrics.

ביטולים שדולגו

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

• עד 120 בקשות בדקה לכל ארגון.
• עד 5,000 שורות בבקשה (500 בביטולים). בצוותים גדולים יותר מפצלים לכמה בקשות.
• HTTPS בלבד. הנתונים נשמרים ב-Google Cloud בישראל (me-west1).
• נשמר רק גיבוב (hash) של המפתח. המפתח אבד? יוצרים חדש בהגדרות.
• כל שינוי שנעשה דרך ה-API נרשם ביומן הפעילות של הארגון.
• גרסה v1 יציבה: מוסיפים שדות אבל לא מוחקים ולא משנים שמות. שינויים שוברים יגיעו כ-v2, בהודעה מראש.

בלי קוד

אין מפתח זמין? Improvit יכולה למשוך ביצועים כל לילה מגיליון Google שהמערכת שלכם מעדכנת (הגדרות ארגון ← עדכון ביצועים ← חיבור אוטומטי) ומנהלים יכולים לייבא קובץ אקסל בכל רגע. את התגמול אפשר לייצא לאקסל ממסך החודש.