איפה נמצא התיעוד של ה-API של ActiveTrail?

על הדומיין mymarketing.co.il ולא על activetrail.com, ולכן חיפוש לא תמיד מוביל לשם. כדאי לשמור את הכתובת, וכדאי לתעד אותה למי שיסקור את רשימת ההיתר בחומת האש בהמשך - שרת שלא נושא את שם המוצר נראה חשוד בסקירת אבטחה.

איך מתאמתים מול ה-API של ActiveTrail?

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

למה האינטגרציה שלי מול ActiveTrail הפסיקה לעבוד בלי שגיאה?

שתי הסיבות הסבירות ביותר הן טוקן שפג או הגבלת IP שכבר לא תואמת אחרי מעבר שרת או deploy לסביבה חדשה. אף אחת מהן לא מייצרת קריסה - פשוט מפסיקים להגיע לידים. יש לטפל בשגיאות אימות במפורש ולא לבלוע אותן, ולהתריע לפני תפוגת טוקן ולא אחריה.

האם יצירת קמפיין ב-ActiveTrail שולחת אותו?

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

מה צריך להעביר יחד עם ליד לרשימת דיוור?

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

ה-API של ActiveTrail - יהונתן סעדיה

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

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

הדבר הראשון שמבלבל: הדומיין

התיעוד ושרת ה-API יושבים על webapi.mymarketing.co.il - לא על activetrail.com.

זה נשמע טריוויאלי ויש לו שתי השלכות מעשיות:

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

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

אימות - והפרטים ששוברים את זה מאוחר

האימות הוא טוקן API בכותרת authorization, שנוצר בממשק תחת הגדרות ואז אפליקציות API.

ושם יש שתי אפשרויות שמשנות הכול:

הטוקן יכול לפוג

אפשר להגדיר לו תאריך תפוגה. זו אבטחה טובה, וזו גם הדרך שבה אינטגרציה מפסיקה לעבוד בלי שאף אחד ידע.

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

הטוקן יכול להיות נעול ל-IP

אפשר להגביל אותו לכתובות ספציפיות. מצוין לאבטחה, ובעייתי כשמשהו זז: מעבר לשרת אחר, שינוי בתשתית, deploy לסביבה חדשה - וכל אלה נראים כמו "האינטגרציה נשברה" ולא כמו "ה-IP השתנה".

מה לעשות בשני המקרים:

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

יצירת קמפיין אינה שליחה שלו

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

קל להתייחס לזה כאל טרחה. זו למעשה תכונת בטיחות, וכדאי לנצל אותה.

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

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

אנשי קשר וקבוצות - ההתאמה שהיא כל העבודה

ברוב הפרויקטים, מה שבאמת קורה הוא סנכרון: לידים מהאתר או מה-CRM נכנסים לרשימת דיוור.

ושם חוזרת אותה שאלה: האם האדם הזה כבר קיים?

לנרמל לפני השוואה. מייל - אותיות קטנות ובלי רווחים. טלפון - ל-E.164, כי 052-1234567 ו-+972521234567 הם אותו אדם ולא ייראו כך במחרוזת.
לעדכן, לא ליצור, כשיש התאמה. אחרת מצטברות כפילויות שמייצרות דיוור כפול - וזו לא רק בעיה טכנית, זו סיבה שאנשים לוחצים "הסר".
אידמפוטנטיות. טופס שנשלח פעמיים לא יוצר שני נרשמים.

מה שחייב לעבור יחד עם הליד

לא רק מייל ושם. מקור הליד - מאיזה קמפיין או עמוד הוא הגיע - הוא מה שיאפשר לפלח בהמשך. אם לא העברת אותו בזמן ההרשמה, הוא אבוד; אי אפשר לשחזר אותו רטרואקטיבית.

SMS מאותו API

ה-API מכסה גם SMS. זה נוח, ויש בו נקודה אחת ששווה לעצור עליה.

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

לכן: טוקן בצד השרת בלבד. לא בקוד המקור, לא בלוגים, ולא בשום דבר שרץ בדפדפן. ואם יש חשד לדליפה - להחליף מיד בממשק, לא "לעקוב ולראות".

מה שחייב להיות

נרמול מייל וטלפון בשני הצדדים לפני השוואה.
אידמפוטנטיות על הרשמות.
תור שגיאות שאדם רואה. ליד שנכשל בכתיבה לרשימה הוא ליד שלא יקבל שום דיוור.
הפרדה בין יצירה לשליחה - ובקרה על מספר הנמענים לפני שליחה אוטומטית.
ניטור תוקף הטוקן אם הוגדרה תפוגה.

צ'קליסט

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

ה-API של ActiveTrail: אנשי קשר, קמפיינים והטוקן שאף אחד לא מתעד

עיקרי הדברים