Aller au contenu principal

Aperçu de l'API Locale

TikMatrix fournit une API RESTful locale qui vous permet de gérer les tâches par programmation. Cela est particulièrement utile pour intégrer TikMatrix dans vos propres systèmes d'automatisation, créer des flux de travail personnalisés ou effectuer des opérations en masse.

Exigences​

Exigences de licence

L'API locale est disponible uniquement pour les utilisateurs des forfaits Pro, Team et Business. Le forfait Starter ne fournit pas d'accès à l'API.

URL de Base​

L'API fonctionne localement à l'adresse :

http://localhost:50809/api/v1/
remarque

Le port 50809 est le port par défaut. Veuillez vous assurer que TikMatrix est en cours d'exécution avant d'envoyer des requêtes.

Format de Réponse​

Toutes les réponses de l'API suivent le format suivant :

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

Description des Codes de Réponse​

CodeDescription
0Succès
40001Requête incorrecte - Paramètres invalides, y compris une script_config qui échoue à la validation
40002Erreur de paramètre - script_name manquant
40003Requête incorrecte - Script non pris en charge par cette build ou cette plateforme, sans implémentation, ou état de tâche invalide
40004Erreur de paramètre - Seules les tâches en cours d'exécution peuvent être arrêtées
40005Erreur de paramètre - task_ids ne peut pas être vide
40301Interdit - L'accès à l'API nécessite un forfait Pro+
40401Non trouvé - La ressource n'existe pas
50001Erreur interne du serveur

Démarrage Rapide​

1. Vérifier l'Accès à l'API​

Tout d'abord, confirmez que votre licence prend en charge l'API :

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

Exemple de réponse :

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

2. Découvrir les scripts et leurs paramètres​

GET /api/v1/schema décrit chaque script que cette build peut exécuter ainsi que les champs script_config exacts qu’il accepte : noms, types, valeurs par défaut, valeurs autorisées et champs obligatoires. Il est généré à partir du même catalogue que celui utilisé pour la validation côté serveur, il ne peut donc pas diverger de ce que la création de tâche accepte.

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

Deux paramètres de requête facultatifs :

ParamètreEffet
platformRestreint la liste à tiktok ou instagram. Une plateforme absente de cette build est rejetée avec 40001. Par défaut, toutes celles de la build.
include_unavailableÀ true, liste aussi les noms de script que l’API accepte mais qui n’ont aucune implémentation. Chacun porte un unavailable_reason.

Réponse (abrégée) :

{
  "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 indique combien de tâches une requête produira : per_device crée une tâche par appareil (ou par compte en mode multi-compte), per_item en crée une par entrée du champ nommé, par appareil.

3. Créer une Tâche​

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": "Regardez ma nouvelle vidéo ! #tendance"
    },
    "enable_multi_account": false
  }'

4. Interroger la Liste des Tâches​

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

Scripts Disponibles​

Le paramètre script_name accepte les valeurs suivantes :

Nom du ScriptDescriptionSupport API
postPublier du contenu✅ Pris en charge
followSuivre des utilisateurs✅ Pris en charge
unfollowSe désabonner✅ Pris en charge
account_warmupPréchauffage de compte✅ Pris en charge
commentPublier un commentaire sur des posts✅ Pris en charge
boost_commentAimer/répondre aux commentaires existants✅ Pris en charge
loginSe connecter au compte✅ Pris en charge
profileMettre à jour le profil✅ Pris en charge
match_accountAssocier les comptes sur l'appareil✅ Pris en charge
likeAimer des posts✅ Pris en charge
viewRegarder une publication pendant une durée✅ Pris en charge
favoriteEnregistrer une publication dans les Favoris✅ Pris en charge
repostRepartager des vidéos TikTok✅ Pris en charge — TikTok uniquement
messageMessage privé❌ Indisponible §
follow_suggestedSuivre les comptes suggérés✅ Pris en charge — TikTok uniquement
super_marketingCampagne de super marketing✅ Pris en charge †
scrape_userExtraire les données utilisateur🔜 Prochainement
† Le super marketing utilise des endpoints dédiés

La campagne de super marketing n'est pas créée via POST /api/v1/task. Elle fonctionne sur un dataset réutilisable de cibles et dispose de ses propres endpoints — voir la Configuration du Script Super Marketing.

§ message n’a pas d’implémentation

message était accepté par la création de tâche, mais le binaire de scripts n’a de gestionnaire pour lui sur aucune des deux plateformes : chaque tâche de ce type échouait sur l’appareil avec « Unknown script ». Elle est désormais rejetée dès la création, avec ce motif. Pour envoyer des messages privés aujourd’hui, utilisez super_marketing, qui pilote les DM via un jeu de cibles.

Scripts propres à une plateforme

repost et follow_suggested ne sont implémentés que pour TikTok. Une création visant Instagram est rejetée au lieu d’être mise en file — auparavant la tâche était créée puis échouait sur l’appareil.

Validation de script_config​

La création de tâche valide script_config contre le schéma ci-dessus avant d’écrire quoi que ce soit : un mauvais paramètre revient donc en 400 en nommant le champ, plutôt qu’en tâche qui échoue plus tard sur le téléphone. Trois choses sont rejetées :

  • un champ obligatoire manquant ou vide,
  • un groupe alternatif dont aucun membre n’est renseigné (par exemple follow exige target_users ou target_user),
  • une valeur hors des choices documentés d’un champ.

Les clés absentes du schéma sont ignorées, pas rejetées : l’application de bureau fait passer ses propres clés par le même objet, et rejeter les clés inconnues casserait les intégrations existantes. Elles sont journalisées côté serveur pour vous permettre de repérer une faute de frappe dans le log.

Les nombres peuvent être envoyés sous forme de chaînes ("20" comme 20), conformément à ce que les scripts acceptent déjà.

États des Tâches​

Code d'ÉtatTexte d'ÉtatDescription
0pendingLa tâche est en attente d'exécution
1runningLa tâche est en cours d'exécution
2completedLa tâche a été exécutée avec succès
3failedL'exécution de la tâche a échoué

Suite​