Mazkira API Documentation | תיעוד API

מבוא

ברוכים הבאים ל-API של מזכירה! API זה מאפשר לך לנהל את מערכת התא הקולי החכם שלך באופן תוכניתי.

Base URL:
https://api.mazkira.co.il/api/

פורמט תגובות

כל התגובות מוחזרות בפורמט JSON עם המבנה הבא:

// תגובה מוצלחת
{
    "success": true,
    "data": { ... }
}

// תגובת שגיאה
{
    "success": false,
    "error": "הודעת שגיאה"
}
        

אימות (Authentication)

כל הבקשות ל-API (למעט /health) דורשות מפתח API.

קבלת מפתח API

התחבר לפורטל בכתובת login.mazkira.co.il
עבור להגדרות → מפתחות API
לחץ "צור מפתח חדש"
שמור את המפתח - הוא יוצג רק פעם אחת!

שימוש במפתח

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

# cURL דוגמה
curl -X GET "https://api.mazkira.co.il/api/mailboxes" \
     -H "X-API-Key: YOUR_API_KEY"

# או כפרמטר URL (לא מומלץ)
curl "https://api.mazkira.co.il/api/mailboxes?api_key=YOUR_API_KEY"
        

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

תיבות דואר (Mailboxes)

GET /mailboxes קבל רשימת כל תיבות הדואר

פרמטרים (Query)

פרמטר	סוג	תיאור
`limit`	integer	מספר תוצאות מקסימלי (ברירת מחדל: 100)
`offset`	integer	היסט לעמודים (ברירת מחדל: 0)

תגובה

{
    "success": true,
    "data": [
        {
            "id": 1,
            "mailbox_number": "1001",
            "name": "דני כהן",
            "email": "dani@example.com",
            "is_active": 1,
            "created_at": "2026-01-01 10:00:00"
        }
    ]
}
                

GET /mailboxes/{id} קבל פרטי תיבת דואר ספציפית

פרמטרים (Path)

פרמטר	סוג	תיאור
`id`	integer	חובה מזהה התיבה

תגובה

{
    "success": true,
    "data": {
        "id": 1,
        "mailbox_number": "1001",
        "name": "דני כהן",
        "email": "dani@example.com",
        "pin": "1234",
        "is_active": 1,
        "max_message_length": 300,
        "email_notification": 1,
        "auto_transcribe": 1
    }
}
                

PUT /mailboxes/{id} עדכן תיבת דואר

פרמטרים (Body - JSON)

פרמטר	סוג	תיאור
`name`	string	שם בעל התיבה
`email`	string	כתובת אימייל
`pin`	string	קוד PIN (4 ספרות)
`is_active`	boolean	תיבה פעילה
`max_message_length`	integer	אורך הודעה מקסימלי בשניות
`email_notification`	boolean	שליחת התראות למייל
`auto_transcribe`	boolean	תמלול אוטומטי

דוגמה

curl -X PUT "https://api.mazkira.co.il/api/mailboxes/1" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
         "name": "דני כהן",
         "email": "dani@newmail.com",
         "email_notification": true
     }'
                

הודעות (Messages)

GET /messages קבל רשימת הודעות

פרמטרים (Query)

פרמטר	סוג	תיאור
`mailbox_id`	integer	סנן לפי תיבת דואר
`status`	string	סנן לפי סטטוס: new, read, deleted
`limit`	integer	מספר תוצאות (ברירת מחדל: 100)
`offset`	integer	היסט

תגובה

{
    "success": true,
    "data": [
        {
            "id": 42,
            "mailbox_id": 1,
            "caller_id": "+972501234567",
            "duration": 45,
            "status": "new",
            "transcription": "שלום, זה דני מחברת...",
            "created_at": "2026-01-13 14:30:00"
        }
    ]
}
                

GET /messages/{id} קבל פרטי הודעה ספציפית

תגובה

