REST API v2

Обзор

Это интерфейс, которым управляет ИИ-агент. Каждый вызов, одно действие, выбранное через action, поэтому агент ищет по каталогу, считывает ставку и лимиты, затем действует, поиск-затем-действие, с ценой, подтверждённой до того, как деньги спишутся. MCP-сервер и CLI оборачивают эти же вызовы; эта страница, сырой протокол под ними.

API следует широко распространённой спецификации SMM API v2, поэтому существующее ПО для панелей, скрипты и интеграции агентов работают с минимальными изменениями. Каждая операция проходит через единую точку доступа и выбирает действие с помощью параметра action. Ответы, в формате JSON, легко разбираемом скриптом или LLM и пригодном для цепочек вызовов.

Точка доступа

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

Аутентификация

Аутентификация выполняется для каждого запроса, без сессии, без рукопожатия, и именно это делает API вызываемым агентом. Передавайте свой секретный key при каждом вызове. Найти и сменить его можно в панели в разделе Аккаунт → API. Относитесь к ключу как к паролю: храните его на стороне сервера, никогда, в клиентском коде или в промпте агента.

Формат запроса

Отправляйте параметры формы application/x-www-form-urlencoded методом POST. Каждый ответ, в формате JSON. Два параметра присутствуют в каждом вызове:

• key, ваш API-ключ (обязательно)
• action, действие, которое нужно выполнить (обязательно)

Формат ошибок

При сбое ответ содержит поле error с понятным человеку сообщением, а HTTP-код состояния отражает суть проблемы (например, 400, некорректный запрос, 401, недействительный ключ). Одна предсказуемая форма, чтобы скрипт или агент мог ветвиться по ней без догадок.

{
  "error": "Incorrect request"
}

Действия

Каждое действие делает одну работу. Агент выстраивает их по порядку: services, найти, что купить, add, купить, status, отследить. Читающие вызовы (services, status, balance) позволяют подтвердить цену и средства до записывающих вызовов (add, refill, cancel), которые что-либо тратят.

1. Список услуг

Каталог, который агент читает первым: каждая услуга, которую он может заказать, с ID услуги, категорией, тарифом (цена за 1000) и минимальным/максимальным количеством. Он использует возвращённые ID из поля service для оформления заказов, и тариф, чтобы подтвердить стоимость до списания.

Запрос

key=YOUR_API_KEY
action=services

Ответ

[
  {
    "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. Добавление заказа

Записывающий вызов. Оформляет заказ для одной услуги, передайте ID услуги service, целевую ссылку link и количество quantity. В ответе возвращается ID нового заказа в поле order для отслеживания. Агент выполняет это только после подтверждения ставки и лимитов.

Параметры

• service, ID услуги из списка услуг
• link, URL поста, профиля или канала
• quantity, количество единиц для доставки

Запрос

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

Ответ

{
  "order": 23501
}

3. Добавление заказа, drip-feed

Разбивает один заказ на несколько меньших поставок, распределённых во времени, для более плавной динамики. Задайте runs (сколько раз доставлять) и interval (минуты между запусками). Общий объём доставки равен quantity × runs, расчёт, который агент использует, чтобы рассчитать масштаб кампании без вашего участия.

Дополнительные параметры

• runs, количество запусков доставки
• interval, минуты между запусками

Запрос

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

Ответ

{
  "order": 23502
}

4. Статус заказа

Возвращает текущее состояние одного заказа: списание, начальный счётчик, статус, оставшееся количество и валюту. Так агент следит за заказом без обновления панели вами, и так он замечает просадку, которую стоит отметить для пополнения.

Запрос

key=YOUR_API_KEY
action=status
order=23501

Ответ

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

Возможные значения status: Pending, In progress, Processing, Completed, Partial, Canceled.

5. Статус нескольких заказов

Проверяйте много заказов одним вызовом, передайте список ID через запятую в параметре orders. Ответ структурирован по ID заказа, поэтому агент опрашивает целую кампанию за один заход, а не по вызову на каждый заказ.

Запрос

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

Ответ

{
  "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: true в списке услуг), и возвращает ID пополнения для отслеживания. Передайте один заказ order или список orders через запятую, так агент может запрашивать пополнения оптом после того, как проверка статуса выявит просадки.

Запрос (одиночный)

key=YOUR_API_KEY
action=refill
order=23501

Ответ

{
  "refill": 4001
}

Запрос (множественный)

key=YOUR_API_KEY
action=refill
orders=23501,23502

Ответ

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

7. Отмена

Запрашивает отмену ещё не обработанных заказов (услуги с cancel: true). Передайте список orders через запятую; ответ сообщает результат по каждому заказу. Отмена, к которой агент прибегает, когда что-то поставлено в очередь по ошибке.

Запрос

key=YOUR_API_KEY
action=cancel
orders=23501,23502

Ответ

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

8. Баланс

Возвращает баланс вашего аккаунта и валюту. Агент читает его, чтобы проверить наличие средств перед оформлением заказа, а ваша панель читает, чтобы показать средства. Самый дешёвый вызов, чтобы убедиться, что есть на что тратить.

Запрос

key=YOUR_API_KEY
action=balance

Ответ

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

Вызывайте откуда угодно

Одна точка доступа, обычные параметры формы, поэтому оболочка, cron-задача или агент управляют ею одинаково. Вот полный заказ, оформленный из командной строки:

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"

Заметки и лучшие практики

• Читайте, прежде чем писать. Вызовите services (или balance), чтобы подтвердить ставку, лимиты и средства, затем вызывайте add, тот же принцип поиск-затем-действие, который используют панель и MCP-сервер, чтобы ничего не тратилось без подтверждённой цены.
• Кэшируйте список услуг и периодически его обновляйте, ID, тарифы и лимиты меняются.
• Проверяйте минимальное/максимальное количество (min/max) перед отправкой заказа, чтобы избежать отклонённых вызовов.
• Опрашивайте статус пакетами через вызов для нескольких заказов вместо одного запроса на каждый заказ.
• Храните ключ на стороне сервера. Если он когда-либо был раскрыт, немедленно смените его в панели.