إنتقل إلى المحتوى الرئيسي

نظرة عامة على API المحلي

يوفر TikMatrix واجهة برمجة تطبيقات RESTful محلية تسمح لك بإدارة المهام برمجيًا. هذا مفيد لدمج TikMatrix في أنظمة الأتمتة الخاصة بك، أو بناء سير عمل مخصص، أو إنشاء عمليات دفعية.

المتطلبات​

متطلبات الترخيص

API المحلي متاح فقط لمستخدمي خطط Pro و Team و Business. لا توفر خطة Starter وصولاً إلى API.

عنوان URL الأساسي​

يعمل API محليًا على:

http://localhost:50809/api/v1/
ملاحظة

المنفذ 50809 هو المنفذ الافتراضي. يرجى التأكد من أن TikMatrix قيد التشغيل قبل إجراء الطلبات.

تنسيق الاستجابة​

تتبع جميع استجابات API التنسيق التالي:

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

توضيح رموز الاستجابة​

الرمزالوصف
0نجح
40001طلب غير صالح - معاملات غير صحيحة، بما في ذلك script_config لا يجتاز التحقق
40002خطأ في المعاملات - script_name مفقود
40003طلب غير صالح - السكربت غير مدعوم في هذه النسخة أو على هذه المنصة، أو ليس له تنفيذ، أو حالة المهمة غير صالحة
40004خطأ في المعاملات - يمكن إيقاف المهام المتوقفة فقط
40005خطأ في المعاملات - لا يمكن أن تكون task_ids فارغة
40301محظور - يتطلب الوصول إلى API خطة 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 تُدرج أيضًا أسماء السكربتات التي تقبلها الواجهة لكن لا تنفيذ فعليًا لها. يحمل كل منها 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": "شاهد الفيديو الجديد الخاص بي! #trending"
    },
    "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استخراج بيانات المستخدم🔜 قريبًا
† التسويق الفائق يستخدم نقاط نهاية مخصصة

حملة التسويق الفائق لا تُنشأ عبر POST /api/v1/task. تعمل على مجموعة بيانات مستهدفة قابلة لإعادة الاستخدام ولها نقاط نهاية مخصصة — راجع تكوين نص التسويق الفائق.

§ لا يوجد تنفيذ لـ message

كان message مقبولًا عند إنشاء المهمة، لكن ملف السكربتات التنفيذي لا يملك معالجًا له على أي من المنصتين، فكانت كل مهمة من هذا النوع تفشل على الجهاز برسالة "Unknown script". أما الآن فتُرفض عند الإنشاء مع ذكر السبب. لإرسال الرسائل المباشرة اليوم، استخدم super_marketing الذي يدير الرسائل عبر مجموعة أهداف.

سكربتات خاصة بمنصة بعينها

repost وfollow_suggested منفَّذان على TikTok فقط. إنشاء أي منهما مقابل هدف على Instagram يُرفض بدل أن يُدرج في قائمة الانتظار — سابقًا كانت المهمة تُنشأ ثم تفشل على الجهاز.

التحقق من script_config​

يتحقق إنشاء المهمة من script_config وفق المخطط أعلاه قبل كتابة أي شيء، فيعود المعامل الخاطئ على هيئة 400 يذكر اسم الحقل بدلًا من مهمة تفشل لاحقًا على الهاتف. تُرفض ثلاثة أمور:

  • حقل مطلوب مفقود أو فارغ،
  • مجموعة «أحدها» لم يُضبط أي عضو فيها (مثلًا يحتاج follow إلى أحد target_users / target_user)،
  • قيمة خارج نطاق choices الموثّقة للحقل.

المفاتيح غير المدرجة في المخطط تُتجاهل ولا تُرفض — فتطبيق سطح المكتب نفسه يمرر مفاتيحه عبر الكائن ذاته، ورفض المفاتيح المجهولة سيكسر التكاملات القائمة. تُسجَّل على الخادم لتتمكن من ملاحظة أي خطأ مطبعي في سجل التطبيق.

يمكن إرسال الأرقام كسلاسل نصية ("20" كما 20)، بما يطابق ما تقبله السكربتات أصلًا.

حالة المهمة​

رمز الحالةنص الحالةالوصف
0pendingالمهمة في انتظار التنفيذ
1runningالمهمة قيد التنفيذ
2completedتم تنفيذ المهمة بنجاح
3failedفشل تنفيذ المهمة

الخطوات التالية​