דלג לתוכן הראשי

Maskyoo REST API

ה-REST API של מסקיו מאפשר גישה פרוגרמטית לניהול מספרי מסקיו, משתמשים, תגיות, רשימה שחורה, הקלטות, הודעות קוליות, שאילתות CDR והמרות Google Ads.

נקודות קצה​

נקודת הקצה הראשית:

https://[MASKYOO_URL]/api/

קישורי Click2Call ציבוריים (שנוצרים על ידי click2call_link) מוחזרים כ-URL מלא שאפשר להטמיע ישירות.

כל פונקציה נקראת על ידי העברת שם ה-service ב-query string או בגוף ה-POST (לדוגמה service=get_maskyoo). הפרמטרים יכולים להישלח ב-GET או POST; עבור העלאות קבצים יש להשתמש ב-multipart/form-data.

אימות (Authentication)​

כל קריאה חייבת לעבור שני שלבי אימות בשרת:

1. הגבלת כתובות IP​

כתובת ה-IP של הלקוח חייבת להופיע ברשימת ה-IP המאושרות של החשבון (מוגדרת בממשק בהגדרות מערכת → הגדרות → לשונית הגדרות API). קריאה מ-IP לא מאושר מחזירה HTTP 401 Unauthorized - IP Address:'…' is not allowed.

2. Bearer Token​

אם מוגדר בחשבון ערך של קוד גישה ל-API, יש לצרף אותו בכותרת Authorization:

Authorization: Bearer YOUR_TOKEN_HERE

אם הטוקן חסר מוחזרת שגיאה 401 Unauthorized - Token Required; אם הוא פג תוקף – 401 Unauthorized - Token Expired; אם הוא לא שייך למערכת – 401 Unauthorized - Invalid Token.

לפרטים על יצירת טוקן ראו הוספת טוקן לגישת API.

דוגמה עם cURL​

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X GET "https://[MASKYOO_URL]/api/?service=get_maskyoo&maskyoo=0776670000&format=json"

פורמט בקשות​

כל ה-services תומכים גם ב-GET וגם ב-POST עם אותם פרמטרים. העלאות (upload_prompt) דורשות multipart/form-data.

בקשת GET​

https://[MASKYOO_URL]/api/?service=SERVICE_NAME&param1=value1&param2=value2

בקשת POST​

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X POST "https://[MASKYOO_URL]/api/" \
     -d "service=SERVICE_NAME" \
     -d "param1=value1"

פורמט תגובה​

פרמטר format קובע את פורמט הפלט:

ערךתיאור
jsonתגובה ב-JSON
xmlתגובה ב-XML (ברירת המחדל אם לא צוין json)

המבנה הכללי של התגובה:

{
  "service": "get_maskyoo",
  "status": { "code": 200, "description": "ok" },
  "result": [ ... ]
}
  • service – שם ה-service שנקרא.
  • status.code – 200 בהצלחה, אחרת קוד שגיאה ייעודי ל-service (ראו בתיעוד של כל פונקציה).
  • status.description – הסבר טקסטואלי.
  • result – תלוי ב-service: אובייקט, מערך אובייקטים, או מחרוזת חופשית.

קטגוריות API​

קטגוריהתיאורמספר services
ניהול מסקיויצירה, עדכון, שחרור, שחזור, הקצאה, שיחות וקישורי Click2Call10
ניהול משתמשיםמשתמשים, הרשאות, שיוך מספרי מסקיו, יומן גישה9
ניהול תגיותיצירה/עדכון/מחיקת תגיות ושיוך מספרי מסקיו אליהן12
שאילתות והקלטותשאילתות CDR, הורדת הקלטה, מטא-דאטה, Google Ads Offline Conversion, יצירת CDR ידני7
רשימה שחורהניהול מספרים חסומים (חסימה גלובלית או חסימה לפי מסקיו)3
הודעות קוליותהעלאה, הורדה, מחיקה, רשימה והקלטה מהטלפון5

דוגמאות בשפות תכנות​

PHP​

<?php
$base_url = "https://[MASKYOO_URL]/api/";
$token    = "YOUR_TOKEN_HERE";

$data = array(
    "service" => "get_maskyoo",
    "maskyoo" => "0776670000",
    "format"  => "json",
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $base_url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Authorization: Bearer " . $token,
));

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

$result = json_decode($response, true);
print_r($result);

C#​

using System.Net;
using System.Collections.Specialized;
using System.Text;

string url   = "https://[MASKYOO_URL]/api/";
string token = "YOUR_TOKEN_HERE";

using (var client = new WebClient())
{
    var values = new NameValueCollection();
    values["service"] = "get_maskyoo";
    values["maskyoo"] = "0776670000";
    values["format"]  = "json";

    client.Headers.Add("Authorization", "Bearer " + token);
    var response       = client.UploadValues(url, values);
    var responseString = Encoding.UTF8.GetString(response);

    Console.WriteLine(responseString);
}

קודי שגיאה כלליים​

קודמשמעות
200הצלחה
401כשל באימות (IP לא מאושר / טוקן חסר / פג תוקף / לא תקין / חשבון מושעה)
998חסר פרמטר service
999שגיאה פנימית

כל service מחזיר קודי שגיאה נוספים ייעודיים לו (למשל 1xxx ל-CDR, 2xxx לרשימה שחורה, 3xxx לשיחות, 4xxx למסקיו, 5xxx לתגיות, 6xxx ליומן גישה, 7xxx-8xxx למשתמשים, 9xxx להודעות קוליות). פירוט מופיע בתיעוד של כל service.

מגבלות וזמני ריצה​

  • בקשה יחידה יכולה לרוץ עד 10 דקות (רלוונטי בעיקר לשאילתות cdr_query כבדות ולהורדת הקלטות מהארכיון).
  • upload_prompt: עד 50 MB לקובץ.
  • חשבון מושעה לא רשאי להשתמש ב-API (יוחזר 401 Unauthorized - Account Suspended).

תמיכה​

לשאלות ותקלות פנו לתמיכת מסקיו.

השפעות על המערכת​

ה‑REST API הוא ערוץ עבודה פרוגרמטי מלא על החשבון:

  • ממשק גרפי — כל שינוי דרך ה‑API (יצירת מסקיו, עדכון משתמש, הוספה לרשימה שחורה) נראה מיידית בממשק של המסקיו וכל השינויים מתועדים בלוג שינויים
  • הרשאות — הטוקן מקושר למשתמש ספציפי ועובד תחת ההרשאות שלו; קריאות שאינן מאושרות ייחסמו
  • ביצועים — שאילתות cdr_query כבדות יכולות לרוץ עד 10 דקות; יש להשתמש בפילטרים וב‑LIMIT כדי לא להעמיס
  • אוטומציה — יצירת CDR ידני (create_maskyoo_cdr) מריצה מיד את כללי האוטומציה של סיום שיחה ואת הפיקסל
  • אבטחה — נדרש גם IP whitelist וגם Bearer Token; חשבון מושעה לא יכול להשתמש ב‑API

ראו גם​