{
    "success": true,
    "data": {
        "id": 42,
        "mailbox_id": 1,
        "caller_id": "+972501234567",
        "caller_name": "דני כהן",
        "duration": 45,
        "file_path": "/path/to/file.wav",
        "file_size": 72400,
        "status": "new",
        "transcription": "שלום, זה דני...",
        "transcription_status": "completed",
        "email_sent": 1,
        "created_at": "2026-01-13 14:30:00"
    }
}
                

GET /messages/{id}/download הורד קובץ אודיו של הודעה

מחזיר את קובץ האודיו בפורמט WAV.

דוגמה

curl -X GET "https://api.mazkira.co.il/api/messages/42/download" \
     -H "X-API-Key: YOUR_API_KEY" \
     --output voicemail.wav
                

POST /messages/{id}/read סמן הודעה כנקראה

תגובה

{
    "success": true,
    "data": {
        "message": "Message marked as read"
    }
}
                

POST /messages/{id}/transcribe בקש תמלול להודעה

תמלול מובנה! התמלול מבוצע על השרת באמצעות מנוע תמלול מובנה.

פרמטרים (Body)

פרמטר	סוג	תיאור
`language`	string	שפה (ברירת מחדל: he). אפשרויות: he, en, ar, ru

תגובה

{
    "success": true,
    "data": {
        "message": "Transcription completed",
        "transcription": "שלום, זה דני מחברת..."
    }
}
                

POST /messages/{id}/email שלח הודעה במייל

פרמטרים (Body)

פרמטר	סוג	תיאור
`email`	string	כתובת מייל (אם לא צוין - ישלח לכתובת ברירת המחדל של התיבה)

דוגמה

curl -X POST "https://api.mazkira.co.il/api/messages/42/email" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"email": "other@example.com"}'
                

DELETE /messages/{id} מחק הודעה

פרמטרים (Query)

פרמטר	סוג	תיאור
`hard`	boolean	מחיקה קשיחה (כולל קובץ). ברירת מחדל: false

דוגמה

# מחיקה רכה (סימון כמחוקה)
curl -X DELETE "https://api.mazkira.co.il/api/messages/42" \
     -H "X-API-Key: YOUR_API_KEY"

# מחיקה קשיחה (מוחק את הקובץ)
curl -X DELETE "https://api.mazkira.co.il/api/messages/42?hard=true" \
     -H "X-API-Key: YOUR_API_KEY"
                

ברכות (Greetings)

GET /greetings קבל רשימת ברכות

פרמטרים (Query)

פרמטר	סוג	תיאור
`mailbox_id`	integer	סנן לפי תיבת דואר

תגובה

{
    "success": true,
    "data": [
        {
            "id": 1,
            "mailbox_id": 1,
            "name": "ברכה אישית",
            "greeting_type": "personal",
            "is_active": 1,
            "duration": 8
        }
    ]
}
                

GET /greetings/{id}/download הורד קובץ ברכה

מחזיר את קובץ האודיו של הברכה.

POST /greetings/upload העלה ברכה חדשה

פרמטרים (Form Data)

פרמטר	סוג	תיאור
`mailbox_id`	integer	חובה מזהה תיבת הדואר
`file`	file	חובה קובץ אודיו (WAV/MP3)
`name`	string	שם הברכה
`greeting_type`	string	סוג: personal, unavailable, busy

דוגמה

curl -X POST "https://api.mazkira.co.il/api/greetings/upload" \
     -H "X-API-Key: YOUR_API_KEY" \
     -F "mailbox_id=1" \
     -F "name=ברכה חדשה" \
     -F "file=@/path/to/greeting.wav"
                

העלאה ב-Base64

curl -X POST "https://api.mazkira.co.il/api/greetings/upload" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
         "mailbox_id": 1,
         "name": "ברכה חדשה",
         "file_content": "BASE64_ENCODED_AUDIO",
         "file_type": "wav"
     }'
                

POST /greetings/{id}/activate הפעל ברכה

