REST API — מדריך מהיר לשימוש ב-API של MyBusiness

מדריך מהיר לביצוע פעולות CRUD (יצירה, קריאה, עדכון, מחיקה) דרך ה-REST API של MyBusiness. כולל דוגמאות קוד ב-curl וב-Node.js, הסבר על אימות, שאילתות מתקדמות, וטיפים לעבודה מאובטחת.

ה-REST API של MyBusiness מאפשר גישה מלאה לנתוני ה-CRM מכל שפת תכנות או כלי שתומך בקריאות HTTP. בין אם אתם בונים אינטגרציה עם מערכת חיצונית, מפתחים אפליקציה מותאמת, או מבצעים עיבוד נתונים אוטומטי — ה-API מספק את כל הכלים הנדרשים.

כתובת הבסיס (Base URL)

כל הקריאות ל-API מבוצעות מול הכתובת:

https://api.mbapps.co.il/parse/

הנתיב המלא לטבלה ספציפית הוא:

https://api.mbapps.co.il/parse/classes/{TABLE_NAME}

לדוגמה, לטבלת חשבונות: https://api.mbapps.co.il/parse/classes/Accounts

אימות (Authentication)

כל בקשה ל-API חייבת לכלול את ה-headers הבאים:

Header	תיאור
X-Parse-Application-Id	מזהה האפליקציה שלכם (חובה בכל בקשה)
X-Parse-Master-Key	מפתח ראשי — לשימוש בצד השרת בלבד
X-Parse-Session-Token	טוקן סשן — לשימוש בהקשר משתמש מחובר

