Pular para o conteúdo principal

Visão Geral da API Local

Atualização dos scripts\nO Threads no Pro oferece message, follow_back, scrape_users e repost; content_type = 2 em post significa um post de texto. O message independente não está disponível no TikTok/Instagram; use o Super Marketing.\n:::

O TikMatrix fornece uma API RESTful local que permite gerenciar tarefas programaticamente. Isso é útil para integrar o TikMatrix com seus próprios sistemas de automação, construir fluxos de trabalho personalizados ou criar operações em lote.

Requisitos​

Requisito de Licença

A API Local está disponível apenas para assinantes dos planos Pro, Team e Business. O plano Starter não tem acesso à API.

URL Base​

A API é executada na sua máquina local em:

http://localhost:50809/api/v1/
observação

A porta 50809 é a porta padrão. Certifique-se de que o TikMatrix esteja em execução antes de fazer requisições à API.

Formato de Resposta​

Todas as respostas da API seguem este formato:

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

Códigos de Resposta​

CódigoDescrição
0Sucesso
40001Requisição inválida - Parâmetros inválidos, incluindo um script_config que não passa na validação
40002Requisição Inválida - script_name ausente
40003Requisição inválida - Script não suportado nesta build ou plataforma, sem implementação, ou estado de tarefa inválido
40004Requisição Inválida - Apenas tarefas em execução podem ser paradas
40005Requisição Inválida - task_ids não pode estar vazio
40301Proibido - Acesso à API requer plano Pro+
40401Não Encontrado - Recurso não encontrado
50001Erro Interno do Servidor

Início Rápido​

1. Verificar Acesso à API​

Primeiro, verifique se sua licença suporta acesso à API:

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

Resposta:

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

2. Descobrir os scripts e seus parâmetros​

GET /api/v1/schema descreve todos os scripts que esta build consegue executar e os campos exatos de script_config que cada um aceita: nomes, tipos, padrões, valores permitidos e quais são obrigatórios. É gerado a partir do mesmo catálogo que o servidor usa para validar, portanto não pode divergir do que a criação de tarefas aceita.

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

Dois parâmetros de consulta opcionais:

ParâmetroEfeito
platformRestringe a listagem a tiktok, instagram ou threads. Uma plataforma que esta build não traz é rejeitada com 40001. Por padrão, todas as da build.
include_unavailableCom true, também lista nomes de script que a API aceita mas que não têm implementação. Cada um traz um unavailable_reason.

Resposta (resumida):

{
  "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 informa quantas tarefas uma requisição vai produzir: per_device cria uma tarefa por dispositivo (ou por conta no modo multiconta), per_item cria uma por entrada do campo indicado, por dispositivo.

3. Criar uma Tarefa​

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": "Confira meu novo vídeo! #viral"
    },
    "enable_multi_account": false,
    "start_time": "14:30"
  }'

4. Listar Tarefas​

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

Scripts Disponíveis​

O parâmetro script_name aceita os seguintes valores:

Nome do ScriptDescriçãoSuporte API
postPublicar vídeos, imagens ou posts somente de texto do Threads✅ Suportado
followSeguir usuários✅ Suportado
unfollowDeixar de seguir usuários✅ Suportado
account_warmupAquecer contas✅ Suportado
commentPublicar um novo comentário em posts✅ Suportado
boost_commentCurtir / responder comentários existentes✅ Suportado
loginFazer login na conta✅ Suportado
profileAtualizar perfil✅ Suportado
match_accountAssociar contas no dispositivo✅ Suportado
likeCurtir posts✅ Suportado
viewAssistir a um post por um período determinado✅ Suportado
favoriteSalvar um post nos Favoritos✅ Suportado
repostRepostar vídeos do TikTok ou posts do Threads✅ Suportado — apenas TikTok e Threads
messageEnviar mensagens diretas✅ Suportado — apenas Threads
follow_backSeguir contas da lista de seguidores✅ Suportado — TikTok, Instagram e Threads
follow_suggestedSeguir contas sugeridas✅ Suportado — apenas TikTok
custom_scriptExecutar um programa que você registrou✅ Suportado ‡
super_marketingCampanha de super marketing✅ Suportado †
scrape_usersExportar nomes de usuário de seguidores, seguidos ou da busca✅ Suportado — TikTok, Instagram e Threads
auto_replyResponder mensagens diretas e comentários❌ Não via API §
† O super marketing usa endpoints dedicados

A campanha de super marketing não é criada através de POST /api/v1/task. Ela funciona com um dataset reutilizável de alvos e tem seus próprios endpoints — veja a Configuração do Script Super Marketing.

Mensagens diretas somente no Threads

A tarefa message isolada conduz o fluxo Perfil → Mensagem no Threads. Para TikTok e Instagram, use super_marketing com um dataset de alvos.

Scripts específicos de plataforma

repost é implementado para TikTok e Threads; follow_suggested continua apenas para TikTok. follow_back e scrape_users usam a interface de seguidores e busca de cada plataforma em dispositivos reais e estão disponíveis no TikTok, Instagram e Threads.

‡ Scripts personalizados precisam ser registrados primeiro

custom_script executa um programa que você registrou em Dispositivos → Scripts personalizados. Informe o id dele em script_config.custom_script_id — veja Scripts personalizados.

§ A resposta automática é executada a partir da própria página

auto_reply responde mensagens diretas e comentários no TikTok, Instagram e Threads, no plano Pro e superiores. Suas rodadas são agendadas pela página Resposta automática do app, que guarda as regras de resposta, o horário de funcionamento e o botão de pausa, por isso não pode ser criado por meio de POST /api/v1/task.

Validação de script_config​

A criação de tarefas valida script_config contra o esquema acima antes de gravar qualquer coisa, então um parâmetro errado volta como 400 nomeando o campo, em vez de uma tarefa que falha depois no telefone. Três coisas são rejeitadas:

  • um campo obrigatório ausente ou vazio,
  • um grupo de alternativas em que nenhum membro foi definido (por exemplo, follow precisa de target_users ou target_user),
  • um valor fora dos choices documentados do campo.

Chaves que o esquema não lista são ignoradas, não rejeitadas — o app desktop passa as próprias chaves pelo mesmo objeto, e rejeitar chaves desconhecidas quebraria integrações existentes. Elas são registradas no servidor para você identificar um erro de digitação no log do app.

Números podem ser enviados como strings ("20" além de 20), acompanhando o que os scripts já aceitam.

Status da Tarefa​

Código de StatusTexto de StatusDescrição
0pendingTarefa aguardando execução
1runningTarefa em execução no momento
2completedTarefa concluída com sucesso
3failedTarefa falhou

Próximos Passos​