מגדיר את הברכה כברכה הפעילה לתיבת הדואר.

DELETE /greetings/{id} מחק ברכה

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

סטטיסטיקות (Statistics)

GET /stats קבל סטטיסטיקות כלליות

תגובה

{
    "success": true,
    "data": {
        "total_mailboxes": 25,
        "active_mailboxes": 22,
        "total_messages": 1250,
        "new_messages": 45,
        "messages_today": 12,
        "total_duration": 18500,
        "avg_message_duration": 35
    }
}
                

בוט AI (AI Secretary)

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

AI מובנה!
כל עיבוד ה-AI מבוצע על השרת:

תמלול (STT): מנוע תמלול מובנה
בינה מלאכותית (LLM): מנוע AI מובנה
דיבור (TTS): מנוע דיבור מובנה

GET /auth?action=aibot-stats קבל סטטיסטיקות של בוט AI

תגובה

{
    "success": true,
    "data": {
        "total_conversations": 156,
        "conversations_today": 8,
        "avg_duration": 45,
        "completion_rate": 87
    }
}
                

GET /auth?action=aibot-config&mailbox_id={id} קבל הגדרות בוט AI לתיבה

תגובה

{
    "success": true,
    "data": {
        "enabled": 1,
        "default_language": "he",
        "auto_language_detect": 1,
        "greeting_style": "professional",
        "collect_name": 1,
        "collect_phone": 1,
        "collect_message": 1,
        "custom_greeting": "שלום, הגעתם למשרד...",
        "max_conversation_duration": 300
    }
}
                

POST /auth?action=aibot-config עדכן הגדרות בוט AI

פרמטרים (Body)

פרמטר	סוג	תיאור
`mailbox_id`	integer	חובה מזהה תיבת הדואר
`enabled`	boolean	הפעל/כבה בוט AI
`default_language`	string	שפת ברירת מחדל: he, en, ar, ru
`auto_language_detect`	boolean	זיהוי שפה אוטומטי
`greeting_style`	string	סגנון: professional, friendly, formal
`custom_greeting`	string	ברכה מותאמת אישית
`collect_name`	boolean	לבקש שם
`collect_phone`	boolean	לבקש טלפון
`collect_message`	boolean	לבקש הודעה
`max_conversation_duration`	integer	משך מקסימלי בשניות

דוגמה

curl -X POST "https://api.mazkira.co.il/api/auth?action=aibot-config" \
     -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
         "mailbox_id": 1,
         "enabled": true,
         "default_language": "he",
         "greeting_style": "friendly",
         "custom_greeting": "שלום! הגעתם למשרדי חברת דוגמה. איך אוכל לעזור?"
     }'
                

GET /auth?action=aibot-conversations קבל היסטוריית שיחות AI

תגובה

{
    "success": true,
    "data": [
        {
            "id": 1,
            "call_uuid": "abc123...",
            "caller_id": "+972501234567",
            "caller_name_collected": "דני כהן",
            "caller_phone_collected": "050-1234567",
            "message_collected": "אני מעוניין בהצעת מחיר",
            "language_detected": "he",
            "duration": 65,
            "status": "completed",
            "email_sent": 1,
            "call_started_at": "2026-01-13 14:30:00"
        }
    ]
}
                

Webhooks

Webhooks מאפשרים לך לקבל התראות בזמן אמת כשמתרחשים אירועים במערכת.

GET /webhooks קבל רשימת webhooks

פרמטרים (Query)

פרמטר	סוג	תיאור
`mailbox_id`	integer	סנן לפי תיבת דואר

POST /webhooks צור webhook חדש

פרמטרים (Body)

פרמטר	סוג	תיאור
`url`	string	חובה כתובת URL לשליחת התראות
`mailbox_id`	integer	הגבל לתיבת דואר ספציפית
`events`	array	אירועים: new_message, transcription_complete, aibot_conversation
`secret`	string	מפתח סודי לאימות

