API REST v2

Panoramica

Questa è la superficie che guida un agente AI. Ogni chiamata è un verbo scelto da action, così un agente cerca nel catalogo, rilegge tariffa e limiti, poi agisce: search-then-act, con il prezzo confermato prima che si muova del denaro. Il server MCP e la CLI incapsulano queste stesse chiamate; questa pagina è il protocollo grezzo sottostante.

L'API segue la forma ampiamente adottata della SMM API v2, così software di pannello, script e integrazioni di agenti esistenti funzionano con modifiche minime. Ogni operazione passa per un singolo endpoint e sceglie il verbo con il parametro action. Le risposte sono JSON. Facili da analizzare e concatenare per uno script o un LLM.

Endpoint

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

Autenticazione

L'autenticazione è per richiesta, niente sessione, niente handshake, ed è proprio questo a renderla richiamabile da un agente. Invia la tua key segreta a ogni chiamata. Trovala e ruotala nella dashboard sotto Account → API. Tratta la chiave come una password: tienila lato server, mai nel codice client o nel prompt di un agente.

Formato della richiesta

Invia parametri form application/x-www-form-urlencoded via POST. Ogni risposta è JSON. Due parametri sono presenti in ogni chiamata:

• key: la tua chiave API (obbligatoria)
• action: il verbo da eseguire (obbligatorio)

Formato degli errori

In caso di errore la risposta porta un campo error con un messaggio leggibile, e lo stato HTTP riflette il problema (es. 400 richiesta errata, 401 chiave non valida). Una forma prevedibile, così uno script o un agente può diramare senza tirare a indovinare.

{
  "error": "Incorrect request"
}

Azioni

Ogni verbo fa un solo lavoro. Un agente li concatena in ordine: services per trovare cosa comprare, add per comprarlo, status per tracciarlo. Le chiamate di lettura (services, status, balance) gli fanno confermare prezzo e fondi prima delle chiamate di scrittura (add, refill, cancel) che spendono.

1. Elenca i servizi

Il catalogo che un agente legge per primo: ogni servizio che può ordinare, con l'ID del servizio, la categoria, la tariffa (prezzo per 1000) e le quantità min/max. Usa gli ID service restituiti per piazzare ordini, e la tariffa per confermare il costo prima di spendere.

Richiesta

key=YOUR_API_KEY
action=services

Risposta

[
  {
    "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. Aggiungi ordine

La chiamata di scrittura. Piazza un ordine per un servizio. Passa l'ID service, il link di destinazione e la quantity. La risposta restituisce il nuovo ID order da tracciare. Un agente la esegue solo dopo aver confermato tariffa e limiti.

Parametri

• service: ID del servizio dall'elenco servizi
• link: l'URL del post / profilo / canale
• quantity: numero di unità da consegnare

Richiesta

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

Risposta

{
  "order": 23501
}

3. Aggiungi ordine: drip-feed

Divide un ordine in consegne più piccole distribuite nel tempo, per una curva più costante. Imposta runs (quante consegne) e interval (minuti tra una e l'altra). Il totale consegnato è quantity × runs, il calcolo che un agente usa per dimensionare una campagna senza che tu lo faccia a mano.

Parametri aggiuntivi

• runs: numero di consegne
• interval: minuti tra una consegna e l'altra

Richiesta

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

Risposta

{
  "order": 23502
}

4. Stato dell'ordine

Restituisce lo stato attuale di un ordine: addebito, conteggio iniziale, stato, quantità rimanente e valuta. È così che un agente sorveglia un ordine senza che tu aggiorni la dashboard, e così individua un calo da segnalare per il refill.

Richiesta

key=YOUR_API_KEY
action=status
order=23501

Risposta

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

Possibili valori di status: Pending, In progress, Processing, Completed, Partial, Canceled.

5. Stato di più ordini

Controlla molti ordini in una sola chiamata. Passa un elenco di ID separati da virgola nel parametro orders. La risposta è indicizzata per ID ordine, così un agente fa polling di un'intera campagna in un solo viaggio invece di una chiamata per ordine.

Richiesta

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

Risposta

{
  "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. Refill

Richiede un refill su un ordine il cui servizio lo supporta (refill: true nell'elenco servizi) e restituisce un ID di refill da tracciare. Passa un singolo order o un elenco orders separato da virgola, così un agente può richiedere refill in blocco dopo che un controllo dello stato segnala dei cali.

Richiesta (singola)

key=YOUR_API_KEY
action=refill
order=23501

Risposta

{
  "refill": 4001
}

Richiesta (multipla)

key=YOUR_API_KEY
action=refill
orders=23501,23502

Risposta

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

7. Annulla

Richiede l'annullamento di ordini non ancora elaborati (servizi con cancel: true). Passa un elenco orders separato da virgola; la risposta riporta l'esito per ogni ordine. L'annulla a cui ricorre un agente quando qualcosa è in coda per errore.

Richiesta

key=YOUR_API_KEY
action=cancel
orders=23501,23502

Risposta

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

8. Saldo

Restituisce il saldo del tuo account e la valuta. Un agente lo legge per regolare la spesa prima di piazzare un ordine, e il tuo stesso pannello lo legge per mostrare i fondi. La chiamata più economica per confermare che ci sono soldi da spendere.

Richiesta

key=YOUR_API_KEY
action=balance

Risposta

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

Chiamala da qualunque cosa

Un endpoint, semplici parametri form, così una shell, un cron job o un agente possono guidarla allo stesso modo. Ecco un ordine completo piazzato dalla riga di comando:

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"

Note e buone pratiche

• Leggi prima di scrivere. Chiama services (o balance) per confermare tariffa, limiti e fondi, poi chiama add, la stessa salvaguardia search-then-act che usano la dashboard e il server MCP, così niente si spende senza un prezzo confermato.
• Metti in cache l'elenco servizi e aggiornalo periodicamente. ID, tariffe e limiti cambiano.
• Valida le quantità min/max prima di inviare un ordine per evitare chiamate rifiutate.
• Fai polling dello stato a lotti con la chiamata multi-ordini invece di una richiesta per ordine.
• Tieni la chiave lato server. Se viene mai esposta, ruotala subito dalla dashboard.