Pular para o conteúdo principal

Visão Geral da API Local

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 ou instagram. 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"],
        "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 conteúdo✅ Suportado
followSeguir usuários✅ Suportado
unfollowDeixar de seguir usuários✅ Suportado
account_warmupAquecer contas✅ Suportado
commentPublicar um 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 uma publicação por uma duração✅ Suportado
favoriteSalvar uma publicação nos Favoritos✅ Suportado
repostRepostar vídeos do TikTok✅ Suportado — apenas TikTok
messageEnviar mensagens diretas❌ Indisponível §
follow_suggestedSeguir contas sugeridas✅ Suportado — apenas TikTok
super_marketingCampanha de super marketing✅ Suportado †
scrape_userExtrair dados de usuário🔜 Em Breve
† 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 dedicados — veja a Configuração do Script Super Marketing.

§ message não tem implementação

message era aceito pela criação de tarefas, mas o binário de scripts não tem tratador para ele em nenhuma das plataformas, então toda tarefa desse tipo falhava no dispositivo com "Unknown script". Agora ela é rejeitada já na criação, com esse motivo. Para enviar mensagens diretas hoje, use super_marketing, que conduz DMs por meio de um conjunto de alvos.

Scripts específicos de plataforma

repost e follow_suggested só estão implementados para TikTok. Criar um contra um alvo do Instagram é rejeitado em vez de enfileirado — antes a tarefa era criada e depois falhava no dispositivo.

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​