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

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

تحديث السكربتات\nيدعم Threads في Pro سكربتات message وfollow_back وscrape_users وrepost؛ وتعني content_type = 2 في post منشوراً نصياً. لا يتوفر message المستقل على TikTok/Instagram، فاستخدم Super Marketing.\n:::

يوفر 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 أو threads. المنصة غير المتوفرة في هذه النسخة تُرفض بالرمز 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", "threads"],
        "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نشر مقاطع الفيديو والصور أو منشورات Threads النصية فقط✅ مدعوم
followمتابعة المستخدمين✅ مدعوم
unfollowإلغاء متابعة المستخدمين✅ مدعوم
account_warmupتسخين الحسابات✅ مدعوم
commentنشر تعليق جديد على المنشورات✅ مدعوم
boost_commentالإعجاب بالتعليقات الموجودة / الرد عليها✅ مدعوم
loginتسجيل الدخول إلى الحساب✅ مدعوم
profileتحديث الملف الشخصي✅ مدعوم
match_accountمطابقة الحسابات على الجهاز✅ مدعوم
likeالإعجاب بالمنشورات✅ مدعوم
viewمشاهدة منشور لمدة محددة✅ مدعوم
favoriteحفظ منشور في المفضلة✅ مدعوم
repostإعادة نشر مقاطع TikTok أو منشورات Threads✅ مدعوم — TikTok و Threads
messageإرسال الرسائل المباشرة✅ مدعوم — Threads فقط
follow_backمتابعة الحسابات من قائمة المتابِعين✅ مدعوم — TikTok و Instagram و Threads
follow_suggestedمتابعة الحسابات المقترحة✅ مدعوم — TikTok فقط
custom_scriptتشغيل برنامج سجّلته بنفسك✅ مدعوم ‡
super_marketingحملة التسويق الفائق✅ مدعوم †
scrape_usersتصدير أسماء المستخدمين من قوائم المتابِعين والمتابَعين أو نتائج البحث✅ مدعوم — TikTok و Instagram و Threads
auto_replyالرد على الرسائل المباشرة والتعليقات❌ غير متاح عبر API §
† التسويق الفائق يستخدم نقاط نهاية مخصصة

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

الرسائل المباشرة على Threads فقط

تُشغّل مهمة message المستقلة مسار الملف الشخصي في Threads ← إرسال الرسالة. أما على TikTok و Instagram فاستخدم super_marketing مع مجموعة بيانات مستهدفة بدلًا من ذلك.

نصوص برمجية خاصة بمنصة بعينها

repost منفَّذ لمنصتي TikTok و Threads، وfollow_suggested مقتصر على TikTok. يستخدم follow_back وscrape_users واجهة المتابِعين والبحث الخاصة بكل منصة على جهاز حقيقي، وهما متاحان على TikTok و Instagram و Threads.

‡ يجب تسجيل النصوص البرمجية المخصصة أولًا

يشغّل custom_script برنامجًا سجّلته ضمن الأجهزة ← النصوص البرمجية المخصصة. مرّر معرّفه في script_config.custom_script_id — راجع النصوص البرمجية المخصصة.

§ يعمل الرد التلقائي من صفحته الخاصة

يرد auto_reply على الرسائل المباشرة والتعليقات في TikTok و Instagram و Threads، وذلك على خطة Pro فما فوق. تُجدول جولاته من صفحة الرد التلقائي في التطبيق، وهي تضم قواعد الرد وساعات العمل ومفتاح الإيقاف المؤقت، ولهذا لا يمكن إنشاؤه عبر POST /api/v1/task.

التحقق من script_config​

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

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

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

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

حالة المهمة​

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

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