API REST v2

Visión general

Esta es la superficie que maneja un agente de IA. Cada llamada es un verbo elegido por action, así que un agente busca el catálogo, lee la tarifa y los límites, y luego actúa: buscar-luego-actuar, con el precio confirmado antes de que se mueva el dinero. El servidor MCP y la CLI envuelven estas mismas llamadas; esta página es el protocolo crudo por debajo.

La API sigue la forma ampliamente adoptada de la API SMM v2, así que el software de paneles, los scripts y las integraciones de agentes existentes funcionan con cambios mínimos. Cada operación pasa por un único endpoint y elige el verbo con el parámetro action. Las respuestas son JSON. Fáciles de parsear y encadenar para un script o un LLM.

Endpoint

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

Autenticación

La autenticación es por solicitud. Sin sesión, sin handshake, que es justo lo que la hace invocable por un agente. Envía tu key secreta en cada llamada. Encuéntrala y rótala en el panel en Cuenta → API. Trata la clave como una contraseña: mantenla del lado del servidor, nunca en código de cliente ni en un prompt de agente.

Formato de la solicitud

Envía parámetros de formulario application/x-www-form-urlencoded por POST. Cada respuesta es JSON. Dos parámetros van en cada llamada:

• key: tu clave API (requerida)
• action: el verbo a ejecutar (requerido)

Formato de error

Ante un fallo, la respuesta lleva un campo error con un mensaje legible, y el estado HTTP refleja el problema (p. ej. 400 solicitud incorrecta, 401 clave inválida). Una forma predecible, para que un script o agente pueda bifurcar sin adivinar.

{
  "error": "Incorrect request"
}

Acciones

Cada verbo hace un trabajo. Un agente los encadena en orden: services para encontrar qué comprar, add para comprarlo, status para rastrearlo. Las llamadas de lectura (services, status, balance) le permiten confirmar precio y fondos antes de las llamadas de escritura (add, refill, cancel) que gastan algo.

1. Listar servicios

El catálogo que un agente lee primero: cada servicio que puede pedir, con el ID del servicio, la categoría, la tarifa (precio por 1000) y las cantidades mín/máx. Usa los IDs de service devueltos para colocar pedidos. Y la tarifa para confirmar el costo antes de gastar.

Solicitud

key=YOUR_API_KEY
action=services

Respuesta

[
  {
    "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. Agregar pedido

La llamada de escritura. Coloca un pedido para un servicio. Pasa el ID de service, el link objetivo y la quantity. La respuesta devuelve el nuevo ID de order para rastrear. Un agente ejecuta esto solo tras haber confirmado la tarifa y los límites.

Parámetros

• service: ID del servicio de la lista de servicios
• link: la URL de la publicación / perfil / canal
• quantity: número de unidades a entregar

Solicitud

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

Respuesta

{
  "order": 23501
}

3. Agregar pedido: drip-feed

Divide un pedido en entregas más pequeñas repartidas en el tiempo, para una curva más estable. Define runs (cuántas entregas) e interval (minutos entre cada una). El total entregado es quantity × runs. La cuenta que un agente usa para dimensionar una campaña sin que tú la hagas a mano.

Parámetros adicionales

• runs: número de entregas
• interval: minutos entre cada entrega

Solicitud

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

Respuesta

{
  "order": 23502
}

4. Estado del pedido

Devuelve el estado actual de un pedido: cargo, conteo inicial, estado, cantidad restante y moneda. Así es como un agente vigila un pedido sin que tú refresques el panel. Y cómo detecta una caída que valga la pena marcar para reposición.

Solicitud

key=YOUR_API_KEY
action=status
order=23501

Respuesta

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

Valores posibles de status: Pending, In progress, Processing, Completed, Partial, Canceled.

5. Estado de múltiples pedidos

Consulta muchos pedidos en una llamada. Pasa una lista de IDs separados por comas en el parámetro orders. La respuesta se indexa por ID de pedido, así un agente consulta toda una campaña en una sola ida y vuelta en lugar de una llamada por pedido.

Solicitud

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

Respuesta

{
  "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. Reposición

Solicita una reposición en un pedido cuyo servicio la admite (refill: true en la lista de servicios) y devuelve un ID de reposición para rastrear. Pasa un solo order o una lista orders separada por comas. Así un agente puede solicitar reposiciones en lote tras una consulta de estado que marca caídas.

Solicitud (única)

key=YOUR_API_KEY
action=refill
order=23501

Respuesta

{
  "refill": 4001
}

Solicitud (múltiple)

key=YOUR_API_KEY
action=refill
orders=23501,23502

Respuesta

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

7. Cancelar

Solicita la cancelación de pedidos aún no procesados (servicios con cancel: true). Pasa una lista orders separada por comas; la respuesta reporta el resultado por pedido. El deshacer al que un agente recurre cuando algo se encola por error.

Solicitud

key=YOUR_API_KEY
action=cancel
orders=23501,23502

Respuesta

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

8. Saldo

Devuelve el saldo de tu cuenta y la moneda. Un agente lo lee para limitar el gasto antes de colocar un pedido. Y tu propio panel lo lee para mostrar los fondos. La llamada más barata para confirmar que hay dinero para gastar.

Solicitud

key=YOUR_API_KEY
action=balance

Respuesta

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

Llámala desde cualquier cosa

Un endpoint, parámetros de formulario simples. Así una shell, un cron job o un agente pueden manejarla de la misma forma. Aquí hay un pedido completo colocado desde la línea de comandos:

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"

Notas y buenas prácticas

• Lee antes de escribir. Llama a services (o balance) para confirmar la tarifa, los límites y los fondos, y luego llama a add. La misma protección de buscar-luego-actuar que usan el panel y el servidor MCP para que nada se gaste sin un precio confirmado.
• Cachea la lista de servicios y refréscala periódicamente. Los IDs, tarifas y límites cambian.
• Valida las cantidades min/max antes de enviar un pedido para evitar llamadas rechazadas.
• Consulta el estado en lotes con la llamada de múltiples pedidos en lugar de una solicitud por pedido.
• Mantén tu clave del lado del servidor. Si alguna vez se expone, rótala de inmediato desde el panel.