Ana içeriğe geç

Yerel API Genel Bakış

TikMatrix, görevleri programatik olarak yönetmenizi sağlayan yerel bir RESTful API sunar. Bu, TikMatrix'i kendi otomasyon sistemlerinizle entegre etmek, özel iş akışları oluşturmak veya toplu işlemler gerçekleştirmek için kullanışlıdır.

Gereksinimler​

Lisans Gereksinimi

Yerel API yalnızca Pro, Team ve Business plan abonelerine açıktır. Starter plan API erişimine sahip değildir.

Temel URL​

API yerel makinenizde çalışır:

http://localhost:50809/api/v1/
not

50809 varsayılan porttur. API istekleri göndermeden önce TikMatrix'in çalıştığından emin olun.

Yanıt Formatı​

Tüm API yanıtları şu formatı takip eder:

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

Yanıt Kodları​

CodeAçıklama
0Başarılı
40001Hatalı İstek - Geçersiz parametreler; doğrulamadan geçemeyen bir script_config dahil
40002Hatalı İstek - script_name eksik
40003Hatalı İstek - Betik bu derlemede veya bu platformda desteklenmiyor, uygulaması yok ya da görev durumu geçersiz
40004Hatalı İstek - Yalnızca çalışan görevler durdurulabilir
40005Hatalı İstek - task_ids boş olamaz
40301Yasak - API erişimi Pro+ planı gerektirir
40401Bulunamadı - Kaynak bulunamadı
50001Dahili Sunucu Hatası

Hızlı Başlangıç​

1. API Erişimini Kontrol Et​

Önce lisansınızın API erişimini destekleyip desteklemediğini doğrulayın:

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

Yanıt:

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

2. Betikleri ve parametrelerini keşfetme​

GET /api/v1/schema, bu derlemenin çalıştırabildiği her betiği ve her birinin aldığı script_config alanlarını tam olarak açıklar: adlar, türler, varsayılanlar, izin verilen değerler ve hangilerinin zorunlu olduğu. Sunucunun doğrulama için kullandığı katalogdan üretildiği için görev oluşturmanın kabul ettiğinden sapamaz.

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

İki isteğe bağlı sorgu parametresi:

ParametreEtkisi
platformListeyi tiktok veya instagram ile sınırlar. Bu derlemede bulunmayan bir platform 40001 ile reddedilir. Varsayılan olarak derlemedeki tüm platformlar.
include_unavailabletrue yapıldığında, API’nin kabul ettiği ama çalışan bir uygulaması olmayan betik adlarını da listeler. Her biri bir unavailable_reason taşır.

Yanıt (kısaltılmış):

{
  "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, bir isteğin kaç görev üreteceğini söyler: per_device cihaz başına bir görev oluşturur (çoklu hesap modunda hesap başına), per_item ise belirtilen alanın her girdisi için cihaz başına bir görev oluşturur.

3. Görev Oluştur​

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": "Yeni videoma göz at! #viral"
    },
    "enable_multi_account": false,
    "start_time": "14:30"
  }'

4. Görevleri Listele​

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

Mevcut Skriptler​

script_name parametresi aşağıdaki değerleri kabul eder:

Script AdıAçıklamaAPI Desteği
postİçerik yayınla✅ Destekleniyor
followKullanıcıları takip et✅ Destekleniyor
unfollowTakibi bırak✅ Destekleniyor
account_warmupHesapları ısıt✅ Destekleniyor
commentGönderilere yorum yap✅ Destekleniyor
boost_commentMevcut yorumları beğen/yanıtla✅ Destekleniyor
loginHesaba giriş yap✅ Destekleniyor
profileProfili güncelle✅ Destekleniyor
match_accountCihazda hesapları eşleştir✅ Destekleniyor
likeBeğen✅ Destekleniyor
viewBir gönderiyi belirli bir süre izle✅ Destekleniyor
favoriteGönderiyi Favorilere kaydet✅ Destekleniyor
repostTikTok videolarını yeniden paylaş✅ Destekleniyor — yalnızca TikTok
messageDoğrudan mesaj gönder❌ Kullanılamıyor §
follow_suggestedÖnerilen hesapları takip et✅ Destekleniyor — yalnızca TikTok
super_marketingSüper pazarlama kampanyası✅ Destekleniyor †
scrape_userKullanıcı verisi çek🔜 Yakında
† Süper marketing özel endpoint'ler kullanır

Süper pazarlama kampanyası POST /api/v1/task üzerinden oluşturulmaz. Yeniden kullanılabilir bir hedef veri setine dayanır ve kendine özgü endpoint'leri vardır — bkz. Süper Marketing Skript Yapılandırması.

§ message için bir uygulama yok

message görev oluşturma tarafından kabul ediliyordu, ancak betik ikilisinin her iki platformda da bunun için bir işleyicisi yok; bu yüzden bu tür her görev cihazda "Unknown script" hatasıyla başarısız oluyordu. Artık bu gerekçeyle daha oluşturulurken reddediliyor. Bugün doğrudan mesaj göndermek için, DM’leri bir hedef veri kümesi üzerinden yürüten super_marketing kullanın.

Platforma özgü betikler

repost ve follow_suggested yalnızca TikTok için uygulanmıştır. Instagram hedefiyle oluşturmak kuyruğa alınmak yerine reddedilir — daha önce görev oluşturuluyor, ardından cihazda başarısız oluyordu.

script_config doğrulaması​

Görev oluşturma, herhangi bir şey yazmadan önce script_config’i yukarıdaki şemaya göre doğrular; böylece hatalı bir parametre, telefonda sonradan başarısız olan bir görev yerine, alanı adlandıran bir 400 olarak geri döner. Üç şey reddedilir:

  • eksik veya boş bırakılmış zorunlu bir alan,
  • hiçbir üyesi ayarlanmamış bir "şunlardan biri" grubu (örneğin follow, target_users / target_user alanlarından birine ihtiyaç duyar),
  • bir alanın belgelenmiş choices değerleri dışında bir değer.

Şemada yer almayan anahtarlar reddedilmez, yok sayılır — masaüstü uygulaması kendi anahtarlarını aynı nesneden geçirir ve bilinmeyen anahtarları reddetmek mevcut entegrasyonları bozardı. Sunucu tarafında günlüklenir, böylece bir yazım hatasını uygulama günlüğünde fark edebilirsiniz.

Sayılar dizge olarak da gönderilebilir (20 kadar "20" de olur); betiklerin zaten kabul ettiği biçimle uyumludur.

Görev Durumu​

Durum KoduDurum MetniAçıklama
0pendingGörev yürütülmeyi bekliyor
1runningGörev şu anda çalışıyor
2completedGörev başarıyla tamamlandı
3failedGörev başarısız oldu

Sonraki Adımlar​