Saltar al contenido principal

Visión General de la API Local

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 o instagram. 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"],
        "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 contenido✅ Compatible
followSeguir usuarios✅ Compatible
unfollowDejar de seguir✅ Compatible
account_warmupCalentamiento de cuenta✅ Compatible
commentPublicar un comentario en posts✅ Compatible
boost_commentDar me gusta/responder comentarios existentes✅ Compatible
loginIniciar sesión en cuenta✅ Compatible
profileActualizar perfil✅ Compatible
match_accountVincular cuentas en dispositivo✅ Compatible
likeMe gusta a posts✅ Compatible
viewVer una publicación durante un tiempo✅ Compatible
favoriteGuardar una publicación en Favoritos✅ Compatible
repostRepostear vídeos de TikTok✅ Admitido — solo TikTok
messageMensaje directo❌ No disponible §
follow_suggestedSeguir cuentas sugeridas✅ Admitido — solo TikTok
super_marketingCampaña de supermarketing✅ Compatible †
scrape_userExtraer datos de usuario🔜 Próximamente
† El supermarketing usa endpoints dedicados

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

§ message no tiene implementación

message era aceptado por la creación de tareas, pero el binario de scripts no tiene manejador para él en ninguna de las dos plataformas, así que toda tarea de este tipo fallaba en el dispositivo con "Unknown script". Ahora se rechaza al crearla, indicando ese motivo. Para enviar mensajes directos hoy, usa super_marketing, que gestiona los DM mediante un conjunto de destinatarios.

Scripts específicos de plataforma

repost y follow_suggested solo están implementados para TikTok. Crear uno contra un objetivo de Instagram se rechaza en lugar de encolarse: antes la tarea se creaba y luego fallaba en el dispositivo.

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​