מדריך API — ניהול רשימות תפוצה

תוכן עניינים

סקירה כללית אימות uplodePhones — ייבוא מספרים phonesList — שליפה phoneEdit — עריכה phonesDelete — מחיקה setStatus — חסימה / שחרור תרחישים נפוצים הערות יישום Markdown למתכנת

סקירה כללית

רשימת תפוצה היא אוסף אנשי קשר עם שם, מספר טלפון ראשי וכתובת מייל. כל איש קשר משויך לרשימה אחת לפי מזהה (mailingList). רשימות תפוצה משמשות לקמפיינים טלפוניים, שליחת מיילים, הקראות IVR ופעולות broadcast נוספות.

סטטוס איש קשר: 0 = פעיל, 1 = חסום. אנשי קשר חסומים אינם נכללים בקמפיינים יוצאים.

כתובת ה-API

https://app.ipsales.co.il/mailingListsApi.php

כל הבקשות חייבות להישלח ב-POST. ניתן לשלוח כ-application/x-www-form-urlencoded, application/json, או multipart/form-data.

שמות פעולות עם איות תאימות לאחור: uplodePhones ו-freeSerch נכתבים בכתיב המקורי כדי לשמור על תאימות עם אינטגרציות קיימות. יש להשתמש בהם בדיוק כפי שמופיעים.

אימות

כל בקשה חייבת לכלול apiKey שמזהה את חשבון הלקוח.

מיקום	דוגמה
POST body (form)	`apiKey=YOUR_API_KEY&...`
POST body (JSON)	`{ "apiKey": "YOUR_API_KEY", ... }`

uplodePhones — ייבוא מספרים לרשימת תפוצה

הוספה / עדכון / החלפה / מחיקה של אנשי קשר ברשימה

POST · action=uplodePhones

פרמטרים

שדה	חובה	סוג	תיאור
action	חובה	string	הערך הקבוע `uplodePhones`
apiKey	חובה	string	מפתח ה-API של החשבון
mailingList	חובה	integer	מזהה מספרי של רשימת התפוצה
phones	חובה*	array / JSON-string	מערך של אנשי קשר. *לא נדרש כאשר `insertType=delete` מיועד לרוקן את כל הרשימה.
insertType	אופציונלי	enum	אופן הייבוא. ברירת מחדל: `all`. ראו טבלה למטה.
name	אופציונלי	string	שם תצוגה של האצווה — שמור לעתיד, ניתן להשמיט.

מבנה איש קשר ב-`phones`

שדה	חובה	תיאור
phone	חובה*	מספר טלפון. ינורמל אוטומטית. *או `phone` או `email` חייב להופיע.
firstName	אופציונלי	שם פרטי
lastName	אופציונלי	שם משפחה
email	אופציונלי*	כתובת מייל
status	אופציונלי	`0` = פעיל (ברירת מחדל), `1` = חסום

מצבי ייבוא — `insertType`

ערך	התנהגות
`all`	ברירת מחדל. מוסיף חדשים ומעדכן קיימים. השוואה לפי `phone`, ואחר כך לפי `email`.
`replacing`	הרסני. ריקון מלא של הרשימה והכנסת השורות מחדש. אנשי הקשר הקיימים נמחקים.
`insert`	הוספה בלבד — אנשי קשר חדשים מתווספים, קיימים מדולגים בשקט.
`delete`	הסרת אנשי הקשר התואמים מהרשימה. שורות שלא נמצאו — מתעלמים מהן.

תגובה — הצלחה

{
  "newNumbers":     12,
  "updateNumbers":  4,
  "errorNumbers":   1,
  "deletedNumbers": 0
}

דוגמה — cURL

curl -X POST https://app.ipsales.co.il/mailingListsApi.php \
  -d "action=uplodePhones" \
  -d "apiKey=YOUR_API_KEY" \
  -d "mailingList=1042" \
  -d "insertType=all" \
  --data-urlencode 'phones=[
    {"phone":"0501234567","firstName":"Avi","lastName":"Cohen","email":"[email protected]","status":0},
    {"phone":"0507654321","firstName":"Dana","lastName":"Levy","email":"","status":0}
  ]'

דוגמה — Python (JSON body)

import requests

r = requests.post('https://app.ipsales.co.il/mailingListsApi.php', json={
    'action':      'uplodePhones',
    'apiKey':      'YOUR_API_KEY',
    'mailingList': 1042,
    'insertType':  'all',
    'phones': [
        {'phone': '0501234567', 'firstName': 'Avi',  'lastName': 'Cohen', 'email': '[email protected]', 'status': 0},
        {'phone': '0507654321', 'firstName': 'Dana', 'lastName': 'Levy',  'email': '',                'status': 0},
    ],
})
print(r.json())

phonesList — שליפת אנשי קשר

קריאת אנשי הקשר ברשימה — תומך בחיפוש ופייג'ינג

