הצטרפות

חיפוש לקוחות וספקים ב-API

חיפוש לקוחות וספקים ב-API

ה-API מאפשר לשלוף את רשימת הלקוחות והספקים של העסק ממערכת חיצונית — לפי ח.פ / ת.ז, מייל, שם, טלפון, מזהה חיצוני, או פשוט את כולם עמוד אחר עמוד. זהו ה-endpoint המשלים ל-addCustomer / updateCustomer: קודם מחפשים, ואז מעדכנים.

ה-endpoints

  • POST /api/customers/searchCustomers — חיפוש לקוחות. מחזיר מערך בשם customers.
  • POST /api/suppliers/searchSuppliers — חיפוש ספקים. אותם שדות בדיוק, מחזיר מערך בשם suppliers.

אופן הפנייה

  • הבקשות מתבצעות באמצעות POST לכתובת מאובטחת (HTTPS): https://app.invoice-maven.co.il/api/customers/searchCustomers
  • גוף הבקשה בפורמט JSON, בקידוד UTF-8, עם הכותרת Content-Type: application/json.
  • את מפתח ה-API אפשר לשלוח בכותרת api_key או בתוך גוף הבקשה בשדה api_key.
  • כל שמות השדות נכתבים ב-lowercase בלבד.

מגבלת קצב: כמו בכל שירותי החיפוש ב-API, ניתן לבצע חיפוש אחד ב-60 שניות לכל עסק. קריאה נוספת בתוך הדקה תחזיר שגיאה 62. לכן כדאי למשוך עמודים גדולים (עד 100 רשומות בכל קריאה) ולא לשלוח קריאה נפרדת לכל לקוח.

שדות הבקשה

כל השדות מלבד api_key הם אופציונליים. בקשה עם מפתח ה-API בלבד מחזירה את כל הלקוחות. סינונים שנשלחים יחד מצטמצמים זה עם זה (AND).

שם השדה סוג ערך חובה תיאור
api_key מחרוזת (String) כן מפתח הגישה לחשבון שלך במערכת. ניתן לשלוח גם בכותרת בשם api_key.
id מחרוזת (GUID) לא המזהה הייחודי של הלקוח — התאמה מדויקת. אותו מזהה שחוזר מיצירת לקוח.
identification מחרוזת (String) לא ח.פ / ת.ז — התאמה מדויקת.
external_customer_id מחרוזת (String) לא המזהה שלכם ממערכת חיצונית (CRM, חנות) — התאמה מדויקת.
email מחרוזת (String) לא כתובת המייל הראשית — התאמה מדויקת.
name מחרוזת (String) לא שם הלקוח — חיפוש מכיל (טקסט חופשי).
phone מחרוזת (String) לא חיפוש מכיל — מחפש גם בטלפון וגם בנייד.
active בוליאני (true / false) לא סינון לפי לקוחות פעילים או לא פעילים.
from_update_date
to_update_date		 תאריך (dd/MM/yyyy) לא טווח תאריכי עדכון (כולל). זו הדרך לבצע סנכרון מצטבר — למשוך רק את מה שהשתנה מאז הפעם הקודמת.
from_insert_date
to_insert_date		 תאריך (dd/MM/yyyy) לא טווח תאריכי יצירה (כולל) — למשיכת לקוחות חדשים בלבד.
sort_by מחרוזת (String) לא שדה למיון: customer_id (ברירת מחדל), name, insert_date, update_date.
sort_dir מחרוזת (String) לא כיוון המיון: asc (ברירת מחדל) או desc.
page מספר (Integer) לא מספר העמוד, מתחיל מ-1. ברירת מחדל: 1.
page_size מספר (Integer) לא כמות הרשומות בעמוד. ברירת מחדל 50, מקסימום 100 (ערך גבוה יותר יצומצם ל-100).

דוגמאות

חיפוש לקוח לפי ח.פ:

POST /api/customers/searchCustomers
Content-Type: application/json
api_key: YOUR_API_KEY

{
  "identification": "123456789"
}

סנכרון מצטבר — כל מי שהשתנה מאז ה-1 ביוני, במנות של 100:

POST /api/customers/searchCustomers
Content-Type: application/json

{
  "api_key": "YOUR_API_KEY",
  "from_update_date": "01/06/2026",
  "sort_by": "update_date",
  "sort_dir": "asc",
  "page": 1,
  "page_size": 100
}

מבנה התשובה

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

{
  "status_code": "0",
  "status_description": "OK",
  "total": 240,
  "page": 1,
  "page_size": 50,
  "pages": 5,
  "customers": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "customer_id": 12345,
      "name": "שלום כהן",
      "identification": "123456789",
      "external_customer_id": "CRM-12345",
      "email": "shalom@example.com",
      "emails": ["shalom@example.com", "accounting@example.com"],
      "phone_number": "03-1234567",
      "cell_phone": "050-9876543",
      "address": "רחוב הרצל 10, תל אביב 6121001",
      "city": "תל אביב",
      "country_code": "IL",
      "accounting_key": "20336",
      "remark": "לקוח ותיק",
      "active": true,
      "customer": true,
      "supplier": false,
      "insert_date": "01/06/2026 09:15:00",
      "update_date": "12/06/2026 14:02:31",
      "custom_fields": { "field_p73n3r": "לקוח מועדף" }
    }
  ]
}
  • id — המזהה הייחודי של הלקוח, וזה בדיוק המזהה ש-updateCustomer ו-addOrUpdateCustomer מקבלים. גם לקוח שנוצר ידנית במסכי המערכת (ולכן עדיין אין לו מזהה כזה) מקבל אותו אוטומטית בפעם הראשונה שהוא חוזר בחיפוש — כך שאפשר למשוך אותו ולעדכן אותו מיד אחר כך.
  • emails — כל כתובות המייל של הלקוח לפי סדרן, כולל הראשית.
  • custom_fields — השדות המותאמים אישית שהוגדרו בעסק, לפי אותם מפתחות (field_key) שהיצירה והעדכון מקבלים. בשדה מסוג רשימת בחירה חוזר הערך שנבחר.
  • שדות ריקים פשוט לא מופיעים בתשובה.

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

x

הצטרפות