API ואינטגרציות

כל בקשת API חייבת לכלול מפתח API תקף לצורך אימות. המפתחות משויכים לארגון שלכם, כלומר מפתח יכול לגשת רק לנתונים השייכים לחברה שלכם.

יצירת מפתח API

1. 1

   נווטו למפתחות API

   בלוח הבקרה, עברו אל ניהול > מפתחות API.

2. 2

   לחצו על "צור מפתח חדש"

   תנו למפתח שם תיאורי (למשל, "אינטגרציית שכר" או "לוח בקרה HR").

3. 3

   העתיקו ושמרו את המפתח

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

מאפייני המפתח

כותרת האימות

כללו את מפתח ה-API בכותרת X-API-Key בכל בקשה:

curl -H "X-API-Key: clk_your_api_key_here" \
     -H "Content-Type: application/json" \
     https://app.clokio.io/api/v1/employees

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

Webhooks מאפשרים לכם לקבל התראות בזמן אמת כאשר מתרחשים אירועי נוכחות, ללא צורך לתשאל את ה-API. כאשר עובד מדווח כניסה, יציאה או יוצא להפסקה, Clokio שולח בקשת HTTP POST לכתובת ה-URL שהגדרתם.

פלטפורמות נתמכות

אירועים נתמכים

סינון

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

• לפי מיקום: קבלו אירועים רק ממיקומי עבודה ספציפיים.
• לפי עובד: עקבו אחר עובדים ספציפיים (למשל, עובדים חדשים בתקופת ניסיון).
• לפי מחלקה: הגבילו התראות למחלקות מסוימות.
• לפי יום בשבוע: שלחו התראות רק בימי עבודה.
• לפי טווח שעות: הפעילו רק בשעות מסוימות (למשל, 6:00 - 10:00 בבוקר לניטור איחורים).

תבניות הודעות מותאמות אישית

התאימו אישית את ההודעה שנשלחת לערוץ שלכם. השתמשו במשתנים כמו {employee_name}, {event_type}, {timestamp} ו-{location_name} כדי לבנות הודעות שמתאימות לסגנון הצוות שלכם.

מעקב משלוחים וניסיונות חוזרים

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

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

משימות חוזרות

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

שרת MCP לסוכני AI

ל-Clokio יש שרת MCP רשמי - 50 כלים שמכסים משימות, נוכחות, עובדים ופרויקטים - כך שעוזרי AI כמו Claude, Cursor או כל קליינט תואם MCP יכולים לעבוד עם הנתונים שלכם ישירות, עם מפתח ה-API שלכם ותו לא:

npx -y clokio-mcp

השרת לא מוסיף הרשאות משלו: כל קריאה כפופה להרשאות המפתח, בדיוק כמו בקשת API ישירה.

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

אפשרות 1: ייצוא CSV (ידני)

הגישה הפשוטה ביותר היא לייצא את הסיכום החודשי כקובץ CSV מלוח הבקרה, ואז לייבא אותו לתוכנת השכר. ה-CSV כולל את כל השדות שמערכות שכר בדרך כלל דורשות: שם/מזהה עובד, סך שעות, שעות נוספות, ימי חופשה ומספר היעדרויות. רוב תוכנות השכר (כולל כלים פופולריים כמו ADP, Gusto ו-QuickBooks) יכולות לייבא קבצי CSV.

1. 1

   עברו לדוחות > סיכום חודשי

   בחרו את החודש והשנה.

2. 2

   לחצו על "ייצוא CSV"

   הקובץ יורד למחשב שלכם.

3. 3

   ייבאו לתוכנת השכר

   השתמשו בתכונת ייבוא ה-CSV של כלי השכר שלכם. מפו את עמודות Clokio לשדות השכר.

אפשרות 2: אינטגרציית API (אוטומטית)

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

1. 1

   מושך את נוכחות אתמול

   קורא ל-GET /api/v1/attendance/daily?date=YYYY-MM-DD עבור תאריך אתמול.

2. 2

   ממיר את הנתונים

   ממפה שדות Clokio לפורמט הנדרש של מערכת השכר.

3. 3

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

   שולח את הנתונים ל-API או לנקודת הייבוא של מערכת השכר.

הנה דוגמת סקריפט (Node.js) ששולף את נוכחות אתמול:

// fetch-attendance.js
const API_KEY = process.env.CLOKIO_API_KEY;
const BASE_URL = 'https://app.clokio.io/api/v1';

// Get yesterday's date
const yesterday = new Date();
yesterday.setDate(yesterday.getDate() - 1);
const dateStr = yesterday.toISOString().split('T')[0];

async function fetchAttendance() {
  const response = await fetch(
    `${BASE_URL}/attendance/daily?date=${dateStr}`,
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const result = await response.json();

  if (result.status === 'success') {
    console.log(`Found ${result.data.length} records for ${dateStr}`);
    // Transform and send to your payroll system here
    return result.data;
  } else {
    console.error('API Error:', result.message);
  }
}

fetchAttendance();

סיכום חודשי לשכר

בסוף כל חודש, השתמשו בנקודת הקצה GET /api/v1/attendance/summary כדי לשלוף סיכום מלא לכל עובד. זה נותן לכם סך שעות, שעות נוספות, ימי חופשה ומספר היעדרויות -- הכל מה שמחלקת השכר צריכה.