API REST v2

Vue d'ensemble

C'est l'interface qu'un agent IA pilote. Chaque appel est un verbe choisi par action, pour qu'un agent cherche le catalogue, relise le tarif et les limites, puis agisse : chercher-puis-agir, avec le prix confirmé avant que le moindre argent ne bouge. Le serveur MCP et la CLI enveloppent ces mêmes appels ; cette page est le protocole brut en dessous.

L'API suit la forme largement adoptée de la SMM API v2, de sorte que les logiciels de panel, scripts et intégrations d'agents existants fonctionnent avec un minimum de modifications. Chaque opération passe par un endpoint unique et choisit le verbe avec le paramètre action. Les réponses sont en JSON. Faciles à analyser et à enchaîner pour un script ou un LLM.

Endpoint

POST https://api.socialgo.com/api/v2

Authentification

L'authentification se fait par requête, pas de session, pas de handshake, c'est exactement ce qui la rend appelable par un agent. Envoyez votre key secrète à chaque appel. Trouvez-la et faites-la pivoter dans le tableau de bord, sous Compte → API. Traitez la clé comme un mot de passe : gardez-la côté serveur, jamais dans le code client ni dans un prompt d'agent.

Format de la requête

Envoyez des paramètres de formulaire application/x-www-form-urlencoded en POST. Chaque réponse est en JSON. Deux paramètres sont présents à chaque appel :

• key : votre clé API (obligatoire)
• action : le verbe à exécuter (obligatoire)

Format d'erreur

En cas d'échec, la réponse contient un champ error avec un message lisible, et le code de statut HTTP reflète le problème (par exemple 400 requête incorrecte, 401 clé invalide). Une seule forme prévisible, pour qu'un script ou un agent puisse brancher dessus sans deviner.

{
  "error": "Incorrect request"
}

Actions

Chaque verbe fait une seule chose. Un agent les enchaîne dans l'ordre : services pour trouver quoi acheter, add pour l'acheter, status pour le suivre. Les appels de lecture (services, status, balance) lui permettent de confirmer prix et fonds avant que les appels d'écriture (add, refill, cancel) ne dépensent quoi que ce soit.

1. Liste des services

Le catalogue qu'un agent lit en premier : chaque service qu'il peut commander, avec l'ID du service, la catégorie, le tarif (prix pour 1000) et les quantités min/max. Il utilise les ID service renvoyés pour passer des commandes, et le tarif pour confirmer le coût avant de dépenser.

Requête

key=YOUR_API_KEY
action=services

Réponse

[
  {
    "service": 1,
    "name": "Instagram Followers",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "50",
    "max": "10000",
    "refill": true,
    "cancel": true
  },
  {
    "service": 2,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.40",
    "min": "10",
    "max": "20000",
    "refill": false,
    "cancel": true
  }
]

2. Ajouter une commande

L'appel d'écriture. Passe une commande pour un service. Fournissez l'ID service, le link cible et la quantity. La réponse renvoie le nouvel ID order à suivre. Un agent ne l'exécute qu'après avoir confirmé le tarif et les limites.

Paramètres

• service : ID du service issu de la liste des services
• link : l'URL de la publication / du profil / de la chaîne
• quantity : nombre d'unités à livrer

Requête

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000

Réponse

{
  "order": 23501
}

3. Ajouter une commande : drip-feed

Répartit une commande en plusieurs livraisons plus petites étalées dans le temps, pour une courbe plus régulière. Définissez runs (combien de livraisons) et interval (minutes entre chacune). Le total livré est quantity × runs : le calcul qu'un agent utilise pour dimensionner une campagne sans que vous le fassiez à la main.

Paramètres supplémentaires

• runs : nombre de cycles de livraison
• interval : minutes entre chaque cycle

Requête

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000
runs=10
interval=60

Réponse

{
  "order": 23502
}

4. Statut de la commande

