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

ה-API מיועד למפתחים ולכל מי שמרגיש בנוח עם קוד מותאם או עם אינטגרציות REST. לכל endpoint, ראו את מדריכי ה-API reference בחלק הזה או את תיעוד ה-API של אקטיב טרייל, שבו אפשר גם לבדוק קריאות עם הנתונים שלכם.

כתובת הבסיס ומשאבים

כל הבקשות נשלחות אל https://webapi.mymarketing.co.il/api/. המשאבים הם שמות עצם, כמו groups או contacts, ולכל פריט יש מזהה (ID) משלו:

  • GET https://webapi.mymarketing.co.il/api/groups מחזיר את הקבוצות שלכם.
  • GET https://webapi.mymarketing.co.il/api/groups/1234 מחזיר את הקבוצה שהמזהה שלה 1234.

אימות

שלחו את מפתח ה-API בכל בקשה, בכותרת (header) בשם Authorization:

curl -X GET "https://webapi.mymarketing.co.il/api/groups" \
  -H "Authorization: YOUR_API_KEY"

כדי ליצור מפתח, ראו מפתחות API. אפשר להגביל מפתח לכתובות IP מסוימות ולהגדיר לו תאריך תפוגה.

שיטות HTTP

  • GET קורא נתונים. הוא אף פעם לא משנה שום דבר.
  • POST יוצר משאב חדש, למשל קבוצה חדשה. גוף הבקשה מכיל את המשאב החדש כ-JSON.
  • PUT מעדכן משאב קיים.
  • DELETE מוחק משאב לפי המזהה שלו.

גוף הבקשה והתגובה בפורמט JSON (יש תמיכה גם ב-XML).

פרמטרים

  • פרמטרים בנתיב (path) הם חלק מהכתובת ומזהים משאב, למשל מזהה הקבוצה ב-/api/groups/{id}/members. החליפו אותם בערכים אמיתיים מהחשבון שלכם.
  • פרמטרים במחרוזת השאילתה (query string) מסננים את התוצאות ומחלקים אותן לעמודים, למשל /api/groups?SearchTerm=vip&Page=1&Limit=50.
  • פרמטרים בגוף הבקשה (body) הם אובייקט ה-JSON שנשלח עם בקשות POST ו-PUT.

הפרמטרים של כל endpoint, ואילו מהם חובה, מפורטים במדריכי ה-API reference.

חלוקה לעמודים

endpoints שמחזירים רשימות מחזירים את התוצאות בעמודים. השתמשו ב-Page כדי לבחור את העמוד (החל מ-1) וב-Limit כדי לקבוע כמה פריטים יחזרו בכל עמוד (עד 100, ובחלק מה-endpoints פחות). אם לא שולחים Limit, מקבלים 20 פריטים. המשיכו לבקש את העמוד הבא עד שמתקבלת תגובה ריקה. לפרטים, ראו מגבלות API וחלוקה לעמודים.

השלבים הבאים