Saltar al contenido principal

Visión General de la API Local

Actualización de scripts\nThreads en Pro admite message, follow_back, scrape_users y repost; content_type = 2 en post significa una publicación de texto. El message independiente no está disponible en TikTok/Instagram: usa Super Marketing.\n:::

TikMatrix proporciona una API RESTful local que te permite gestionar tareas de forma programática. Esto es útil para integrar TikMatrix en tus propios sistemas de automatización, construir flujos de trabajo personalizados o crear operaciones por lotes.

Requisitos​

Requisito de Licencia

La API local está disponible solo para usuarios de los planes Pro, Team y Business. El plan Starter no proporciona acceso a la API.

URL Base​

La API se ejecuta localmente en:

http://localhost:50809/api/v1/
nota

El puerto 50809 es el puerto predeterminado. Asegúrate de que TikMatrix esté en ejecución antes de realizar solicitudes.

Formato de Respuesta​

Todas las respuestas de la API siguen este formato:

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

Códigos de Respuesta​

CodeDescripción
0Éxito
40001Solicitud incorrecta - Parámetros no válidos, incluida una script_config que no pasa la validación
40002Error de parámetro - Falta script_name
40003Solicitud incorrecta - Script no admitido en esta compilación o plataforma, sin implementación, o estado de tarea no válido
40004Error de parámetro - Solo se pueden detener tareas en ejecución
40005Error de parámetro - task_ids no puede estar vacío
40301Prohibido - El acceso a la API requiere plan Pro+
40401No encontrado - El recurso no existe
50001Error interno del servidor

Inicio Rápido​

1. Verificar Acceso a la API​

Primero, confirma si tu licencia soporta API:

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

Respuesta de ejemplo:

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

2. Descubrir los scripts y sus parámetros​

GET /api/v1/schema describe cada script que esta compilación puede ejecutar y los campos exactos de script_config que acepta: nombres, tipos, valores por defecto, valores permitidos y cuáles son obligatorios. Se genera a partir del mismo catálogo con el que valida el servidor, así que no puede desviarse de lo que acepta la creación de tareas.

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

Dos parámetros de consulta opcionales:

ParámetroEfecto
platformLimita el listado a tiktok, instagram o threads. Una plataforma que esta compilación no incluye se rechaza con 40001. Por defecto devuelve todas las de la compilación.
include_unavailableCon true, incluye también los nombres de script que la API acepta pero que no tienen implementación. Cada uno lleva un unavailable_reason.

Respuesta (abreviada):

{
  "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 indica cuántas tareas producirá una petición: per_device crea una tarea por dispositivo (o por cuenta en modo multicuenta), per_item crea una por cada entrada del campo indicado, por dispositivo.

3. Crear una Tarea​

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": "¡Mira mi nuevo video! #viral"
    },
    "enable_multi_account": false
  }'

4. Listar Tareas​

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

Scripts Disponibles​

El parámetro script_name acepta los siguientes valores:

Nombre del ScriptDescripciónSoporte API
postPublicar vídeos, imágenes o publicaciones de solo texto en Threads✅ Compatible
followSeguir usuarios✅ Compatible
unfollowDejar de seguir usuarios✅ Compatible
account_warmupCalentar cuentas✅ Compatible
commentPublicar un comentario nuevo en publicaciones✅ Compatible
boost_commentDar me gusta o responder a comentarios existentes✅ Compatible
loginIniciar sesión en la cuenta✅ Compatible
profileActualizar el perfil✅ Compatible
match_accountVincular cuentas en el dispositivo✅ Compatible
likeDar me gusta a publicaciones✅ Compatible
viewVer una publicación durante un tiempo determinado✅ Compatible
favoriteGuardar una publicación en Favoritos✅ Compatible
repostRepostear vídeos de TikTok o publicaciones de Threads✅ Compatible — TikTok y Threads
messageEnviar mensajes directos✅ Compatible — solo Threads
follow_backSeguir cuentas de la lista de seguidores✅ Compatible — TikTok, Instagram y Threads
follow_suggestedSeguir cuentas sugeridas✅ Compatible — solo TikTok
custom_scriptEjecutar un programa que tú mismo registraste✅ Compatible ‡
super_marketingCampaña de supermarketing✅ Compatible †
scrape_usersExportar nombres de usuario de seguidores, seguidos o búsquedas✅ Compatible — TikTok, Instagram y Threads
auto_replyResponder a mensajes directos y comentarios❌ No disponible vía API §
† El supermarketing usa endpoints dedicados

La campaña de supermarketing no se crea a través de POST /api/v1/task. Se ejecuta sobre un dataset reutilizable de objetivos y tiene sus propios endpoints — consulta la Configuración del Script Super Marketing.

Mensajes directos solo en Threads

La tarea independiente message sigue el flujo perfil de Threads → Mensaje. Para TikTok e Instagram, usa super_marketing con un dataset reutilizable de objetivos en su lugar.

Scripts específicos de cada plataforma

repost está implementado para TikTok y Threads; follow_suggested sigue siendo exclusivo de TikTok. follow_back y scrape_users usan la interfaz de seguidores y búsqueda de cada plataforma en un dispositivo real, y están disponibles en TikTok, Instagram y Threads.

‡ Los scripts personalizados deben registrarse primero

custom_script ejecuta un programa que registraste en Dispositivos → Scripts personalizados. Pasa su id en script_config.custom_script_id; consulta Scripts personalizados.

§ La respuesta automática se ejecuta desde su propia página

auto_reply responde a mensajes directos y comentarios en TikTok, Instagram y Threads, en el plan Pro o superior. Sus rondas las programa la página Respuesta automática de la app, que contiene las reglas de respuesta, el horario de trabajo y el interruptor de pausa, por lo que no se puede crear a través de POST /api/v1/task.

Validación de script_config​

La creación de tareas valida script_config contra el esquema anterior antes de escribir nada, de modo que un parámetro incorrecto vuelve como un 400 que nombra el campo, en vez de una tarea que falla más tarde en el teléfono. Se rechazan tres cosas:

  • un campo obligatorio ausente o vacío,
  • un grupo de alternativas donde no se ha fijado ninguno de sus miembros (por ejemplo, follow necesita uno de target_users / target_user),
  • un valor fuera de los choices documentados de un campo.

Las claves que el esquema no lista se ignoran, no se rechazan: la aplicación de escritorio pasa sus propias claves por el mismo objeto y rechazar las desconocidas rompería integraciones existentes. Se registran en el servidor para que puedas detectar una errata en el log de la aplicación.

Los números pueden enviarse como cadenas ("20" además de 20), igual que ya aceptan los scripts.

Estados de Tarea​

Código de EstadoTexto de EstadoDescripción
0pendingTarea esperando ejecución
1runningTarea en ejecución
2completedTarea completada exitosamente
3failedTarea fallida

Siguiente Paso​