דוגמה

curl -X POST "https://api.mazkira.co.il/api/webhooks" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
         "url": "https://yourserver.com/webhook",
         "events": ["new_message", "aibot_conversation"],
         "secret": "your_secret_key"
     }'
                

פורמט Webhook Payload

{
    "event": "new_message",
    "timestamp": "2026-01-13T14:30:00Z",
    "data": {
        "message_id": 42,
        "mailbox_id": 1,
        "caller_id": "+972501234567",
        "duration": 45
    },
    "signature": "hmac_sha256_signature"
}
                

DELETE /webhooks/{id} מחק webhook

מוחק webhook קיים.

קודי שגיאה

קוד	משמעות	תיאור
`200`	OK	הבקשה הצליחה
`201`	Created	המשאב נוצר בהצלחה
`400`	Bad Request	בקשה לא תקינה - בדוק את הפרמטרים
`401`	Unauthorized	מפתח API חסר או לא תקין
`403`	Forbidden	אין הרשאה לפעולה זו
`404`	Not Found	המשאב לא נמצא
`405`	Method Not Allowed	השיטה (GET/POST/etc) לא נתמכת
`429`	Too Many Requests	חריגה ממגבלת קצב הבקשות
`500`	Server Error	שגיאת שרת - נסה שוב מאוחר יותר

דוגמה לתגובת שגיאה

{
    "success": false,
    "error": "Invalid API key"
}
        

מגבלות קצב (Rate Limiting)

סוג בקשה	מגבלה
בקשות API כלליות	100 בקשות לדקה
התחברות (Login)	5 ניסיונות ב-15 דקות
יצירת משאבים	30 בקשות לדקה

שים לב: חריגה ממגבלות הקצב תגרום לחסימה זמנית של הגישה ל-API.

דוגמאות קוד

JavaScript (Node.js)

const axios = require('axios');

const API_KEY = 'your_api_key';
const BASE_URL = 'https://api.mazkira.co.il/api';

// קבל הודעות חדשות
async function getNewMessages() {
    const response = await axios.get(`${BASE_URL}/messages`, {
        headers: { 'X-API-Key': API_KEY },
        params: { status: 'new' }
    });
    return response.data.data;
}

// סמן הודעה כנקראה
async function markAsRead(messageId) {
    await axios.post(`${BASE_URL}/messages/${messageId}/read`, {}, {
        headers: { 'X-API-Key': API_KEY }
    });
}
        

Python

import requests

API_KEY = 'your_api_key'
BASE_URL = 'https://api.mazkira.co.il/api'

headers = {'X-API-Key': API_KEY}

# קבל הודעות חדשות
def get_new_messages():
    response = requests.get(
        f'{BASE_URL}/messages',
        headers=headers,
        params={'status': 'new'}
    )
    return response.json()['data']

# הורד הקלטה
def download_message(message_id, output_path):
    response = requests.get(
        f'{BASE_URL}/messages/{message_id}/download',
        headers=headers
    )
    with open(output_path, 'wb') as f:
        f.write(response.content)
        

PHP

<?php
$apiKey = 'your_api_key';
$baseUrl = 'https://api.mazkira.co.il/api';

// קבל הודעות
function getMessages($status = null) {
    global $apiKey, $baseUrl;

    $url = "$baseUrl/messages";
    if ($status) {
        $url .= "?status=$status";
    }

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"]
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true)['data'];
}

// בקש תמלול
function transcribeMessage($messageId) {
    global $apiKey, $baseUrl;

    $ch = curl_init("$baseUrl/messages/$messageId/transcribe");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            "X-API-Key: $apiKey",
            "Content-Type: application/json"
        ],
        CURLOPT_POSTFIELDS => json_encode(['language' => 'he'])
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}
        

תמיכה

יש לך שאלות? צריך עזרה?

אימייל: support@mazkira.co.il
פורטל: login.mazkira.co.il

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