API de Gerenciamento de Tarefas

Esta página documenta todos os endpoints da API disponíveis para gerenciar tarefas no TikMatrix.

Criar Tarefa

Cria uma nova tarefa para um ou mais dispositivos ou usuários.

Endpoint: POST /api/v1/task
Content-Type: application/json

Parâmetros da Requisição

A API suporta dois modos para criar tarefas:

Modo 1: Baseado em Dispositivo - Use serials para criar tarefas para dispositivos Modo 2: Baseado em Usuário - Use usernames para criar tarefas diretamente para contas específicas

Parâmetro	Tipo	Obrigatório	Descrição
serials	string[]	Condicional	Array de números de série dos dispositivos (obrigatório se `usernames` não for fornecido)
usernames	string[]	Condicional	Array de nomes de usuário para criar tarefas (obrigatório se `serials` não for fornecido). Quando fornecido, as tarefas são criadas diretamente para essas contas.
script_name	string	Sim	Nome do script a ser executado
script_config	object	Sim	Parâmetros de configuração para o script (veja documentação específica do script)
enable_multi_account	boolean	Não	Habilitar modo de múltiplas contas (padrão: false). Aplicável apenas no modo baseado em dispositivo.
start_time	string	Não	Horário de início agendado no formato "HH:MM"
close_app	boolean	Não	Se o app de destino é fechado (forçado a parar) quando a tarefa termina (padrão: `true`). Use `false` para deixar o app em execução ao concluir a tarefa.
platform	string	Não	Plataforma de destino (`tiktok` ou `instagram`). Usado apenas pelo TikMatrix Pro; ignorado por versões de plataforma única.

Scripts Suportados

Nome do Script	Descrição	Documentação
post	Publicar vídeos ou imagens no TikTok/Instagram	Configuração do Script Post
follow	Seguir ou deixar de seguir usuários	Configuração do Script Follow
unfollow	Deixar de seguir usuários	Configuração do Script Unfollow
account_warmup	Aquecer contas	Configuração do Script Account Warmup
comment	Comentar publicações	Configuração do Script Comment
login	Fazer login na conta	Configuração do Script de Login
profile	Atualizar perfil	Configuração do Script de Perfil
match_account	Associar contas no dispositivo	Configuração do Script de Correspondência de Conta
like	Curtir publicações	Configuração do Script Like
view	Visualizar uma publicação por um período de tempo	Configuração do Script View
favorite	Salvar uma publicação em Favoritos	Configuração do Script Favorite
repost	Compartilhar vídeos do TikTok novamente	Configuração do Script Repost
message	Enviar mensagens diretas	Configuração do Script Message
follow_suggested	Seguir contas sugeridas	Configuração do Script Follow Suggested

Exemplo

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "post",
    "script_config": {
      "content_type": 0,
      "captions": "Check out my new video! #viral #fyp",
      "material_list": ["C:/Videos/video1.mp4"],
      "upload_wait_time": 60
    }
  }'

Manter o app aberto após a tarefa

Por padrão, o app de destino é encerrado à força quando a tarefa termina, para refletir o comportamento do aplicativo e liberar recursos do dispositivo. Passe "close_app": false para deixar o app em execução ao concluir a tarefa, útil para encadear tarefas ou inspecionar o resultado no dispositivo:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "like",
    "script_config": {
      "target_post_url": "https://www.tiktok.com/@user/video/123"
    },
    "close_app": false
  }'

Para parâmetros detalhados de script_config e mais exemplos, veja Configuração do Script Post e Configuração do Script Follow.

Resposta

{
  "code": 0,
  "message": "success",
  "data": {
    "task_ids": [101, 102],
    "created_count": 2
  }
}

Listar Tarefas

Consultar tarefas com filtros opcionais.

Endpoint: GET /api/v1/task

Parâmetro	Tipo	Obrigatório	Descrição
status	integer	Não	Filtrar por status (0=pendente, 1=em execução, 2=concluída, 3=falhou)
serial	string	Não	Filtrar por número de série do dispositivo
script_name	string	Não	Filtrar por nome do script
source	string	Não	Filtrar por origem ("ui" ou "api")
page	integer	Não	Número da página (padrão: 1)
page_size	integer	Não	Itens por página (padrão: 20, máximo: 100)

Obter Detalhes da Tarefa

Obter informações detalhadas sobre uma tarefa específica.

Endpoint: GET /api/v1/task/{task_id}

Excluir Tarefa

Excluir uma tarefa. Se a tarefa estiver em execução, ela será interrompida primeiro.

Endpoint: DELETE /api/v1/task/{task_id}

Excluir Tarefas em Lote

Excluir várias tarefas de uma vez. Tarefas em execução serão interrompidas primeiro.

Endpoint: DELETE /api/v1/task/batch
Body: { "task_ids": [1, 2, 3] }

Parar Tarefa

Parar uma tarefa em execução.

Endpoint: POST /api/v1/task/{task_id}/stop

Retentar Tarefa Falhada

Retentar uma tarefa que falhou.

Endpoint: POST /api/v1/task/{task_id}/retry

Retentar Todas as Tarefas Falhadas

Retentar todas as tarefas falhadas de uma vez.

Endpoint: POST /api/v1/task/retry-all

Obter Estatísticas de Tarefas

Obter estatísticas sobre todas as tarefas.

Endpoint: GET /api/v1/task/stats
Resposta: Retorna contagem total, pendente, em execução, concluída e falha.

Verificar Licença da API

Verificar se sua licença suporta acesso à API.

Endpoint: GET /api/v1/license/check
Nota: Plano Starter retorna código de erro 40301. Planos Pro, Team e Business têm acesso à API.

Criar Tarefa​

Parâmetros da Requisição​

Scripts Suportados​

Exemplo​

Manter o app aberto após a tarefa​

Resposta​

Listar Tarefas​

Obter Detalhes da Tarefa​

Excluir Tarefa​

Excluir Tarefas em Lote​

Parar Tarefa​

Retentar Tarefa Falhada​

Retentar Todas as Tarefas Falhadas​

Obter Estatísticas de Tarefas​

Verificar Licença da API​