בעזרת ה-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 וחלוקה לעמודים.