Masuri Core Logo

Masuri Core

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

חיבור המערכת לשירותים חיצוניים כמו Zapier, Make, או קוד מותאם אישית.

מפתחות ופרטי API
App IDapp_1234567890abcdef
Company IDcomp_fedcba0987654321
API Keyb44_secret_abcdef1234567890_fedcba0987654321
Endpoint ו-Payload ליצירת ליד

כדי ליצור ליד חדש, שלח בקשת POST לכתובת הבאה:

POST https://app.base44.com/api/v1/apps/app_1234567890abcdef/entities/leads/records

Headers (כותרות)

ודא שהבקשה כוללת את הכותרות הבאות:

Content-Type: application/json
Authorization: Bearer b44_secret_abcdef1234567890_fedcba0987654321

Body (גוף הבקשה)

דוגמת JSON תקינה. השתמש במבנה זה ב-Zapier/Make ומפה את העמודות הרלוונטיות מה-Google Sheet.

{
  "company_id": "comp_fedcba0987654321", 
  "name": "שם הליד מהגיליון",
  "phone": "050-1234567",
  "email": "lead@example.com",
  "status": "new",
  "source": "Google Sheet",
  "notes": "פרטים נוספים מהגיליון"
}

* שדות חובה: company_id, name, phone, status.

הנחיות ליישום בצד השרת (Backend)

1. אכיפת Tenant ID (חובה)

כל בקשת API ליצירה, קריאה, עדכון או מחיקה של רשומה חייבת להיות מסוננת לפי `company_id` של ה-Tenant. יש לוודא שה-API Key שסופק ב-Header שייך לאותו `company_id`.

2. דרישת Headers

יש לדרוש את ה-Headers הבאים בכל בקשת `POST` ליצירת רשומה:

  • `X-Tenant-ID`: חייב להכיל את ה-`company_id` של הלקוח.
  • `X-Idempotency-Key`: מזהה ייחודי לבקשה למניעת כפילויות.

3. לוגיקת אידמפוטנטיות (Idempotency)

לפני יצירת ליד חדש, יש לבדוק אם כבר קיים ליד עם מזהה ייחודי עבור אותו Tenant. הסדר המומלץ:

// Pseudocode for Idempotency Logic
function createLead(request) {
  const { tenantId, idempotencyKey, payload } = request;

  // 1. Check idempotency key first
  const existingRequest = findRequestByIdempotencyKey(idempotencyKey, tenantId);
  if (existingRequest) {
    return 200 (OK) with existingRequest.response;
  }

  // 2. Check for external_id if provided
  if (payload.external_id) {
    const existingLead = findLeadBy({ external_id: payload.external_id, company_id: tenantId });
    if (existingLead) {
      // Record the idempotency key and return conflict
      recordIdempotency(idempotencyKey, existingLead);
      return 409 (Conflict) with existingLead;
    }
  }

  // 3. Fallback: Hash key if no external_id
  const hashKey = createHash(payload.email, payload.phone, payload.campaign, tenantId);
  const existingLeadByHash = findLeadBy({ hash_key: hashKey, company_id: tenantId });
  if (existingLeadByHash) {
    recordIdempotency(idempotencyKey, existingLeadByHash);
    return 409 (Conflict) with existingLeadByHash;
  }

  // 4. All checks passed, create new lead
  const newLead = createNewLeadInDB(payload, tenantId, hashKey);
  recordIdempotency(idempotencyKey, newLead);
  return 201 (Created) with newLead;
}

4. קודי תגובה (Status Codes)

השתמש בקודי הסטטוס הנכונים כדי לספק משוב ברור:

  • `201 Created`: הליד נוצר בהצלחה.
  • `200 OK`: הבקשה טופלה בהצלחה (למשל, מפתח אידמפוטנטיות כפול, הוחזר הליד המקורי).
  • `409 Conflict`: זוהה ליד כפול על סמך המזהים הייחודיים.
  • `422 Unprocessable Entity`: שגיאת ולידציה ב-Payload (למשל, חסר אימייל וטלפון).
  • `401 Unauthorized` / `403 Forbidden`: שגיאת הרשאות או API Key לא תקין.