Lewati ke konten utama

Gambaran Umum API Lokal

TikMatrix menyediakan RESTful API lokal yang memungkinkan Anda mengelola tugas secara terprogram. Ini sangat berguna untuk mengintegrasikan TikMatrix ke dalam sistem otomasi Anda sendiri, membangun alur kerja kustom, atau membuat operasi batch.

Persyaratan​

Persyaratan Lisensi

API Lokal hanya tersedia untuk pengguna paket Pro, Team, dan Business. Paket Starter tidak menyediakan akses API.

Base URL​

API berjalan secara lokal di:

http://localhost:50809/api/v1/
catatan

Port 50809 adalah port default. Pastikan TikMatrix sedang berjalan sebelum mengirim permintaan.

Format Response​

Semua response API mengikuti format berikut:

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

Penjelasan Kode Response​

CodeDeskripsi
0Sukses
40001Permintaan Buruk - Parameter tidak valid, termasuk script_config yang gagal validasi
40002Kesalahan parameter - script_name tidak ada
40003Permintaan Buruk - Skrip tidak didukung pada build atau platform ini, tidak memiliki implementasi, atau status tugas tidak valid
40004Kesalahan parameter - Hanya tugas yang sedang berjalan yang dapat dihentikan
40005Kesalahan parameter - task_ids tidak dapat kosong
40301Terlarang - Akses API memerlukan paket Pro+
40401Tidak ditemukan - Resource tidak ada
50001Kesalahan internal server

Memulai Cepat​

1. Periksa Akses API​

Pertama, konfirmasi apakah lisensi Anda mendukung API:

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

Contoh response:

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

2. Menemukan skrip dan parameternya​

GET /api/v1/schema menjelaskan setiap skrip yang dapat dijalankan build ini beserta field script_config yang tepat: nama, tipe, nilai bawaan, nilai yang diizinkan, dan mana yang wajib. Ia dihasilkan dari katalog yang sama dengan yang dipakai server untuk validasi, sehingga tidak bisa menyimpang dari apa yang diterima saat pembuatan tugas.

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

Dua parameter kueri opsional:

ParameterEfek
platformMembatasi daftar ke tiktok atau instagram. Platform yang tidak disertakan build ini ditolak dengan 40001. Bawaannya semua platform yang disertakan build.
include_unavailableJika true, juga menampilkan nama skrip yang diterima API tetapi tidak memiliki implementasi yang berfungsi. Masing-masing membawa unavailable_reason.

Respons (diringkas):

{
  "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 memberi tahu berapa tugas yang akan dihasilkan sebuah permintaan: per_device membuat satu tugas per perangkat (atau per akun dalam mode multi-akun), per_item membuat satu per entri field yang disebut, per perangkat.

3. Membuat Tugas​

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": "Lihat video baru saya! #trending"
    },
    "enable_multi_account": false
  }'

4. Query Daftar Tugas​

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

Script yang Tersedia​

Parameter script_name dapat menerima nilai berikut:

Nama ScriptDeskripsiDukungan API
postPosting konten✅ Didukung
followMengikuti pengguna✅ Didukung
unfollowBerhenti mengikuti✅ Didukung
account_warmupPemanasan akun✅ Didukung
commentKomentar pada postingan✅ Didukung
boost_commentSuka/balas komentar yang ada✅ Didukung
loginMasuk ke akun✅ Didukung
profilePerbarui profil✅ Didukung
match_accountCocokkan akun di perangkat✅ Didukung
likeSuka pada postingan✅ Didukung
viewTonton postingan selama durasi tertentu✅ Didukung
favoriteSimpan postingan ke Favorit✅ Didukung
repostRepost video TikTok✅ Didukung — hanya TikTok
messagePesan pribadi❌ Tidak tersedia §
follow_suggestedIkuti akun yang disarankan✅ Didukung — hanya TikTok
super_marketingKampanye super marketing✅ Didukung †
scrape_userScrape data pengguna🔜 Segera
† Super marketing menggunakan titik akhir khusus

Kampanye super marketing tidak dibuat melalui POST /api/v1/task. Kampanye ini menggunakan kumpulan data target yang dapat digunakan kembali dan memiliki titik akhir tersendiri — lihat Konfigurasi Skrip Super Marketing.

§ message tidak punya implementasi

message dulu diterima oleh pembuatan tugas, tetapi biner skrip tidak punya penangan untuknya di kedua platform, sehingga setiap tugas semacam itu gagal di perangkat dengan "Unknown script". Kini ia ditolak sejak pembuatan, dengan alasan tersebut. Untuk mengirim pesan langsung saat ini, gunakan super_marketing, yang menjalankan DM melalui kumpulan target.

Skrip khusus platform

repost dan follow_suggested hanya diimplementasikan untuk TikTok. Membuatnya untuk target Instagram akan ditolak alih-alih diantrekan — sebelumnya tugas dibuat lalu gagal di perangkat.

Validasi script_config​

Pembuatan tugas memvalidasi script_config terhadap skema di atas sebelum menulis apa pun, sehingga parameter yang salah kembali sebagai 400 yang menyebut field-nya, bukan tugas yang gagal di ponsel belakangan. Tiga hal ditolak:

  • field wajib yang hilang atau kosong,
  • grup salah-satu yang tidak satu pun anggotanya diisi (misalnya follow butuh salah satu dari target_users / target_user),
  • nilai di luar choices yang terdokumentasi untuk sebuah field.

Kunci yang tidak terdaftar di skema diabaikan, bukan ditolak — aplikasi desktop meneruskan kuncinya sendiri lewat objek yang sama, dan menolak kunci tak dikenal akan merusak integrasi yang ada. Semuanya dicatat di sisi server sehingga salah ketik bisa Anda temukan di log aplikasi.

Angka boleh dikirim sebagai string ("20" maupun 20), sesuai dengan yang sudah diterima skrip.

Status Tugas​

Kode StatusTeks StatusDeskripsi
0pendingTugas menunggu eksekusi
1runningTugas sedang dieksekusi
2completedTugas berhasil dieksekusi
3failedTugas gagal dieksekusi

Selanjutnya​