API REST v2

Visão geral

Esta é a superfície que um agente de IA dirige. Cada chamada é um verbo escolhido pelo action: o agente busca o catálogo, lê o preço e os limites e então age, search-then-act, com o preço confirmado antes de qualquer gasto. O servidor MCP e a CLI embrulham essas mesmas chamadas; esta página é o protocolo cru por baixo.

A API segue o formato amplamente adotado SMM API v2, então softwares de painel, scripts e integrações de agente existentes funcionam com mudanças mínimas. Toda operação passa por um único endpoint e escolhe o verbo pelo parâmetro action. As respostas são JSON. Fáceis de um script ou um LLM ler e encadear.

Endpoint

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

Autenticação

A autenticação é por requisição. Sem sessão, sem handshake, que é justamente o que a torna chamável por um agente. Envie sua key secreta em toda chamada. Encontre e rotacione a chave no painel em Conta → API. Trate a chave como senha: mantenha no servidor, nunca no código do cliente ou no prompt de um agente.

Formato da requisição

Envie parâmetros application/x-www-form-urlencoded via POST. Toda resposta é JSON. Dois parâmetros vão em toda chamada:

• key: sua chave de API (obrigatório)
• action: o verbo a executar (obrigatório)

Formato de erro

Na falha a resposta traz um campo error com mensagem legível, e o status HTTP reflete o problema (ex.: 400 requisição inválida, 401 chave inválida). Um formato previsível, então um script ou agente decide o caminho sem adivinhar.

{
  "error": "Incorrect request"
}

Ações

Cada verbo faz um trabalho. Um agente encadeia em ordem: services pra achar o que comprar, add pra comprar, status pra acompanhar. As leituras (services, status, balance) deixam ele confirmar preço e saldo antes das escritas (add, refill, cancel) gastarem qualquer coisa.

1. Listar serviços

O catálogo que um agente lê primeiro: todo serviço que ele pode pedir, com o ID do serviço, categoria, preço (por 1000) e quantidades mín./máx. Ele usa os IDs de service retornados pra criar pedidos. E o preço pra confirmar o custo antes de gastar.

Requisição

key=YOUR_API_KEY
action=services

Resposta

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

A chamada de escrita. Cria um pedido pra um serviço. Passe o ID em service, o link alvo e a quantity. A resposta devolve o ID em order pra acompanhar. Um agente só roda isso depois de confirmar o preço e os limites.

Parâmetros

• service: ID do serviço da lista de serviços
• link: a URL do post / perfil / canal
• quantity: número de unidades a entregar

Requisição

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

Resposta

{
  "order": 23501
}

3. Criar pedido, drip-feed

Divide um pedido em entregas menores espalhadas no tempo, pra uma curva mais estável. Defina runs (quantas entregas) e interval (minutos entre cada uma). O total entregue é quantity × runs. A conta que um agente usa pra dimensionar uma campanha sem você fazer na mão.

Parâmetros adicionais

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

Requisição

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

Resposta

{
  "order": 23502
}

4. Status do pedido

Devolve o estado atual de um pedido: cobrança, contagem inicial, status, quantidade restante e moeda. É assim que um agente acompanha um pedido sem você atualizar o painel. E como ele detecta uma queda que vale sinalizar pra reposição.

Requisição

key=YOUR_API_KEY
action=status
order=23501

Resposta

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

Valores possíveis de status: Pending, In progress, Processing, Completed, Partial, Canceled.

5. Status de múltiplos pedidos

Consulte vários pedidos numa chamada. Passe uma lista de IDs separados por vírgula em orders. A resposta é indexada por ID, então um agente acompanha uma campanha inteira numa ida só, em vez de uma chamada por pedido.

Requisição

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

Resposta

{
  "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. Reposição

Pede reposição de um pedido cujo serviço suporta (refill: true na lista de serviços) e devolve um ID de reposição pra acompanhar. Passe um order único ou uma lista orders separada por vírgula. Assim um agente pede reposições em lote depois de um status sinalizar quedas.

Requisição (único)

key=YOUR_API_KEY
action=refill
order=23501

Resposta

{
  "refill": 4001
}

Requisição (múltiplos)

key=YOUR_API_KEY
action=refill
orders=23501,23502

Resposta

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

7. Cancelar

Pede cancelamento de pedidos ainda não processados (serviços com cancel: true). Passe uma lista orders separada por vírgula; a resposta reporta o resultado por pedido. O desfazer que um agente usa quando algo entra na fila por engano.

Requisição

key=YOUR_API_KEY
action=cancel
orders=23501,23502

Resposta

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

8. Saldo

Devolve o saldo e a moeda da sua conta. Um agente lê pra travar o gasto antes de criar um pedido. E seu painel lê pra exibir os fundos. A chamada mais barata pra confirmar que há dinheiro pra gastar.

Requisição

key=YOUR_API_KEY
action=balance

Resposta

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

Chame de qualquer lugar

Um endpoint, parâmetros de formulário simples. Então um shell, um cron ou um agente dirigem do mesmo jeito. Aqui um pedido completo criado pela linha de 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"

Notas e boas práticas

• Leia antes de escrever. Chame services (ou balance) pra confirmar preço, limites e saldo, e só então chame add. O mesmo guardrail search-then-act que o painel e o servidor MCP usam, pra nada gastar sem preço confirmado.
• Faça cache da lista de serviços e atualize periodicamente. IDs, preços e limites mudam.
• Valide as quantidades min/max antes de enviar um pedido pra evitar chamadas rejeitadas.
• Consulte status em lote com a chamada de múltiplos pedidos, em vez de uma requisição por pedido.
• Mantenha sua chave no servidor. Se ela vazar, rotacione na hora pelo painel.