דלג לתוכן הראשי

סקירת API מקומי

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

דרישות​

דרישות רישיון

ה-API המקומי זמין רק למשתמשי תוכניות Pro, Team ו-Business. תוכנית Starter אינה כוללת גישה ל-API.

כתובת URL בסיסית​

ה-API פועל מקומית בכתובת:

http://localhost:50809/api/v1/
note

הפורט 50809 הוא פורט ברירת המחדל. ודא ש-TikMatrix פועל לפני שליחת בקשות.

פורמט תגובה​

כל תגובות ה-API עוקבות אחר הפורמט הבא:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

קודי תגובה​

קודתיאור
0הצלחה
40001בקשה שגויה - פרמטרים לא תקינים, לרבות script_config שאינו עובר את האימות
40002שגיאת פרמטר - script_name חסר
40003בקשה שגויה - הסקריפט אינו נתמך בגרסה או בפלטפורמה הזו, אין לו מימוש, או שמצב המשימה אינו תקין
40004שגיאת פרמטר - רק משימות בהפעלה יכולות להיעצר
40005שגיאת פרמטר - task_ids לא יכול להיות ריק
40301אסור - דרושה תוכנית Pro+
40401לא נמצא - המשאב אינו קיים
50001שגיאת שרת פנימית

התחלה מהירה​

1. בדוק גישת API​

ראשית, ודא שהרישיון שלך תומך ב-API:

curl http://localhost:50809/api/v1/license/check

תגובה לדוגמה:

{
  "code": 0,
  "message": "success",
  "data": {
    "plan_name": "Pro",
    "api_enabled": true,
    "device_limit": 20,
    "message": "API access enabled"
  }
}

2. גילוי הסקריפטים והפרמטרים שלהם​

GET /api/v1/schema מתאר כל סקריפט שהגרסה הזו יכולה להריץ ואת שדות script_config המדויקים שהוא מקבל: שמות, טיפוסים, ברירות מחדל, ערכים מותרים ואילו שדות נדרשים. הוא נוצר מאותו קטלוג שלפיו השרת מאמת, ולכן אינו יכול להתרחק ממה שיצירת המשימה מקבלת בפועל.

curl http://localhost:50809/api/v1/schema

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

פרמטרהשפעה
platformמצמצם את הרשימה ל-tiktok או ל-instagram. פלטפורמה שאינה נכללת בגרסה נדחית עם 40001. ברירת המחדל היא כל מה שהגרסה כוללת.
include_unavailableבערך true מוצגים גם שמות סקריפטים שה-API מקבל אך אין להם מימוש פעיל. לכל אחד מהם מצורף unavailable_reason.

תגובה (מקוצרת):

{
  "code": 0,
  "message": "success",
  "data": {
    "build": { "platforms": ["tiktok"] },
    "scripts": [
      {
        "name": "follow",
        "internal_name": "follow",
        "summary": "Follow the given users. One task per target.",
        "platforms": ["tiktok", "instagram"],
        "available": true,
        "fan_out": { "kind": "per_item", "key": "target_users", "alt_key": "target_user" },
        "any_of": [["target_users", "target_user"]],
        "fields": [
          {
            "key": "access_method",
            "type": "string",
            "required": false,
            "default": "direct",
            "choices": ["direct", "search"],
            "description": "How to reach the profile: direct (via URL) or search."
          }
        ]
      }
    ]
  }
}

fan_out מציין כמה משימות תיצור בקשה: per_device יוצר משימה לכל מכשיר (או לכל חשבון במצב ריבוי חשבונות), ו-per_item יוצר אחת לכל פריט בשדה שצוין, לכל מכשיר.

3. צור משימה​

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1", "device_serial_2"],
    "script_name": "post",
    "script_config": {
      "content_type": 1,
      "captions": "תבדקו את הסרטון החדש שלי! #וויראלי"
    },
    "enable_multi_account": false,
    "start_time": "14:30"
  }'

4. קבל רשימת משימות​

curl http://localhost:50809/api/v1/task?status=0&page=1&page_size=20

סקריפטים זמינים​

הפרמטר script_name מקבל את הערכים הבאים:

שם סקריפטתיאורתמיכה ב-API
postפרסום תוכן✅ נתמך
followמעקב אחרי משתמשים✅ נתמך
unfollowביטול מעקב✅ נתמך
account_warmupחימום חשבון✅ נתמך
commentפרסום תגובה חדשה על פוסטים✅ נתמך
boost_commentלייק / תגובה לתגובות קיימות✅ נתמך
loginהתחבר לחשבון✅ נתמך
profileעדכן פרופיל✅ נתמך
match_accountהתאם חשבונות במכשיר✅ נתמך
likeלייק לפוסטים✅ נתמך
viewצפייה בפוסט למשך זמן מסוים✅ נתמך
favoriteשמירת פוסט למועדפים✅ נתמך
repostשיתוף מחדש של סרטוני TikTok✅ נתמך — TikTok בלבד
messageשליחת הודעות ישירות❌ לא זמין §
follow_suggestedעקוב אחר חשבונות מוצעים✅ נתמך — TikTok בלבד
super_marketingקמפיין שיווק מתקדם✅ נתמך †
scrape_userגרידת נתוני משתמש🔜 בקרוב
† שיווק מתקדם משתמש ב-endpoints ייעודיים

קמפיין השיווק המתקדם אינו נוצר דרך POST /api/v1/task. הוא עובד על בסיס מאגר יעדים לשימוש חוזר ויש לו endpoints ייעודיים — ראה הגדרת סקריפט שיווק מתקדם.

§ ל-message אין מימוש

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

סקריפטים ייעודיים לפלטפורמה

repost ו-follow_suggested ממומשים ל-TikTok בלבד. יצירה מולם עבור יעד באינסטגרם נדחית במקום להיכנס לתור — בעבר המשימה נוצרה ואז נכשלה במכשיר.

אימות script_config​

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

  • שדה חובה חסר או ריק,
  • קבוצת "אחד מהם" שאף אחד מחבריה לא הוגדר (למשל follow דורש את target_users או target_user),
  • ערך מחוץ ל-choices המתועדים של השדה.

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

מספרים אפשר לשלוח כמחרוזות ("20" בדיוק כמו 20), בהתאם למה שהסקריפטים כבר מקבלים.

סטטוס משימה​

קוד סטטוסטקסט סטטוסתיאור
0pendingהמשימה ממתינה לביצוע
1runningהמשימה מתבצעת כעת
2completedהמשימה הושלמה בהצלחה
3failedהמשימה נכשלה

ראה גם​