Passa al contenuto principale

Panoramica dell'API Locale

TikMatrix fornisce un'API RESTful locale che consente di gestire le attività in modo programmatico. Questo è utile per integrare TikMatrix nei tuoi sistemi di automazione, creare flussi di lavoro personalizzati o eseguire operazioni in blocco.

Requisiti​

Requisito di Licenza

L'API locale è disponibile solo per gli abbonati ai piani Pro, Team e Business. Il piano Starter non ha accesso all'API.

URL Base​

L'API è in esecuzione sulla tua macchina locale all'indirizzo:

http://localhost:50809/api/v1/
note

La porta 50809 è la porta predefinita. Assicurati che TikMatrix sia in esecuzione prima di effettuare richieste API.

Formato di Risposta​

Tutte le risposte API seguono questo formato:

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

Codici di Risposta​

CodiceDescrizione
0Successo
40001Richiesta non valida - Parametri non validi, inclusa una script_config che non supera la convalida
40002Richiesta non valida - script_name mancante
40003Richiesta non valida - Script non supportato su questa build o piattaforma, privo di implementazione, o stato attività non valido
40004Richiesta non valida - Solo le attività in esecuzione possono essere interrotte
40005Richiesta non valida - task_ids non può essere vuoto
40301Vietato - L'accesso all'API richiede il piano Pro+
40401Non trovato - Risorsa non trovata
50001Errore interno del server

Avvio Rapido​

1. Verifica Accesso API​

Prima di tutto, verifica che la tua licenza supporti l'accesso all'API:

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

Risposta:

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

2. Scoprire gli script e i loro parametri​

GET /api/v1/schema descrive ogni script che questa build può eseguire e i campi esatti di script_config che accetta: nomi, tipi, valori predefiniti, valori ammessi e quali sono obbligatori. È generato dallo stesso catalogo usato dal server per la convalida, quindi non può divergere da ciò che la creazione attività accetta.

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

Due parametri di query facoltativi:

ParametroEffetto
platformLimita l’elenco a tiktok o instagram. Una piattaforma non inclusa in questa build viene rifiutata con 40001. Per impostazione predefinita, tutte quelle della build.
include_unavailableImpostato a true, elenca anche i nomi di script accettati dall’API ma privi di implementazione. Ognuno riporta un unavailable_reason.

Risposta (abbreviata):

{
  "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 quante attività produrrà una richiesta: per_device crea un’attività per dispositivo (o per account in modalità multi-account), per_item ne crea una per ogni voce del campo indicato, per dispositivo.

3. Creare un'Attività​

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": "Guarda il mio nuovo video! #virale"
    },
    "enable_multi_account": false,
    "start_time": "14:30"
  }'

4. Elenco Attività​

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

Script Disponibili​

Il parametro script_name accetta i seguenti valori:

Nome ScriptDescrizioneSupporto API
postPubblica contenuto✅ Supportato
followSegui utenti✅ Supportato
unfollowSmetti di seguire✅ Supportato
account_warmupRiscalda account✅ Supportato
commentPubblica un commento sui post✅ Supportato
boost_commentMetti mi piace/rispondi ai commenti esistenti✅ Supportato
loginAccedi all'account✅ Supportato
profileAggiorna profilo✅ Supportato
match_accountAbbina account sul dispositivo✅ Supportato
likeMi piace ai post✅ Supportato
viewGuarda un post per una durata✅ Supportato
favoriteSalva un post nei Preferiti✅ Supportato
repostRipubblica video TikTok✅ Supportato — solo TikTok
messageMessaggio diretto❌ Non disponibile §
follow_suggestedSegui account suggeriti✅ Supportato — solo TikTok
super_marketingCampagna di super marketing✅ Supportato †
scrape_userEstrai dati utente🔜 Prossimamente
† Il super marketing utilizza endpoint dedicati

La campagna di super marketing non viene creata tramite POST /api/v1/task. Funziona su un dataset riutilizzabile di target e ha i propri endpoint dedicati — vedi la Configurazione dello Script Super Marketing.

§ message non ha un’implementazione

message veniva accettato dalla creazione attività, ma il binario degli script non ha un gestore per esso su nessuna delle due piattaforme, perciò ogni attività di questo tipo falliva sul dispositivo con "Unknown script". Ora viene rifiutata già in fase di creazione, indicando il motivo. Per inviare messaggi diretti oggi, usa super_marketing, che gestisce i DM tramite un dataset di destinatari.

Script specifici per piattaforma

repost e follow_suggested sono implementati solo per TikTok. Crearne uno per un obiettivo Instagram viene rifiutato invece che accodato: prima l’attività veniva creata e poi falliva sul dispositivo.

Convalida di script_config​

La creazione attività convalida script_config rispetto allo schema qui sopra prima di scrivere qualsiasi cosa, così un parametro sbagliato torna come 400 che nomina il campo, invece di un’attività che fallisce più tardi sul telefono. Vengono rifiutate tre cose:

  • un campo obbligatorio mancante o vuoto,
  • un gruppo alternativo in cui nessun membro è impostato (per esempio follow richiede uno tra target_users / target_user),
  • un valore fuori dai choices documentati di un campo.

Le chiavi non elencate nello schema vengono ignorate, non rifiutate: l’app desktop fa passare le proprie chiavi attraverso lo stesso oggetto e rifiutare quelle sconosciute romperebbe le integrazioni esistenti. Vengono registrate lato server così puoi individuare un refuso nel log dell’app.

I numeri possono essere inviati come stringhe ("20" oltre a 20), coerentemente con quanto gli script già accettano.

Stato dell'Attività​

Codice StatoTesto StatoDescrizione
0pendingAttività in attesa di esecuzione
1runningAttività in esecuzione
2completedAttività completata con successo
3failedAttività fallita

Passi Successivi​