Renvoie l'état actuel d'une commande : montant débité, compteur de départ, statut, quantité restante et devise. C'est ainsi qu'un agent surveille une commande sans que vous rafraîchissiez le tableau de bord, et qu'il repère une baisse à signaler pour recharge.

Requête

key=YOUR_API_KEY
action=status
order=23501

Réponse

{
  "charge": "0.90",
  "start_count": "4250",
  "status": "In progress",
  "remains": "200",
  "currency": "USD"
}

Valeurs possibles de status : Pending, In progress, Processing, Completed, Partial, Canceled.

5. Statut de plusieurs commandes

Vérifiez plusieurs commandes en un seul appel. Passez une liste d'ID séparés par des virgules dans le paramètre orders. La réponse est indexée par ID de commande, pour qu'un agent interroge toute une campagne en un seul aller-retour au lieu d'un appel par commande.

Requête

key=YOUR_API_KEY
action=status
orders=23501,23502,23503

Réponse

{
  "23501": {
    "charge": "0.90",
    "start_count": "4250",
    "status": "Completed",
    "remains": "0",
    "currency": "USD"
  },
  "23502": {
    "charge": "9.00",
    "start_count": "1200",
    "status": "In progress",
    "remains": "500",
    "currency": "USD"
  },
  "23503": {
    "error": "Incorrect order ID"
  }
}

6. Recharge

Demande une recharge pour une commande dont le service la prend en charge (refill: true dans la liste des services) et renvoie un ID de recharge à suivre. Passez une seule order ou une liste orders séparée par des virgules, pour qu'un agent puisse demander des recharges en masse après qu'une vérification de statut a signalé des baisses.

Requête (unique)

key=YOUR_API_KEY
action=refill
order=23501

Réponse

{
  "refill": 4001
}

Requête (multiple)

key=YOUR_API_KEY
action=refill
orders=23501,23502

Réponse

[
  { "order": 23501, "refill": 4001 },
  { "order": 23502, "refill": { "error": "Refill not available" } }
]

7. Annuler

Demande l'annulation de commandes pas encore traitées (services avec cancel: true). Passez une liste orders séparée par des virgules ; la réponse indique le résultat pour chaque commande. L'annulation qu'un agent dégaine quand quelque chose est mis en file par erreur.

Requête

key=YOUR_API_KEY
action=cancel
orders=23501,23502

Réponse

[
  { "order": 23501, "cancel": 1 },
  { "order": 23502, "cancel": { "error": "Incorrect order ID" } }
]

8. Solde

Renvoie le solde et la devise de votre compte. Un agent le lit pour conditionner la dépense avant de passer une commande, et votre propre panel le lit pour afficher les fonds. L'appel le moins coûteux pour confirmer qu'il y a de quoi dépenser.

Requête

key=YOUR_API_KEY
action=balance

Réponse

{
  "balance": "182.45",
  "currency": "USD"
}

Appelez-la depuis n'importe quoi

Un seul endpoint, de simples paramètres de formulaire, pour qu'un shell, une tâche cron ou un agent puisse le piloter de la même façon. Voici une commande complète passée depuis la ligne de commande :

curl -X POST https://api.socialgo.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1" \
  -d "link=https://instagram.com/example" \
  -d "quantity=1000"

Notes et bonnes pratiques

• Lisez avant d'écrire. Appelez services (ou balance) pour confirmer le tarif, les limites et les fonds, puis appelez add : le même garde-fou chercher-puis-agir qu'utilisent le tableau de bord et le serveur MCP pour que rien ne dépense sans un prix confirmé.
• Mettez en cache la liste des services et actualisez-la régulièrement, les ID, tarifs et limites changent.
• Validez les quantités min/max avant de soumettre une commande pour éviter les appels rejetés.
• Interrogez le statut par lots avec l'appel multi-commandes plutôt qu'une requête par commande.
• Gardez votre clé côté serveur. Si elle est jamais exposée, faites-la pivoter immédiatement depuis le tableau de bord.