Перейти до основного вмісту

Огляд локального API

TikMatrix надає локальний RESTful API, що дозволяє програмно керувати завданнями. Це корисно для інтеграції TikMatrix у власні системи автоматизації, побудови кастомних робочих процесів або виконання пакетних операцій.

Вимоги​

Вимоги до ліцензії

Локальний API доступний лише для підписників планів Pro, Team і Business. Для плану Starter доступ до API відсутній.

Базова URL-адреса​

API працює локально за адресою:

http://localhost:50809/api/v1/
примітка

Порт 50809 — порт за замовчуванням. Переконайтеся, що TikMatrix запущено перед надсиланням запитів.

Формат відповіді​

Усі відповіді API мають формат:

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

Коди відповідей​

CodeОпис
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 додатково перелічує назви скриптів, які 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Збирати дані користувачів🔜 Незабаром
† Супер-маркетинг використовує окремі ендпоінти

Кампанія супер-маркетингу не створюється через 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Завдання завершилося з помилкою

Далі​