POST · action=phonesList

פרמטרים

שדה	חובה	סוג	תיאור
action	חובה	string	`phonesList`
apiKey	חובה	string	מפתח ה-API
mailingList	חובה	integer	מזהה רשימת התפוצה
freeSerch	אופציונלי	string	חיפוש חופשי על טלפון, שם פרטי או שם משפחה. (איות תאימות לאחור.)
limit	אופציונלי	integer	גודל עמוד. בלי הפרמטר — מוחזרות כל השורות.
page	אופציונלי	integer	מספר עמוד (זרו-בייסד). יש לשלוח יחד עם `limit`.

תגובה — הצלחה

{
  "phonesList": {
    "10001": {
      "id":        "10001",
      "phone1":    "0501234567",
      "phone2":    "",
      "phone3":    "",
      "phones":    "0501234567",
      "firstName": "Avi",
      "lastName":  "Cohen",
      "email":     "[email protected]",
      "email2":    "",
      "emails":    "[email protected]",
      "status":    "0",
      "RHstatus":  0
    }
  },
  "phonesCount": "1,250",
  "fromLine":    0,
  "toLine":      50
}

חשוב: ה-key של כל איש קשר ב-phonesList הוא ה-id שלו — וזה הערך שעובר אחר כך ל-phonesDelete או ל-setStatus.

דוגמה — cURL

curl -X POST https://app.ipsales.co.il/mailingListsApi.php \
  -d "action=phonesList" \
  -d "apiKey=YOUR_API_KEY" \
  -d "mailingList=1042" \
  -d "freeSerch=Cohen" \
  -d "limit=50" \
  -d "page=0"

phoneEdit — הוספה / עדכון איש קשר בודד

שמירת איש קשר אחד — חדש או עדכון של קיים

POST · action=phoneEdit

פרמטרים

שדה	חובה	סוג	תיאור
action	חובה	string	`phoneEdit`
apiKey	חובה	string	מפתח ה-API
mailingList	חובה	integer	מזהה רשימת התפוצה
id	אופציונלי	integer / string	מזהה איש קשר לעדכון. אם חסר או קטן/שווה אפס — תתבצע הוספה.
phone1	חובה*	string	טלפון ראשי. *או `phone1` או `email` חייב להופיע.
firstName	אופציונלי	string	שם פרטי
lastName	אופציונלי	string	שם משפחה
email	חובה*	string	מייל ראשי
email2	אופציונלי	string	מייל משני

בלי id — השרת מחפש קודם לפי phone1 או email; אם נמצאה התאמה, השורה תתעדכן, אחרת תיווצר חדשה.

תגובה — הצלחה

{ "status": "Ok", "note": "איש הקשר נשמר בהצלחה" }

תגובה — שגיאה

{ "status": "Error", "note": "חייב טלפון ראשי או כתובת מייל" }

דוגמה — cURL

curl -X POST https://app.ipsales.co.il/mailingListsApi.php \
  -d "action=phoneEdit" \
  -d "apiKey=YOUR_API_KEY" \
  -d "mailingList=1042" \
  -d "phone1=0501234567" \
  -d "firstName=Avi" \
  -d "lastName=Cohen" \
  -d "[email protected]"

phonesDelete — מחיקת אנשי קשר

מחיקה מוחלטת של אנשי קשר לפי ID

POST · action=phonesDelete

פרמטרים

שדה	חובה	סוג	תיאור
action	חובה	string	`phonesDelete`
apiKey	חובה	string	מפתח ה-API
mailingList	חובה	integer	מזהה רשימת התפוצה
deleteList	חובה	string / array	רשימת מזהי אנשי קשר — מחרוזת מופרדת בפסיקים, או JSON array.

תגובה — הצלחה

{ "status": "Ok", "note": "המספרים נמחקו בהצלחה" }

דוגמה

curl -X POST https://app.ipsales.co.il/mailingListsApi.php \
  -d "action=phonesDelete" \
  -d "apiKey=YOUR_API_KEY" \
  -d "mailingList=1042" \
  -d "deleteList=10001,10002,10003"

setStatus — חסימה / שחרור אנשי קשר

סימון איש קשר כפעיל או חסום

POST · action=setStatus

אנשי קשר חסומים (status=1) אינם נכללים בקמפיינים יוצאים עד לשחרור.

פרמטרים

שדה	חובה	סוג	תיאור
action	חובה	string	`setStatus`
apiKey	חובה	string	מפתח ה-API
mailingList	חובה	integer	מזהה רשימת התפוצה
phone	חובה	string	מזהה איש קשר אחד, או רשימת מזהים מופרדים בפסיקים (לדוגמה `10001,10002`). למרות השם — הפרמטר מקבל ID של איש קשר (כפי שמוחזר ב-`phonesList`), לא מספר טלפון.
status	חובה	integer	`1` = חסימה, `0` = שחרור.

תגובה — הצלחה