חשוב: השתמשו ב-Master-Key רק בקוד צד-שרת (Node.js, Python, וכו'). לעולם אל תחשפו את ה-Master Key בקוד צד-לקוח (דפדפן, אפליקציה מובייל). לקריאות מצד הלקוח, השתמשו ב-Session-Token שמתקבל לאחר הזדהות משתמש.

יצירת רשומה (POST)

ליצירת רשומה חדשה, שלחו בקשת POST עם גוף JSON:

curl -X POST https://api.mbapps.co.il/parse/classes/Accounts \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Name": "חברת דוגמה", "Phone": "03-1234567"}'

תגובה מוצלחת (201 Created):

{
  "objectId": "aB1cD2eF3g",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

קריאת רשומה בודדת (GET)

לקריאת רשומה ספציפית, הוסיפו את ה-objectId לנתיב:

curl -X GET https://api.mbapps.co.il/parse/classes/Accounts/OBJECT_ID \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY"

תגובה:

{
  "objectId": "aB1cD2eF3g",
  "Name": "חברת דוגמה",
  "Phone": "03-1234567",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

עדכון רשומה (PUT)

לעדכון שדות ברשומה קיימת, שלחו רק את השדות שרוצים לעדכן:

curl -X PUT https://api.mbapps.co.il/parse/classes/Accounts/OBJECT_ID \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Phone": "03-9876543"}'

תגובה מוצלחת (200 OK):

{
  "updatedAt": "2025-01-15T11:00:00.000Z"
}

מחיקת רשומה (DELETE)

למחיקת רשומה, שלחו בקשת DELETE עם ה-objectId:

curl -X DELETE https://api.mbapps.co.il/parse/classes/Accounts/OBJECT_ID \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY"

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

שאילתות מתקדמות (Queries)

לשליפת רשומות מרובות עם סינון, השתמשו בפרמטר where בבקשת GET:

סינון בסיסי

curl -X GET \
  --data-urlencode 'where={"Status":"פעיל"}' \
  https://api.mbapps.co.il/parse/classes/Accounts \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY"

אופרטורים נתמכים

אופרטור	תיאור	דוגמה
$gt	גדול מ-	{"Amount": {"$gt": 1000}}
$lt	קטן מ-	{"Amount": {"$lt": 500}}
$gte	גדול או שווה	{"Amount": {"$gte": 1000}}
$lte	קטן או שווה	{"Amount": {"$lte": 500}}
$ne	שונה מ-	{"Status": {"$ne": "סגור"}}
$in	אחד מתוך רשימה	{"Status": {"$in": ["פעיל","חדש"]}}
$nin	לא ברשימה	{"Status": {"$nin": ["סגור","בוטל"]}}
$regex	ביטוי רגולרי	{"Name": {"$regex": "חברת"}}
$exists	השדה קיים/לא קיים	{"Email": {"$exists": true}}

שאילתת OR

לחיפוש לפי תנאי OR (אחד מהתנאים מתקיים):

curl -X GET \
  --data-urlencode 'where={"$or": [{"Status":"פעיל"}, {"Status":"חדש"}]}' \
  https://api.mbapps.co.il/parse/classes/Accounts \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY"

עימוד תוצאות (Pagination)

פרמטר	תיאור	ברירת מחדל
limit	מספר תוצאות מרבי	100
skip	מספר רשומות לדלג עליהן	0
order	שדה מיון (תחילית - למיון יורד)	—
count	הוספת count=1 מחזיר גם סך כל הרשומות	—

curl -X GET \
  "https://api.mbapps.co.il/parse/classes/Accounts?limit=10&skip=20&order=-createdAt" \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY"

הרחבת Pointers עם include

כאשר לרשומה יש שדה Pointer (הפניה לטבלה אחרת), ניתן לכלול את הנתונים המלאים של הרשומה המקושרת:

curl -X GET \
  "https://api.mbapps.co.il/parse/classes/Sales?include=AccountId" \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY"

במקום לקבל רק את ה-objectId של החשבון, תקבלו את כל פרטי החשבון בתוך התגובה.

דוגמת קוד ב-Node.js

const axios = require('axios');

const API_BASE = 'https://api.mbapps.co.il/parse/classes';
const HEADERS = {
  'X-Parse-Application-Id': 'YOUR_APP_ID',
  'X-Parse-Master-Key': 'YOUR_MASTER_KEY',
  'Content-Type': 'application/json'
};

// יצירת רשומה
async function createAccount(data) {
  const response = await axios.post(`${API_BASE}/Accounts`, data, {
    headers: HEADERS
  });
  return response.data;
}

// שליפת רשומות עם סינון
async function getActiveAccounts() {
  const response = await axios.get(`${API_BASE}/Accounts`, {
    headers: HEADERS,
    params: {
      where: JSON.stringify({ Status: 'פעיל' }),
      limit: 50,
      order: '-createdAt',
      include: 'OwnerId'
    }
  });
  return response.data.results;
}

// עדכון רשומה
async function updateAccount(objectId, data) {
  const response = await axios.put(
    `${API_BASE}/Accounts/${objectId}`,
    data,
    { headers: HEADERS }
  );
  return response.data;
}

// שימוש לדוגמה
(async () => {
  // יצירת חשבון חדש
  const newAccount = await createAccount({
    Name: 'חברה חדשה',
    Phone: '03-5551234',
    Status: 'פעיל'
  });
  console.log('Created:', newAccount.objectId);

  // שליפת חשבונות פעילים
  const accounts = await getActiveAccounts();
  console.log(`Found ${accounts.length} active accounts`);

  // עדכון חשבון
  await updateAccount(newAccount.objectId, {
    Phone: '03-5559876'
  });
  console.log('Updated successfully');
})();

טיפים ושיטות עבודה מומלצות

• אבטחת Master Key — לעולם אל תכללו את ה-Master Key בקוד צד-לקוח. אחסנו אותו במשתני סביבה (environment variables) בשרת.
• סביבת בדיקה — בדקו את כל הקריאות בסביבת Demo לפני הפעלה בסביבת הייצור.
• שימוש ב-include — השתמשו בפרמטר include כדי לשלוף נתוני Pointer בקריאה אחת במקום קריאות נפרדות, וכך לצמצם את מספר הבקשות לשרת.
• עימוד — תמיד השתמשו ב-limit ו-skip כשעובדים עם טבלאות גדולות. אל תנסו לשלוף את כל הרשומות בקריאה אחת.
• טיפול בשגיאות — תמיד בדקו את קוד ה-HTTP בתגובה. קודים נפוצים: 200/201 להצלחה, 400 לבקשה שגויה, 401 לבעיית אימות, 404 לרשומה שלא נמצאה.