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

ה-Public API v1 של Clokio הוא RESTful API. כל נקודות הקצה נמצאות תחת /api/v1/ ומחזירות JSON. כל תגובה עוקבת אחרי אותו פורמט:

{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": { ... }
}

נקודות קצה לקריאה (GET)

curl -H "X-API-Key: clk_your_key" \
     https://app.clokio.io/api/v1/employees

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/daily?date=2026-02-10"

{
  "status": "success",
  "message": "Daily attendance retrieved",
  "data": [
    {
      "employee_id": 42,
      "employee_name": "Sarah Johnson",
      "nip": "EMP-1042",
      "clock_in": "2026-02-10T08:55:00Z",
      "clock_out": "2026-02-10T17:32:00Z",
      "total_hours": 7.87,
      "break_minutes": 45,
      "status": "present"
    }
  ]
}

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/range?start=2026-02-01&end=2026-02-28"

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/employee/EMP-1042"

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/summary?month=02&year=2026"

נקודות קצה לכתיבה (POST)

curl -X POST \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"nip": "EMP-1042", "latitude": 32.0853, "longitude": 34.7818}' \
     https://app.clokio.io/api/v1/attendance/clock-in

{
  "status": "success",
  "message": "Employee clocked in successfully",
  "data": {
    "attendance_id": 8847,
    "employee_name": "Sarah Johnson",
    "clock_in": "2026-02-12T08:55:12Z",
    "location": "Main Office"
  }
}

curl -X POST \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"nip": "EMP-1042", "latitude": 32.0853, "longitude": 34.7818}' \
     https://app.clokio.io/api/v1/attendance/clock-out

curl -X POST \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"nip": "EMP-1042"}' \
     https://app.clokio.io/api/v1/attendance/break-start

curl -X POST \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"nip": "EMP-1042"}' \
     https://app.clokio.io/api/v1/attendance/break-end

טיפול בשגיאות

כאשר בקשה נכשלת, ה-API מחזיר קוד סטטוס HTTP מתאים יחד עם הודעת שגיאה:

// 401 Unauthorized - Invalid or missing API key
{
  "status": "error",
  "message": "Invalid API key",
  "data": null
}

// 422 Unprocessable Entity - Validation error
{
  "status": "error",
  "message": "The date field is required",
  "data": null
}

// 429 Too Many Requests - Rate limit exceeded
{
  "status": "error",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "data": null
}

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

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

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

סינון

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

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

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

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

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

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

אחד השימושים בעלי הערך הגבוה ביותר ב-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 כדי לשלוף סיכום מלא לכל עובד. זה נותן לכם סך שעות, שעות נוספות, ימי חופשה ומספר היעדרויות -- הכל מה שמחלקת השכר צריכה.