כל בקשת API של Telm מאומתת עם מפתח API שמתחיל ב־tk_live_ — לעולם לא עם התחברות לוח הבקרה שלכם. צרו מפתח בחשבונכם, שלחו אותו בכותרת Authorization כטוקן Bearer, והוא פועל בשם החשבון שלכם בקבוצות שבהן אתם מנהלים. אם מפתח דולף, בטלו אותו בלוח הבקרה והנפיקו חדש.
1איך מפתחות API עובדים
ה־REST API של Telm אינו משתמש בהפעלת הדפדפן שלכם. במקום זאת, כל בקשה נושאת מפתח API — מחרוזת סוד ארוכה שמתחילה בקידומת tk_live_ ואחריה תווים אקראיים. המפתח מזהה את החשבון שלכם ומאשר את הקריאה.
אתם מייצרים מפתחות מחשבונכם ויכולים להחזיק כמה בבת אחת (למשל, אחד לכל סקריפט או שירות). הסוד המלא מוצג פעם אחת בלבד, בזמן היצירה; לאחר מכן לוח הבקרה מציג מפתח לפי הקידומת הקצרה שלו (tk_live_ בתוספת התווים הראשונים) כדי שתזהו אותו, והערך המלא לעולם אינו נשמר לאחר מכן.
- מפתח נראה כמו tk_live_ ואחריו מחרוזת אקראית ארוכה.
- מפתחות נוצרים ומנוהלים בלוח הבקרה שלכם.
- הסוד המלא מוצג פעם אחת בלבד — העתיקו אותו מיד ואחסנו אותו במקום בטוח.
- התייחסו למפתח כמו לסיסמה: כל מי שמחזיק בו יכול לקרוא ל־API בשמכם.
2שליחת המפתח עם כל בקשה
העבירו את המפתח בכותרת Authorization בשיטת Bearer. ערך הכותרת הוא המילה Bearer, רווח, ואז המפתח שלכם — למשל, Authorization: Bearer tk_live_your_key_here.
עבור לקוחות שאינם יכולים להגדיר בנוחות כותרת Authorization, ה־API מקבל גם את המפתח בכותרת X-API-Key. אם שתיהן קיימות, כותרת Authorization מנצחת. בקשות מעל כל דבר שאינו HTTPS אינן מתקבלות בפרודקשן.
- מועדף: שלחו Authorization: Bearer tk_live_...
- חלופה: שלחו את המפתח בכותרת X-API-Key במקום.
- כתובת הבסיס לכל קריאה היא api.telm.com/api/public/v1.
- ראו את רשימת נקודות הקצה והסכמות המלאה בעמוד המפתחים.
3למה מפתח יכול לגשת
מפתח פועל אך ורק בשם החשבון שלכם. הוא יכול לקרוא או לשנות רק קבוצות שבהן החשבון שלכם מנהל — בקשה שמכוונת לכל קבוצה אחרת מחזירה 404, כך שה־API לעולם אינו חושף שקבוצה שאינכם יכולים לנהל אפילו קיימת.
הגישה תלויה גם בתוכנית של קבוצת היעד. נקודת הקצה של בדיקת הספאם פתוחה לכל תוכנית בתוך המכסה היומית, בעוד ה־API המלא (כללים, הגדרות, רשימה לבנה, יומן, אנליטיקה, בדיקות אצווה ו-webhooks) זמין בתוכנית Pro ומעלה בקבוצה המעורבת.
- מפתח יכול לגעת רק בקבוצות שבהן אתם מנהלים.
- בקשות לקבוצות שאינכם מנהלים מחזירות 404, לא 403.
- המכסה היומית משותפת לכל המפתחות שלכם, נספרת לכל חשבון.
4ביטול והחלפת מפתחות
אם מפתח נחשף — הוכנס למאגר, הודבק לצ'אט, או דלף בכל דרך אחרת — בטלו אותו מיד מלוח הבקרה שלכם. הביטול נכנס לתוקף מיד: המפתח המבוטל מפסיק לעבוד תוך שניות, לא לאחר עיכוב כלשהו.
מכיוון שהמכסה היומית משותפת לכל חשבון, ביטול מפתח אחד אינו מאפס את מונה השימוש שלכם. החלפת מפתחות באופן קבוע היא היגיינה טובה: צרו את המפתח החדש, פרסו אותו לשירות שלכם, אשרו שהוא עובד, ואז בטלו את הישן כדי שלא יהיה זמן השבתה.
- בטלו מפתח מלוח הבקרה שלכם; הוא מפסיק לעבוד כמעט מיד.
- צרו את המחליף תחילה, השיקו אותו, ואז בטלו את המפתח הישן להחלפה ללא זמן השבתה.
- ביטול מפתח אינו מאפס את המכסה היומית שלכם — היא מתאפסת בחצות UTC.
5שגיאות אימות
מפתח חסר, פגום או מבוטל מחזיר 401 עם קוד שגיאה קריא־מכונה והודעה קריאה־אדם. אם הבקשות שלכם מתחילות פתאום להיכשל עם 401, בדקו שהמפתח לא בוטל ושכותרת Authorization מאויתת בדיוק כ־Bearer בתוספת רווח בתוספת המפתח.
מפתח תקף שמכוון לקבוצה שאינכם מנהלים מחזיר 404. מפתח תקף בתוכנית מתחת ל־Pro שקורא לנקודת קצה של Pro בלבד מחזיר 403 עם קוד plan_required ורמז שדרוג.
- 401 — המפתח חסר, פגום או מבוטל.
- 404 — קבוצת היעד אינה קיימת או שאינכם מנהלים שלה.
- 403 plan_required — נקודת הקצה דורשת Pro ומעלה באותה קבוצה.