{
  "status": "Ok",
  "note":   "המספר נחסם בהצלחה",
  "phones": ["10001", "10002"]
}

note יהיה "המספר נחסם בהצלחה" בחסימה ו-"המספר אושר בהצלחה" בשחרור.

דוגמה — חסימת שני אנשי קשר

curl -X POST https://app.ipsales.co.il/mailingListsApi.php \
  -d "action=setStatus" \
  -d "apiKey=YOUR_API_KEY" \
  -d "mailingList=1042" \
  -d "phone=10001,10002" \
  -d "status=1"

תרחישים נפוצים

1. סנכרון פלח לקוחות יומי לרשימת קמפיין

השתמשו ב-insertType=all — חדשים מתווספים, קיימים מתעדכנים לפי טלפון.

requests.post(URL, json={
    'action': 'uplodePhones', 'apiKey': KEY, 'mailingList': 1042,
    'insertType': 'all',
    'phones': [
        {'phone': c.phone, 'firstName': c.first, 'lastName': c.last,
         'email': c.email, 'status': 0}
        for c in todays_segment
    ],
})

2. החלפת רשימת broadcast שבועית

השתמשו ב-insertType=replacing — הרשימה מתרוקנת ונטענת מחדש.

requests.post(URL, json={
    'action': 'uplodePhones', 'apiKey': KEY, 'mailingList': 1042,
    'insertType': 'replacing',
    'phones': new_weekly_list,
})

3. טיפול ב-opt-out

שלוף את ה-ID דרך phonesList, ואז קרא ל-setStatus עם status=1:

listing = requests.post(URL, data={'action':'phonesList', 'apiKey':KEY,
                                   'mailingList':1042, 'freeSerch':optout_phone}).json()
ids = ','.join(listing['phonesList'].keys())
requests.post(URL, data={'action':'setStatus', 'apiKey':KEY,
                         'mailingList':1042, 'phone':ids, 'status':1})

4. הסרה מוחלטת של אנשי קשר

requests.post(URL, data={'action':'phonesDelete', 'apiKey':KEY,
                         'mailingList':1042, 'deleteList':'10001,10002'})

הערות יישום

תמיד בדקו status === "Ok" — ה-API מחזיר "Ok" (אות גדולה אחת) בהצלחה. בהשוואה למספר APIs במקביל — מומלץ להשוות case-insensitive.
נורמליזציה של טלפונים. השרת מסיר תווים שאינם ספרות ומיישר לפורמט ישראלי מקומי. ניתן לשלוח 050-123-4567 או +972-50-123-4567 — השרת ידע לטפל.
חובה טלפון או מייל בכל איש קשר. שורות שאין בהן אף אחד מהם — נסגרות בשקט ונספרות ב-errorNumbers.
חסימה מול מחיקה. setStatus משאיר את השורה אך מסמן אותה כבלתי-פעילה — שימושי למעקב opt-out תקין. phonesDelete מסיר את השורה לחלוטין.
שמות פרמטרים עם איות תאימות. uplodePhones ו-freeSerch נשמרו בכתיב המקורי משיקולי תאימות לאחור. שלחו אותם בדיוק כך.
phone ב-setStatus = ID, לא מספר טלפון. כדי לחסום מספר אנשי קשר בקריאה אחת, שלחו רשימת ID-ים מופרדת בפסיקים.

תוכן עניינים

סקירה כללית

כתובת ה-API

אימות

uplodePhones — ייבוא מספרים לרשימת תפוצה

הוספה / עדכון / החלפה / מחיקה של אנשי קשר ברשימה

פרמטרים

מבנה איש קשר ב-phones

מצבי ייבוא — insertType

תגובה — הצלחה

דוגמה — cURL

דוגמה — Python (JSON body)

phonesList — שליפת אנשי קשר

קריאת אנשי הקשר ברשימה — תומך בחיפוש ופייג'ינג

פרמטרים

תגובה — הצלחה

דוגמה — cURL

phoneEdit — הוספה / עדכון איש קשר בודד

שמירת איש קשר אחד — חדש או עדכון של קיים

פרמטרים

תגובה — הצלחה

תגובה — שגיאה

דוגמה — cURL

phonesDelete — מחיקת אנשי קשר

מחיקה מוחלטת של אנשי קשר לפי ID

פרמטרים

תגובה — הצלחה

דוגמה

setStatus — חסימה / שחרור אנשי קשר

סימון איש קשר כפעיל או חסום

פרמטרים

תגובה — הצלחה

דוגמה — חסימת שני אנשי קשר

תרחישים נפוצים

1. סנכרון פלח לקוחות יומי לרשימת קמפיין

2. החלפת רשימת broadcast שבועית

3. טיפול ב-opt-out

4. הסרה מוחלטת של אנשי קשר

הערות יישום

מבנה איש קשר ב-`phones`

מצבי ייבוא — `insertType`